Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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 document was published by the Web Events Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. 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 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.
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.
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.
Touch InterfaceThis interface defines an individual point of contact for a touch event.
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;
readonly attribute long radiusX;
readonly attribute long radiusY;
readonly attribute float rotationAngle;
readonly attribute float force;
};
clientX of type long, readonlyclientY of type long, readonlyforce of type float, readonly0 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.
identifier of type long, readonlyThe algorithm for determining the identifier value is as follows:
0
Touch object in any
active touch event session
pageX of type long, readonlypageY of type long, readonlyradiusX of type long, readonly1 if no value is
known. The value must be positive.
Issue: What are units of radiusX/radiusY? CSS Pixels?
radiusY of type long, readonly1 if no value is
known. The value must be positive.
rotationAngle of type float, readonly
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.)
screenX of type long, readonlyscreenY of type long, readonlyTouchList InterfaceThis interface defines a list of individual points of contact for a touch event.
interface TouchList {
readonly attribute unsigned long length;
getter Touch item (in unsigned long index);
Touch identifiedTouch (in long identifier);
};
length of type unsigned long, readonlyTouches in the list
identifiedTouchTouch with long identifier from the
list
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| identifier | long | ✘ | ✘ |
TouchitemTouch with index index from the list,
sorted in order from latest to earliest
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| index | unsigned long | ✘ | ✘ |
getter TouchTouchEvent InterfaceThis interface defines the touchstart, touchend, touchmove, touchenter, touchleave, and touchcancel event types.
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;
readonly attribute EventTarget? relatedTarget;
void initTouchEvent (in DOMString type, in boolean canBubble, in boolean cancelable, in AbstractView view, in long detail, in boolean ctrlKey, in boolean altKey, in boolean shiftKey, in boolean metaKey, in TouchList touches, in TouchList targetTouches, in TouchList changedTouches);
};
altKey of type boolean, readonlytrue if the alt (Alternate) key modifier is activated;
otherwise false
changedTouches of type TouchList, readonlyTouches for every point of contact which contributed
to the event
ctrlKey of type boolean, readonlytrue if the ctrl (Control) key modifier is activated;
otherwise false
metaKey of type boolean, readonlytrue if the meta (Meta) key modifier is activated;
otherwise false. On some platforms this attribute may
map to a differently-named key modifier.
null.
shiftKey of type boolean, readonlytrue if the shift (Shift) key modifier is activated;
otherwise false
targetTouches of type TouchList, readonlyTouches for every point of contact currently
touching the surface, which started on the same target
touches of type TouchList, readonlyTouches for every point of contact currently
touching the surface
initTouchEvent| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| type | DOMString | ✘ | ✘ | |
| canBubble | boolean | ✘ | ✘ | |
| cancelable | boolean | ✘ | ✘ | |
| view | AbstractView | ✘ | ✘ | |
| detail | long | ✘ | ✘ | |
| ctrlKey | boolean | ✘ | ✘ | |
| altKey | boolean | ✘ | ✘ | |
| shiftKey | boolean | ✘ | ✘ | |
| metaKey | boolean | ✘ | ✘ | |
| touches | | ✘ | ✘ | |
| targetTouches | | ✘ | ✘ | |
| changedTouches | | ✘ | ✘ |
voidA 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.
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.
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.
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.
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.
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.
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.
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 (in AbstractView view, in EventTarget target, in long identifier, in long pageX, in long pageY, in long screenX, in long screenY, in optional long clientX, in optional long clientY, in optional long radiusX, in optional long radiusY, in optional float rotationAngle, in optional float force);
TouchList createTouchList (in Touch[] touches);
TouchList createTouchList (in Touch touch);
};
createTouchTouch object with the specified attributes.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| view | AbstractView | ✘ | ✘ | |
| target | EventTarget | ✘ | ✘ | |
| identifier | long | ✘ | ✘ | |
| pageX | long | ✘ | ✘ | |
| pageY | long | ✘ | ✘ | |
| screenX | long | ✘ | ✘ | |
| screenY | long | ✘ | ✘ | |
| clientX | long | ✘ | ✔ | |
| clientY | long | ✘ | ✔ | |
| radiusX | long | ✘ | ✔ | |
| radiusY | long | ✘ | ✔ | |
| rotationAngle | float | ✘ | ✔ | |
| force | float | ✘ | ✔ |
TouchcreateTouchListTouchList object containing the specified
Touch objects.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| touches | | ✘ | ✘ |
TouchListcreateTouchListTouchList object containing a single Touch.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| touch | | ✘ | ✘ |
TouchListIssue: Does createTouch need to take both pageX/pageY and clientX/clientY as parameters? If not, which pair should be removed?
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.
The default actions and ordering of any further touch and mouse events are implementation-defined, except as specified elsewhere.
TouchEvent event with at least one non-empty TouchList.
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, and Cathy Chan. If I inadvertently omitted your name, please let me know.
No informative references.