Handling gesture events

To handle gesture events for a UI component set to receive them, the MIDlet must implement the GestureListener class. You can define multiple GestureListeners for a MIDlet.

To handle gesture events:

1. Create a new listener class that implements GestureListener. The following code snippet creates the framework for the MyGestureListener custom class.

   // import the necessary classes
   import com.nokia.mid.ui.gestures.GestureEvent;
   import com.nokia.mid.ui.gestures.GestureInteractiveZone;
   import com.nokia.mid.ui.gestures.GestureListener;
   
   public class MyGestureListener implements GestureListener {
   
       // implement gestureAction (see step 2 of this example)
   
   } // end class MyGestureListener

2. Define the gestureAction method for the class. This method is called every time a gesture event occurs for a UI component that uses MyGestureListener. The method is called with all the information related to the gesture event. The following code snippet creates the framework for a gestureAction implementation.

   public void gestureAction(Object container,
                             GestureInteractiveZone gestureInteractiveZone,
                             GestureEvent gestureEvent) {
   
       // handle received gesture events (see step 3 of this example)
   
   } // end gestureAction()

   The gestureAction method is called with the following parameters detailing the gesture event:

   Table: gestureAction parameters

   Parameter	Description	Type
   container	The UI component for which the gesture event occurred. This is either a Canvas or CustomItem instance.	Object
   gestureInteractiveZone	The GestureInteractiveZone instance in which the gesture event occurred. This is one of the interactive zones registered for the UI component specified in container.	GestureInteractiveZone
   gestureEvent	The gesture event that occurred for container in gestureInteractiveZone. The GestureEvent object provides a number of methods for retrieving data about the gesture event. Each type of gesture event supports a specific subset of methods. To retrieve the type of the current gesture event, use the getType method: int gestureEventType = gestureEvent.getType(); The method returns one of the gesture event constants defined in the GestureInteractiveZone class. For more information about the methods supported for each type, see the following table.	GestureEvent

3. Handle the gesture events returned by the gestureAction method. Use the GestureEvent.getType method to determine the gesture event type and then call the appropriate methods to retrieve the event details (see the following table). You can handle the gesture events either directly in the gestureAction method, or you can use the gestureAction method to call separately defined handler methods or classes. For information about optimizing the gestureAction method for performance, see Using the gestureAction method correctly.

   Table: Supported GestureEvent methods per gesture event type

   Gesture event type	Supported methods	Description
   GESTURE_TAP GESTURE_LONG_PRESS GESTURE_LONG_PRESS_REPEATED	getType getStartX getStartY	The getStartX and getStartY methods return the coordinates (x pixels, y pixels) where the gesture occurred. The coordinates are relative to the top left corner (0,0) of the UI component.
   GESTURE_DRAG GESTURE_DROP	getType getStartX getStartY getDragDistanceX getDragDistanceY	The getStartX and getStartY methods return the coordinates (x pixels, y pixels) where the associated drag gesture started, that is, where the initial touch down event occurred. Therefore, the GESTURE_DRAG events registered for a given drag gesture always return the same coordinates. The coordinates are relative to the top left corner (0,0) of the UI component. For a GESTURE_DRAG event, the getDragDistanceX and getDragDistanceY methods return the number of pixels moved horizontally (x-axis) and vertically (y-axis) since the previous GESTURE_DRAG event or, if the event is the first GESTURE_DRAG event for the gesture, since the initial touch down event that started the gesture. For a GESTURE_DROP event, the getDragDistanceX and getDragDistanceY methods always return 0.
   GESTURE_FLICK	getType getStartX getStartY getFlickDirection getFlickSpeed getFlickSpeedX getFlickSpeedY	The getStartX and getStartY methods return the coordinates (x pixels, y pixels) where the flick gesture started. The coordinates are relative to the top left corner (0,0) of the UI component. The getFlickDirection method returns the direction of the flick gesture in radians. The value can range from -π radians to π radians. 0 indicates a direction to the right along the x-axis, while -π and π indicate a direction to the left along the x-axis. The getFlickSpeed method returns the flick speed in pixels per second in the flick direction. The getFlickSpeedX and getFlickSpeedY methods return the horizontal (x-axis) and vertical (y-axis) flick speeds in pixels per second, respectively.

   The following code snippet handles received gesture events by first determining their type and then calling the corresponding getter methods to store the event details in local variables. In this example, the GestureInteractiveZone only receives taps and long taps, so GESTURE_TAP and GESTURE_LONG_PRESS are the only gesture events that need handling.

   // retrieve the tap or long tap details and store them
   switch (gestureEvent.getType()) {
       case GestureInteractiveZone.GESTURE_TAP:
       case GestureInteractiveZone.GESTURE_LONG_PRESS:
           try {
               int startLocationX = gestureEvent.getStartX();
               int startLocationY = gestureEvent.getStartY();
           } catch (IllegalStateException e) {
               ;
           }
           break;
   }