Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Navigation events

Respond to navigation events

You can use the Screen navigation methods to create a BlackBerry device application. If your existing BlackBerry device application implements the TrackwheelListener interface, update your BlackBerry device application to use the Screen navigation methods.

  1. Import the net.rim.device.api.ui.Screen class.

  2. Manage navigation events by extending the net.rim.device.api.ui.Screen class (or one of its subclasses) and overriding the following navigation methods:

    navigationClick(int status, int time)
    navigationUnclick(int status, int time)
    navigationMovement(int dx, int dy, int status, int time)

Determine the type of input method

  1. Import one or more of the following classes:

    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.Field
  2. Import the net.rim.device.api.system.KeypadListener interface.

  3. Implement the net.rim.device.api.system.KeypadListener interface.

  4. Extend the Screen class, the Field class, or both.

  5. In your implementation of one of the navigationClick, navigationUnclick, or navigationMovement methods, perform a bitwise AND operation on the status parameter to yield more information about the event. Implement the navigationClick(int status, int time) method to determine if the trackwheel or a four way navigation input device (for example, a trackball) triggers an event.

    public boolean navigationClick(int status, int time) {
       if ((status & KeypadListener.STATUS_TRACKWHEEL) == KeypadListener.STATUS_TRACKWHEEL) {
          //Input came from the trackwheel
       } else if 
         ((status & KeypadListener.STATUS_FOUR_WAY) == KeypadListener.STATUS_FOUR_WAY) {
          //Input came from a four way navigation input device 
       }
       return super.navigationClick(status, time);
    }

Touch screen interaction models

BlackBerry devices with a touch screen and a trackpad use a forceless click interaction model, where a BlackBerry device user taps the screen or uses the trackpad to perform an action. This model differs from BlackBerry devices with a SurePress touch screen, where the user clicks (or presses) the screen to perform an action.

On both types of devices, when the user touches the screen, a TouchEvent.DOWN event occurs.

On devices with a SurePress touch screen, when the user applies pressure and clicks the screen, a TouchEvent.CLICK event occurs. When the pressure is lessened, a TouchEvent.UNCLICK event occurs. Typically, actions (such as invoking an action based on a button) occur on the TouchEvent.UNCLICK event. When the user releases the screen completely, a TouchEvent.UP event occurs.

On devices with a touch screen that supports forceless clicks, there is no physical clicking and unclicking. Instead, actions are expected to occur when the user taps the screen. A tap is a TouchEvent.DOWN event followed quickly by a TouchEvent.UP event. This combination of touch events is referred to as a gesture, and therefore a TouchGesture occurs. In the case of a tap, a TouchGesture.TAP event occurs (along with the TouchEvent.DOWN and TouchEvent.UP event).

For greater compatibility between the two types of touch screen interaction models, on devices that support forceless clicks, the TouchEvent.CLICK event and TouchEvent.UNCLICK event occur after the TouchGesture.TAP event, so you can invoke an action on the TouchEvent.UNCLICK event on all touch screen devices, whether the device has a SurePress touch screen or not.

User action

Devices that support a forceless click

Devices with a SurePress touch screen

Touch the screen.

TouchEvent.DOWN

TouchEvent.DOWN

Touch and hold a finger on an item.

TouchGesture.HOVER

TouchGesture.HOVER

Click the screen.

TouchEvent.CLICK

Click and hold the screen.

TouchEvent.CLICK_REPEAT

Release the screen.

TouchEvent.UNCLICK

Remove a finger from the screen.

TouchEvent.UP

TouchEvent.UP

Tap the screen.

TouchEvent.DOWN

TouchGesture.TAP

TouchEvent.CLICK

TouchEvent.UNCLICK

TouchEvent.UP

TouchEvent.DOWN

TouchGesture.TAP

TouchEvent.UP

You can determine whether a device with a touch screen supports forceless clicks by invoking DeviceCapability.isTouchClickSupported(). If the device supports forceless clicks, the method returns false. If the device has a SurePress touch screen, the method returns true.

Responding to touch screen events

BlackBerry device users can perform the same actions on a device with a touch screen as they can on a BlackBerry device with a trackball. For example, BlackBerry device users can use the touch screen to open a menu, scroll through a list of options, and select an option.

If you use a version of the BlackBerry Java Development Environment earlier than version 4.7 to create a BlackBerry device application, you can alter the .jad file of the application to enable the application to respond when a BlackBerry device user touches the touch screen. In the .jad file, you would set the RIM-TouchCompatibilityMode option to false.

If you use BlackBerry JDE version 4.7 or later to create a BlackBerry device application, you can enable the application to identify the action the BlackBerry device user performs on the touch screen by extending the net.rim.device.api.ui.Screen class, the net.rim.device.api.ui.Field class, or one of the subclasses of the Field class and overriding the touchEvent() method. Within the touchEvent() method, compare the value that TouchEvent.getEvent() returns to the constants from the net.rim.device.api.ui.TouchEvent class and the net.rim.device.api.ui.TouchGesture class.

The TouchEvent class contains the constants that represent the different actions that a user can perform on the touch screen. For example, the click, touch, and move actions correspond to the TouchEvent.CLICK, TouchEvent.DOWN, and TouchEvent.MOVE constants.

The TouchGesture class contains the constants that represent the different gestures that a user can perform on a touch screen. For example, the tap and swipe gestures correspond to the TouchGesture.TAP and TouchGesture.SWIPE constants.

Code sample: Identifying the action a user performs on the touch screen

The following code sample uses a switch statement to identify the action.

protected boolean touchEvent(TouchEvent message) {
switch(message.getEvent()) {
    case TouchEvent.CLICK:
    Dialog.alert("A click action occurred");
    return true;

case TouchEvent.DOWN:
    Dialog.alert("A down action occurred");
    return true;

case TouchEvent.MOVE:
    Dialog.alert("A move action occurred");
    return true;
}

return false;
}

Respond to system events while the user touches the screen

  1. Import the following classes:

    • net.rim.device.api.ui.TouchEvent
    • net.rim.device.api.ui.Field
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.component.Dialog
  2. Create a class that extends the Manager class, the Screen class, the Field class, or one of the Field subclasses.

    public class newButtonField extends ButtonField {
  3. In your implementation of the touchEvent(TouchEvent message) method, invoke TouchEvent.getEvent().

  4. Check if the value that TouchEvent.getEvent() returns is equal to TouchEvent.CANCEL.

    protected boolean touchEvent(TouchEvent message) {
    switch(message.getEvent()) {
      case TouchEvent.CANCEL:
       Dialog.alert("System event occurred while processing touch events");
        return true;
       }
     return false;                 
    }

Respond to a user sliding a finger up quickly on the screen

  1. Import the following classes:

    • net.rim.device.api.ui.TouchEvent
    • net.rim.device.api.ui.TouchGesture
    • net.rim.device.api.ui.Field
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.component.Dialog
  2. Create a class that extends the Manager class, the Screen class, the Field class, or one of the Field subclasses.

    public class newButtonField extends ButtonField {
  3. In your implementation of the touchEvent(TouchEvent message) method, invoke TouchEvent.getEvent().

  4. Check if the value that TouchGesture.getSwipeDirection() returns is equal to TouchGesture.SWIPE_NORTH.

    protected boolean touchEvent(TouchEvent message) {
       switch(message.getEvent()) {
          case TouchEvent.GESTURE:
             TouchGesture gesture = message.getGesture();
             switch(gesture.getEvent()) {
                case TouchGesture.SWIPE:
                   if(gesture.getSwipeDirection() == TouchGesture.SWIPE_NORTH) {
                      Dialog.alert("Upward swipe occurred");
                      return true;
                   }
             }
             return false;
       }  
    }

Respond to a user sliding a finger down quickly on the screen

  1. Import the following classes:

    • net.rim.device.api.ui.TouchEvent
    • net.rim.device.api.ui.TouchGesture
    • net.rim.device.api.ui.Field
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.component.Dialog
  2. Create a class that extends the Manager class, the Screen class, the Field class, or one of the Field subclasses.

    public class newButtonField extends ButtonField {
  3. In your implementation of the touchEvent(TouchEvent message) method, invoke TouchEvent.getEvent().

  4. Check if the value that TouchGesture.getSwipeDirection() returns is equal to TouchGesture.SWIPE_SOUTH.

    protected boolean touchEvent(TouchEvent message) {
       switch(message.getEvent()) {
       case TouchEvent.GESTURE:
          TouchGesture gesture = message.getGesture();
          switch(gesture.getEvent()) {
             case TouchGesture.SWIPE:
                if(gesture.getSwipeDirection() == TouchGesture.SWIPE_SOUTH) {
                   Dialog.alert("Downward swipe occurred");
                   return true;
                }
          }
          return false;
       }  
    }

Respond to a user sliding a finger to the left quickly on the screen

  1. Import the following classes:

    • net.rim.device.api.ui.TouchEvent
    • net.rim.device.api.ui.TouchGesture
    • net.rim.device.api.ui.Field
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.component.Dialog
  2. Create a class that extends the Manager class, the Screen class, the Field class, or one of the Field subclasses.

    public class newButtonField extends ButtonField {
  3. In your implementation of the touchEvent(TouchEvent message) method, invoke TouchEvent.getEvent().

  4. Check if the value that TouchGesture.getSwipeDirection() returns is equal to TouchGesture.SWIPE_EAST.

    protected boolean touchEvent(TouchEvent message) {
       switch(message.getEvent()) {
          case TouchEvent.GESTURE:
             TouchGesture gesture = message.getGesture();
             switch(gesture.getEvent()) {
                case TouchGesture.SWIPE:
                   if(gesture.getSwipeDirection() == TouchGesture.SWIPE_EAST) {
                      Dialog.alert("Eastward swipe occurred");
                      return true;
                   } 
             }
             return false;
       }  
    }  

Respond to a user sliding a finger to the right quickly on the screen

  1. Import the following classes:

    • net.rim.device.api.ui.TouchEvent
    • net.rim.device.api.ui.TouchGesture
    • net.rim.device.api.ui.Field
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.component.Dialog
  2. Create a class that extends the Manager class, the Screen class, the Field class, or one of the Field subclasses.

    public class newButtonField extends ButtonField {
  3. In your implementation of the touchEvent(TouchEvent message) method, invoke TouchEvent.getEvent().

  4. Check if the value that TouchGesture.getSwipeDirection() returns is equal to TouchGesture.SWIPE_WEST.

    protected boolean touchEvent(TouchEvent message) {
       switch(message.getEvent()) {
          case TouchEvent.GESTURE:
             TouchGesture gesture = message.getGesture();
             switch(gesture.getEvent()) { 
                case TouchGesture.SWIPE:
                   if(gesture.getSwipeDirection() == TouchGesture.SWIPE_WEST) {
                      Dialog.alert("Westward swipe occurred");
                      return true;
                   }
             }
             return false;
       }  
    }

Respond to a user clicking the screen

  1. Import the following classes:

    • net.rim.device.api.ui.TouchEvent
    • net.rim.device.api.ui.Field
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.component.Dialog
  2. Create a class that extends the Manager class, the Screen class, the Field class, or one of the Field subclasses.

    public class newButtonField extends ButtonField {
  3. In your implementation of the touchEvent(TouchEvent message) method, invoke TouchEvent.getEvent().

  4. Check if the value that TouchEvent.getEvent() returns is equal to TouchEvent.CLICK.

    protected boolean touchEvent(TouchEvent message) {
       switch(message.getEvent()) {
          case TouchEvent.CLICK:
             Dialog.alert("CLICK occurred");
             return true;
       }
       return false; 
    } 

Respond to a user touching the screen twice quickly

  1. Import the following classes:

    • net.rim.device.api.ui.TouchEvent
    • net.rim.device.api.ui.TouchGesture
    • net.rim.device.api.ui.Field
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.component.Dialog
  2. Create a class that extends the Manager class, the Screen class, the Field class, or one of the Field subclasses.

    public class newButtonField extends ButtonField {
  3. In your implementation of the touchEvent(TouchEvent message) method, check for the occurrence of a TouchGesture.TAP event and that TouchGesture.getTapCount returns 2.

    protected boolean touchEvent(TouchEvent message) {
       switch(message.getEvent()) {
          case TouchEvent.GESTURE:
             TouchGesture gesture = message.getGesture();
             switch(gesture.getEvent()) {
                case TouchGesture.TAP:
                   if(gesture.getTapCount() == 2) {
                      Dialog.alert("Double tap occurred");
                      return true;
                   }
              }
       }
     return false;
    }   

Respond to a user touching and dragging an item on the screen

  1. Import the following classes:

    • net.rim.device.api.ui.TouchEvent
    • net.rim.device.api.ui.Field
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.component.Dialog
  2. Create a class that extends the Manager class, the Screen class, the Field class, or one of the Field subclasses.

    public class newButtonField extends ButtonField {
  3. In your implementation of the touchEvent(TouchEvent message) method, invoke TouchEvent.getEvent().

  4. Check if the value that TouchEvent.getEvent() returns is equal to TouchEvent.MOVE.

    protected boolean touchEvent(TouchEvent message) {
       switch(message.getEvent()) {
          case TouchEvent.MOVE:
             Dialog.alert("Move event occurred");
             return true;
       }
       return false;
    }  
    

Respond to a user touching the screen lightly

  1. Import the following classes:

    • net.rim.device.api.ui.TouchEvent
    • net.rim.device.api.ui.TouchGesture
    • net.rim.device.api.ui.Field
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.component.Dialog
  2. Create a class that extends the Manager class, the Screen class, the Field class, or one of the Field subclasses.

    public class newButtonField extends ButtonField {
  3. In your implementation of the touchEvent(TouchEvent message) method, invoke TouchEvent.getEvent().

  4. Check if the value that TouchEvent.getEvent() returns is equal to TouchEvent.DOWN.

    protected boolean touchEvent(TouchEvent message) {
       switch(message.getEvent()) {
          case TouchEvent.DOWN:
             Dialog.alert("Touch occurred");
             return true;
       }
       return false;
    } 

Respond to a scroll action

  1. Import the following classes:

    • net.rim.device.api.ui.TouchEvent
    • net.rim.device.api.ui.TouchGesture
    • net.rim.device.api.ui.Field
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.Screen
  2. Create a class that extends the Manager class.

     public class newManager extends Manager {
  3. In your implementation of the touchEvent(TouchEvent message) method, check if the value TouchEvent.getEvent() returns is equal to TouchEvent.MOVE.

    protected boolean touchEvent(TouchEvent message) {
       switch(message.getEvent()) {
          case TouchEvent.MOVE:
          return true;
       }
       return false;
    }

Respond to a user touching the screen in two locations at the same time

  1. Import the following classes:

    • net.rim.device.api.ui.TouchEvent
    • net.rim.device.api.ui.Field
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.component.Dialog
  2. Create a class that extends the Manager class, the Screen class, the Field class, or one of the Field subclasses.

    public class newButtonField extends ButtonField {
  3. In your implementation of the touchEvent(TouchEvent message) method, check if the following method invocations return values greater than zero: TouchEvent.getX(1), TouchEvent.getY(1), TouchEvent.getX(2), TouchEvent.getY(2).

    protected boolean touchEvent(TouchEvent message) {
       switch(message.getEvent()) {
       case TouchEvent.MOVE:
          if(message.getX(1) > 0 && message.getY(1) > 0) {
             Dialog.alert("First finger touched/moved");
          }
          if(message.getX(2) > 0 && message.getY(2) > 0) {
             Dialog.alert("Second finger touched/moved");
          }
          return true;
       }
       return false;
    }

Pinch gestures

BlackBerry devices with a touch screen support pinch gestures. Pinch gestures typically zoom in and out of an object on the screen.

A pinch begins when two touch points are detected on the touch screen. A pinch’s focal point is defined as the midpoint between the two initial touch points.

  • When two touch points are detected, a TouchGesture.PINCH_BEGIN event occurs. The coordinate points of the focal point of the pinch gesture are stored as TouchEvent.getX(1) and TouchEvent.getY(1). You can access the initial zoom value by invoking TouchGesture.getPinchMagnitude().

  • As the user moves one or both touch points, a series of TouchGesture.PINCH_UPDATE events occur. You can access the zoom values during the pinch by invoking TouchGesture.getPinchMagnitude().

  • When the user completes the gesture, a TouchGesture.PINCH_END event occurs. You can access the final zoom value by invoking TouchGesture.getPinchMagnitude().

Code sample: Retrieving information about a pinch gesture

protected boolean touchEvent(TouchEvent message) 
{
   switch(message.getEvent()) 
   {
      case TouchEvent.GESTURE:
         TouchGesture gesture = message.getGesture();
         switch(gesture.getEvent()) 
         {
           case TouchGesture.PINCH_END:
             Dialog.alert("Focal point: " + message.getX(1) 
             +            ", " + message.getY(1)
             +            "\nFinal zoom value: " + gesture.getPinchMagnitude());
             return true;
         }
   }
   return false;
}

Enable pinch gestures

By default, pinch gestures are not enabled on a screen in a BlackBerry device application. You must set a screen property to enable the generation of pinch gestures on a screen.

  1. Import the required classes and interfaces.

    import net.rim.device.api.ui.*;
    import net.rim.device.api.ui.container.*;
    import net.rim.device.api.ui.input.*;
  2. In your screen object, create an InputSettings object to populate with touch screen properties.

    InputSettings ts = TouchscreenSettings.createEmptySet();
  3. Set the TouchscreenSettings.DETECT_PINCH property to 1.

    ts.set(TouchscreenSettings.DETECT_PINCH, 1);
  4. Invoke Screen.addInputSettings() to add the input settings to the screen.

    addInputSettings(ts);

    You can change the value of the TouchscreenSettings.DETECT_PINCH property at any time, not just when you create the screen.

Code sample

This sample demonstrates how to enable pinch gestures in a screen's constructor.

public MyScreen()
{          
   setTitle("Sample Screen");
            
   InputSettings ts = TouchscreenSettings.createEmptySet();
   ts.set(TouchscreenSettings.DETECT_PINCH, 1);
   addInputSettings(ts); 

   ...                
}

Swipe gestures with trackpads

Similar to BlackBerry devices with a touch screen, devices with a trackpad support swipe gestures that BlackBerry device users make on the trackpad.

A TouchEvent object with the event type TouchGesture.NAVIGATION_SWIPE is generated when the user swipes across the trackpad. You can retrieve information about the trackpad swipe by using the following methods:

Code sample: Retrieving information about a trackpad swipe

This sample demonstrates how to handle a trackpad swipe in a screen's touchEvent() method.

protected boolean touchEvent(TouchEvent message) 
{
   switch(message.getEvent()) 
   {
      case TouchEvent.GESTURE:
         TouchGesture gesture = message.getGesture();
         switch(gesture.getEvent()) 
         {
           case TouchGesture.NAVIGATION_SWIPE:
             Dialog.alert("Swipe direction: " + gesture.getSwipeDirection()  
             +            ", "
             +            "\nMagnitude: " + gesture.getSwipeMagnitude());
             return true;
         }
   }
   return false;
}

Enable swipe gestures that users make on the trackpad

By default, swipe gestures that BlackBerry device users make on the trackpad are not enabled on a screen. You must set a navigation property to enable the generation of trackpad swipe gestures on a screen.

  1. Import the required classes and interfaces.

    import net.rim.device.api.ui.*;
    import net.rim.device.api.ui.container.*;
    import net.rim.device.api.ui.input.*;
  2. In your screen object, create an InputSettings object to populate with navigation properties.

    InputSettings nd = NavigationDeviceSettings.createEmptySet();
  3. Set the NavigationDeviceSettings.DETECT_SWIPE property to 1.

    nd.set(NavigationDeviceSettings.DETECT_SWIPE, 1);
  4. Invoke Screen.addInputSettings() to add the input settings to the screen.

    addInputSettings(nd);

    You can change the value of the NavigationDeviceSettings.DETECT_SWIPE property at any time, not just when you create the screen.

Code sample

This sample demonstrates how to enable trackpad swipe gestures in a screen's constructor.
public MyScreen()
{          
   setTitle("Sample Screen");
            
   InputSettings nd = NavigationDeviceSettings.createEmptySet();
   nd.set(NavigationDeviceSettings.DETECT_SWIPE, 1);
   addInputSettings(nd); 

   ...                
}

Event injection

You can generate UI events programmatically by using the EventInjector class and its inner classes. On BlackBerry devices that run BlackBerry Device Software version 5.0 or later and have touch screens, you can inject touch events such as swipes and taps. You can use one of the EventInjector inner classes to model an event and you can use the invokeEvent() method to inject the event. The event is sent to the application that is currently selected and ready to accept input.

You can use event injection to automate testing. You can also use event injection to provide a way for peripherals to interact with a BlackBerry device. You can also use it in accessible applications such as speech-to-text converters. For a sample application that demonstrates event injection, visit www.blackberry.com/go/toucheventinjectorsampleapp to download the Touch Event Injector sample application. For more information about the sample application, visit www.blackberry.com/go/docs/developers to read the Touch Event Injector Sample Application Overview.