JavaScript Reference

Local Navigation

Touch API

Method name

Description

BlackBerry Tablet OS

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.

Back To Top

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.

Back To Top

TouchEvent properties

Property name

Type

Description

Status

Support level

BlackBerry Tablet OS

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+

Back To Top

TouchEvent methods

Method name

Description

Support level

BlackBerry Tablet OS

initTouchEvent()

Initializes the value of a TouchEvent.

Touch Events

7.0+

1.0+

Back To Top

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.

Back To Top

TouchList properties

Property name

Type

Description

Status

Support level

BlackBerry Tablet OS

length

unsigned long

Returns the number of TouchPoints in the list.

read only

Touch Events

7.0+

1.0+

Back To Top

TouchList methods

Method name

Description

Support level

BlackBerry Tablet OS

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+

Back To Top

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.

Back To Top

TouchPoint properties

Property name

Type

Description

Status

Support level

BlackBerry Tablet OS

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+

Back To Top
Next topic: Traversal API
Previous topic: Worker methods

Was this information helpful? Send us your comments.