--- a/touchevents.html Sat Apr 30 10:38:20 2011 -0400
+++ b/touchevents.html Sun May 01 11:04:32 2011 +0200
@@ -95,40 +95,89 @@
</head>
<body>
<section id='abstract'>
- 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.
+ 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.
</section>
<section id='introduction' class='informative'>
<h2>Introduction</h2>
-
- <p>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.</p>
- <p>Meanwhile, native applications are capable of handling both cases with the provided system APIs.</p>
+ <p>
+ 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.
+ </p>
- <p>The Touch Events specification provides a solution to this problem by specifing interfaces to allow web applications to directly handle touch events, and multiple touch points for capable devices.</p>
+ <p>
+ Meanwhile, native applications are capable of handling both cases with
+ the provided system APIs.
+ </p>
+
+ <p>
+ The Touch Events specification provides a solution to this problem by
+ specifing interfaces to allow web applications to directly handle touch
+ events, and multiple touch points for capable devices.
+ </p>
</section>
<section id='conformance'>
- <p>This specification defines conformance criteria that apply to a single product: the <dfn id="dfn-user-agent">user agent</dfn> that implements the interfaces that it contains. </p>
+ <p>
+ This specification defines conformance criteria that apply to a single
+ product: the <dfn id="dfn-user-agent">user agent</dfn> that implements
+ the interfaces that it contains.
+ </p>
- <p>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. </p>
+ <p>
+ 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.
+ </p>
- <p> A conforming implementation is required to implement all fields defined in this specification. </p>
+ <p>
+ A conforming implementation is required to implement all fields
+ defined in this specification.
+ </p>
</section>
<section>
<h2><a>Touch</a> Interface</h2>
- <p>This interface defines an individual point of contact for a touch event.</p>
+ <p>
+ This interface defines an individual point of contact for a touch
+ event.
+ </p>
<dl title='interface Touch' class='idl'>
<dt>readonly attribute long identifier</dt>
<dd>
- An identification number for each <a>touch point</a>, unique to that <a>touch point</a> per session.
+ An identification number for each <a>touch point</a>, unique to that
+ <a>touch point</a> per session.
- <p>The algorithm for determining the <a>identifier</a> value is as follows:</p>
+ <p>
+ The algorithm for determining the <a>identifier</a> value is as
+ follows:
+ </p>
<ol>
- <li>if there are no other <a>active touch event session</a>s, the value of <a>identifier</a> must be <code>0</code></li>
- <li>if there is at least one <a>active touch event session</a>, the value of <a>identifier</a> must be the lowest integer not currently used by any active <a>Touch</a> object in any <a>active touch event session</a></li>
+ <li>
+ if there are no other <a>active touch event session</a>s, the
+ value of <a>identifier</a> must be <code>0</code>
+ </li>
+ <li>
+ if there is at least one <a>active touch event session</a>, the
+ value of <a>identifier</a> must be the lowest integer not
+ currently used by any active <a>Touch</a> object in any
+ <a>active touch event session</a>
+ </li>
</ol>
</dd>
@@ -143,30 +192,41 @@
<dt>readonly attribute long clientX</dt>
<dd>
- x-coordinate of point relative to the viewport, excluding any scroll offset
+ x-coordinate of point relative to the viewport, excluding any scroll
+ offset
</dd>
<dt>readonly attribute long clientY</dt>
<dd>
- y-coordinate of point relative to the viewport, excluding any scroll offset
+ y-coordinate of point relative to the viewport, excluding any scroll
+ offset
</dd>
<dt>readonly attribute long pageX</dt>
<dd>
- x-coordinate of point relative to the viewport, including any scroll offset
+ x-coordinate of point relative to the viewport, including any scroll
+ offset
</dd>
<dt>readonly attribute long pageY</dt>
<dd>
- y-coordinate of point relative to the viewport, including any scroll offset
+ y-coordinate of point relative to the viewport, including any scroll
+ offset
</dd>
<dt>readonly attribute long radiusX</dt>
<dd>
- 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 <a>screenX</a>; <code>1</code> if no value is known. The value must be positive.
- <p class="issue" id="issue-units"><strong>Issue:</strong> What are units of radiusX/radiusY? CSS Pixels?</p>
+ 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 <a>screenX</a>; <code>1</code> if no value is
+ known. The value must be positive.
+ <p class="issue" id="issue-units"><strong>Issue:</strong> What are
+ units of radiusX/radiusY? CSS Pixels?</p>
</dd>
<dt>readonly attribute long radiusY</dt>
<dd>
- 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 <a>screenY</a>; <code>1</code> if no value is known. The value must be positive.
+ 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 <a>screenY</a>; <code>1</code> if no value is
+ known. The value must be positive.
</dd>
<dt>readonly attribute float rotationAngle</dt>
@@ -189,16 +249,31 @@
<dt>readonly attribute float force</dt>
<dd>
- a relative value of pressure applied, in the range <code>0</code> to <code>1</code>, where <code>0</code> is no pressure, and <code>1</code> is the highest level of pressure the touch device is capable of sensing; <code>0</code> if no value is known. In environments where <a>force</a> is known, the absolute pressure represented by the <a>force</a> attribute, and the sensitivity in levels of pressure, may vary.
+ a relative value of pressure applied, in the range <code>0</code> to
+ <code>1</code>, where <code>0</code> is no pressure, and
+ <code>1</code> is the highest level of pressure the touch device is
+ capable of sensing; <code>0</code> if no value is known. In
+ environments where <a>force</a> is known, the absolute pressure
+ represented by the <a>force</a> attribute, and the sensitivity in
+ levels of pressure, may vary.
- <p class="issue" id="issue-inkml"><strong>Issue:</strong> Consider aligning with other "channels" and values from <a href="http://www.w3.org/TR/InkML/#channelContents">Ink Markup Language (InkML)</a>, in addition to <a>force</a>, e.g. adding <a>angle</a>, <a>clientZ</a>, <a>rotation</a>, etc.</p>
+ <p class="issue" id="issue-inkml">
+ <strong>Issue:</strong>
+ Consider aligning with other "channels" and values from
+ <a href="http://www.w3.org/TR/InkML/#channelContents">Ink Markup
+ Language (InkML)</a>, in addition to <a>force</a>, e.g. adding
+ <a>angle</a>, <a>clientZ</a>, <a>rotation</a>, etc.
+ </p>
</dd>
</dl>
</section>
<section>
<h2><a>TouchList</a> Interface</h2>
- <p>This interface defines a list of individual points of contact for a touch event.</p>
+ <p>
+ This interface defines a list of individual points of contact for a
+ touch event.
+ </p>
<dl title='interface TouchList' class='idl'>
<dt>readonly attribute unsigned long length</dt>
@@ -207,48 +282,62 @@
</dd>
<dt>getter <a>Touch</a> item (in unsigned long <a>index</a>)</dt>
<dd>
- returns the <a>Touch</a> with index <a>index</a> from the list, sorted in order from latest to earliest
+ returns the <a>Touch</a> with index <a>index</a> from the list,
+ sorted in order from latest to earliest
</dd>
<dt><a>Touch</a> identifiedTouch (in long <a>identifier</a>)</dt>
<dd>
- returns the first <a>Touch</a> with long <a>identifier</a> from the list
+ returns the first <a>Touch</a> with long <a>identifier</a> from the
+ list
</dd>
</dl>
</section>
<section>
<h2><a>TouchEvent</a> Interface</h2>
- <p>This interface defines the <a>touchstart</a>, <a>touchend</a>, <a>touchmove</a>, <a>touchenter</a>, <a>touchleave</a>, and <a>touchcancel</a> event types.</p>
+ <p>
+ This interface defines the <a>touchstart</a>, <a>touchend</a>,
+ <a>touchmove</a>, <a>touchenter</a>, <a>touchleave</a>, and
+ <a>touchcancel</a> event types.
+ </p>
<dl title='interface TouchEvent : UIEvent' class='idl'>
<dt>readonly attribute <a>TouchList</a> touches</dt>
<dd>
- a list of <a>Touch</a>es for every point of contact currently touching the surface
+ a list of <a>Touch</a>es for every point of contact currently
+ touching the surface
</dd>
<dt>readonly attribute <a>TouchList</a> targetTouches</dt>
<dd>
- a list of <a>Touch</a>es for every point of contact currently touching the surface, which started on the same target
+ a list of <a>Touch</a>es for every point of contact currently
+ touching the surface, which started on the same target
</dd>
<dt>readonly attribute <a>TouchList</a> changedTouches</dt>
<dd>
- a list of <a>Touch</a>es for every point of contact which contributed to the event
+ a list of <a>Touch</a>es for every point of contact which contributed
+ to the event
</dd>
<dt>readonly attribute boolean altKey</dt>
<dd>
- <code>true</code> if the alt (Alternate) key modifier is activated; otherwise <code>false</code>
+ <code>true</code> if the alt (Alternate) key modifier is activated;
+ otherwise <code>false</code>
</dd>
<dt>readonly attribute boolean metaKey</dt>
<dd>
- <code>true</code> if the meta (Meta) key modifier is activated; otherwise <code>false</code>. On some platforms this attribute may map to a differently-named key modifier.
+ <code>true</code> if the meta (Meta) key modifier is activated;
+ otherwise <code>false</code>. On some platforms this attribute may
+ map to a differently-named key modifier.
</dd>
<dt>readonly attribute boolean ctrlKey</dt>
<dd>
- <code>true</code> if the ctrl (Control) key modifier is activated; otherwise <code>false</code>
+ <code>true</code> if the ctrl (Control) key modifier is activated;
+ otherwise <code>false</code>
</dd>
<dt>readonly attribute boolean shiftKey</dt>
<dd>
- <code>true</code> if the shift (Shift) key modifier is activated; otherwise <code>false</code>
+ <code>true</code> if the shift (Shift) key modifier is activated;
+ otherwise <code>false</code>
</dd>
<dt>readonly attribute EventTarget? relatedTarget</dt>
<dd>
@@ -263,7 +352,8 @@
<!-- Methods -->
<dt>void initTouchEvent()</dt>
<dd>
- initializes a TouchEvent created through the <a>DocumentEvent</a> interface.
+ initializes a TouchEvent created through the <a>DocumentEvent</a>
+ interface.
<dl class='parameters'>
<dt>DOMString type</dt> <dd></dd>
<dt>boolean canBubble</dt> <dd></dd>
@@ -282,83 +372,113 @@
</dl>
<section>
- <h3 id="event-touchstart">The <dfn class="event">touchstart</dfn> event</h3>
- <p>A user agent must dispatch this event type to indicate when the user
- places a <a>touch point</a> on the touch surface.</p>
+ <h3 id="event-touchstart">The <dfn class="event">touchstart</dfn>
+ event</h3>
+ <p>
+ A user agent must dispatch this event type to indicate when the user
+ places a <a>touch point</a> on the touch surface.
+ </p>
- <p>The target of this event must be an <a>Element</a>.</p>
+ <p>
+ The target of this event must be an <a>Element</a>.
+ </p>
</section>
<section>
<h3 id="event-touchend">The <dfn class="event">touchend</dfn> event</h3>
- <p>A user agent must dispatch this event type to indicate when the user
- removes a <a>touch point</a> from the touch surface, also including
- cases where the touch point physically leaves the touch surface, such
- as being dragged off of the screen.</p>
+ <p>
+ A user agent must dispatch this event type to indicate when the user
+ removes a <a>touch point</a> from the touch surface, also including
+ cases where the touch point physically leaves the touch surface, such
+ as being dragged off of the screen.
+ </p>
- <p>The <a>target</a> of this event must be the same <a>Element</a> that
- received the <a>touchstart</a> event when this <a>touch point</a> was
- placed on the surface, even if the <a>touch point</a> has since moved
- outside the interactive area of the <a>target</a> element.</p>
+ <p>
+ The <a>target</a> of this event must be the same <a>Element</a> that
+ received the <a>touchstart</a> event when this <a>touch point</a> was
+ placed on the surface, even if the <a>touch point</a> has since moved
+ outside the interactive area of the <a>target</a> element.
+ </p>
- <p>The <a>touch point</a> or points that were removed must be included
- in the <a>changedTouches</a> attribute of the <a>TouchEvent</a>, and
- must not be included in the <a>touches</a> and <a>targetTouches</a>
- attributes.</p>
+ <p>
+ The <a>touch point</a> or points that were removed must be included
+ in the <a>changedTouches</a> attribute of the <a>TouchEvent</a>, and
+ must not be included in the <a>touches</a> and <a>targetTouches</a>
+ attributes.
+ </p>
</section>
<section>
<h3 id="event-touchmove">The <dfn class="event">touchmove</dfn> event</h3>
- <p>A user agent must dispatch this event type to indicate when the user
- moves a <a>touch point</a> along the touch surface.
-
- <p>The <a>target</a> of this event must be the same <a>Element</a> that
- received the <a>touchstart</a> event when this <a>touch point</a> was
- placed on the surface, even if the <a>touch point</a> has since moved
- outside the interactive area of the <a>target</a> element.</p>
+ <p>
+ A user agent must dispatch this event type to indicate when the user
+ moves a <a>touch point</a> along the touch surface.
+ </p>
- <p>If the values of <a>radiusX</a>, <a>radiusY</a>,
- <a>rotationAngle</a>, or <a>force</a> are known, then the user agent
- also must dispatch this event type to indicate when any of these
- attributes of a <a>touch point</a> have changed.</p>
+ <p>
+ The <a>target</a> of this event must be the same <a>Element</a> that
+ received the <a>touchstart</a> event when this <a>touch point</a> was
+ placed on the surface, even if the <a>touch point</a> has since moved
+ outside the interactive area of the <a>target</a> element.
+ </p>
- <p>Note that the rate at which the user agent sends <a>touchmove</a>
- events is implementation-defined, and may depend on hardware
- capabilities and other implementation details.</p>
+ <p>
+ If the values of <a>radiusX</a>, <a>radiusY</a>,
+ <a>rotationAngle</a>, or <a>force</a> are known, then the user agent
+ also must dispatch this event type to indicate when any of these
+ attributes of a <a>touch point</a> have changed.
+ </p>
+
+ <p>
+ Note that the rate at which the user agent sends <a>touchmove</a>
+ events is implementation-defined, and may depend on hardware
+ capabilities and other implementation details.
+ </p>
</section>
<section>
<h3 id="event-touchenter">The <dfn class="event">touchenter</dfn> event</h3>
- <p>A user agent must dispatch this event type to indicate when a
- <a>touch point</a> moves onto the interactive area defined by a DOM
- element. Events of this type must not bubble.</p>
+ <p>
+ A user agent must dispatch this event type to indicate when a
+ <a>touch point</a> moves onto the interactive area defined by a DOM
+ element. Events of this type must not bubble.
+ </p>
</section>
<section>
<h3 id="event-touchleave">The <dfn class="event">touchleave</dfn> event</h3>
- <p>A user agent must dispatch this event type to indicate when a
- <a>touch point</a> moves off the interactive area defined by a DOM
- element. Events of this type must not bubble.</p>
+ <p>
+ A user agent must dispatch this event type to indicate when a
+ <a>touch point</a> moves off the interactive area defined by a DOM
+ element. Events of this type must not bubble.
+ </p>
</section>
<section>
<h3 id="event-touchcancel">The <dfn class="event">touchcancel</dfn> event</h3>
- <p>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 <a>touch point</a>s
- on the touch surface than the device or implementation is configured to
- store, in which case the earliest <a>Touch</a> object in the
- <a>TouchList</a> should be removed.</p>
+ <p>
+ 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 <a>touch
+ point</a>s on the touch surface than the device or implementation is
+ configured to store, in which case the earliest <a>Touch</a> object
+ in the <a>TouchList</a> should be removed.
+ </p>
</section>
</section>
<section>
<h2><a>DocumentTouch</a> Interface</h2>
- <p>The <a>DocumentTouch</a> interface provides a mechanism by which the user can create <a>Touch</a> and <a>TouchList</a> objects. The <a>DocumentTouch</a> interface must be implemented on the <a>Document</a> object.</p>
+ <p>
+ The <a>DocumentTouch</a> interface provides a mechanism by which the
+ user can create <a>Touch</a> and <a>TouchList</a> objects. The
+ <a>DocumentTouch</a> interface must be implemented on the
+ <a>Document</a> object.
+ </p>
<dl title='interface DocumentTouch' class='idl'>
<dt>Touch createTouch()</dt>
@@ -383,7 +503,8 @@
<dt>TouchList createTouchList()</dt>
<dd>
- Creates a <a>TouchList</a> object containing the specified <a>Touch</a> objects.
+ Creates a <a>TouchList</a> object containing the specified
+ <a>Touch</a> objects.
<dl class='parameters'>
<dt>Touch[] touches</dt> <dd></dd>
</dl>
@@ -398,7 +519,8 @@
</dd>
</dl>
- <p class="issue" id="issue-createTouch-pageXY"><strong>Issue:</strong>
+ <p class="issue" id="issue-createTouch-pageXY">
+ <strong>Issue:</strong>
Does <a>createTouch</a> need to take both pageX/pageY <em>and</em>
clientX/clientY as parameters? If not, which pair should be removed?
</p>
@@ -406,17 +528,21 @@
<section id="mouse-events">
<h2>Interaction with Mouse Events</h2>
- <p>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 <a>touchstart</a> event type must be
- dispatched before any mouse event types for that action. If the
- <a>preventDefault</a> method of <a>touchstart</a> or <a>touchmove</a>
- is called, the user agent should not dispatch any mouse event that
- would be a consequential result of the the prevented touch event. </p>
+ <p>
+ 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 <a>touchstart</a> event type must be
+ dispatched before any mouse event types for that action. If the
+ <a>preventDefault</a> method of <a>touchstart</a> or <a>touchmove</a>
+ is called, the user agent should not dispatch any mouse event that
+ would be a consequential result of the the prevented touch event.
+ </p>
- <p>The default actions and ordering of any further touch and mouse events
- are implementation-defined, except as specified elsewhere.</p>
+ <p>
+ The default actions and ordering of any further touch and mouse events
+ are implementation-defined, except as specified elsewhere.
+ </p>
</section>
<section>
@@ -424,28 +550,51 @@
<dl>
<dt><dfn>active touch event session</dfn></dt>
- <dd>A conceptual state in which there is at least one instance of a <a>TouchEvent</a> event with at least one non-empty <a>TouchList</a>.
+ <dd>
+ A conceptual state in which there is at least one instance of a
+ <a>TouchEvent</a> event with at least one non-empty <a>TouchList</a>.
<!-- <pre class='example'>
</pre> -->
</dd>
<dt><dfn>touch point</dfn></dt>
- <dd>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.</dd>
+ <dd>
+ 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.
+ </dd>
</dl>
</section>
<section id='issues' class='informative'>
<h2>Issues</h2>
- <p>The working group maintains <a href='http://www.w3.org/2010/webevents/track/products/2'>a list of open issues in this specification</a>. These issues may be addressed in future revisions of the specification.</p>
+ <p>
+ The working group maintains <a
+ href='http://www.w3.org/2010/webevents/track/products/2'
+ >a list of open issues in this specification</a>. These issues may be
+ addressed in future revisions of the specification.
+ </p>
</section>
<section class='appendix informative'>
<h2>Acknowledgements</h2>
<p>
- 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 <a href="http://dev.w3.org/2009/dap/ReSpec.js/documentation.html">ReSpec.js spec authoring tool</a>, and the WebEvents WG for their many contributions.
+ 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 <a
+ href="http://dev.w3.org/2009/dap/ReSpec.js/documentation.html"
+ >ReSpec.js spec authoring tool</a>, and the WebEvents WG for their many
+ contributions.
</p>
- <p>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.</p>
+ <p>
+ 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.
+ </p>
</section>
</body>
</html>