Please refer to the errata for this document, which may include some normative corrections.
The English version of this specification is the only normative version. Non-normative translations may also be available.
Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
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 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/.
By publishing this Recommendation, W3C expects that the functionality specified in this Touch Events 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 document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
This document was published by the Web Events Working Group as a Recommendation. If you wish to make comments regarding this document, please send them to [email protected] (subscribe, archives). All comments are welcome. A list of changes since the last publication is available in Appendix B.
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.
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.
The W3C's Protocols and Formats Working Group created a non-normative document that includes a mapping of hardware events (e.g. keyboard events) to touch events. For more information see Touch Events Accessibility Mapping.
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.
WindowProxy is defined in [HTML5].
The IDL blocks in this specification are conforming IDL fragments as defined by the Web IDL 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:
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.
interface Touch {
readonly attribute long identifier;
readonly attribute EventTarget target;
readonly attribute long screenX;
readonly attribute long screenY;
readonly attribute long clientX;
readonly attribute long clientY;
readonly attribute long pageX;
readonly attribute long pageY;
};
clientX
of type long, readonly clientY
of type long, readonly identifier
of type long, readonly pageX
of type long, readonly pageY
of type long, readonly screenX
of type long, readonly screenY
of type long, readonly target
of type EventTarget, readonly 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.
interface TouchList {
readonly attribute unsigned long length;
getter Touch? item (unsigned long index);
};
length
of type unsigned long, readonly Touch
es in the list
item
Touch
at the specified index in the list or
null if the index is not less than the length of the list.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
index | unsigned long | ✘ | ✘ |
Touch
, nullableTouchEvent
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;
};
altKey
of type boolean, readonly true
if the alt (Alternate) key modifier is activated;
otherwise false
changedTouches
of type TouchList
, readonly
a list of Touch
es 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.
ctrlKey
of type boolean, readonly true
if the ctrl (Control) key modifier is activated;
otherwise false
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.
shiftKey
of type boolean, readonly true
if the shift (Shift) key modifier is activated;
otherwise false
targetTouches
of type TouchList
, readonly Touch
es for every point of contact that is touching
the surface and started on the element that is the
target of the current event.
touches
of type TouchList
, readonly Touch
es for every point of contact currently
touching the surface.
This section is non-normative.
User agents should ensure that all Touch
objects available from a given
TouchEvent
are all associated to the same document that the TouchEvent
was dispatched
to. To implement this, user agents should maintain a notion of the current
touch-active document. On first touch, this is set to the target document
where the touch was created. When all active touch points are released, the
touch-active document is cleared. All TouchEvent
s are dispatched to the
current touch-active document, and each Touch
object it contains refers
only to DOM elements (and co-ordinates) in that document. If a touch starts entirely
outside the currently touch-active document, then it is ignored entirely.
This section is non-normative.
The examples below demonstrate the relations between the different
TouchList
members defined in a TouchEvent
.
TouchEvent
This section is non-normative.
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);
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);
TouchEvent
typesThis section is non-normative.
The following table provides a summary of the types of possible
TouchEvent
types defined in this specification. All events
should accomplish the bubbling phase. Some events are not cancelable
(see preventDefault).
Event Type | Sync / Async | Bubbling phase | Trusted proximal event target types | DOM interface | Cancelable | Default Action |
---|---|---|---|---|---|---|
touchstart | Sync | Yes | Document, Element |
TouchEvent |
Yes | undefined |
touchend | Sync | Yes | Document, Element |
TouchEvent |
Yes | Varies: mousemove (If point has been moved), mousedown, mouseup, click |
touchmove | Sync | Yes | Document, Element |
TouchEvent |
Yes | undefined |
touchcancel | Sync | Yes | Document, Element |
TouchEvent |
No | none |
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.
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 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 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.
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 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 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.
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.
The target of this event must be the same Element 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 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.
Document
Interface
The Document
interface [DOM-LEVEL-3-CORE] contains methods
by which the user can create Touch
and TouchList
objects.
partial interface Document {
Touch
createTouch (WindowProxy view, EventTarget target, long identifier, long pageX, long pageY, long screenX, long screenY);
TouchList
createTouchList (Touch
... touches);
};
createTouch
Touch
object with the specified attributes.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
view | WindowProxy | ✘ | ✘ | |
target | EventTarget | ✘ | ✘ | |
identifier | long | ✘ | ✘ | |
pageX | long | ✘ | ✘ | |
pageY | long | ✘ | ✘ | |
screenX | long | ✘ | ✘ | |
screenY | long | ✘ | ✘ |
Touch
createTouchList
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).
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
touches |
| ✘ | ✘ |
TouchList
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 yet standardized, but it may appear
in some form in a future specification.
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 a Web application can process touch events, it can intercept them, 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 can react to the subsequent mouse events instead.
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.
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.
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, Cathy Chan, and Boris Zbarsky. If we inadvertently omitted your name, please let me know.
The group acknowledges the following contributors to this specification's test suite: Matt Brubeck, Olli Pettay, Art Barstow, Cathy Chan and Rick Byers.
This section is non-normative.
The following non-substantive changes were made since the 09 May 2013 Proposed Recommendation was published:
optional
keyword from the Web IDL describing the createTouchList interface, per section 3.2.3. Operations of the Web IDL specification.