net.rim.device.api.ui
Class TouchEvent

java.lang.Object
  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:

TouchEvent	Touch Point 1	Touch Point 2	Array 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