com.nokia.mid.ui.gestures
Class GestureInteractiveZone

java.lang.Object
  com.nokia.mid.ui.gestures.GestureInteractiveZone

public class GestureInteractiveZone
extends java.lang.Object

The GestureInteractiveZone class is used by an application to define an area of the screen that reacts to a set of specified gestures.

The application can register for one or more gestures, without specifying them individually. Once registered, all specified gesture events received on the container will be automatically routed to the GestureListener.

The gesture API supports the following events:

• GESTURE_TAP - Simple press and release.
• GESTURE_LONG_PRESS - Press and hold for long press interval followed by release.
• GESTURE_LONG_PRESS_REPEATED - Repeated long presses.
• GESTURE_DRAG - Press and move.
• GESTURE_DROP - Press and move followed by release. It is possible that a Flick gesture maybe recognised instead of the drop gesture.
• GESTURE_FLICK - Press and move followed by release. It is possible that a Drop gesture maybe returned if Flick gesture cannot be recognised.
• GESTURE_PINCH - Press for first finger, press for second finger and move for either finger. When either finger is released, move and hold for the remaining finger will be recognised as drag gesture.
• GESTURE_DOUBLE_TAP - Quickly tap the screen twice in the same location. Similar to double-click with the mouse.
• GESTURE_RECOGNITION_START - Virtual gesture for the initial state of the gesture recognition. Press always starts gesture recognition.
• GESTURE_RECOGNITION_END - Virtual gesture for the end state of the gesture recognition. Release always ends gesture recognition.

The application can either register for events for the whole canvas or can specify one or more rectangular zones within which it wants to receive events. To specify a rectangular zone the application must call setRectangle(int x, int y, int width, int height). Note: The application does not need to call setRectangle(int x, int y, int width, int height) if it wants to receive gesture events for the whole canvas.

The application is limited to the number of rectangular gesture zones that the application can define per container.

The platform supports the application defining overlapping gesture zones, in this case the registered listener for each zone will receive the gesture event.

When a rectangular gesture zone has been specified the application will only receive events where the touch event originated within the defined rectangular region. This is the case for all touch event types (tap, drag, drop and flick). E.g. If the user starts the drag inside the rectangle region and finishes outside the region then an event will be received. However, if the user starts a drag action outside the rectangular region and finishes within the region no event will be received.

There are two special cases for tap only type events.

If the application has registered for only the GESTURE_TAP type of event and a rectangular gesture zone has been specified then the tap gesture will only be received if the initial press and the release occur within the gesture zone. If the tap moves outside of the gesture zone at any time the gesture event will be still received as long as the release occurs back inside the gesture zone.

If the application has registered for only GESTURE_LONG_PRESS or GESTURE_LONG_PRESS_REPEATED type events and a rectangular gesture zone has been specified then the tap gestures will only be received if the initial press and the release occur within the gesture zone.If the tap moves outside of the gesture zone at any time the gesture recognition is ended and no gesture event will be received. If the application has registered for GESTURE_TAP type events at the same time as these events then the rules described in the previous paragraph still hold for the GESTURE_TAP event.

The application can use setRectangle(int x, int y, int width, int height) to change the size and location of an interactive gesture zone at any time. The API imposes the limitation that the zone will not be updated until the current gesture recognition has ended.

The application can modify the repeated long press interval at any time. The API imposes the limitation that the interval will not be updated until the current gesture recognition has ended.

The application can use GESTURE_RECOGNITION_START and GESTURE_RECOGNITION_END to keep track of state of the gesture recognition. These virtual gestures are generated once for each finger (press and release respectively). Application receives all registered and recognized gestures in between recognition start and recognition end virtual gestures.

Field Summary

static int	GESTURE_ALL Constant for All Gesture Events.
static int	GESTURE_DOUBLE_TAP Constant for the Double Tap Gesture.
static int	GESTURE_DRAG Constant for the Drag Gesture.
static int	GESTURE_DROP Constant for the Drop Gesture.
static int	GESTURE_FLICK Constant for the Flick Gesture.
static int	GESTURE_LONG_PRESS Constant for the Long Press Gesture.
static int	GESTURE_LONG_PRESS_REPEATED Constant for the Long Press Repeated Gesture.
static int	GESTURE_PINCH Constant for the Pinch Gesture.
static int	GESTURE_RECOGNITION_END Constant for the Gesture Recognition Ended.
static int	GESTURE_RECOGNITION_START Constant for the Gesture Recognition Started .
static int	GESTURE_TAP Constant for the Tap Gesture.

Constructor Summary

GestureInteractiveZone(int gestures)
Construct a new Gesture Interactive Zone.

GestureInteractiveZone(int gestures, int timeInterval)
Construct a new Gesture Interactive Zone.

Method Summary

int	getGestures() Query for the gestures associated with the gesture event registration.
int	getHeight() Query for the height of the gesture event rectangle in pixels.
int	getLongPressTimeInterval() Query for the long press gesture time interval in milliseconds.
int	getWidth() Query for the width of the gesture event rectangle in pixels.
int	getX() Query for the horizontal location of the gesture event rectangle.
int	getY() Query for the vertical location of the gesture event rectangle.
static boolean	isSupported(int gestureEventIdentity) Query if a specific gesture is supported by the platform.
void	setGestures(int gestures) Update the list of gestures that are detected for the interactive zone.
void	setLongPressTimeInterval(int timeInterval) Set the long press event time interval.
void	setRectangle(int x, int y, int width, int height) Defines the gesture event rectangle location and dimensions.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GESTURE_TAP

public static final int GESTURE_TAP

Constant for the Tap Gesture.

GESTURE_TAP has the value 0x1.

See Also:

Constant Field Values

GESTURE_LONG_PRESS

public static final int GESTURE_LONG_PRESS

Constant for the Long Press Gesture.

GESTURE_LONG_PRESS has the value 0x2.

See Also:

Constant Field Values

GESTURE_DRAG

public static final int GESTURE_DRAG

Constant for the Drag Gesture.

GESTURE_DRAG has the value 0x4.

See Also:

Constant Field Values

GESTURE_DROP

public static final int GESTURE_DROP

Constant for the Drop Gesture.

GESTURE_DROP has the value 0x8.

See Also:

Constant Field Values

GESTURE_FLICK

public static final int GESTURE_FLICK

Constant for the Flick Gesture.

GESTURE_FLICK has the value 0x10.

See Also:

Constant Field Values

GESTURE_LONG_PRESS_REPEATED

public static final int GESTURE_LONG_PRESS_REPEATED

Constant for the Long Press Repeated Gesture.

GESTURE_LONG_PRESS_REPEATED has the value 0x20.

See Also:

Constant Field Values

GESTURE_PINCH

public static final int GESTURE_PINCH

Constant for the Pinch Gesture.

GESTURE_PINCH has the value 0x40.

Since:

1.1

See Also:

Constant Field Values

GESTURE_DOUBLE_TAP

public static final int GESTURE_DOUBLE_TAP

Constant for the Double Tap Gesture.

GESTURE_TAP has the value 0x80.

See Also:

Constant Field Values

GESTURE_RECOGNITION_START

public static final int GESTURE_RECOGNITION_START

Constant for the Gesture Recognition Started .

GESTURE_RECOGNITION_START has the value 0x4000.

See Also:

Constant Field Values

GESTURE_RECOGNITION_END

public static final int GESTURE_RECOGNITION_END

Constant for the Gesture Recognition Ended.

GESTURE_RECOGNITION_END has the value 0x8000.

See Also:

Constant Field Values

GESTURE_ALL

public static final int GESTURE_ALL

Constant for All Gesture Events.

See Also:

Constant Field Values

Constructor Detail

GestureInteractiveZone

public GestureInteractiveZone(int gestures)

Construct a new Gesture Interactive Zone.

The MIDlet can register for more than one gesture event at a time.

Parameters:

gestures - - gesture events to receive.

Throws:

java.lang.IllegalArgumentException - - if gestures contains no defined gestures or only contains undefined gesture events.

GestureInteractiveZone

public GestureInteractiveZone(int gestures,
                              int timeInterval)

Construct a new Gesture Interactive Zone.

The MIDlet can register for more than one gesture event at a time.

Parameters:

gestures - - gesture events to receive.

timeInterval - - time interval in milliseconds for repeated long press events.

Throws:

java.lang.IllegalArgumentException - - if gestures contains no defined gestures or only contains undefined gesture events.

java.lang.IllegalArgumentException - - if time interval is less than 0.

Method Detail

setRectangle

public void setRectangle(int x,
                         int y,
                         int width,
                         int height)

Defines the gesture event rectangle location and dimensions.

The X and Y coordinate locations can be set to any values, however the rectangle will be clipped against the registered container.

Parameters:

x - - the horizontal location of the gesture event rectangle in pixels relative to the containers origin (the corner where x is smallest).

y - - the vertical location of the gesture event rectangle in pixels relative to the containers origin (the corner where y is smallest).

width - - the width of the gesture event rectangle in pixels.

height - - the height of the gesture event rectangle in pixels.

Throws:

java.lang.IllegalArgumentException - - if either the width or height is zero or less.

setLongPressTimeInterval

public void setLongPressTimeInterval(int timeInterval)

Set the long press event time interval.

Parameters:

timeInterval - - time interval in milliseconds for repeated long press gesture.

Throws:

java.lang.IllegalArgumentException - - if time interval is less than 0.

getGestures

public int getGestures()

Query for the gestures associated with the gesture event registration.

Returns:

gestures- this is the gestures accepted by the platform and there for may not match what the application originally specified.

setGestures

public void setGestures(int gestures)

Update the list of gestures that are detected for the interactive zone.

Parameters:

gestures - - gesture events to receive.

getX

public int getX()

Query for the horizontal location of the gesture event rectangle.

Returns:

horizontal location of the gesture event rectangle. 0 is returned if rectangle not set.

getY

public int getY()

Query for the vertical location of the gesture event rectangle.

Returns:

vertical location of the gesture event rectangle. 0 is returned if rectangle not set.

getWidth

public int getWidth()

Query for the width of the gesture event rectangle in pixels.

Returns:

width of the gesture event rectangle. 0 is returned if rectangle not set.

getHeight

public int getHeight()

Query for the height of the gesture event rectangle in pixels.

Returns:

height of the gesture event rectangle. 0 is returned if rectangle not set.

getLongPressTimeInterval

public int getLongPressTimeInterval()

Query for the long press gesture time interval in milliseconds.

Returns:

long press gesture time interval in milliseconds.

isSupported

public static boolean isSupported(int gestureEventIdentity)

Query if a specific gesture is supported by the platform.

Parameters:

gestureEventIdentity - - Gesture event identity to check for platform support.

Returns:

true if gesture is supported, else false.