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). It also addresses pen-tablet devices, such as drawing tablets, with consideration toward stylus capabilities.

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

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 public-webevents@w3.org (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.

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.

Note

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.

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.

WindowProxy is defined in [HTML5].

WebIDL Conformance

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.

3. 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;
  };

3.1 Attributes

clientX of type long, readonly
The horizontal coordinate of point relative to the viewport in pixels, excluding any scroll offset
clientY of type long, readonly
The vertical coordinate of point relative to the viewport in pixels, excluding any scroll offset
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.
pageX of type long, readonly
The horizontal coordinate of point relative to the viewport in pixels, including any scroll offset
pageY of type long, readonly
The vertical coordinate of point relative to the viewport in pixels, including any scroll offset
screenX of type long, readonly
The horizontal coordinate of point relative to the screen in pixels
screenY of type long, readonly
The vertical coordinate of point relative to the screen in pixels
target of type EventTarget, readonly
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.

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.

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);
  };

4.1 Attributes

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

4.2 Methods

item
returns the Touch at the specified index in the list or null if the index is not less than the length of the list.
ParameterTypeNullableOptionalDescription
indexunsigned long✘✘
Return type: Touch, nullable

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;
  };

5.1 Attributes

altKey of type boolean, readonly
true if the alt (Alternate) key modifier is activated; otherwise false
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 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
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.
touches of type TouchList, readonly
a list of Touches for every point of contact currently touching the surface.

5.2 TouchEvent Implementer's Note

This section is non-normative.

Note

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

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 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:

Example 1
<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:

Example 2
<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 List of TouchEvent types

This 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

5.5 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.6 The touchend event

A user agent must dispatch this event type to indicate when the user removes a