By publishing this Recommendation, W3C expects that the functionality specified in this Touch Interface Recommendation will not be affected by changes to HTML5 or Web IDL as those specifications proceed to Recommendation. The WG has completed and approved this specification's Test Suite and created an Implementation Report that shows that two or more independent implementations pass each test. This version of the specification includes fixes and improvements to Level 1, and incorporates the features previously published as Touch Event Extentions.

The Touch Events specification defines a set of low-level events that represent one or more points of contact with a touch-sensitive surface, and changes of those points with respect to the surface and any DOM elements displayed upon it (e.g. for touch screens) or associated with it (e.g. for drawing tablets without displays). It also addresses pen-tablet devices, such as drawing tablets, with consideration toward stylus capabilities.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

WindowProxy is defined in [[!HTML5]].

WebIDL Conformance

The IDL blocks in this specification are conforming IDL fragments as defined by the WebIDL specification [[!WEBIDL]].

A conforming Web Events user agent must also be a conforming ECMAScript implementation of this IDL fragments in this specification, with the following exception:

• section 4.4.6 of Web IDL requires that IDL attributes are reflected as accessor properties on interface prototype objects. Instead of this, the user agent may reflect IDL attributes as data properties on the platform objects that implement the relevant interface. These data properties must have the same behavior when getting and setting as would be exhibited when invoking the getter and setter of the accessor properties on the platform object.

Note: Both ways of reflecting IDL attributes allow for simply getting and setting the property on the platform object to work. For example, given a Touch object aTouch, evaluating aTouch.target would return the EventTarget for the Touch object. If the user agent implements IDL attributes as accessor properties, then the property access invokes the getter which returns the EventTarget. If the user agent implements IDL attributes as data properties on the platform object with the same behavior as would be found with the accessor properties, then the object would appear to have an own property named target whose value is an EventTarget object, and the property access would return this value.

Touch Interface

This interface describes an individual touch point for a touch event. Touch objects are immutable; after one is created, its attributes must not change.

readonly attribute long identifier

An identification number for each touch point. When a touch point becomes active, it must be assigned an identifier that is distinct from any other active touch point. While the touch point remains active, all events that refer to it must assign it the same identifier.

readonly attribute EventTarget target

The EventTarget on which the touch point started when it was first placed on the surface, even if the touch point has since moved outside the interactive area of that element.

readonly attribute double screenX

The horizontal coordinate of point relative to the screen in pixels

readonly attribute double screenY

The vertical coordinate of point relative to the screen in pixels

readonly attribute double clientX

The horizontal coordinate of point relative to the viewport in pixels, excluding any scroll offset

readonly attribute double clientY

The vertical coordinate of point relative to the viewport in pixels, excluding any scroll offset

readonly attribute double pageX

The horizontal coordinate of point relative to the viewport in pixels, including any scroll offset

readonly attribute double pageY

The vertical coordinate of point relative to the viewport in pixels, including any scroll offset

readonly attribute float radiusX

the radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the axis indicated by rotationAngle, in CSS pixels of the same scale as screenX; 0 if no value is known. The value must not be negative.

readonly attribute float radiusY

the radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the axis perpendicular to that indicated by rotationAngle, in CSS pixels of the same scale as screenY; 0 if no value is known. The value must not be negative.

readonly attribute float rotationAngle

the angle (in degrees) that the ellipse described by radiusX and radiusY is rotated clockwise about its center; 0 if no value is known. The value must be greater than or equal to 0 and less than 90. If the ellipse described by radiusX and radiusY is circular, then rotationAngle has no effect. The user agent may use 0 as the value in this case, or it may use any other value in the allowed range. (For example, the user agent may use the rotationAngle value from the previous touch event, to avoid sudden changes.)

readonly attribute float force

a relative value of pressure applied, in the range 0 to 1, where 0 is no pressure, and 1 is the highest level of pressure the touch device is capable of sensing; 0 if no value is known. In environments where force is known, the absolute pressure represented by the force attribute, and the sensitivity in levels of pressure, may vary.

required long identifier

Initializes the identifier property of the Touch object.

required EventTarget target

Initializes the target property of the Touch object.

double clientX = 0

Initializes the clientX and pageX properties of the Touch object.

double clientY = 0

Initializes the clientY and pageY properties of the Touch object.

double screenX = 0

Initializes the screenX property of the Touch object.

double screenY = 0

Initializes the screenY property of the Touch object.

float radiusX = 0

Initializes the radiusX property of the Touch object.

float radiusY = 0

Initializes the radiusY property of the Touch object.

float rotationAngle = 0

Initializes the rotationAngle property of the Touch object.

float force = 0

Initializes the force property of the Touch object.

TouchList Interface

This interface defines a list of individual points of contact for a touch event. TouchList objects are immutable; after one is created, its contents must not change.

A TouchList object's supported property indices ([[!WEBIDL]]) are the numbers in the range 0 to one less than the length of the list.

readonly attribute unsigned long length

returns the number of Touch objects in the list

getter Touch? item (in unsigned long index)

returns the Touch at the specified index in the list or null if the index is not less than the length of the list.

TouchEvent Interface

This interface defines the touchstart, touchend, touchmove, and touchcancel event types. TouchEvent objects are immutable; after one is created and initialized, its attributes must not change.

readonly attribute TouchList touches

a list of Touch objects for every point of contact currently touching the surface.

readonly attribute TouchList targetTouches

a list of Touch objects for every point of contact that is touching the surface and started on the element that is the target of the current event.

readonly attribute TouchList changedTouches

a list of Touch objects for every point of contact which contributed to the event.

For the touchstart event this must be a list of the touch points that just became active with the current event. For the touchmove event this must be a list of the touch points that have moved since the last event. For the touchend and touchcancel events this must be a list of the touch points that have just been removed from the surface, with the last known coordinates of the touch points before they were removed.

readonly attribute boolean altKey

true if the alt (Alternate) key modifier is activated; otherwise false

readonly attribute boolean metaKey

true if the meta (Meta) key modifier is activated; otherwise false. On some platforms this attribute may map to a differently-named key modifier.

readonly attribute boolean ctrlKey

true if the ctrl (Control) key modifier is activated; otherwise false

readonly attribute boolean shiftKey

true if the shift (Shift) key modifier is activated; otherwise false

sequence<Touch> touches = []

Initializes the touches property of the TouchEvent object with each element from the sequence.

sequence<Touch> targetTouches = []

Initializes the targetTouches property of the TouchEvent object with each element from the sequence.

sequence<Touch> changedTouches = []

Initializes the changedTouches property of the TouchEvent object with each element from the sequence.

boolean altKey

Initializes the altKey property of the TouchEvent object.

boolean metaKey

Initializes the metaKey property of the TouchEvent object.

boolean ctrlKey

Initializes the ctrlKey property of the TouchEvent object.

boolean shiftKey

Initializes the shiftKey property of the TouchEvent object.

<div id='touchable'>This element is touchable.</div>

<script>
document.getElementById('touchable').addEventListener('touchstart', function(ev) {

    if (ev.touches.item(0) == ev.targetTouches.item(0))
    {
        /**
         * If the first touch on the surface is also targeting the
         * "touchable" element, the code below should execute.
         * Since targetTouches is a subset of touches which covers the
         * entire surface, TouchEvent.touches >= TouchEvents.targetTouches
         * is always true.
         */

        document.write('Hello Touch Events!');
    }

    if (ev.touches.length == ev.targetTouches.length)
    {
        /**
         * If all of the active touch points are on the "touchable"
         * element, the length properties should be the same.
         */

        document.write('All points are on target element')
    }

    if (ev.touches.length > 1)
    {
        /**
         * On a single touch input device, there can only be one point
         * of contact on the surface, so the following code can only
         * execute when the terminal supports multiple touches.
         */

        document.write('Hello Multiple Touch!');
    }

}, false);
</script>

<div id='touchable'>This element is touchable.</div>

<script>
document.getElementById('touchable').addEventListener('touchend', function(ev) {

    /**
     * Example output when three touch points are on the surface,
     * two of them being on the "touchable" element and one point
     * in the "touchable" element is lifted from the surface:
     *
     * Touch points removed: 1
     * Touch points left on element: 1
     * Touch points left on document: 2
     */

    document.write('Removed: ' + ev.changedTouches.length);
    document.write('Remaining on element: ' + ev.targetTouches.length);
    document.write('Remaining on document: ' + ev.touches.length);

}, false);
</script>

Extensions to the Document Interface

The Document interface [[!DOM-LEVEL-3-CORE]] contains methods by which the user can create Touch and TouchList objects.

Touch createTouch()

Creates a Touch object with the specified attributes.

WindowProxy view

EventTarget target

long identifier

double pageX

double pageY

double screenX

double screenY

TouchList createTouchList()

Creates a TouchList object consisting of zero or more Touch objects. Calling this method with no arguments creates a TouchList with no objects in it and length 0 (zero).

Touch... touches

Some user agents implement an initTouchEvent method as part of the TouchEvent interface. When this method is available, scripts can use it to initialize the properties of a TouchEvent object, including its TouchList properties (which can be initialized with values returned from createTouchList). The initTouchEvent method is not standardized and is superseded by the TouchEvent constructor.

Interaction with Mouse Events and click

The user agent may dispatch both touch events and mouse events [[!DOM-LEVEL-2-EVENTS]] in response to the same user input. If the user agent dispatches both touch events and mouse events in response to a single user action, then the touchstart event type must be dispatched before any mouse event types for that action. If touchstart, touchmove, or touchend are canceled, the user agent should not dispatch any mouse event that would be a consequential result of the the prevented touch event.

If a Web application can process touch events, it can cancel the events, and no corresponding mouse events would need to be dispatched by the user agent. If the Web application is not specifically written for touch input devices, it will react to the subsequent mouse events instead.

User agents will typically dispatch mouse and click events when there is only a single active touch point. Multi-touch interactions – involving two or more active touch points – will usually only generate touch events.

If the user agent interprets a sequence of touch events as a click, then it should dispatch mousemove, mousedown, mouseup, and click events (in that order) at the location of the touchend event for the corresponding touch input. If the contents of the document have changed during processing of the touch events, then the user agent may dispatch the mouse events to a different target than the touch events.

The default actions and ordering of any further touch and mouse events are implementation-defined, except as specified elsewhere.

Glossary

active touch point

A touch point which is currently on the screen and is being tracked by the user agent. The touch point becomes active when the user agent first dispatches a touchstart event indicating its appearance. It ceases to be active after the user agent dispatches a touchend or touchcancel event indicating that the touch point is removed from the surface or no longer tracked.

touch point

The coordinate point at which a pointer (e.g finger or stylus) intersects the target surface of an interface. This may apply to a finger touching a touch-screen, or an digital pen writing on a piece of paper.

canceled event

An event whose default action was prevented by means of preventDefault(), returning false in an event handler, or other means as defined by [[!DOM-LEVEL-3-EVENTS]] and [[!HTML5]].