BlackBerry Platform Support Events

Introduction

The BlackBerry platform support library, BPS, provides an API for system events. In Qt, BPS events are integrated into Qt's event loop, i.e. Qt receives and consumes BPS events. One example in which Qt consumes a BPS event is the NAVIGATOR_EXIT event - when receiving that event, Qt will trigger quitting the application. See Handling BPS events article for more details.

Receiving BPS events

Since BPS events are integrated into Qt's event loop, how is it possible as a user to still receive BPS events? An application should never call bps_get_event() itself, as that would 'steal' the events from Qt, and Qt would miss out on important events like the above mentioned NAVIGATOR_EXIT.

Instead, Qt offers to install native event filters. Once a native event filter is installed, Qt will forward all BPS events to that native event filter. So the solution for receiving BPS events is to install a native event filter and process the BPS events in the event filter function.

The following example shows how to install native event filters to process a NAVIGATOR_SWIPE_DOWN event. The Qt4 and the Qt5 versions are a bit different, therefore the two code examples.

Native event filters are installed on a per-thread basis, as each thread in Qt has its own event dispatcher. Each thread only receives the native events requested in that thread. If your code that installs the native event filter is running in multiple threads, this needs to be considered, especially in Qt4 version, in which the previous event filter pointer then needs to be stored on a per-thread basis, and not as a global variable.

Note that this wiki page is about native events only, e.g. BPS events on the BlackBerry platform. Receiving normal QEvents is an entirely unrelated matter, see the documentation of QCoreApplication::notify() for details about that.

Qt4 Example

First, install the native event filter. Note that the previous event filter needs to be remembered, as the native event filters form a chain - one event filter always needs to pass on the native event to the previous filter in the chain, otherwise the event gets lost!

static QAbstractEventDispatcher::EventFilter s_previousEventFilter = 0;
s_previousEventFilter = QAbstractEventDispatcher::instance()->setEventFilter(s_eventFilter);

Afterwards, make sure BPS delivers navigator events to the current thread. For certain types of events, like navigator and virtual keyboard events, Qt will already have requested the events, but I can't hurt to request them twice:

navigator_request_events();

Other event types, such as mmrenderer events, are not automatically requested by Qt, there you have to call the appropriate foo_request_events() function yourself. Note that it is not necessary to call bps_initialize() yourself, Qt already does that for you. But again, it doesn't hurt either. Lastly, let's have a look at the event filter function:

static bool s_eventFilter(void* message)
{
    bps_event_t* const event = static_cast<bps_event_t*>(message);
    if (event && bps_event_get_domain(event)  navigator_get_domain()) {
        const int id = bps_event_get_code(event);
        if (id  NAVIGATOR_SWIPE_DOWN)
            qDebug() << "The user swiped down!";
    }
    if (s_previousEventFilter)
        return s_previousEventFilter(message);
    else
        return false;
}

Note that in Qt4, native event filters should never be removed once installed, as that will easily break the chain. Instead of removing a native event filter, simply don't do any event processing in it anymore, apart from passing the event on to the previous element in the chain.

Qt5 Example

The API for native event filters in Qt5 has been improved, the brittle event filter chaining is no longer exposed.

Instead of an event filter function like in Qt4, there is an event filter object:

class MyEventFilter : public QAbstractNativeEventFilter
{
    bool nativeEventFilter(const QByteArray& eventType, void* message, long* result) Q_DECL_OVERRIDE
    {
        Q_UNUSED(eventType);
        Q_UNUSED(result);
        bps_event_t* const event = static_cast<bps_event_t*>(message);
        if (event && bps_event_get_domain(event)  navigator_get_domain()) {
            const int id = bps_event_get_code(event);
            if (id  NAVIGATOR_SWIPE_DOWN)
                qDebug() << "The user swiped down!";
        }
        return false; // Do not filter out the event
    }
};

Installing the event filter is easy:

MyEventFilter *filter = …;
QCoreApplication::eventDispatcher()->installNativeEventFilter(filter);

Afterwards, make sure BPS delivers navigator events to the current thread. For certain types of events, like navigator and virtual keyboard events, Qt will already have requested the events, but I can't hurt to request them twice:

navigator_request_events();

Other event types, such as mmrenderer events, are not automatically requested by Qt, there you have to call the appropriate foo_request_events() function yourself. Note that it is not necessary to call bps_initialize() yourself, Qt already does that for you. But again, it doesn't hurt either.