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 15 December 2011 Candidate Recommendation.
Comments for the
13 September 2011 Last Call Working Draft
are tracked in the
comment tracking document
and comments for the
27 October 2011 Last Call Working Draft
are tracked in a separate
comment tracking document.
During the Candidate Recommendation period, the WG will complete its
test suite and two or more independent implementations
must pass each test before the specification exits Candidate Recommendation.
The group will also create an Implementation Report.
This document was published by the Web Events Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to [email protected] (subscribe, archives). W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 15 March 2012. All feedback is welcome.
Publication as a Candidate Recommendation 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.
Implementors should note that
patent disclosures
have been made related to this specification.
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
No exceptions.
clientY of type long, readonly-
The vertical coordinate of point relative to the viewport in pixels,
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-
The horizontal coordinate of point relative to the viewport in pixels,
including any scroll offset
No exceptions.
pageY of type long, readonly-
The vertical coordinate of point relative to the viewport in pixels,
including any scroll offset
No exceptions.
screenX of type long, readonly-
The horizontal coordinate of point relative to the screen in pixels
No exceptions.
screenY of type long, readonly-
The vertical coordinate of point relative to the screen in pixels
No exceptions.
target of type EventTarget, readonly-
The 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 that element.
No exceptions.
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
| Parameter | Type | Nullable | Optional | Description |
|---|
| identifier | long | ✘ | ✘ | |
No exceptions.
item-
returns the
Touch at the specified index in the list
No exceptions.
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
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 and
touchcancel events 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.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 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.
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 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.
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.
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.
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 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.
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.
- preventDefault
-
If a event is cancelable, the preventDefault method is used to signify
that the event is to be canceled, and any default actions defined in the
user agent as a result of this event, or consequential events from the
canceled event will not occur. Calling this method on non-cancelable
events will have no effect.