Receiving gesture events

To handle gesture events and thereby implement a touch UI, a MIDlet must be able to receive gesture events for its UI components. The MIDlet must separately set each UI component to receive gesture events.

The following figure shows the relationship between the Gesture API classes required for receiving gesture events.

Figure: Relationship between Gesture API classes

To receive gesture events:

1. Create the UI component. The component can be either a Canvas or CustomItem. The following code snippet creates a custom Canvas class called GestureCanvas.

   // import the necessary classes
   import com.nokia.mid.ui.gestures.GestureInteractiveZone;
   import com.nokia.mid.ui.gestures.GestureRegistrationManager;
   import javax.microedition.lcdui.Canvas;
   
   public class GestureCanvas extends Canvas {
   
       public GestureCanvas() {
   
           // register a GestureListener for GestureCanvas (see step 2 of this example)
   
           // register a GestureInteractiveZone for GestureCanvas (see step 3 of this example)
   
       } // end GestureCanvas()
   
       // create the Canvas UI by implementing the paint method and
       // other necessary methods (see the LCDUI instructions)
   
   } // end class GestureCanvas

2. Register a GestureListener for the UI component. The GestureListener notifies the MIDlet of gesture events associated with the UI component. Each UI component can only have one GestureListener registered for it. However, you can register the same GestureListener for multiple different UI components. The following code snippet registers a custom GestureListener called MyGestureListener for GestureCanvas.

   // create a listener instance
   MyGestureListener myGestureListener = new MyGestureListener();
   
   // set the listener to register events for GestureCanvas (this)
   GestureRegistrationManager.setListener(this, myGestureListener);

   For detailed information about the MyGestureListener implementation, see section Handling gesture events.

3. Register a GestureInteractiveZone for the UI component. The GestureInteractiveZone defines the touchable screen area, a rectangle-shaped interactive zone, from which the GestureListener receives gesture events for the UI component. The GestureInteractiveZone also defines which types of gesture events the listener receives from this area. To define which gesture events are received, use one of the following value constants when creating the GestureInteractiveZone instance. Each gesture event corresponds to a basic touch action.

   Table: Supported gesture events

   Value	Description
   GESTURE_ALL	Receive all gesture events.
   GESTURE_TAP	Receive taps.
   GESTURE_LONG_PRESS	Receive long taps.
   GESTURE_LONG_PRESS_REPEATED	Receive repeated long taps.
   GESTURE_DRAG	Receive drag events.
   GESTURE_DROP	Receive drop events.
   GESTURE_FLICK	Receive flicks.

   To change the set of gesture events received from the area, use the setGestures method after you create the GestureInteractiveZone instance.

   By default, the touchable screen area corresponds to the area taken up by the UI component. To define a different area, use the setRectangle method on the GestureInteractiveZone instance. The location of the area is defined relative to the upper left corner of the UI component.

   You can register a specific GestureInteractiveZone for only a single UI component. However, a UI component can have multiple different GestureInteractiveZones registered for it. This is useful, for example, when you create a Canvas with multiple Images and want to make each Image an independent interactive component. In this case, you register multiple GestureInteractiveZones for the Canvas, one for each Image, and set the touchable areas to match the areas taken up by the Images.

   GestureInteractiveZones can overlap. The GestureListener associated with each overlapping zone receives all gesture events for that zone.

   The following code snippet registers a single GestureInteractiveZone for GestureCanvas. The GestureInteractiveZone is set to receive taps and long taps, and its screen area is set to 40x20 pixels positioned in the upper left corner (0,0) of GestureCanvas.

   // create an interactive zone and set it to receive taps
   GestureInteractiveZone myGestureZone = new GestureInteractiveZone(GestureInteractiveZone.GESTURE_TAP);
   
   // set the interactive zone to also receive long taps
   myGestureZone.setGestures(GestureInteractiveZone.GESTURE_LONG_PRESS);
   
   // set the location (relative to the container) and size of the interactive zone:
   // x=0, y=0, width=40px, height=20px
   myGestureZone.setRectangle(0, 0, 40, 20);
   
   // register the interactive zone for GestureCanvas (this)
   GestureRegistrationManager.register(this, myGestureZone);

Now that you have created the UI component and set it to receive gesture events, define how it handles the gesture events by implementing the GestureListener class.