--- a/html/DOM3-Events.html Thu Dec 17 18:45:59 2009 +0900
+++ b/html/DOM3-Events.html Thu Jan 21 03:53:41 2010 +0900
@@ -172,11 +172,11 @@
</p>
<h1 id="Overview-title">Document Object Model (DOM) Level 3 Events Specification</h1>
<!-- @@@ -->
- <h2 id="Overview-W3C-doctype">W3C Editor's Draft <time datetime="2009-12-14">17 December 2009</time></h2>
+ <h2 id="Overview-W3C-doctype">W3C Editor's Draft <time datetime="2009-12-14">20 January 2009</time></h2>
<dl>
<dt>This version:</dt>
<dd>
- <a href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.108">http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.108</a>
+ <a href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.109">http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.109</a>
</dd>
<dt>Latest stable version:</dt>
<dd>
@@ -184,7 +184,7 @@
</dd>
<dt>Previous version:</dt>
<dd>
- <a href="http://dev.w3.org/cvsweb/~checkout~/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.107">http://dev.w3.org/cvsweb/~checkout~/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.107</a>
+ <a href="http://dev.w3.org/cvsweb/~checkout~/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.108">http://dev.w3.org/cvsweb/~checkout~/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.108</a>
</dd>
<dt>Editor's Draft:</dt>
<dd>
@@ -354,7 +354,8 @@
<li>
<a href="#events-mouseevents">5.2.3 Mouse Event Types</a>
<ul class="toc">
- <li><a href="#events-mouse-event-order">5.2.7.1 Mouse Event Order</a></li>
+ <li><a href="#events-mouseevent-coord-norm">5.2.3.1 Coordinate Normalization</a></li>
+ <li><a href="#events-mouse-event-order">5.2.3.2 Mouse Event Order</a></li>
<li><a class="eventtype" href="#event-type-click"><code>click</code> event</a></li>
<li><a class="eventtype" href="#event-type-dblclick"><code>dblclick</code> event</a></li>
<li><a class="eventtype" href="#event-type-mousedown"><code>mousedown</code> event</a></li>
@@ -868,7 +869,8 @@
<!-- div2 Events-flow-cancelation -->
<div class="div2">
<h3 class="div2"><a id="event-flow-activation" href="#event-flow-activation">3.3 Activation requests and behavior</a></h3>
- <p>(This section is currently being rewritten.)</p>
+ <p class="note" id="activation-rewritten"><strong>Note:</strong> This section is currently being rewritten.</p>
+ <p class="warning" id="activation-deprecated"><strong>Warning!</strong> The <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> <a class="def" href="#glossary-event-type">event type</a> is deprecated in this specification, and this section will be revised to reflect this.</p>
<p>Event targets may have associated <a class="def" href="#glossary-activation-behavior">activation behavior</a> that implementations perform in response to an <em>activation request</em>. As an example, the typical activation behavior associated with hyperlinks is to follow the link. Activation requests are typically initiated by users through an input device.</p>
<p>In terms of this specification, the activation behavior of the event target shall be the <a class="def" href="#glossary-default-action">default action</a> of the <a class="def" href="#glossary-event-type">event type</a> <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a>. Authors should use this <a class="def" href="#glossary-event-type">event type</a> whenever they wish to make or react to an activation request.</p>
<p>Implementations must dispatch the <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> event as the <a class="def" href="#glossary-default-action">default action</a> of a <a class="eventtype" href="#event-type-click"><code>click</code></a> event. This <a class="eventtype" href="#event-type-click"><code>click</code></a> event shall be either part of the activation request (e.g., a user requests activiation using a mouse), or synthesized by the implementation to accomodate legacy applications. Context information of such a <code>click</code> event is implementation dependent.</p>
@@ -1025,7 +1027,7 @@
<dt><code class="attribute-name"><a id="events-event-type-timeStamp">timeStamp</a></code> of type <code>DOMTimeStamp</code>, readonly</dt>
<dd>Used to specify the time at which the event was created in milliseconds relative to 1970-01-01T00:00:00Z. Due to the fact that some systems may not provide this information the value of <code>timeStamp</code> may be not available for all events. When not available, the value shall be <code>0</code>.<br /></dd>
<dt><code class="attribute-name"><a id="events-event-type-type">type</a></code> of type <code>DOMString</code>, readonly</dt>
- <dd>The name of the event type. The name must be a <code>DOMString</code>, must not contain whitespace characters, and must be case-sensitive.<br /></dd>
+ <dd>The name of the event type. The name must be a <code>DOMString</code>. <a href="#conf-specs">Specifications that define events</a>, <a href="#conf-authors">authors</a>, and <a href="#conf-author-tools">authoring tools</a> must use case-sensitive event type names that do not contain whitespace characters.<br /></dd>
</dl>
</dd>
<dt>
@@ -1549,7 +1551,7 @@
<p>The following table provides a non-normative summary of the event types defined in this specification. All events must accomplish the capture and target phases, but not all of them must accomplish the bubbling phase (see also <a href="#event-flow">Event dispatch and DOM event flow</a>). Some events are not <a href="#events-dt-cancelable-event">cancelable</a> (see <a href="#event-flow-cancelation">Default actions and cancelable events</a>). Some events must only be dispatched to a specific set of possible targets in the DOM event flow, specified using node types. Contextual information related to the event type must be accessible using DOM interfaces.</p>
<table border="1" cellpadding="2" cellspacing="0" summary="This table contains the complete list of event types defined by DOM Level 3 Events. The first column contains the local name of the event type. The second column indicates if the event accomplish the bubbling phase or not (all events accomplish the capture and target phases). The third column indicates if the default action associated with the event can be canceled. The fourth column indicates the nodes that can be target of the event. the fifth (and last) column indicates the DOM interface implemented by the event object.">
<tr>
- <th>type</th>
+ <th>Event Type</th>
<th>Bubbling phase</th>
<th>Proximal event target types</th>
<th>DOM interface</th>
@@ -1560,7 +1562,7 @@
<td>
<a class="eventtype" href="#event-type-abort"><code>abort</code></a>
</td>
- <td>Yes</td>
+ <td>No</td>
<td>
<code>Element</code>
</td>
@@ -1852,7 +1854,7 @@
<td>
<a class="eventtype" href="#event-type-error"><code>error</code></a>
</td>
- <td>Yes</td>
+ <td>No</td>
<td>
<code>Element</code>
</td>
@@ -2278,6 +2280,10 @@
</dt>
<dd><table border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0"><tr class="assert must"><th>Type</th><td class="eventname"><strong><code>DOMActivate</code></strong></td></tr><tr class="assert must"><th>Interface</th><td><a href="#events-Events-UIEvent"><code>UIEvent</code></a></td></tr><tr class="assert must"><th>Bubbles</th><td>Yes</td></tr><tr class="assert must"><th>Target</th><td><code>Element</code></td></tr><tr class="assert must"><th>Cancelable</th><td>Yes</td></tr><tr class="assert must"><th>Default action</th><td>none</td></tr><tr class="assert must"><th>Context info</th><td><a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> is in use.</td></tr></table>
A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a button, link, or other state-changing element is activated. Refer to <a href="#event-flow-activation">Activation requests and behavior</a> for more details.</dd>
+
+ <p class="warning" id="DOMActivate-deprecated"><strong>Warning!</strong> The <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> <a class="def" href="#glossary-event-type">event type</a> is defined in this specification for reference and completeness, but this specification <a class="def" href="#glossary-deprecated">deprecates</a> the use of this event type in favor of the related <a class="def" href="#glossary-event-type">event type</a> <a class="eventtype" href="#event-type-click"><code>click</code></a>. Other specifications may define and maintain their own <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> <a class="def" href="#glossary-event-type">event type</a> for backwards compatibility.</p>
+
+ <p class="note" id="DOMActivate-click"><strong>Note:</strong> While <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> and <a class="eventtype" href="#event-type-click"><code>click</code></a> are not completely equivalent, implemented behavior for the <a class="eventtype" href="#event-type-click"><code>click</code></a> <a class="def" href="#glossary-event-type">event type</a> has developed to encompass the most critical accessibility aspects for which the <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> <a class="def" href="#glossary-event-type">event type</a> was designed, and is more widely implemented. Authors are encouraged to use the <a class="eventtype" href="#event-type-click"><code>click</code></a> <a class="def" href="#glossary-event-type">event type</a> rather than the related <a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a> or <a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a> <a class="def" href="#glossary-event-type">event type</a> to ensure maximum accessibility.</p>
</dl>
</div>
@@ -2324,7 +2330,7 @@
<dt id="event-type-abort">
<a class="eventtype noxref" href="#event-type-abort"><code>abort</code></a>
</dt>
- <dd><table border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0"><tr class="assert must"><th>Type</th><td class="eventname"><strong><code>abort</code></strong></td></tr><tr class="assert must"><th>Interface</th><td><a href="#events-Events-UIEvent"><code>UIEvent</code></a> if generated from a user interface, <a href="#events-Events-Event"><code>Event</code></a> otherwise.</td></tr><tr class="assert must"><th>Bubbles</th><td>Yes</td></tr><tr class="assert must"><th>Target</th><td><code>Element</code></td></tr><tr class="assert must"><th>Cancelable</th><td>No</td></tr><tr class="assert must"><th>Default action</th><td>none</td></tr><tr class="assert must"><th>Context info</th><td><a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> may be in use.</td></tr></table>
+ <dd><table border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0"><tr class="assert must"><th>Type</th><td class="eventname"><strong><code>abort</code></strong></td></tr><tr class="assert must"><th>Interface</th><td><a href="#events-Events-UIEvent"><code>UIEvent</code></a> if generated from a user interface, <a href="#events-Events-Event"><code>Event</code></a> otherwise.</td></tr><tr class="assert must"><th>Bubbles</th><td>No</td></tr><tr class="assert must"><th>Target</th><td><code>Element</code></td></tr><tr class="assert must"><th>Cancelable</th><td>No</td></tr><tr class="assert must"><th>Default action</th><td>none</td></tr><tr class="assert must"><th>Context info</th><td><a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> may be in use.</td></tr></table>
A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when the loading of a resource has been aborted.</dd>
</dl>
</div>
@@ -2335,7 +2341,7 @@
<dt id="event-type-error">
<a class="eventtype noxref" href="#event-type-error"><code>error</code></a>
</dt>
- <dd><table border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0"><tr class="assert must"><th>Type</th><td class="eventname"><strong><code>error</code></strong></td></tr><tr class="assert must"><th>Interface</th><td><a href="#events-Events-UIEvent"><code>UIEvent</code></a> if generated from a user interface, <a href="#events-Events-Event"><code>Event</code></a> otherwise.</td></tr><tr class="assert must"><th>Bubbles</th><td>Yes</td></tr><tr class="assert must"><th>Target</th><td><code>Element</code></td></tr><tr class="assert must"><th>Cancelable</th><td>No</td></tr><tr class="assert must"><th>Default action</th><td>none</td></tr><tr class="assert must"><th>Context info</th><td><a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> may be in use.</td></tr></table>
+ <dd><table border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0"><tr class="assert must"><th>Type</th><td class="eventname"><strong><code>error</code></strong></td></tr><tr class="assert must"><th>Interface</th><td><a href="#events-Events-UIEvent"><code>UIEvent</code></a> if generated from a user interface, <a href="#events-Events-Event"><code>Event</code></a> otherwise.</td></tr><tr class="assert must"><th>Bubbles</th><td>No</td></tr><tr class="assert must"><th>Target</th><td><code>Element</code></td></tr><tr class="assert must"><th>Cancelable</th><td>No</td></tr><tr class="assert must"><th>Default action</th><td>none</td></tr><tr class="assert must"><th>Context info</th><td><a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> may be in use.</td></tr></table>
A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a resource failed to load, or has been loaded but cannot be interpreted according to its semantics, such as an invalid image, a script execution error, or non-well-formed XML.</dd>
</dl>
</div>
@@ -2594,6 +2600,8 @@
readonly attribute long <a class="noxref" href="#events-Events-MouseEvent-screenY">screenY</a>;
readonly attribute long <a class="noxref" href="#events-Events-MouseEvent-clientX">clientX</a>;
readonly attribute long <a class="noxref" href="#events-Events-MouseEvent-clientY">clientY</a>;
+ readonly attribute long <a class="noxref" href="#events-Events-MouseEvent-nx">nx</a>;
+ readonly attribute long <a class="noxref" href="#events-Events-MouseEvent-ny">ny</a>;
readonly attribute boolean <a class="noxref" href="#events-Events-MouseEvent-ctrlKey">ctrlKey</a>;
readonly attribute boolean <a class="noxref" href="#events-Events-MouseEvent-shiftKey">shiftKey</a>;
readonly attribute boolean <a class="noxref" href="#events-Events-MouseEvent-altKey">altKey</a>;
@@ -2660,6 +2668,12 @@
<dd>The horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system.<br /></dd>
<dt><code class="attribute-name"><a id="events-Events-MouseEvent-screenY">screenY</a></code> of type <code>long</code>, readonly</dt>
<dd>The vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.<br /></dd>
+
+ <dt><code class="attribute-name"><a id="events-Events-MouseEvent-nx">nx</a></code> of type <code>long</code>, readonly</dt>
+ <dd>The horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system, taking into account all transformations and viewport adjustments, as described in the <a href="#events-mouseevent-coord-norm">coordinate normalization algorithm</a>.<br /></dd>
+ <dt><code class="attribute-name"><a id="events-Events-MouseEvent-ny">ny</a></code> of type <code>long</code>, readonly</dt>
+ <dd>The vertical coordinate at which the event occurred relative to the origin of the screen coordinate system, taking into account all transformations and viewport adjustments, as described in the <a href="#events-mouseevent-coord-norm">coordinate normalization algorithm</a>.<br /></dd>
+
<dt><code class="attribute-name"><a id="events-Events-MouseEvent-shiftKey">shiftKey</a></code> of type <code>boolean</code>, readonly</dt>
<dd>Refer to the <a href="#events-Events-KeyboardEvent-shiftKey"><code>KeyboardEvent.shiftKey</code></a> attribute.<br /></dd>
</dl>
@@ -2705,7 +2719,69 @@
<!-- click -->
- <h4 class="div3 needswork"><a id="events-mouseevent-event-order" href="#events-mouseevent-event-order">5.2.3.1 Mouse Event Order</a></h4>
+ <h4 class="div3 needswork"><a id="events-mouseevent-coord-norm" href="#events-mouseevent-coord-norm">5.2.3.1 Coordinate Normalization</a></h4>
+ <p>Some languages, such as SVG or CSS, may allow the author to apply matrix transformations to the content, such as coordinate translations, rotation, skewing, or scaling, or adjustments to the viewport to show only a selected portion of the whole document canvas. These combined transformations distort the perceived client coordinates with respect to the rendered content. In order to provide coordinates to realigned the client coordinates relative to the transformed content, the user agent must return results as if the following coordinate normalization algorithm were applied:</p>
+ <ol class="proposal">
+ <li>Establish a point, CP, initialized with the clientX and clientY attributes of the event</li>
+ <li>Establish a <code>2x3</code> calculation matrix (CM) with all values set to <code>0</code>.</li>
+ <li>Find the coordinate transformation matrix (CTM) for the proximal target element, and store it in the calculation matrix as the initial value</li>
+ <li>For each ancestor element of the proximal target element, in ascending order toward the rootmost element:
+ <ol>
+ <li>Find the coordinate transformation matrix (CTM) for the current target element</li>
+ <li>Multiply the calculation matrix by the new CTM</li>
+ <li>Store the result as the new value of the the calculation matrix</li>
+ </ol>
+ </li>
+ <li>Calculate the inverse of the calculation matrix, and store the result as the new value of the the calculation matrix</li>
+ <li>Find the transformation matrix for the rootmost element
+ <ol>
+ <li><i class="issue" id="ratio"><strong>To Do:</strong> the following is half-baked... work out real algorithm</i></li>
+ <li>Determine the width and height of the viewport</li>
+ <li>Find the width and height of the document, if any</li>
+ <li>Calculate the ratio of the viewport dimensions to the document dimensions
+ <ol>
+ <li>If the width of the document is expressed as a percentage, then:
+ <ol>
+ <li>Multiply the width of the viewport by the numerical percentage of the width of the document</li>
+ </ol>
+ </li>
+ <li>Otherwise:
+ <ol>
+ <li>Divide the width of the viewport by the numerical width of the document</li>
+ </ol>
+ </li>
+ </ol>
+ <ol>
+ <li>If the height of the document is expressed as a percentage, then:
+ <ol>
+ <li>Multiply the height of the viewport by the numerical percentage of the height of the document</li>
+ </ol>
+ </li>
+ <li>Otherwise:
+ <ol>
+ <li>Divide the height of the viewport by the numerical height of the document</li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+ <li><i class="issue" id="meet-slice-mid-max"><strong>To Do:</strong> describe the effects of "meet", "slice", "Mid", "Max" on the ratio</i></li>
+ <li><i class="issue" id="currentTranslate-currentScale"><strong>To Do:</strong>take into account the currentTranslate and currentScale<>/i></li>
+ <li>Store the ratio as the scale and translate values of the transformation matrix for the rootmost element</li>
+ </ol>
+ </li>
+ <li>Apply a matrix tranformation to CP using the transformation matrix for the rootmost element, and store the result as the new value of CP</li>
+ <li>Apply a matrix tranformation to CP using the calculation matrix, and store the result as the new value of CP</li>
+ <li>Set the value of the event.tx and event.ty attributes to CP.x and CP.y, respectively</li>
+ </ol>
+
+ <p class="note"><strong>Note:</strong> If no transformations or viewport adjustments are in effect in the document, the <a href="#events-Events-MouseEvent-nx"><code>MouseEvent.nx</code></a> and <a href="#events-Events-MouseEvent-ny"><code>MouseEvent.ny</code></a> attributes must have identical values to the <a href="#events-Events-MouseEvent-clientX"><code>MouseEvent.clientX</code></a> and <a href="#events-Events-MouseEvent-clientY"><code>MouseEvent.clientY</code></a> attributes, respectively.</p>
+
+ <p class="issue" id="issue-coord-norm-scroll"><strong>Issue:</strong> coordinate normalization scrolling. Should this algorithm also account for scrolling "transformations"?</p>
+
+ <p class="issue" id="issue-coord-norm-root"><strong>Issue:</strong> coordinate normalization root. Should this algorithm apply only to the nearest nested root, or to the document as a whole?</p>
+
+
+ <h4 class="div3 needswork"><a id="events-mouseevent-event-order" href="#events-mouseevent-event-order">5.2.3.2 Mouse Event Order</a></h4>
<p>Certain mouse events defined in this specification occur in a set order relative to one another. The following is the typical sequence of events when a pointing device's cursor is moved over an element:</p>
<ol>
<li><a class="eventtype" href="#event-type-mousemove"><code>mousemove</code></a></li>
@@ -3402,7 +3478,7 @@
</dt>
<dd>
<div class="method">Queries the state of a modifier using a key value. See also <a href="#keyset-Modifiers">Modifier keys</a>.
- <div class="parameters"><strong>Parameters</strong><div class="paramtable"><dl><dt><code class="parameter-name">keyArg</code> of type <code>DOMString</code></dt><dd>A modifier key value. Common modifier keys are <code class="value">'Alt'</code>, <code class="value">'AltGraph'</code>, <code class="value">'CapsLock'</code>, <code class="value">'Control'</code>, <code class="value">'Meta'</code>, <code class="value">'NumLock'</code>, <code class="value">'Scroll'</code>, or <code class="value">'Shift'</code>.
+ <div class="parameters"><strong>Parameters</strong><div class="paramtable"><dl><dt><code class="parameter-name">keyArg</code> of type <code>DOMString</code></dt><dd>A modifier key value. Modifier keys defined in this specification are <code class="value">'Alt'</code>, <code class="value">'AltGraph'</code>, <code class="value">'CapsLock'</code>, <code class="value">'Control'</code>, <code class="value">'Fn'</code>, <code class="value">'Meta'</code>, <code class="value">'NumLock'</code>, <code class="value">'Scroll'</code>, and <code class="value">'Shift'</code>, and <code class="value">'Win'</code>. User agents may support additional implementation-specific modifier keys depending on the environment.
<p class="note"><strong>Note:</strong> If an application wishes to distinguish between right and left modifiers, this information could be deduced using keyboard events and <a href="#events-Events-KeyboardEvent-location"><code>KeyboardEvent.location</code></a>.</p>
</dd></dl></div></div>
<!-- parameters -->
@@ -4650,7 +4726,9 @@
<dd>The Menu key.</dd>
<dt><a id="keyset-key-Meta"><code class="value keyname">'Meta'</code></a></dt>
- <dd>The Meta key.</dd>
+ <dd>The Meta key.
+ <span class="note"><strong>Note:</strong> This key value shall be also used for the Return (Macintosh numpad) key.</span>
+ </dd>
<dt><a id="keyset-key-MediaNextTrack"><code class="value keyname">'MediaNextTrack'</code></a></dt>
<dd>The Media Next Track key.</dd>