Touch API

JavaScript Reference

Search This Document

Télécharger le PDF

Method name	Description
`TouchEvent`	Represents an event that is fired when data in the user touches a touch-sensitive screen.	7.0+	1.0+
`TouchList`	Contains an ordered collection of individual points of contact for a touch event.	7.0+	1.0+
`TouchPoint`	Represents an individual point of contact for a touch event on a touch-sensitive screen.	7.0+	1.0+

Object: TouchEvent

Availability	BlackBerry Device Software 7.0 or later BlackBerry Tablet OS 1.0 or later
Extends	`UIEvent`

The TouchEvent object extends the UIEvent object and represents an event generated when the user touches the surface of a touch-sensitive screen.

By default, touch events from the user are consumed by the BlackBerry Browser UI. The browser uses these events in order to provide improvements in usability. For example, the user must use their finger to scroll through the content, and can double-tap to zoom in to a content block. To prevent these events from being consumed by the UI, you can use the touch-event-mode meta tag.

With this meta tag, you can disable these UI features for a web page, so that the browser passes the entire array of events and gestures to the web page unprocessed. With access to raw touch events, you can, for example, track both the direction and distance of a swipe event, and respond differently based on the swipe direction or distance.

The touch-event-mode meta tag is added to the <head> section of a page as part of a <meta> element. For more information see touch-event-mode.

Touch event types

Event type	Bubbles	Cancelable	Description
`touchstart`	yes	yes	Occurs when the user places a touch point on a touch-sensitive screen.
`touchend`	yes	yes	Occurs when the user removes a touch point from a touch-sensitive screen.
`touchmove`	yes	yes	Occurs when the user moves a touch point along the surface of a touch-sensitive screen, or if there is a change in one or more of `radiusX`, `radiusY`, `rotation`, or `force`.
`touchenter`	no	yes	Occurs when the user moves a touch point onto an interactive area defined by a DOM element.
`touchleave`	no	yes	Occurs when the user moves a touch point off of an interactive area defined by a DOM element.
`touchcancel`	yes	yes	Occurs when the user performs some action that disrupts the sequence of touch points.

TouchEvent properties

Property name	Type	Description	Status	Support level
`changedTouches`	`TouchList`	Specifies a `TouchList` containing a list of `TouchPoint` objects that represent every point of contact that contributed to the touch event.	read only	Touch Events	7.0+	1.0+
`targetTouches`	`TouchList`	Specifies a `TouchList` containing a list of `TouchPoint` objects that represent every point of contact currently touching the screen surface that started on the same target.	read only	Touch Events	7.0+	1.0+
`touches`	`TouchList`	Specifies a `TouchList` containing a list of `TouchPoint` objects that represent every point of contact currently touching the screen surface.	read only	Touch Events	7.0+	1.0+

TouchEvent methods

Method name	Description	Support level
`initTouchEvent()`	Initializes the value of a `TouchEvent`.	Touch Events	7.0+	1.0+

Object: TouchList

Availability

BlackBerry Device Software 7.0 or later
BlackBerry Tablet OS 1.0 or later

The TouchList object is an array that contains an ordered collection of individual points of contact (represented by TouchPoint objects) for a touch event.

TouchList properties

Property name	Type	Description	Status	Support level
`length`	unsigned long	Returns the number of `TouchPoint`s in the list.	read only	Touch Events	7.0+	1.0+

TouchList methods

Method name	Description	Support level
`identifiedPoint()`	Returns the first `TouchPoint` with the specified identifier in the collection.	Touch Events	7.0+	1.0+
`item()`	Returns the `TouchPoint` at the specified index in the collection.	Touch Events	7.0+	1.0+

Object: TouchPoint

Availability

BlackBerry Device Software 7.0 or later
BlackBerry Tablet OS 1.0 or later

The TouchPoint object represents an individual point of contact for a touch event on a touch-sensitive screen.

TouchPoint properties

Property name	Type	Description	Status	Support level
`clientX`	long	Returns the X coordinate of the `TouchPoint`, relative to the viewport, excluding any scroll offset.	read only	Touch Events	7.0+	1.0+
`clientY`	long	Returns the Y coordinate of the `TouchPoint`, relative to the viewport, excluding any scroll offset.	read only	Touch Events	7.0+	1.0+
`force`	float	Returns the relative value of pressure. The value is between 0 and 1, where 0 indicates no pressure, and 1 indicates the maximum amount of pressure that the touch screen can detect.	read only	Touch Events	7.0+	1.0+
`identifier`	long	Returns the identification number for the `TouchPoint`.	read only	Touch Events	7.0+	1.0+
`pageX`	long	Returns the X coordinate of the `TouchPoint`, relative to the viewport, including any scroll offset.	read only	Touch Events	7.0+	1.0+
`pageY`	long	Returns the Y coordinate of the `TouchPoint`, relative to the viewport, including any scroll offset.	read only	Touch Events	7.0+	1.0+
`radiusX`	long	Returns the radius of the ellipse which most closely circumscribes the touching area along the x-axis, in pixels. If this value cannot be determined, a value of 1 is returned.	read only	Touch Events	7.0+	1.0+
`radiusY`	long	Returns the radius of the ellipse which most closely circumscribes the touching area along the Y-axis, in pixels. If this value cannot be determined, a value of 1 is returned.	read only	Touch Events	7.0+	1.0+
`rotationAngle`	float	Returns the angle, in degrees, that the ellipse defined by radiusX and radiusY is rotated about its center.	read only	Touch Events	7.0+	1.0+
`screenX`	long	Returns the X coordinate of the `TouchPoint`, relative to the device screen.	read only	Touch Events	7.0+	1.0+
`screenY`	long	Returns the Y coordinate of the `TouchPoint`, relative to the device screen.	read only	Touch Events	7.0+	1.0+
`target`	`EventTarget`	Returns the element closest to the original `TouchPoint`, which serves as the target of the event.	read only	Touch Events	7.0+	1.0+

Next topic: Traversal API

Previous topic: Worker methods

Was this information helpful? Send us your comments.

Global Navigation