W3C

Touch Events version 1

W3C Working Draft 13 September 2011

This version:
http://www.w3.org/TR/2011/WD-touch-events-20110913/
Latest published version:
http://www.w3.org/TR/touch-events/
Latest editor's draft:
http://dvcs.w3.org/hg/webevents/raw-file/v1/touchevents.html
Previous version:
http://www.w3.org/TR/2011/WD-touch-events-20110505/
Public Comments:
public-webevents@w3.org
Working Group:
Web Events WG
Editors:
Matt Brubeck, Mozilla
Doug Schepers, W3C
Sangwhan Moon, Opera Software ASA

Abstract

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).

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This specification is the 13 September 2011 Last Call Working Draft. The Last Call review period will end on 11 October 2011.

This document was published by the Web Events Working Group. If you wish to make comments regarding this document, please send them to public-webevents@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Last Call Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is non-normative.

User Agents that run on terminals which provide touch input to use web applications typically use interpreted mouse events to allow users to access interactive web applications. However, these interpreted events, being normalized data based on the physical touch input, tend to have limitations on delivering the intended user experience. Additionally, it is not possible to handle concurrent input regardless of device capability, due to constraints of mouse events: both system level limitations and legacy compatibility.

Meanwhile, native applications are capable of handling both cases with the provided system APIs.

The Touch Events specification provides a solution to this problem by specifying interfaces to allow web applications to directly handle touch events, and multiple touch points for capable devices.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

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

Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL] as this specification uses that specification and terminology.

A conforming implementation is required to implement all fields defined in this specification.

3. Touch Interface

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

interface Touch {
    readonly attribute long identifier;
    readonly attribute long screenX;
    readonly attribute long screenY;
    readonly attribute long clientX;
    readonly attribute long clientY;
    readonly attribute long pageX;
    readonly attribute long pageY;
};

3.1 Attributes

clientX of type long, readonly
x-coordinate of point relative to the viewport, excluding any scroll offset
No exceptions.
clientY of type long, readonly
y-coordinate of point relative to the viewport, excluding any scroll offset
No exceptions.
identifier of type long, readonly
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.
No exceptions.
pageX of type long, readonly
x-coordinate of point relative to the viewport, including any scroll offset
No exceptions.
pageY of type long, readonly
y-coordinate of point relative to the viewport, including any scroll offset
No exceptions.
screenX of type long, readonly
x-coordinate of point relative to the screen
No exceptions.
screenY of type long, readonly
y-coordinate of point relative to the screen
No exceptions.

4. 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.

interface TouchList {
    readonly attribute unsigned long length;
    getter Touch item (unsigned long index);
    Touch        identifiedTouch (long identifier);
};

4.1 Attributes

length of type unsigned long, readonly
returns the number of Touches in the list
No exceptions.

4.2 Methods

identifiedTouch
returns the first Touch item in the list whose identifier property matches the specified identifier
ParameterTypeNullableOptionalDescription
identifierlong
No exceptions.
Return type: Touch
item
returns the Touch at the specified index in the list
ParameterTypeNullableOptionalDescription
indexunsigned long
No exceptions.
Return type: getter Touch

5. 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.

interface TouchEvent : UIEvent {
    readonly attribute TouchList touches;
    readonly attribute TouchList targetTouches;
    readonly attribute TouchList changedTouches;
    readonly attribute boolean   altKey;
    readonly attribute boolean   metaKey;
    readonly attribute boolean   ctrlKey;
    readonly attribute boolean   shiftKey;
    void initTouchEvent (DOMString type, boolean canBubble, boolean cancelable, AbstractView view, long detail, boolean ctrlKey, boolean altKey, boolean shiftKey, boolean metaKey, TouchList touches, TouchList targetTouches, TouchList changedTouches);
};

5.1 Attributes

altKey of type boolean, readonly
true if the alt (Alternate) key modifier is activated; otherwise false
No exceptions.
changedTouches of type TouchList, readonly

a list of Touches 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 event this must be a list of the touch points that have just been removed from the surface.

No exceptions.
ctrlKey of type boolean, readonly
true if the ctrl (Control) key modifier is activated; otherwise false
No exceptions.
metaKey of type boolean, readonly
true if the meta (Meta) key modifier is activated; otherwise false. On some platforms this attribute may map to a differently-named key modifier.
No exceptions.
shiftKey of type boolean, readonly
true if the shift (Shift) key modifier is activated; otherwise false
No exceptions.
targetTouches of type TouchList, readonly
a list of Touches for every point of contact that is touching the surface and started on the element that is the target of the current event.
No exceptions.
touches of type TouchList, readonly
a list of Touches for every point of contact currently touching the surface.
No exceptions.

5.2 Methods

initTouchEvent
initializes a TouchEvent created through the DocumentEvent interface.
ParameterTypeNullableOptionalDescription
typeDOMString
canBubbleboolean
cancelableboolean
viewAbstractView
detaillong
ctrlKeyboolean
altKeyboolean
shiftKeyboolean
metaKeyboolean
touchesTouchList
targetTouchesTouchList
changedTouchesTouchList
No exceptions.
Return type: void

5.3 Usage Examples

This section is non-normative.

The examples below demonstrate the relations between the different TouchList members defined in a TouchEvent.

5.3.1 touches and targetTouches of a TouchEvent

This example demonstrates the utility and relations between the touches and targetTouches members defined in the TouchEvent interface. The following code will generate different output based on the number of touch points on the touchable element and the document:

<div id='touchable'>
    This element is touchable.
</div>
          
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);

5.3.2 changedTouches of a TouchEvent

This example demonstrates the utility of changedTouches and it's relation with the other TouchList members of the TouchEvent interface. The code is a example which triggers whenever a touch point is removed from the defined touchable element:

<div id='touchable'>
    This element is touchable.
</div>
              
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);

5.4 The touchstart event

A user agent must dispatch this event type to indicate when the user places a touch point on the touch surface.

The target of this event must be an Element. If the touch point is within a frame, the event should be dispatched to an element in the child browsing context of that frame.

If the preventDefault method is called on this event, it should prevent any default actions caused by any touch events associated with the same active touch point, including mouse events or scrolling.

5.5 The touchend event

A user agent must dispatch this event type to indicate when the user removes a touch point from the touch surface, also including cases where the touch point physically leaves the touch surface, such as being dragged off of the screen.

The target of this event must be the same Element that received the touchstart event when this touch point was placed on the surface, even if the touch point has since moved outside the interactive area of the target element.

The touch point or points that were removed must be included in the changedTouches attribute of the TouchEvent, and must not be included in the touches and targetTouches attributes.

5.6 The touchmove event

A user agent must dispatch this event type to indicate when the user moves a touch point along the touch surface.

The target of this event must be the same Element that received the touchstart event when this touch point was placed on the surface, even if the touch point has since moved outside the interactive area of the target element.

Note that the rate at which the user agent sends touchmove events is implementation-defined, and may depend on hardware capabilities and other implementation details.

If the preventDefault method is called on the first touchmove event of an active touch point, it should prevent any default action caused by any touchmove event associated with the same active touch point, such as scrolling.

5.7 The touchcancel event

A user agent must dispatch this event type to indicate when a touch point has been disrupted in an implementation-specific manner, such as a synchronous event or action originating from the UA canceling the touch, or the touch point leaving the document window into a non-document area which is capable of handling user interactions. (e.g. The UA's native user interface, plug-ins) A user agent may also dispatch this event type when the user places more touch points on the touch surface than the device or implementation is configured to store, in which case the earliest Touch object in the TouchList should be removed.

6. DocumentTouch Interface

The DocumentTouch interface provides a mechanism by which the user can create Touch and TouchList objects. The DocumentTouch interface must be implemented on the Document object.

interface DocumentTouch {
    Touch     createTouch (AbstractView view, EventTarget target, long identifier, long pageX, long pageY, long screenX, long screenY);
    TouchList createTouchList (Touch[] touches);
    TouchList createTouchList (Touch touch);
};

6.1 Methods

createTouch
Creates a Touch object with the specified attributes.
ParameterTypeNullableOptionalDescription
viewAbstractView
targetEventTarget
identifierlong
pageXlong
pageYlong
screenXlong
screenYlong
No exceptions.
Return type: Touch
createTouchList
Creates a TouchList object containing the specified Touch objects.
ParameterTypeNullableOptionalDescription
touchesTouch[]
No exceptions.
Return type: TouchList
createTouchList
Creates a TouchList object containing a single Touch.
ParameterTypeNullableOptionalDescription
touchTouch
No exceptions.
Return type: TouchList

7. Interaction with Mouse Events

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 the preventDefault method of touchstart or touchmove is called, the user agent should not dispatch any mouse event that would be a consequential result of the the prevented touch event.

If the user agent intreprets 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.

8. 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.

9. Issues

This section is non-normative.

The working group maintains a list of open issues in this specification. These issues may be addressed in future revisions of the specification.

A. Acknowledgements

This section is non-normative.

Many thanks to the WebKit engineers for developing the model used as a basis for this spec, Neil Roberts (SitePen) for his summary of WebKit touch events, Peter-Paul Koch (PPK) for his write-ups and suggestions, Robin Berjon for developing the ReSpec.js spec authoring tool, and the WebEvents WG for their many contributions.

Many others have made additional comments as the spec developed, which have led to steady improvements. Among them are Matthew Schinckel, Andrew Grieve, and Cathy Chan. If I inadvertently omitted your name, please let me know.

B. References

B.1 Normative references

[DOM-LEVEL-2-EVENTS]
Tom Pixley. Document Object Model (DOM) Level 2 Events Specification. 13 November 2000. W3C Recommendation. URL: http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219

B.2 Informative references

No informative references.