net.rim.device.api.ui
Class TouchEvent

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

public abstract class TouchEvent
extends Object

TouchEvent contains touch input events originating from the user that the application uses when overriding Field.touchEvent(net.rim.device.api.ui.TouchEvent) for customizing touch interaction behavior. TouchEvent also defines the available basic touch input event types originating from the user: TouchEvent.DOWN, TouchEvent.UP, TouchEvent.CLICK, TouchEvent.UNCLICK, TouchEvent.MOVE, and TouchEvent.CANCEL. An additional event, TouchEvent.GESTURE , indicates whether or not the event is a combination of basic touch input events. For more information on pre-defined gestures, see TouchGesture.

TouchEvent is a proxy class with a finite lifetime that begins when the application detects a touch input event, and ends when the application's main thread completes touch input event processing. See TouchEvent.isValid(). In addition, this proxy class is not considered thread-safe and, as a result, the values returned by the accessor APIs are not guaranteed outside of the primary application thread.

Caching of TouchEvent objects is not recommended. Instead, cache the data within TouchEvent by acquiring the values using TouchEvent.getGlobalX(int), TouchEvent.getGlobalY(int), TouchEvent.getX(int), TouchEvent.getY(int), TouchEvent.getEvent(), TouchEvent.getTime(), TouchEvent.getMovePoints(int, int[], int[], int[]), TouchEvent.getMovePointsSize(), and TouchEvent.getGesture().

Since:
BlackBerry API 4.7.0

Field Summary
static int CANCEL
          Touch input cancelled event that is generated when an existing series of touch input events is interrupted by an overriding system event (such as an incoming voice call).
static int CLICK
          Touch click input event that is generated when the user clicks the touchscreen.
static int DOWN
          Touch down input event that is generated when the user touches the touchscreen, without clicking, with a maximum of two fingers.
static int GESTURE
          Touch gesture event that is generated when a specific set of basic touch input events is detected within a specific time period.
static int MOVE
          Touch move input event that is generated in sequence as the user moves finger around the touchscreen.
static int UNCLICK
          Touch unclick input event that is generated when the user releases from a click on the touchscreen.
static int UP
          Touch up input event that is generated when the user removes touch from the touchscreen (with a maximum of two fingers).
 
Method Summary
abstract  int getEvent()
          Retrieves the event code associated with this touch event.
abstract  TouchGesture getGesture()
          Retrieves the gesture associated with this touch event.
abstract  int getGlobalX(int touch)
          Retrieves the global x coordinate for the specified touch point.
abstract  int getGlobalY(int touch)
          Retrieves the global y coordinate for the specified touch point.
abstract  void getMovePoints(int touch, int[] x, int[] y, int[] time)
          Retrieves the global coordinates for the current sequence of touch move input events for the specified touch point.
abstract  int getMovePointsSize()
          Retrieves the number of global coordinates stored for the current sequence of touch move input events.
abstract  int getTime()
          Retrieves the time/ticks (in milliseconds) associated with this touch event.
abstract  int getX(int touch)
          Retrieves the mapped x coordinate for the specified touch point.
abstract  int getY(int touch)
          Retrieves the mapped y coordinate for the specified touch point.
abstract  boolean isValid()
          Indicates whether this touch input event proxy object is valid, or no longer exists.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

DOWN

public static final int DOWN
Touch down input event that is generated when the user touches the touchscreen, without clicking, with a maximum of two fingers. Typically used to focus or highlight UI components on the touchscreen display.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

UP

public static final int UP
Touch up input event that is generated when the user removes touch from the touchscreen (with a maximum of two fingers).

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

CLICK

public static final int CLICK
Touch click input event that is generated when the user clicks the touchscreen. Typically used to highlight or activate UI components on the display.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

UNCLICK

public static final int UNCLICK
Touch unclick input event that is generated when the user releases from a click on the touchscreen. Typically used to activate UI components on the display.

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

MOVE

public static final int MOVE
Touch move input event that is generated in sequence as the user moves finger around the touchscreen. A typical drag input sequence is: DOWN, MOVE, MOVE..., UP. Can be retrieved individually with each message containing a set of mapped coordinates, or retrieved as an array of global move coordinates that are acquired by invoking TouchEvent.getMovePoints(int, int[], int[], int[]).

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

CANCEL

public static final int CANCEL
Touch input cancelled event that is generated when an existing series of touch input events is interrupted by an overriding system event (such as an incoming voice call).

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0

GESTURE

public static final int GESTURE
Touch gesture event that is generated when a specific set of basic touch input events is detected within a specific time period. See TouchGesture for more details on pre-defined gestures. A TouchGesture event is retrieved by calling TouchEvent.getGesture().

See Also:
Constant Field Values
Since:
BlackBerry API 4.7.0


Method Detail

getX

public abstract int getX(int touch)
Retrieves the mapped x coordinate for the specified touch point.

Parameters:
touch - Touch point associated with the x coordinate; 1 for the first (finger) touch point, 2 for the second (finger) touch point.
Returns:
Mapped x coordinate for the specified touch point.
Throws:
IllegalArgumentException - If touch is invalid.
RuntimeException - If this proxy object is invalid, see TouchEvent.isValid().
Since:
BlackBerry API 4.7.0

getY

public abstract int getY(int touch)
Retrieves the mapped y coordinate for the specified touch point.

Parameters:
touch - Touch point associated with the y coordinate; 1 for the first (finger) touch point, 2 for the second (finger) touch point.
Returns:
Mapped y coordinate for the specified touch point.
Throws:
IllegalArgumentException - If touch is invalid.
RuntimeException - If this proxy object is invalid, see TouchEvent.isValid().
Since:
BlackBerry API 4.7.0

getGlobalX

public abstract int getGlobalX(int touch)
Retrieves the global x coordinate for the specified touch point.

Parameters:
touch - Touch point associated with the global x coordinate; 1 for the first (finger) touch point, 2 for the second (finger) touch point.
Returns:
Global x coordinate for the specified touch point.
Throws:
IllegalArgumentException - If touch is invalid.
RuntimeException - If this proxy object is invalid, see TouchEvent.isValid().
Since:
BlackBerry API 4.7.0

getGlobalY

public abstract int getGlobalY(int touch)
Retrieves the global y coordinate for the specified touch point.

Parameters:
touch - Touch point associated with the global y coordinate; 1 for the first (finger) touch point, 2 for the second (finger) touch point.
Returns:
Global y coordinate for the specified touch point.
Throws:
IllegalArgumentException - If touch is invalid.
RuntimeException - If this proxy object is invalid, see TouchEvent.isValid().
Since:
BlackBerry API 4.7.0

getMovePoints

public abstract void getMovePoints(int touch,
                                   int[] x,
                                   int[] y,
                                   int[] time)

Retrieves the global coordinates for the current sequence of touch move input events for the specified touch point. A sequence begins with the first TouchEvent.DOWN touch input event, and ends with the last TouchEvent.UP touch input event. Each time a MOVE touch event occurs, the coordinates and time are added to a set of arrays. The arrays persist until the touch sequence ends, that is, all fingers lifted from touchscreen, or the sequence is interrupted by an overriding event (see TouchEvent.CANCEL). For example, the following sequence contains five move points:

TouchEventTouch Point 1Touch Point 2Array Size
TouchEvent.DOWN(1, 1)(-1, -1)0
TouchEvent.MOVE(2, 3)(-1, -1)1
TouchEvent.MOVE(12, 15)(-1, -1)2
TouchEvent.DOWN(-1, -1)(50, 65)2
TouchEvent.MOVE(25, 21)(51, 75)3
TouchEvent.MOVE(33, 35)(67, 75)4
TouchEvent.UP(-1, 1)(67, 75)4
TouchEvent.MOVE(35, 40)(-1, -1)5
TouchEvent.UP(35, 40)(-1, -1)5

Parameters:
touch - Touch point associated with the x and y coordinates; 1 for the first (finger) touch point, 2 for the second (finger) touch point, and so on.
x - Array populated with the MOVE x coordinates.
y - Array populated with the MOVE y coordinates.
time - Array populated with time/ticks (in milliseconds) associated with each MOVE coordinate; null if not required.
Throws:
IllegalArgumentException - If touch is invalid or if x and/or y are null.
ArrayIndexOutOfBoundsException - If one or a combination of x.length, y.length and time.length are less than the value returned by TouchEvent.getMovePointsSize().
RuntimeException - If this proxy object is invalid, see TouchEvent.isValid().
Since:
BlackBerry API 4.7.0

getMovePointsSize

public abstract int getMovePointsSize()
Retrieves the number of global coordinates stored for the current sequence of touch move input events. The path or array of coordinates can be retrieved by calling TouchEvent.getMovePoints(int, int[], int[], int[]).

Returns:
Number of coordinates stored in this touch event.
Throws:
RuntimeException - If this proxy object is invalid, see TouchEvent.isValid().
Since:
BlackBerry API 4.7.0

getGesture

public abstract TouchGesture getGesture()
Retrieves the gesture associated with this touch event.

Returns:
TouchGesture object containing details of the gesture; null if this event is not a gesture.
Throws:
RuntimeException - If this proxy object is invalid, see TouchEvent.isValid().
Since:
BlackBerry API 4.7.0

getEvent

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

Returns:
One of the following touch event codes: TouchEvent.DOWN, TouchEvent.UP, TouchEvent.CLICK, TouchEvent.UNCLICK, TouchEvent.MOVE, TouchEvent.CANCEL, TouchEvent.GESTURE.
Throws:
RuntimeException - If this proxy object is invalid, see TouchEvent.isValid().
Since:
BlackBerry API 4.7.0

getTime

public abstract int getTime()
Retrieves the time/ticks (in milliseconds) associated with this touch event.

Returns:
Ticks, in milliseconds.
Throws:
RuntimeException - If this proxy object is invalid, see TouchEvent.isValid().
Since:
BlackBerry API 4.7.0

isValid

public abstract boolean isValid()
Indicates whether this touch input event proxy object is valid, or no longer exists. When a touch input event expires, the proxy object representing it is no longer valid.

Returns:
true if this touch input event proxy object is valid; false otherwise.
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.