RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Developing Touch-Enabled Applications with the Blackberry Touch API : Page 2

Learn all the major touch programming features supported through the BlackBerry JDE API. Along the way, you will see Java code snippets that demonstrate how to program these features.


Introducing Touch Programming for Blackberry

Three concepts constitute the foundation of Blackberry's touch-oriented programming: taps, gestures, and the virtual keyboard. These concepts translate into programmable functions on Blackberry platforms. Touch-enabled devices running the Blackberry SDK recognize taps as light touches, double taps, press-holds, press-and-drags, and multi-touches (i.e., simultaneously touching two UI items). They recognize gestures as movements of one or more contacts (i.e., fingers) across the UI and in the four designated directions: NORTH, EAST, WEST, and SOUTH. The nature of the motion is represented as a swipe or a move along taps or clicks.

The virtual keyboard is a built-in UI component (an instance of the net.rim.device.api.ui.VirtualKeyboard class) that the Blackberry device automatically displays when the user enters the input field UI component. Alternatively, you can programmatically display the virtual keyboard by retrieving the virtual keyboard singleton from the screen and executing the show method on the instance.

VirtualKeyboard keyboard;
MainScreen screen = new MainScreen( MainScreen.VERTICAL_SCROLL );
keyboard = screen.getVirtualKeyboard();
keyboard.setVisibility( VirtualKeyboard.SHOW );

The following groups of commands are modeled as constants in the net.rim.device.api.ui package of the TouchEvent and TouchGesture classes.

  • Tapping and dragging gestures are recognized as two distinct groups of Touch events.
  • Taps and clicks are simple inputs compatible with more conventional command-button or trackball clicks.
  • Touch gestures are commands for reorganizing the screen, dragging items, and scrolling.

Devices that run off the Blackberry SDK 4.7+ and are touch enabled by default can support touch functionality even for applications that were not initially developed for touch. Using the auto-activated virtual keyboard, the SDK automatically handles events such as clicking, scrolling, and entering text into edit fields through taps, gestures, or entries.

These functions are limited to only a few very basic behaviors, however. Developers must develop their own handlers in custom code for more advanced and specialized user interface (UI) interactions.

Author's Note: The layout of the virtual keyboard depends on the orientation of the screen. The landscape mode shows the virtual keyboard in full QWERTY display. The portrait mode shows the virtual keyboard in an abbreviated display, where two characters are placed in one field so the actual value of the user's key selection is retrieved by counting the number of times that key is clicked.

In addition to allowing you to control the appearance and layout of the keyboard, the Blackberry SDK also supports programmatic control of the spellchecking events. This feature is beyond the scope of this article, but if you are interested in programming for the virtual keyboard spellchecker, check the classes and supported events within the net.rim.blackberry.api.spellcheck package.

Programming for Touch Events

The key to programming touch functionality is handling the supported touch events properly. This section details what these events are and how you can translate them into programs that enable custom touch functionality.

The following are the necessary steps for handling touch events:

  1. Extend one of the classes—Manager, Screen, Field, or some of the Field's subclasses (depending on the scope of the event handling)—and override the method-protected Boolean touchEvent (TouchEvent event).
    private class NameField extends Field {
       protected boolean touchEvent( TouchEvent event ) {
       }// end method
    }//end class
  2. Determine the type of touch by interrogating the instance of the net.rim.device.api.ui.TouchEvent class.
    // handle touch event
    protected boolean touchEvent( TouchEvent event ) {
    int eventCode = event.getEvent();
    if ( eventCode == TouchEvent.CLICK ) {
         //Handle click event here
    If ( eventCode == TouchEvent.MOVE ) {
        //Handle move event here
    In addition to the demonstrated TouchEvent, other common touch event types include TouchEvent.DOWN for light touch, TouchEvent.TAP for tapping, TouchEvent.SWIPE for the swiping gesture, TouchEvent.CLICK for pressing, and TouchEvent.HOVER for press and hold. (Refer to the Blackberry API documentation for a list of all supported event types.)
  3. When you invoke the touchEvent function, determine the event type by examining the type property and comparing it with the TouchEvent constants.
    protected boolean touchEvent( TouchEvent event ) {
    switch( event.getEvent()  ) {
    case TouchEvent.CLICK:
       //handle click event here
       return true;
    case TouchEvent.DOWN:
       //handle down event here 
       return true;
    case TouchEvent.MOVE:
       ///handle move event here
       return true;
    return false;
    }//end method

The example above demonstrates the essence of all the touch-event processing within the Blackberry SDK. Any differences are related to the specifics of sub-event recognition, such as for Gestures, and to the additional properties related to these subclasses.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date