net.rim.device.api.ui
Class TouchGesture

java.lang.Object
  extended by net.rim.device.api.ui.TouchGesture

public abstract class TouchGesture
extends Object

TouchGesture contains a set of basic touch input events originating from the user. TouchGesture events are acquired using TouchEvent.getGesture() when a gesture is detected. TouchGesture currently defines four common gestures: TouchGesture.CLICK_REPEAT, TouchGesture.HOVER, TouchGesture.SWIPE, and TouchGesture.TAP. TouchGesture objects are immutable, and can be cached.

Since:
BlackBerry API 4.7.0

Field Summary
static int CLICK_REPEAT
          Click and pause at a specific point on the touch screen for more than 500 milliseconds.
static int DOUBLE_TAP
          Two consecutive quick touch and release gesture on the touch screen.
static int HOVER
          Touch and pause at a specific point on the touch screen for more than the user-defined number of milliseconds (configurable setting found in Screen/Keyboard Options).
static int SWIPE
          Quick motion gesture across the touch screen.
static int SWIPE_EAST
          Gesture direction equivalent that is to 0 degrees +/- 45 degrees relative to the device's current upward direction.
static int SWIPE_NORTH
          Gesture direction that is equivalent to 90 degrees +/- 45 degrees relative to the device's current upward direction.
static int SWIPE_SOUTH
          Gesture direction that is equivalent to 270 degrees +/- 45 degrees relative to the device's current upward direction.
static int SWIPE_WEST
          Gesture direction that is equivalent to 180 degrees +/- 45 degrees relative to the device's current upward direction.
static int TAP
          Quick touch and release gesture on the touch screen.
 
Method Summary
 int getClickRepeatCount()
          Retrieves the number of TouchGesture.CLICK_REPEAT events generated before the user moves or releases from the touch screen.
abstract  int getEvent()
          Retrieves the event code associated with this touch gesture.
 int getHoverCount()
          Retrieves the number of TouchGesture.HOVER events generated before the user moves or removes touch from the touch screen.
 int getSwipeAngle()
          Retrieves the angle (in degrees) associated with a swipe gesture relative to the device's current upward direction.
 int getSwipeDirection()
          Retrieves the relative cardinal direction associated with a swipe gesture based on the device's upward direction.
 int getSwipeMagnitude()
          Retrieves the magnitude (in pixels) associated with a swipe gesture.
 int getTapCount()
          Retrieves the consecutive number of TouchGesture.TAP events generated before the user moves or maintains touch for greater than 150 milliseconds.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

HOVER

public static final int HOVER
Touch and pause at a specific point on the touch screen for more than the user-defined number of milliseconds (configurable setting found in Screen/Keyboard Options). A new consecutive HOVER event is generated at this interval in milliseconds until the user moves or removes touch from the touch screen. Invoke TouchGesture.getHoverCount() to retrieve the number of consecutive HOVER events.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

SWIPE

public static final int SWIPE
Quick motion gesture across the touch screen. Invoke TouchGesture.getSwipeAngle() and TouchGesture.getSwipeMagnitude() to retrieve the angle and magnitude of the swipe, respectively. Invoke TouchGesture.getSwipeDirection() to retrieve the cardinal direction of the swipe.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

CLICK_REPEAT

public static final int CLICK_REPEAT
Click and pause at a specific point on the touch screen for more than 500 milliseconds. A new consecutive CLICK_REPEAT event is generated every 500 milliseconds until the user moves or removes touch from the touch screen. Invoke TouchGesture.getClickRepeatCount() to retrieve the number of generated consecutive CLICK_REPEAT events.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

TAP

public static final int TAP
Quick touch and release gesture on the touch screen. TAP events are independent of TouchEvent.UP events, i.e. applications will receive a TAP event prior to a TouchEvent.UP. Invoke TouchGesture.getTapCount() to retrieve the number of consecutive taps (for example, double-tap or triple-tap).

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

DOUBLE_TAP

public static final int DOUBLE_TAP
Two consecutive quick touch and release gesture on the touch screen. DOUBLE_TAP events are independent of TouchGesture.TAP and TouchEvent.UP events, i.e. applications will receive a DOUBLE_TAP event after a TouchGesture.TAP and prior to a TouchEvent.UP.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

SWIPE_NORTH

public static final int SWIPE_NORTH
Gesture direction that is equivalent to 90 degrees +/- 45 degrees relative to the device's current upward direction. Can be bitwise ORed with other cardinal directions. For more information on swipe gestures, see TouchGesture.getSwipeAngle() and TouchGesture.getSwipeDirection().

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

SWIPE_SOUTH

public static final int SWIPE_SOUTH
Gesture direction that is equivalent to 270 degrees +/- 45 degrees relative to the device's current upward direction. Can be bitwise ORed with other cardinal directions. For more information on swipe gestures, see TouchGesture.getSwipeAngle() and TouchGesture.getSwipeDirection().

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

SWIPE_EAST

public static final int SWIPE_EAST
Gesture direction equivalent that is to 0 degrees +/- 45 degrees relative to the device's current upward direction. Can be bitwise ORed with other cardinal directions. For more information on swipe gestures, see TouchGesture.getSwipeAngle() and TouchGesture.getSwipeDirection().

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

SWIPE_WEST

public static final int SWIPE_WEST
Gesture direction that is equivalent to 180 degrees +/- 45 degrees relative to the device's current upward direction. Can be bitwise ORed with other cardinal directions. For more information on swipe gestures, see TouchGesture.getSwipeAngle() and TouchGesture.getSwipeDirection().

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0


Method Detail

getEvent

public abstract int getEvent()
Retrieves the event code associated with this touch gesture.

Returns:
One of the following touch event codes: TouchGesture.HOVER, TouchGesture.SWIPE, TouchGesture.CLICK_REPEAT, or TouchGesture.TAP.
Since:
BlackBerry API 4.7.0

getHoverCount

public int getHoverCount()
Retrieves the number of TouchGesture.HOVER events generated before the user moves or removes touch from the touch screen. A new consecutive TouchGesture.HOVER event is generated every 100 milliseconds.

Returns:
Number of consecutive TouchGesture.HOVER events.
Since:
BlackBerry API 4.7.0

getClickRepeatCount

public int getClickRepeatCount()
Retrieves the number of TouchGesture.CLICK_REPEAT events generated before the user moves or releases from the touch screen. A new consecutive TouchGesture.CLICK_REPEAT event is generated every 500 milliseconds.

Returns:
Number of consecutive TouchGesture.CLICK_REPEAT events.
Since:
BlackBerry API 4.7.0

getSwipeAngle

public int getSwipeAngle()
Retrieves the angle (in degrees) associated with a swipe gesture relative to the device's current upward direction. For instance, 90 degrees always refers to the side of the display closest to the top of the device.

Returns:
Relative swipe angle in degrees for this gesture. Returns -1 if the gesture is not a swipe,
Since:
BlackBerry API 4.7.0

getSwipeMagnitude

public int getSwipeMagnitude()
Retrieves the magnitude (in pixels) associated with a swipe gesture.

Returns:
Swipe magnitude (in pixels) for this gesture. Returns 0 if the gesture is not a swipe.
Since:
BlackBerry API 4.7.0

getSwipeDirection

public int getSwipeDirection()
Retrieves the relative cardinal direction associated with a swipe gesture based on the device's upward direction. That is, TouchGesture.SWIPE_NORTH always refers to the side of the display closest to the top of the device. Swipe gestures that occur at 90 degree intervals (North, South, West, East) are +/- ~23 degrees. For example, TouchGesture.SWIPE_NORTH is returned for (67, 112], where 67 is exclusive, and 112 is inclusive. For swipe gestures occurring at a 45 degree interval +/- ~23 degrees, the two directions are bitwise ORed, so 135 degrees returns TouchGesture.SWIPE_NORTH | TouchGesture.SWIPE_WEST.

Returns:
TouchGesture.SWIPE_NORTH, TouchGesture.SWIPE_SOUTH, TouchGesture.SWIPE_EAST, TouchGesture.SWIPE_WEST, or a bitwise ORed combination of two swipe events. Returns -1 if the gesture is not a swipe.
Since:
BlackBerry API 4.7.0

getTapCount

public int getTapCount()
Retrieves the consecutive number of TouchGesture.TAP events generated before the user moves or maintains touch for greater than 150 milliseconds.

Returns:
Number of consecutive TouchGesture.TAP events.
Since:
BlackBerry API 4.7.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.