The Touch Interface 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.

Introduction

User Agents that run on terminals which provide touch input to use web applications typically use interpreted mouse events to allow the 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 exact intended user experience. Additionally, it is not possible to handle concurrent input regardless of the device capability, due the 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 with a interface to allow web applications to directly handle touch events, and multiple touch points for capable devices.

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.

TouchPoint Interface

This interface defines an individual point of contact for a touch event.

readonly attribute long identifier
An identification number for each touch point, unique to that touch point per session.

The algorithm for determining the identifier value is as follows:

  1. if there are no other active touch event sessions, the value of identifier must be 0
  2. if there is at least one active touch event session, the value of identifier must be the lowest integer not currently used by any active TouchPoint object in any active touch event session
readonly attribute EventTarget target
the original proximal event target for this touch point. The target must be an Element.
readonly attribute long screenX
x-coordinate of point relative to the screen
readonly attribute long screenY
y-coordinate of point relative to the screen
readonly attribute long clientX
x-coordinate of point relative to the viewport, excluding any scroll offset
readonly attribute long clientY
y-coordinate of point relative to the viewport, excluding any scroll offset
readonly attribute long pageX
x-coordinate of point relative to the viewport, including any scroll offset
readonly attribute long pageY
y-coordinate of point relative to the viewport, including any scroll offset
readonly attribute long radiusX
the radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the x-axis, in pixels of the same scale as screenX; 1 if no value is known. The value must be positive.

Issue: What are units of radiusX/radiusY? CSS Pixels?

readonly attribute long radiusY
the radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the y-axis, in pixels of the same scale as screenY; 1 if no value is known. The value must be positive.
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.

Issue: Consider aligning with other "channels" and values from Ink Markup Language (InkML), in addition to force, e.g. adding angle, clientZ, rotation, etc.

TouchList Interface

This interface defines a list of individual points of contact for a touch event.

readonly attribute unsigned long length
returns the number of touchpoints in the list
caller getter TouchPoint item (in unsigned long index)
returns the touchpoint with index index from the list, sorted in order from latest to earliest
caller getter TouchPoint identifiedPoint (in long identifier)
returns the first touchpoint with long identifier from the list

TouchEvent Interface

This interface defines the touchstart, touchend, touchmove, touchenter, touchleave, and touchcancel event types.

readonly attribute TouchList touches
a list of TouchPoints for every point of contact currently touching the surface
readonly attribute TouchList targetTouches
a list of TouchPoints for every point of contact currently touching the surface, which started on the same target
readonly attribute TouchList changedTouches
a list of TouchPoints for every point of contact which contributed to the event
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
readonly attribute EventTarget? relatedTarget
identifies a secondary EventTarget related to a touch event. This attribute is used with the touchenter event to indicate the EventTarget the touch point exited, and with the touchleave event to indicate the EventTarget the touch point entered. For other event types, this attribute must be null.
void initTouchEvent()
initializes a TouchEvent created through the DocumentEvent interface.
DOMString type
boolean canBubble
boolean cancelable
DOMWindow view
long detail
boolean ctrlKey
boolean altKey
boolean shiftKey
boolean metaKey
TouchList touches
TouchList targetTouches
TouchList changedTouches

Issue: define behavior of preventDefault() method.

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 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 touchmove event

A user agent must dispatch this event type to indicate when the user moves a touch point along the touch surface, even outside the interactive area of the target element.

If the values of radiusX, radiusY, rotationAngle, or force are known, then the user agent also must dispatch this event type to indicate when any of these attributes of a touch point have changed.

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.

The touchenter event

A user agent must dispatch this event type to indicate when a touch point moves onto the interactive area defined by a DOM element. Events of this type must not bubble.

The touchleave event

A user agent must dispatch this event type to indicate when a touch point moves off the interactive area defined by a DOM element. Events of this type must not bubble.

The touchcancel event

A user agent must dispatch this event type to indicate when a TouchPoint 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 TouchPoint object in the TouchList should be removed.

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. The ordering of any further touch events and mouse events is left to the implementation, except as specified elsewhere.

Glossary

active touch event session
A conceptual state in which there is at least one instance of a TouchEvent event with at least one non-empty TouchList.
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.

Acknowledgements

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 writeups 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, . If I inadvertently omitted your name, please let me know.