Responding to touch events

How to

Respond to touch, move, and release events on the screen of the BlackBerry PlayBook tablet.

Solution

screen_context_t screen_cxt;
screen_create_context(&screen_cxt, 0);

bps_initialize();

screen_request_events(screen_cxt);   // Pass in the screen context that
                                     // you created

while (!shutdown) {
    bps_event_t *event = NULL;
    bps_get_event(&event, 0);        // 0 means that the function 
                                     // doesn't wait for an event
                                     // before returning (polling)

    if (event) {
        if (bps_event_get_domain(event) == screen_get_domain()) {
            int screen_val;

            screen_event_t screen_event = screen_event_get_event(event);

            screen_get_event_property_iv(screen_event,
                                             SCREEN_PROPERTY_TYPE,
                                             &screen_val);

            if (screen_val == SCREEN_EVENT_MTOUCH_TOUCH) {
                // Handle an initial finger press event here
            } else if (screen_val == SCREEN_EVENT_MTOUCH_MOVE) {
                // Handle a finger move event here
            } else if (screen_val == SCREEN_EVENT_MTOUCH_RELEASE) {
                // Handle a finger release event here
        }
    }
}

Build requirements

You must include the following header files from the BlackBerry Platform Services (BPS) library:

#include <bps/bps.h>
#include <bps/screen.h>

Discussion

The primary input method on the tablet is the touch screen, so most of the applications that you create will need to respond to touch events in some way. You use a combination of the screen library functions and BlackBerry Platform Services functions to request and handle these events.

First, you must create a screen context for the screen of the tablet by calling screen_create_context(). This context is associated with the libscreen library, and allows your application to receive screen events. You also use this context to draw on the screen, but this solution doesn't implement any screen drawing functionality. For that, you'd need to initialize EGL to use the context. For more information about how to do this, read the Create an OpenGL window tutorial.

Next, you need to initialize the BlackBerry Platform Services library by calling bps_initialize(). You can then call screen_request_events() to start receiving screen events, passing in the screen context that you created. It's important to note that you can request events only for a single screen context at a time.

After your application is registered to receive screen events, you can call bps_get_event() to retrieve the next available event from the library. You can use an event loop with a simple exit condition to process events continuously while your application is running. After an event is received, you should determine whether it's a screen event by calling bps_event_get_domain() and screen_get_domain().

When you know you've got a screen event, you should extract the specific event from the generic BlackBerry Platform Services event by calling screen_event_get_event(). This step is important because it allows you to query the libscreen event for various properties. The property that you need for detecting a touch event is SCREEN_PROPERTY_TYPE, and you can call screen_get_event_property_iv() to get the value of that property. After you store the value, you can test to see if it's the start of a touch event (represented by SCREEN_EVENT_MTOUCH_TOUCH) and handle the touch event accordingly. If you want to know whether the event corresponds to the user moving a finger on the screen or releasing a finger from the screen, you could test the retrieved property value against SCREEN_EVENT_MTOUCH_MOVE or SCREEN_EVENT_MTOUCH_RELEASE, respectively.

Nice to know

The libscreen library describes other properties of screen events that you can use in your applications. For example, you can call screen_get_event_property_iv() with the SCREEN_PROPERTY_SOURCE_POSITION argument to get the position on the screen where a touch event occurred. You can also call screen_get_event_property_iv() with the SCREEN_PROPERTY_BUTTONS argument to determine whether the user pressed a mouse button. This is useful if you want your application to work properly if it's running on the BlackBerry Tablet Simulator or if the user is using a USB mouse that's connected to the tablet. For more information about how to respond to mouse button events, read the Create the Falling Blocks application tutorial.