Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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 represents a combination of basic touch input events originating from the user. TouchGesture events are acquired using TouchEvent.getGesture() when a gesture is detected (that is, when TouchEvent.getEvent() returns TouchEvent.GESTURE). TouchGesture defines several common gestures, including TouchGesture.CLICK_REPEAT, TouchGesture.HOVER, PINCH, TouchGesture.NAVIGATION_SWIPE, TouchGesture.SWIPE, and TouchGesture.TAP.

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 NAVIGATION_SWIPE
          Quick motion gesture made with the trackpad.
static int PINCH_BEGIN
          Two touch points are detected on the touch screen, beginning a Pinch gesture.
static int PINCH_END
          One or both touch points are released during a Pinch gesture.
static int PINCH_UPDATE
          One or both touch points are moved during a Pinch gesture.
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.
 float getPinchMagnitude()
          Retrieves the pinch magnitude of the TouchGesture.PINCH_BEGIN, TouchGesture.PINCH_UPDATE, or TouchGesture.PINCH_END event currently being processed.
 int getSwipeAngle()
          Retrieves the angle (in degrees) associated with a swipe gesture relative to the device's current upward direction.
 int getSwipeContentAngle()
          Typically Touchscreen SWIPE is used to move content off screen in the direction of the swipe (with new content moving onscreen from the other 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

PINCH_BEGIN

public static final int PINCH_BEGIN
Two touch points are detected on the touch screen, beginning a Pinch gesture. The midpoint between the two initial touch points is stored as TouchEvent.getX(1) and TouchEvent.getY(1).

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PINCH_UPDATE

public static final int PINCH_UPDATE
One or both touch points are moved during a Pinch gesture. A Pinch gesture generates a series of PINCH_UPDATE events as the user moves one or both fingers. Invoke TouchGesture.getPinchMagnitude() to retrieve the zoom value during a PINCH_UPDATE event.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PINCH_END

public static final int PINCH_END
One or both touch points are released during a Pinch gesture. Invoke TouchGesture.getPinchMagnitude() to retrieve the zoom value during a PINCH_END event.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

NAVIGATION_SWIPE

public static final int NAVIGATION_SWIPE
Quick motion gesture made with the trackpad. Invoke TouchGesture.getSwipeDirection() to retrieve the cardinal direction of the swipe. The swipe magnitude is currently always 1.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.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, TouchGesture.TAP, TouchGesture.DOUBLE_TAP, TouchGesture.PINCH_BEGIN, TouchGesture.PINCH_UPDATE, TouchGesture.PINCH_END, or TouchGesture.NAVIGATION_SWIPE.
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 0 if the gesture is not a swipe.
Since:
BlackBerry API 4.7.0

getSwipeContentAngle

public int getSwipeContentAngle()
Typically Touchscreen SWIPE is used to move content off screen in the direction of the swipe (with new content moving onscreen from the other direction). Trackpad NAVIGATION_SWIPE, however, typically works in the opposite direction (because of the nature of how the trackpad navigates the field with focus, as well as when in 'cursor' mode). This function is a 'convenience function' making it easier to implement standard swipe behaviour. Retrieves the direction in which to move screen Content, for typical handling of both TouchGesture.SWIPE and TouchGesture.NAVIGATION_SWIPE. ie returns getSwipeAngle() for SWIPE and the opposite for NAVIGATION_SWIPE (ie getSwipeAngle() + 180 degrees, normalized to the range [0, 369]).

Returns:
The expected direction of motion for screen content or swipe events. Returns -1 if the gesture is not a swipe.
Since:
BlackBerry API 6.0.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

getPinchMagnitude

public float getPinchMagnitude()
Retrieves the pinch magnitude of the TouchGesture.PINCH_BEGIN, TouchGesture.PINCH_UPDATE, or TouchGesture.PINCH_END event currently being processed.

Returns:
Pinch magnitude of the current PINCH gesture.
Since:
BlackBerry API 6.0.0



Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal