|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--net.rim.device.api.ui.TouchEvent
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: DOWN, UP, CLICK,
UNCLICK, MOVE, and CANCEL. An additional event, 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 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
getGlobalX(int), getGlobalY(int), getX(int), getY(int), getEvent(),
getTime(), getMovePoints(int, int[], int[], int[]), getMovePointsSize(), and getGesture().
| 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 |
public static final int CANCEL
public static final int CLICK
public static final int DOWN
public static final int GESTURE
TouchGesture for more details on pre-defined gestures. A TouchGesture
event is retrieved by calling getGesture().public static final int MOVE
getMovePoints(int, int[], int[], int[]).public static final int UNCLICK
public static final int UP
| Method Detail |
public abstract TouchGesture getGesture()
TouchGesture object containing details of the gesture; null if this
event is not a gesture.RuntimeException - If this proxy object is invalid, see isValid().public abstract int getGlobalX(int touch)
touch - Touch point associated with the global x coordinate; 1 for the first
(finger) touch point, 2 for the second (finger) touch point.IllegalArgumentException - If touch is invalid.RuntimeException - If this proxy object is invalid, see isValid().public abstract int getGlobalY(int touch)
touch - Touch point associated with the global y coordinate; 1 for the first
(finger) touch point, 2 for the second (finger) touch point.IllegalArgumentException - If touch is invalid.RuntimeException - If this proxy object is invalid, see isValid().
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 DOWN touch input
event, and ends with the last 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 CANCEL). For example, the following sequence contains
five move points:
| TouchEvent | Touch Point 1 | Touch Point 2 | Array Size |
DOWN | (1, 1) | (-1, -1) | 0 |
MOVE | (2, 3) | (-1, -1) | 1 |
MOVE | (12, 15) | (-1, -1) | 2 |
DOWN | (-1, -1) | (50, 65) | 2 |
MOVE | (25, 21) | (51, 75) | 3 |
MOVE | (33, 35) | (67, 75) | 4 |
UP | (-1, 1) | (67, 75) | 4 |
MOVE | (35, 40) | (-1, -1) | 5 |
UP | (35, 40) | (-1, -1) | 5 |
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.IllegalArgumentException - If touch is invalid.ArrayIndexOutOfBoundsException - If one or a combination of x.length, y.length
and time.length are less than the value returned by getMovePointsSize().RuntimeException - If this proxy object is invalid, see isValid().public abstract int getMovePointsSize()
getMovePoints(int, int[], int[], int[]).RuntimeException - If this proxy object is invalid, see isValid().public abstract int getTime()
RuntimeException - If this proxy object is invalid, see isValid().public abstract int getX(int touch)
touch - Touch point associated with the x coordinate; 1 for the first
(finger) touch point, 2 for the second (finger) touch point.IllegalArgumentException - If touch is invalid.RuntimeException - If this proxy object is invalid, see isValid().public abstract int getY(int touch)
touch - Touch point associated with the y coordinate; 1 for the first
(finger) touch point, 2 for the second (finger) touch point.IllegalArgumentException - If touch is invalid.RuntimeException - If this proxy object is invalid, see isValid().public abstract boolean isValid()
true if this touch input event proxy object is valid; false otherwise.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.