--- a/html/DOM3-Events.html Mon Feb 01 16:16:07 2010 +0900
+++ b/html/DOM3-Events.html Mon Feb 08 18:18:43 2010 +0900
@@ -20,16 +20,16 @@
</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="2010-02-01">01 February 2010</time></h2>
+ <h2 id="Overview-W3C-doctype">W3C Editor's Draft <time datetime="2010-02-08">08 February 2010</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.118">http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.118</a></dd>
+ <dd><a href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.119">http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.119</a></dd>
<dt>Latest stable version:</dt>
<dd><a href="http://www.w3.org/TR/DOM-Level-3-Events">http://www.w3.org/TR/DOM-Level-3-Events</a></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.117">http://dev.w3.org/cvsweb/~checkout~/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.117</a></dd>
+ <dd><a href="http://dev.w3.org/cvsweb/~checkout~/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.118">http://dev.w3.org/cvsweb/~checkout~/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.118</a></dd>
<dt>Editor's Draft:</dt>
<dd><a href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html">http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html</a></dd>
@@ -326,18 +326,13 @@
<p>This specification is to be understood in the context of the DOM Level 3 Core specification [<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>] and the general considerations for DOM implementations apply. For example, behavior in exceptional circumstances (such as when a <code>null</code> argument is passed when <code>null</code> was not expected) is discussed under <a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-17189187"><em>DOMException</em></a>, and handling of <a class="def" href="#glossary-namespaceURI">namespace URIs</a> is discussed in <a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Namespaces-Considerations"><em>XML Namespaces</em></a>. For additional information about <a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/introduction.html#ID-Conformance"><em>conformance</em></a>, please see the DOM Level 3 Core specification [<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>].</p>
<p>This specification defines several classes of conformance for different <a class="def" href="#glossary-user-agent">user agents</a>, specifications, and authors:</p>
<dl>
+
<dt id="conf-interactive-ua">Web browsers and other dynamic or interactive <a class="def" href="#glossary-user-agent">user agents</a></dt>
<dd>
- <p>A dynamic or interactive <a class="def" href="#glossary-user-agent">user agent</a>, referred to here as a "browser" (be it a Web browser or other similar program), conforms to DOM Level 3 Events if it supports the Core module defined in [<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>], the <a href="#event-flow">Event dispatch and DOM event flow</a> mechanism, all the interfaces and events with their associated methods, attributes, and semantics defined in this specification which are not marked as <a class="def" href="#glossary-deprecated">deprecated</a><!-- or <a class="def" href="#glossary-obsolete">obsolete</a> -->, and the complete set of <a class="def" href="#glossary-character-value">character values</a> and <a class="def" href="#glossary-key-name">key names</a> in the <a href="#key-values">Key Values Set</a>, as well as all other normative requirements defined in this specification. A conforming browser must <a class="def" href="#glossary-dispatch">dispatch</a> events appropriate to the given <a href="#events-Events-EventTarget">EventTarget</a> when the conditions defined for that <a class="def" href="#glossary-event-type">event type</a> have been met.</p>
- <p>
- <span id="conform-arch">A browser conforms specifically to the DOM Level 3 Events Architecture if it implements the <a href="#dom-event-architecture">DOM Event Architecture</a> and <a href="#event-interfaces">Basic Event Interfaces</a>, regardless of its support for any other event interfaces or <a class="def" href="#glossary-event-type">event types</a> defined in this specification.</span>
- <span id="conform-module">A browser conforms specifically to the DOM Level 3 Events Module if it implements the interfaces and its related <a class="def" href="#glossary-event-type">event types</a> specified in the <a href="#events-module">Events Module</a>, and to each event interface if it implements that interface and its related <a class="def" href="#glossary-event-type">event types</a>.</span>
- </p>
- <p>
- <span id="conform-script">A conforming browser must support scripting, declarative interactivity, or some other means of detecting and dispatching events in the manner described by this specification, and with the attributes specified for that <a class="def" href="#glossary-event-type">event type</a>.</span>
- <span id="conform-declarative">A declarative browser may still conform to this specification if it does not directly support or expose the methods defined for the DOM Level 3 Events interfaces, but it should provide compatible functionality by other means.</span>
- </p>
- <p>In addition to meeting all other conformance criteria, a conforming browser may implement features of this specification marked as <a class="def" href="#glossary-deprecated">deprecated</a><!-- or <a class="def" href="#glossary-obsolete">obsolete</a> -->, for backwards compatibility with existing content, but such implementation is discouraged.</p>
+ <p>A dynamic or interactive <a class="def" href="#glossary-user-agent">user agent</a>, referred to here as a "browser" (be it a Web browser, AT (Accessibility Technology) application, or other similar program), conforms to DOM Level 3 Events if it supports the Core module defined in [<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>], the <a href="#event-flow">Event dispatch and DOM event flow</a> mechanism, all the interfaces and events with their associated methods, attributes, and semantics defined in this specification which are not marked as <a class="def" href="#glossary-deprecated">deprecated</a>, and the complete set of <a class="def" href="#glossary-character-value">character values</a> and <a class="def" href="#glossary-key-name">key names</a> in the <a href="#key-values">Key Values Set</a>, as well as all other normative requirements defined in this specification. A conforming browser must <a class="def" href="#glossary-dispatch">dispatch</a> events appropriate to the given <a href="#events-Events-EventTarget">EventTarget</a> when the conditions defined for that <a class="def" href="#glossary-event-type">event type</a> have been met.</p>
+ <p><span id="conform-arch">A browser conforms specifically to the DOM Level 3 Events Architecture if it implements the <a href="#dom-event-architecture">DOM Event Architecture</a> and <a href="#event-interfaces">Basic Event Interfaces</a>, regardless of its support for any other event interfaces or <a class="def" href="#glossary-event-type">event types</a> defined in this specification.</span> <span id="conform-module">A browser conforms specifically to the DOM Level 3 Events Module if it implements the interfaces and its related <a class="def" href="#glossary-event-type">event types</a> specified in the <a href="#events-module">Events Module</a>, and to each event interface if it implements that interface and its related <a class="def" href="#glossary-event-type">event types</a>.</span></p>
+ <p><span id="conform-script">A conforming browser must support scripting, declarative interactivity, or some other means of detecting and dispatching events in the manner described by this specification, and with the attributes specified for that <a class="def" href="#glossary-event-type">event type</a>.</span> <span id="conform-declarative">A declarative browser may still conform to this specification if it does not directly support or expose the methods defined for the DOM Level 3 Events interfaces, but it should provide compatible functionality by other means.</span></p>
+ <p>In addition to meeting all other conformance criteria, a conforming browser may implement features of this specification marked as <a class="def" href="#glossary-deprecated">deprecated</a>, for backwards compatibility with existing content, but such implementation is discouraged.</p>
<p>A conforming browser may also support features not found in this specification, but which use the <a href="#event-flow">Event dispatch and DOM event flow</a> mechanism, interfaces, events, or other features defined in DOM Level 3 Events, and may implement additional interfaces and <a class="def" href="#glossary-event-type">event types</a> appropriate to that implementation. Such features may be later standardized in future specifications.</p>
<p>A browser which does not conform to all required portions of this specification must not claim conformance to DOM Level 3 Events. Such an implementation which does conform to portions of this specification may claim conformance to those specific portions.</p>
<!-- //if we move to Web IDL, use something like the HTML5 wording:
@@ -425,11 +420,14 @@
<dt id="glossary-activation-trigger"><dfn>activation trigger</dfn></dt>
<dd>An event which is defined to initiate an <a class="def" href="#glossary-activation-behavior">activation behavior</a>. Refer to <a href="#event-flow-activation">Activation triggers and behavior</a> for more details.</dd>
+ <dt id="glossary-author"><dfn>author</dfn></dt>
+ <dd>In the context of this specification, an <em>author</em> is a person who writes script or other executable content that uses the interfaces, events, and event flow defined in this specification. See <a href="#conf-authors">Authors and content</a> conformance category for more details.</dd>
+
<dt id="glossary-bubbling-phase"><dfn>bubbling phase</dfn></dt>
- <dd>The process by which an <a class="def" href="#glossary-event">event</a> can be handled by one of the target ancestors after being handled by the <a class="def" href="#glossary-proximal-event-target">proximal event target</a>.</dd>
+ <dd>The process by which an <a class="def" href="#glossary-event">event</a> can be handled by one of the target ancestors after being handled by the <a class="def" href="#glossary-proximal-event-target">proximal event target</a>. See the description of the <a href="#bubble-phase">bubble phase</a> in the context of event flow for more details.</dd>
<dt id="glossary-capture-phase"><dfn>capture phase</dfn></dt>
- <dd>The process by which an <a class="def" href="#glossary-event">event</a> can be handled by one of the target ancestors before being handled by the <a class="def" href="#glossary-proximal-event-target">proximal event target</a>.</dd>
+ <dd>The process by which an <a class="def" href="#glossary-event">event</a> can be handled by one of the target ancestors before being handled by the <a class="def" href="#glossary-proximal-event-target">proximal event target</a>. See the description of the <a href="#capture-phase">capture phase</a> in the context of event flow for more details.</dd>
<dt id="glossary-character-value"><dfn>character value</dfn></dt>
<dd>In the context of key values, a character value is a string representing a single Unicode character, such as a letter or symbol, as a UTF-16 character escape (e.g. <code class="value">'\u0041'</code> for the Latin Capital Letter A key, <code class="value charval">A</code>.). <i class="issue" id="issue-character_value"><strong>Issue:</strong> this may not be the best way to represent a character value, see notes in key values. Also, is "character value" the best term?</i></dd>
@@ -526,7 +524,7 @@
<dd>A software component which interprets some form of alternate input, such as a <a class="def" href="#glossary-ime">input method editor</a>, a speech processor, or a handwriting recognition system, and converts it to text.</dd>
<dt id="glossary-target-phase"><dfn>target phase</dfn></dt>
- <dd>The process by which an <a class="def" href="#glossary-event">event</a> can be handled by the <a class="def" href="#glossary-proximal-event-target">proximal event target</a>.</dd>
+ <dd>The process by which an <a class="def" href="#glossary-event">event</a> can be handled by the <a class="def" href="#glossary-proximal-event-target">proximal event target</a>. See the description of the <a href="#target-phase">target phase</a> in the context of event flow for more details.</dd>
<dt id="glossary-topmost-event-target"><dfn>topmost event target</dfn></dt>
<dd>The <a class="def" href="#glossary-topmost-event-target">topmost event target</a> shall be the element highest in the rendering order which is capable of being an <a class="def" href="#glossary-event-target">event target</a>. In this case, 'top' shall refer not to the position on the screen, but the logical order of the element in relation to other elements in drawing or stacking order on the z-axis (where the x-axis is the screen width and the y-axis is the screen height). In HTML and CSS, or in SVG, this is controlled by the document order, as modified in HTML and CSS by the <code>'z-index'</code> property. In some cases, such as when using some values of the SVG <code>'pointer-events'</code> property, the topmost element may not receive pointer events, in which case, the next element in z-index order which can receive pointer-events is the <a class="def" href="#glossary-topmost-event-target">topmost event target</a>. Note that visibility of the element does not necessarily affect its ability to be the <a class="def" href="#glossary-topmost-event-target">topmost event target</a>, since an element which is hidden by use of the CSS <code>'visibility'</code> property can still receive pointer events (though not one with a <code>'display'</code> property of <code>none</code>), and the <a class="def" href="#glossary-topmost-event-target">topmost event target</a> may be completely obscured by another element which cannot receive pointer events. Unless otherwise noted, there is only one <a class="def" href="#glossary-topmost-event-target">topmost event target</a> in any event. For specific details regarding hit testing and stacking order, refer to the <a class="def" href="#glossary-host-language">host language</a>.</dd>
@@ -541,7 +539,7 @@
<dd>A Unicode code point is a unique hexadecimal number signifying a character by its index in the Unicode codespace (or library of characters). In the context of key values, a Unicode code point is expressed as a string in the format "\u" followed by a hexadecimal character index in the range <code>0000</code> to <code>10FFFF</code>, using at least four digits. See also <a class="def charval" href="#glossary-character-value">character value</a>.</dd>
<dt id="glossary-user-agent"><dfn>user agent</dfn></dt>
- <dd>A program, such as a browser or authoring tool, normally running on a client machine, which acts on a user's behalf in retrieving, interpreting, executing, presenting, or creating content conforming to a specification. Users may act on the content using different user agents at different times, for different purposes.</dd>
+ <dd>A program, such as a browser or authoring tool, normally running on a client machine, which acts on a user's behalf in retrieving, interpreting, executing, presenting, or creating content conforming to a specification. Users may act on the content using different user agents at different times, for different purposes. See the <a href="#conf-interactive-ua">Web browsers and other dynamic or interactive user agents</a> and <a href="#conf-author-tools">Authoring tools</a> conformance categories for more details.</dd>
</dl>
</div>
@@ -568,8 +566,9 @@
<li>The <strong id="target-phase">target phase</strong>: <span class="assert must">the event object must arrive at the event object's <a class="def" href="#glossary-proximal-event-target">proximal event target</a>.</span> This phase is also known as the <em>at-target phase</em>. <span class="assert must">Event listeners registered for this phase must handle the event once it has reached its target.</span> <span class="assert must">If the <a class="def" href="#glossary-event-type">event type</a> indicates that the event must not bubble, the event object must halt after completion of this phase.</span></li>
<li>The <strong id="bubble-phase">bubble phase</strong>: <span class="assert must">the event object propagates through the target's ancestors in reverse order, starting with the target's parent and ending with the <a class="def" href="#glossary-defaultView">defaultView</a>.</span> This phase is also known as the <em>bubbling phase</em>. <span class="assert must">Event listeners registered for this phase shall handle the event after it has reached its target.</span></li>
</ol>
+
<p>
- <span class="assert must">Implementations let event objects accomplish an event phase by applying the following steps while there are pending event targets in the partial propagation path for this phase and the event object's propagation has not been stopped through <a href="#events-event-type-stopPropagation"><code>Event.stopPropagation()</code></a>.</span>
+ <span class="assert must">Implementations must let event objects accomplish an event phase by applying the following steps while there are pending event targets in the partial propagation path for this phase and the event object's propagation has not been stopped through <a href="#events-event-type-stopPropagation"><code>Event.stopPropagation()</code></a>.</span>
</p>
<p>
<span class="assert must">First, the implementation must determine the <em>current target</em>. This shall be the next pending event target in the partial propagation path, starting with the first. From the perspective of an event listener this shall be the event target the listener has been registered on.</span>
@@ -644,12 +643,15 @@
<p class="example" id="example-activation"><strong>Example:</strong> Both HTML and SVG have an <code class="element">a</code> element which indicates a link. Relevant <a class="def" href="#glossary-activation-trigger">activation triggers</a> for an <code class="element">a</code> element are a <a class="eventtype" href="#event-type-click"><code>click</code></a> event on the text or image content of the <code class="element">a</code> element, or a <a class="eventtype" href="#event-type-keydown"><code>keydown</code></a> event with a <a href="#events-Events-KeyboardEvent-key">key</a> attribute value of <a href="#key-Enter"><code class="value keyname">'Enter'</code></a> key when the <code class="element">a</code> element has focus. The activation behavior for an <code class="element">a</code> element is normally to change the content of the window to the content of the new document, in the case of external links, or to reposition the current document relative to the new anchor, in the case of internal links.</p>
<p>An <a class="def" href="#glossary-activation-trigger">activation trigger</a> is a user action or an event which indicates to the implementation that an activation behavior should be initiated. User-initiated <a class="def" href="#glossary-activation-trigger">activation triggers</a> include clicking a mouse button on an activatable element, pressing the <a href="#key-Enter"><code class="value keyname">'Enter'</code></a> key when an activatable element has focus, or pressing a key that is somehow linked to an activatable element (a "hotkey" or "access key") even when that element does not have focus. Event-based <a class="def" href="#glossary-activation-trigger">activation triggers</a> may include timer-based events that activate an element at a certain clock time or after a certain time period has elapsed, progress events after a certain action has been completed, or many other condition-based or state-based events.</p>
<p>In some cases, a <a class="def" href="#glossary-host-language">host language</a> may define attributes or even attribute values which add to or change the native <a class="def" href="#glossary-activation-trigger">activation trigger</a> or <a class="def" href="#glossary-activation-behavior">activation behavior</a> of an element. For example, ARIA [<cite><a class="informative" href="#ref-ARIA">ARIA</a></cite>] defines values for the <code class="attr">role</code> attribute that add semantics to the element to which it is applied, for purposes of enhanced accessibility. In such cases, if the <a class="def" href="#glossary-host-language">host language</a> does not explicitly define the <a class="def" href="#glossary-activation-trigger">activation trigger</a> or <a class="def" href="#glossary-activation-behavior">activation behavior</a>, the author must provide the mechanics of the <a class="def" href="#glossary-activation-trigger">activation trigger</a> (via an event listener) or <a class="def" href="#glossary-activation-behavior">activation behavior</a> (such as calling an ECMAScript function) for that element when applying that attributes or attribute value.</p>
- <p>If the instance of the <a class="def" href="#glossary-activation-trigger">activation trigger</a> is not an event of <a class="def" href="#glossary-event-type">event type</a> <a class="eventtype" href="#event-type-click"><code>click</code></a> (that is, when it does not result from a user activating a button or link using a mouse or equivalent pointing device), the implementation must synthesize and dispatch an event of <a class="def" href="#glossary-event-type">event type</a> <a class="eventtype" href="#event-type-click"><code>click</code></a> as one of the <a class="def" href="#glossary-default-action">default actions</a> of that <a class="def" href="#glossary-activation-trigger">activation trigger</a>. Context information of such a <a class="eventtype" href="#event-type-click"><code>click</code></a> event is implementation dependent, but for historical purposes, the interface for the <a class="eventtype" href="#event-type-click"><code>click</code></a> event must be the <a href="#events-Events-MouseEvent"><code>MouseEvent interface</code></a>, regardless of the actual device used to activate the element. Preventing the <a class="def" href="#glossary-default-action">default action</a> of the <a class="def" href="#glossary-activation-trigger">activation trigger</a>, such as with the <a href="#events-event-type-preventDefault"><code>Event.preventDefault()</code></a>, must stop the initiation of the <a class="def" href="#glossary-activation-behavior">activation behavior</a>.</p>
+
+ <h4><a id="click-synthesis" href="#click-synthesis">3.5.1 Activation event synthesis</a></h4>
+
+ <p>If the instance of the <a class="def" href="#glossary-activation-trigger">activation trigger</a> is not an event of <a class="def" href="#glossary-event-type">event type</a> <a class="eventtype" href="#event-type-click"><code>click</code></a> (that is, when it does not result from a user activating a button or link using a mouse or equivalent pointing device), the implementation must synthesize and dispatch an event of <a class="def" href="#glossary-event-type">event type</a> <a class="eventtype" href="#event-type-click"><code>click</code></a> as one of the <a class="def" href="#glossary-default-action">default actions</a> of that <a class="def" href="#glossary-activation-trigger">activation trigger</a>; the value of the <code class="attribute-name"><a href="#events-event-type-target">Event.target</a></code> must be set to the <a class="def" href="#glossary-proximal-event-target">proximal event target</a> (normally, the currently focused element), and the event must simulate a <em>left click</em> (i.e. the <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a> attribute value must be <code>0</code>, and the <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a> attribute value must be <code>1</code>). Other context information of such a simulated <a class="eventtype" href="#event-type-click"><code>click</code></a> event is implementation dependent, but for historical purposes, the interface for the <a class="eventtype" href="#event-type-click"><code>click</code></a> event must be the <a href="#events-Events-MouseEvent"><code>MouseEvent interface</code></a>, regardless of the actual device used to activate the element. Preventing the <a class="def" href="#glossary-default-action">default action</a> of the <a class="def" href="#glossary-activation-trigger">activation trigger</a>, such as with the <a href="#events-event-type-preventDefault"><code>Event.preventDefault()</code></a>, must stop the initiation of the <a class="def" href="#glossary-activation-behavior">activation behavior</a>.</p>
<p class="example" id="example-activation-click"><strong>Example:</strong> When a user activates a hyperlink using a keyboard, such as by focusing the hyperlink element and pressing the <a href="#key-Enter"><code class="value keyname">'Enter'</code></a> or <a href="#key-Space"><code class="value keyname">'Space'</code></a> key, a <a class="eventtype" href="#event-type-click"><code>click</code></a> event would be dispatched as the <a class="def" href="#glossary-default-action">default action</a> of the respective <a class="eventtype" href="#event-type-keydown"><code>keydown</code></a> event.</p>
<p>Implementations must dispatch the synthesized <a class="eventtype" href="#event-type-click"><code>click</code></a> event as described above even if they do not normally dispatch such an event (e.g. when activation is requested by a voice command, since this specification does not address <a class="def" href="#glossary-event-type">event types</a> for voice input).</p>
- <p class="note" id="application-dependent-activation"><strong>Note:</strong> The activation of an event target is device dependent but is also application dependent, e.g. a link in a document can be activated using a mouse click or a mouse double click.</p>
+ <p class="note" id="application-dependent-activation"><strong>Note:</strong> The activation of an event target is device dependent, but is also application dependent, e.g. a link in a document can be activated using a mouse click or a mouse double click.</p>
<p>Implementations which support the <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> <a class="def" href="#glossary-event-type">event type</a> should also dispatch a <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> event as a <a class="def" href="#glossary-default-action">default action</a> of a <a class="eventtype" href="#event-type-click"><code>click</code></a> event which is associated with an <a class="def" href="#glossary-activation-trigger">activation trigger</a>. However, such implementations should only initiate the associated <a class="def" href="#glossary-activation-behavior">activation behavior</a> once for any given occurrence of an <a class="def" href="#glossary-activation-trigger">activation trigger</a>.</p>
- <p class="example" id="example-activation-DOMActivate"><strong>Example:</strong> The <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a><a class="def" href="#glossary-event-type">event type</a> is required to be supported for XForms [<cite><a class="informative" href="#ref-xforms">XFORMS</a></cite>], which is intended for implementation within a <a class="def" href="#glossary-host-language">host language</a>. In a scenario where a plugin or script-based implementation of XForms is intended for installation in a native implementation of this specification which does not support the <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a><a class="def" href="#glossary-event-type">event type</a>, the XForms <a class="def" href="#glossary-user-agent">user agent</a> must synthesize and dispatch its own <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> events based on the appropriate <a class="def" href="#glossary-activation-trigger">activation triggers</a>. Thus, when a <a class="eventtype" href="#event-type-click"><code>click</code></a> event is dispatched by the DOM Level 3 Events <a class="def" href="#glossary-user-agent">user agent</a>, the XForms <a class="def" href="#glossary-user-agent">user agent</a> must determine whether to synthesize a <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> event with the same relevant properties as a <a class="def" href="#glossary-default-action">default action</a> of that <a class="eventtype" href="#event-type-click"><code>click</code></a> event; appropriate cues may be whether the <a class="eventtype" href="#event-type-click"><code>click</code></a> event is <a href="#trusted-events">trusted</a>, or whether its <a class="def" href="#glossary-proximal-event-target">proximal event target</a> has a <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> event listener registered.</p>
+ <p class="example" id="example-activation-DOMActivate"><strong>Example:</strong> The <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> <a class="def" href="#glossary-event-type">event type</a> is required to be supported for XForms [<cite><a class="informative" href="#ref-xforms">XFORMS</a></cite>], which is intended for implementation within a <a class="def" href="#glossary-host-language">host language</a>. In a scenario where a plugin or script-based implementation of XForms is intended for installation in a native implementation of this specification which does not support the <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> <a class="def" href="#glossary-event-type">event type</a>, the XForms <a class="def" href="#glossary-user-agent">user agent</a> must synthesize and dispatch its own <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> events based on the appropriate <a class="def" href="#glossary-activation-trigger">activation triggers</a>. Thus, when a <a class="eventtype" href="#event-type-click"><code>click</code></a> event is dispatched by the DOM Level 3 Events <a class="def" href="#glossary-user-agent">user agent</a>, the XForms <a class="def" href="#glossary-user-agent">user agent</a> must determine whether to synthesize a <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> event with the same relevant properties as a <a class="def" href="#glossary-default-action">default action</a> of that <a class="eventtype" href="#event-type-click"><code>click</code></a> event; appropriate cues may be whether the <a class="eventtype" href="#event-type-click"><code>click</code></a> event is <a href="#trusted-events">trusted</a>, or whether its <a class="def" href="#glossary-proximal-event-target">proximal event target</a> has a <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> event listener registered.</p>
<p class="note" id="authors-activation"><strong>Note:</strong> Authors should not rely upon the interoperable support of <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> in many <a class="def" href="#glossary-user-agent">user agents</a>. Thus, authors may use the <a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a><a class="def" href="#glossary-event-type">event type</a> whenever they wish to make or react to an <a class="def" href="#glossary-activation-trigger">activation trigger</a>, but should use the <a class="eventtype" href="#event-type-click"><code>click</code></a><a class="def" href="#glossary-event-type">event type</a> for more accessible behavior instead, due to wider implementation.</p>
<h4 class="needswork">
<a id="events-activation-event-order" href="#events-activation-event-order">3.5.1 Activation Event Order</a>
@@ -1692,17 +1694,6 @@
<td>Yes</td>
<td>none</td>
</tr>
-<!-- <tr>
- <td><a class="eventtype" href="#event-type-mousewheel">
- <code>mousewheel</code>
- </a></td>
- <td>Sync</td>
- <td>Yes</td>
- <td><a class="def" href="#glossary-defaultView"><code>defaultView</code></a>, <code>Document</code>, <code>Element</code></td>
- <td><a href="#events-Events-MouseWheelEvent"><code>MouseWheelEvent</code></a></td>
- <td>Yes</td>
- <td>Scroll (or zoom) the document</td>
- </tr> -->
<tr>
<td><a class="eventtype" href="#event-type-resize">
<code>resize</code>
@@ -1769,7 +1760,7 @@
<td>Yes</td>
<td>Scroll (or zoom) the document</td>
</tr>
-<!-- <tr>
+ <tr>
<td><a class="eventtype" href="#event-type-zoom">
<code>zoom</code>
</a></td>
@@ -1779,7 +1770,7 @@
<td><a href="#events-Events-UIEvent"><code>UIEvent</code></a></td>
<td>No</td>
<td>none</td>
- </tr> -->
+ </tr>
</table>
<p>As an example of interpreting of this table, the event <a class="eventtype" href="#event-type-load"><code>load</code></a> must trigger event listeners attached on <code>Element</code> nodes for that event and on the capture and target phases. This event cannot be cancelled. If an event listener for the <a class="eventtype" href="#event-type-load"><code>load</code></a> event is attached to a node other than <a class="def" href="#glossary-defaultView"><code>defaultView</code></a>, <code>Document</code>, or <code>Element</code> nodes, or if it is attached to the bubbling phase only, this event listener must not be triggered.</p>
<p>The event objects associated with the event types described above may contain context information. Refer to the description of the DOM interfaces for further information.</p>
@@ -2018,8 +2009,15 @@
<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>
- <p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a user selects some text. This specification does not provide contextual information to access the selected text. <i class="issue" id="issue-selected_text"><strong>Issue:</strong> need to detail how the author can get at this information, perhaps through HTML5 <a href="http://dev.w3.org/html5/spec/editing.html#selection" title="7 User Interaction — HTML 5">text selection APIs</a></i> <!-- The <a class="def" href="#glossary-user-agent">user agent</a> must make the selected text passage available through the <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> attribute. <span class="issue"><strong>Issue:</strong> should the selection include the markup structure, or just the text-content?</span> --> This event is dispatched after the selection has occurred.</p>
- <p class="note"><strong>Note:</strong> The <a class="eventtype" href="#event-type-select"><code>select</code></a> event may not be available for all elements in all languages. For example, in [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>], <a class="eventtype" href="#event-type-select"><code>select</code></a> events will only be dispatched on only form <code>input</code> and <code>textarea</code> elements. Implementations may dispatch <a class="eventtype" href="#event-type-select"><code>select</code></a> events in any context deemed appropriate, including text selections outside of form controls, or image or markup selections such as in SVG.</p>
+ <p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a user selects some text. This event is dispatched after the selection has occurred.</p>
+
+ <p>This specification does not provide contextual information to access the selected text. Where applicable, a <a class="def" href="#glossary-host-language">host language</a> should define rules for how a user may select content (with consideration for international language conventions), at what point the <a class="eventtype" href="#event-type-select"><code>select</code></a> event is dispatched, and how an author may access the user-selected content.</p>
+
+ <p class="note" id="note-get-select"><strong>Note:</strong> In order to access to user-selected content, authors should use native capabilities of the <a class="def" href="#glossary-host-language">host languages</a>, such as the <code>Document.getSelection()</code> method of HTML's <a href="http://dev.w3.org/html5/spec/editing.html#selection" title="7 User Interaction — HTML 5">text selection APIs</a> [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>].</p>
+
+ <p class="note"><strong>Note:</strong> The <a class="eventtype" href="#event-type-select"><code>select</code></a> event may not be available for all elements in all languages. For example, in [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>], <a class="eventtype" href="#event-type-select"><code>select</code></a> events may only be dispatched on only form <code>input</code> and <code>textarea</code> elements. Implementations may dispatch <a class="eventtype" href="#event-type-select"><code>select</code></a> events in any context deemed appropriate, including text selections outside of form controls, or image or markup selections such as in SVG.</p>
+
+
</dd>
</dl>
</div>
@@ -2077,8 +2075,9 @@
</dd>
</dl>
</div>
+
<!-- zoom -->
-<!-- <div class="event-definition assert must">
+ <div class="event-definition assert must">
<dl>
<dt id="event-type-zoom"><dfn><a class="eventtype" href="#event-type-zoom"><code>zoom</code></a></dfn></dt>
<dd>
@@ -2090,15 +2089,19 @@
<tr class="assert must"><th>Target</th><td><a class="def" href="#glossary-defaultView"><code>defaultView</code></a>, <code>Document</code>, <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> is in use. The <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> attribute indicates the <a href="#events-current-scale-coefficient">current scale coefficient</a> of the <a class="def" href="#glossary-event-target">event target</a>.</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>
+ <!-- <tr class="assert must"><th>Context info</th><td><a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> is in use. The <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> attribute indicates the <a href="#events-current-scale-coefficient">current scale coefficient</a> of the <a class="def" href="#glossary-event-target">event target</a>.</td></tr> -->
</table>
<p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a document view or an element has been zoomed. This event type is dispatched after the scroll has occurred.</p>
- <p>The value of <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> must reflect the <dfn id="events-current-scale-coefficient">current scale coefficient</dfn> (or "zoom level") of the document or element. The initial value for the current scale coefficient must be 1. Each doubling in size of the <a class="def" href="#glossary-event-target">event target</a> must multiply the current scale coefficient, and each halving</p>
+ <p class="note"><strong>Note:</strong> The <a class="eventtype" href="#event-type-zoom"><code>zoom</code></a> event may not be available for all elements in all languages. For example, in [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>], <a class="eventtype" href="#event-type-select"><code>select</code></a> events will only be dispatched on only form <code>input</code> and <code>textarea</code> elements. Implementations may dispatch <a class="eventtype" href="#event-type-select"><code>select</code></a> events in any context deemed appropriate, including text selections outside of form controls, or image or markup selections such as in SVG.</p>
+
+ <!-- <p>A <a class="def" href="#glossary-host-language">host language</a> which can be zoomed should define a way for authors to access the manner</p> -->
+ <!-- <p>The value of <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> must reflect the <dfn id="events-current-scale-coefficient">current scale coefficient</dfn> (or "zoom level") of the document or element. The initial value for the current scale coefficient must be 1. Each doubling in size of the <a class="def" href="#glossary-event-target">event target</a> must multiply the current scale coefficient, and each halving</p> -->
</dd>
</dl>
</div>
- -->
+
</div>
</div>
<!-- interface events-focusevents -->
@@ -2396,15 +2399,28 @@
<dd>Refer to the <a href="#events-Events-KeyboardEvent-altKey"><code>KeyboardEvent.altKey</code></a> attribute.<br /></dd>
<dt><code class="attribute-name"><a id="events-Events-MouseEvent-button">button</a></code> of type <code>unsigned short</code>, readonly</dt>
- <dd>During mouse events caused by the depression or release of a mouse button, <code>button</code> shall be used to indicate which pointer device button changed state. <code>0</code> must indicate the primary button of the device (in general, the left button or the only button on single-button devices, used to activate a user interface control or select text). <code>2</code> must indicate the secondary button (in general, the right button, often used to display a context menu). <code>1</code> must indicate the auxiliary button (in general, the middle button, often combined with a mouse wheel). Some mice may provide or simulate more buttons, and values higher than <code>2</code> may be used to represent such buttons.<br /></dd>
+ <dd>
+ During mouse events caused by the depression or release of a mouse button, <code>button</code> shall be used to indicate which pointer device button changed state.
+ <p>The value of the <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a> attribute must be as follows:</p>
+ <ul>
+ <li><code>0</code> must indicate the primary button of the device (in general, the left button or the only button on single-button devices, used to activate a user interface control or select text).</li>
+ <li><code>1</code> must indicate the auxiliary button (in general, the middle button, often combined with a mouse wheel).</li>
+ <li><code>2</code> must indicate the secondary button (in general, the right button, often used to display a context menu).</li>
+ </ul>
+ <p>Some pointing devices may provide or simulate more buttons, and values higher than <code>2</code> may be used to represent such buttons.</p>
+ </dd>
<dt><code class="attribute-name"><a id="events-Events-MouseEvent-buttons">buttons</a></code> of type <code>unsigned short</code>, readonly</dt>
<dd>During mouse events caused by the depression or release of a mouse button, <code>buttons</code> shall be used to indicate which combination of mouse buttons are currently being pressed, expressed as a bitmask. <span class="note"><strong>Note:</strong> This should not be confused with the <a href="#events-Events-MouseEvent-button">button</a> attribute.</span>
- <code>0</code> must indicates no button is currently active.
- <code>1</code> must indicate the primary button of the device (in general, the left button or the only button on single-button devices, used to activate a user interface control or select text).
- <code>2</code> must indicate the secondary button (in general, the right button, often used to display a context menu), if present.
- <code>4</code> must indicate the auxiliary button (in general, the middle button, often combined with a mouse wheel).
- Some pointer devices may provide or simulate more buttons. To represent such buttons, the value must be doubled for each successive button (in the binary series <code>8</code>, <code>16</code>, <code>32</code>, ... ), and the buttons should alternate sides of the device, from left to right. For example, with a 5-button mouse, the primary button (on the left) would have the value <code>1</code>, the secondary button (on the right) would have the value <code>2</code>, the auxiliary button (in the middle) would have the value <code>4</code>, the fourth button (on the left) would have the value <code>8</code>, and the fifth button (on the right) would have the value <code>16</code>. Because the sum of any set of button values is a unique number, an author can use a bitwise operation to determine how many buttons are currently being pressed and which buttons they are, for an arbitrary number of mouse buttons on a device, e.g. the value <code>3</code> indicates that the left and right button are currently both pressed, while the value <code>5</code> indicates that the left and middle button are currently both pressed.
+ <p>The value of the <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a> attribute must be as follows:</p>
+ <ul>
+ <li><code>0</code> must indicates no button is currently active.</li>
+ <li><code>1</code> must indicate the primary button of the device (in general, the left button or the only button on single-button devices, used to activate a user interface control or select text).</li>
+ <li><code>2</code> must indicate the secondary button (in general, the right button, often used to display a context menu), if present.</li>
+ <li><code>4</code> must indicate the auxiliary button (in general, the middle button, often combined with a mouse wheel).</li>
+ </ul>
+ <p>Some pointing devices may provide or simulate more buttons. To represent such buttons, the value must be doubled for each successive button (in the binary series <code>8</code>, <code>16</code>, <code>32</code>, ... ), and the buttons should alternate sides of the device, from left to right. For example, with a 5-button mouse, the primary button (on the left) would have the value <code>1</code>, the secondary button (on the right) would have the value <code>2</code>, the auxiliary button (in the middle) would have the value <code>4</code>, the fourth button (on the left) would have the value <code>8</code>, and the fifth button (on the right) would have the value <code>16</code>. </p>
+ <span class="note" id="buttons-mask"><strong>Note:</strong> Because the sum of any set of button values is a unique number, an author can use a bitwise operation to determine how many buttons are currently being pressed and which buttons they are, for an arbitrary number of mouse buttons on a device, e.g. the value <code>3</code> indicates that the left and right button are currently both pressed, while the value <code>5</code> indicates that the left and middle button are currently both pressed.</p>
</dd>
<dt><code class="attribute-name"><a id="events-Events-MouseEvent-clientX">clientX</a></code> of type <code>long</code>, readonly</dt>
@@ -2554,10 +2570,36 @@
<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><a class="eventtype" href="#event-type-DOMActivate"><code>DOMActivate</code></a> event</td></tr>
- <tr class="assert must"><th>Context info</th><td><a href="#events-Events-MouseEvent-screenX"><code>MouseEvent.screenX</code></a>, <a href="#events-Events-MouseEvent-screenY"><code>MouseEvent.screenY</code></a>, <a href="#events-Events-MouseEvent-clientX"><code>MouseEvent.clientX</code></a>, <a href="#events-Events-MouseEvent-clientY"><code>MouseEvent.clientY</code></a>, <a href="#events-Events-MouseEvent-altKey"><code>MouseEvent.altKey</code></a>, <a href="#events-Events-MouseEvent-ctrlKey"><code>MouseEvent.ctrlKey</code></a>, <a href="#events-Events-MouseEvent-shiftKey"><code>MouseEvent.shiftKey</code></a>, <a href="#events-Events-MouseEvent-metaKey"><code>MouseEvent.metaKey</code></a>, <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a>, and <a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> are in use. The <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> attribute indicates the <a href="#events-dt-current-click-count">current click count</a>. The attribute value shall be <code>1</code> when the user begins this action and increments by <code>1</code> for each click.</td></tr>
+ <tr class="assert must"><th>Default action</th><td>Varies</td></tr>
+ <tr class="assert must"><th>Context info</th><td><a href="#events-Events-MouseEvent-screenX"><code>MouseEvent.screenX</code></a>, <a href="#events-Events-MouseEvent-screenY"><code>MouseEvent.screenY</code></a>, <a href="#events-Events-MouseEvent-clientX"><code>MouseEvent.clientX</code></a>, <a href="#events-Events-MouseEvent-clientY"><code>MouseEvent.clientY</code></a>, <a href="#events-Events-MouseEvent-altKey"><code>MouseEvent.altKey</code></a>, <a href="#events-Events-MouseEvent-ctrlKey"><code>MouseEvent.ctrlKey</code></a>, <a href="#events-Events-MouseEvent-shiftKey"><code>MouseEvent.shiftKey</code></a>, <a href="#events-Events-MouseEvent-metaKey"><code>MouseEvent.metaKey</code></a>, <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a>, <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a>, and <a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> are in use. The <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> attribute indicates the <a href="#events-dt-current-click-count">current click count</a>. The attribute value shall be <code>1</code> when the user begins this action and increments by <code>1</code> for each click.</td></tr>
</table>
- <p>The <a class="eventtype" href="#event-type-click"><code>click</code></a> event must be dispatched on the <a class="def" href="#glossary-topmost-event-target">topmost event target</a> indicated by the pointer, when the user presses down and releases the pointer button, or otherwise activates the pointer in a manner that simulates such an action. Activation of the button may depend upon the pointer device and the environment configuration, e.g. it may depend on the screen location or the delay between the press and release of the pointing device button. The <a class="eventtype" href="#event-type-click"><code>click</code></a> event may be preceded by the <a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a> and <a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a> events on the same element. Depending upon the environment configuration, the <a class="eventtype" href="#event-type-click"><code>click</code></a> event may be dispatched if one or more of the event types <a class="eventtype" href="#event-type-mouseover"><code>mouseover</code></a>, <a class="eventtype" href="#event-type-mousemove"><code>mousemove</code></a>, and <a class="eventtype" href="#event-type-mouseout"><code>mouseout</code></a> occur between the press and release of the pointing device button. The <a class="eventtype" href="#event-type-click"><code>click</code></a> event may also be followed by the <a class="eventtype" href="#event-type-dblclick"><code>dblclick</code></a> event. The <a class="eventtype" href="#event-type-click"><code>click</code></a> event type must be dispatched as described in <a href="#event-flow-activation">Activation triggers and behavior</a>.</p>
+ <p>The <a class="eventtype" href="#event-type-click"><code>click</code></a> event must be dispatched on the <a class="def" href="#glossary-topmost-event-target">topmost event target</a> indicated by the pointer, when the user presses down and releases the pointer button, or otherwise activates the pointer in a manner that simulates such an action. Activation of the button may depend upon the pointer device and the environment configuration, e.g. it may depend on the screen location or the delay between the press and release of the pointing device button. The <a class="eventtype" href="#event-type-click"><code>click</code></a> event may be preceded by the <a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a> and <a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a> events on the same element. Depending upon the environment configuration, the <a class="eventtype" href="#event-type-click"><code>click</code></a> event may be dispatched if one or more of the event types <a class="eventtype" href="#event-type-mouseover"><code>mouseover</code></a>, <a class="eventtype" href="#event-type-mousemove"><code>mousemove</code></a>, and <a class="eventtype" href="#event-type-mouseout"><code>mouseout</code></a> occur between the press and release of the pointing device button. The <a class="eventtype" href="#event-type-click"><code>click</code></a> event may also be followed by the <a class="eventtype" href="#event-type-dblclick"><code>dblclick</code></a> event.</p>
+
+ <p>In addition to being associated with pointer devices, the <a class="eventtype" href="#event-type-click"><code>click</code></a> event type must be dispatched as part of an element activation, as described in <a href="#event-flow-activation">Activation triggers and behavior</a>.</p>
+
+ <p class="note" id="click-activation"><strong>Note:</strong> For maximum accessibility, authors should use the <a class="eventtype" href="#event-type-click"><code>click</code></a> event type when defining activation behavior for custom controls, rather than other pointing-device event types such as <a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a> or <a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a>, which are more device-specific.</p>
+
+ <p>The <a class="def" href="#glossary-default-action">default action</a> of the <a class="eventtype" href="#event-type-click"><code>click</code></a> event type varies based on the <a class="def" href="#glossary-proximal-event-target">proximal event target</a> of the event and the value of the <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a> or <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a> attributes. Typical <a class="def" href="#glossary-default-action">default actions</a> of the <a class="eventtype" href="#event-type-click"><code>click</code></a> event type are as follows:</p>
+ <ul>
+ <li><em>Left click</em> (<a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a> value is <code>0</code>, <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a> value is <code>1</code>):
+ <ul>
+ <li>If the <a class="def" href="#glossary-proximal-event-target">proximal event target</a> has associated activation behavior, the <a class="def" href="#glossary-default-action">default action</a> shall be to execute that activation behavior (see <a href="#event-flow-activation">Activation triggers and behavior</a>).</li>
+ <li>If the <a class="def" href="#glossary-proximal-event-target">proximal event target</a> is focusable, the <a class="def" href="#glossary-default-action">default action</a> shall be to give that element document focus.</li>
+ </ul>
+ </li>
+ <li><em>Right click</em> (<a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a> value is <code>1</code>, <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a> value is <code>2</code>):
+ <ul>
+ <li>The <a class="def" href="#glossary-default-action">default action</a> shall be to provide a context menu of options related to that <a class="def" href="#glossary-proximal-event-target">proximal event target</a>.</li>
+ </ul>
+ </li>
+ <li><em>Middle click</em> (<a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a> value is <code>2</code>, <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a> value is <code>4</code>):
+ <ul>
+ <li>If the <a class="def" href="#glossary-proximal-event-target">proximal event target</a> has associated activation behavior, the <a class="def" href="#glossary-default-action">default action</a> shall be to execute that activation behavior in an alternate fashion (such as opening a link in a new tab or window).</li>
+ <li>If the <a class="def" href="#glossary-proximal-event-target">proximal event target</a> has no associated activation behavior, the <a class="def" href="#glossary-default-action">default action</a> shall be device- and user-defined, but when associated with a device wheel, is often to activate an alternate scrolling or panning mode.</li>
+ </ul>
+ </li>
+ </ul>
+
<!-- <a class="def" href="#glossary-topmost-event-target">topmost event target</a> -->
<!-- || Are you asking for the spec to say something along the lines of, "The
|| 'click' event is fired when the user presses a button on the pointer
@@ -2591,10 +2633,18 @@
<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-MouseEvent-screenX"><code>MouseEvent.screenX</code></a>, <a href="#events-Events-MouseEvent-screenY"><code>MouseEvent.screenY</code></a>, <a href="#events-Events-MouseEvent-clientX"><code>MouseEvent.clientX</code></a>, <a href="#events-Events-MouseEvent-clientY"><code>MouseEvent.clientY</code></a>, <a href="#events-Events-MouseEvent-altKey"><code>MouseEvent.altKey</code></a>, <a href="#events-Events-MouseEvent-ctrlKey"><code>MouseEvent.ctrlKey</code></a>, <a href="#events-Events-MouseEvent-shiftKey"><code>MouseEvent.shiftKey</code></a>, <a href="#events-Events-MouseEvent-metaKey"><code>MouseEvent.metaKey</code></a>, <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a>, and <a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> are in use. The <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> attribute indicates the <a href="#events-dt-current-click-count">current click count</a>.</td></tr>
+ <tr class="assert must"><th>Context info</th><td><a href="#events-Events-MouseEvent-screenX"><code>MouseEvent.screenX</code></a>, <a href="#events-Events-MouseEvent-screenY"><code>MouseEvent.screenY</code></a>, <a href="#events-Events-MouseEvent-clientX"><code>MouseEvent.clientX</code></a>, <a href="#events-Events-MouseEvent-clientY"><code>MouseEvent.clientY</code></a>, <a href="#events-Events-MouseEvent-altKey"><code>MouseEvent.altKey</code></a>, <a href="#events-Events-MouseEvent-ctrlKey"><code>MouseEvent.ctrlKey</code></a>, <a href="#events-Events-MouseEvent-shiftKey"><code>MouseEvent.shiftKey</code></a>, <a href="#events-Events-MouseEvent-metaKey"><code>MouseEvent.metaKey</code></a>, <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a>, <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a>, and <a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> are in use. The <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> attribute indicates the <a href="#events-dt-current-click-count">current click count</a>.</td></tr>
</table>
<p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a pointing device button is clicked twice over an element. The definition of a double click depends on the environment configuration, except that the event target must be the same between <a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a>, <a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a>, and <a class="eventtype" href="#event-type-dblclick"><code>dblclick</code></a>. This event type must be dispatched after the event type <a class="eventtype" href="#event-type-click"><code>click</code></a> if a click and double click occur simultaneously, and after the event type <a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a> otherwise.</p>
<p class="note"><strong>Note:</strong> Canceling the <a class="eventtype" href="#event-type-click"><code>click</code></a> event must not not affect the firing of a <a class="eventtype" href="#event-type-dblclick"><code>dblclick</code></a> event.</p>
+ <p>As with the <a class="eventtype" href="#event-type-click"><code>click</code></a> event type, the <a class="def" href="#glossary-default-action">default action</a> of the <a class="eventtype" href="#event-type-dblclick"><code>dblclick</code></a> event type varies based on the <a class="def" href="#glossary-proximal-event-target">proximal event target</a> of the event and the value of the <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a> or <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a> attributes. Normally, the typical <a class="def" href="#glossary-default-action">default actions</a> of the <a class="eventtype" href="#event-type-dblclick"><code>dblclick</code></a> event type match those of the <a class="eventtype" href="#event-type-click"><code>click</code></a> event type, with the following additional behavior:</p>
+ <ul>
+ <li><em>Left click</em> (<a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a> value is <code>0</code>, <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a> value is <code>1</code>):
+ <ul>
+ <li>If the <a class="def" href="#glossary-proximal-event-target">proximal event target</a> is selectable, the <a class="def" href="#glossary-default-action">default action</a> shall be to select part or all of the selectable content; subsequent clicks may select additional selectable portions of that content.</li>
+ </ul>
+ </li>
+ </ul>
</dd>
</dl>
</div>
@@ -2614,7 +2664,7 @@
<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-MouseEvent-screenX"><code>MouseEvent.screenX</code></a>, <a href="#events-Events-MouseEvent-screenY"><code>MouseEvent.screenY</code></a>, <a href="#events-Events-MouseEvent-clientX"><code>MouseEvent.clientX</code></a>, <a href="#events-Events-MouseEvent-clientY"><code>MouseEvent.clientY</code></a>, <a href="#events-Events-MouseEvent-altKey"><code>MouseEvent.altKey</code></a>, <a href="#events-Events-MouseEvent-ctrlKey"><code>MouseEvent.ctrlKey</code></a>, <a href="#events-Events-MouseEvent-shiftKey"><code>MouseEvent.shiftKey</code></a>, <a href="#events-Events-MouseEvent-metaKey"><code>MouseEvent.metaKey</code></a>, <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a>, and <a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> are in use. The <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> attribute indicates the <a href="#events-dt-current-click-count">current click count</a> incremented by one. For example, if no click happened before the mousedown, <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> must contain the value <code>1</code>.</td></tr>
+ <tr class="assert must"><th>Context info</th><td><a href="#events-Events-MouseEvent-screenX"><code>MouseEvent.screenX</code></a>, <a href="#events-Events-MouseEvent-screenY"><code>MouseEvent.screenY</code></a>, <a href="#events-Events-MouseEvent-clientX"><code>MouseEvent.clientX</code></a>, <a href="#events-Events-MouseEvent-clientY"><code>MouseEvent.clientY</code></a>, <a href="#events-Events-MouseEvent-altKey"><code>MouseEvent.altKey</code></a>, <a href="#events-Events-MouseEvent-ctrlKey"><code>MouseEvent.ctrlKey</code></a>, <a href="#events-Events-MouseEvent-shiftKey"><code>MouseEvent.shiftKey</code></a>, <a href="#events-Events-MouseEvent-metaKey"><code>MouseEvent.metaKey</code></a>, <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a>, <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a>, and <a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> are in use. The <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> attribute indicates the <a href="#events-dt-current-click-count">current click count</a> incremented by one. For example, if no click happened before the mousedown, <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> must contain the value <code>1</code>.</td></tr>
</table>
<p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a pointing device button is pressed over an element.</p>
</dd>
@@ -2752,7 +2802,7 @@
<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-MouseEvent-screenX"><code>MouseEvent.screenX</code></a>, <a href="#events-Events-MouseEvent-screenY"><code>MouseEvent.screenY</code></a>, <a href="#events-Events-MouseEvent-clientX"><code>MouseEvent.clientX</code></a>, <a href="#events-Events-MouseEvent-clientY"><code>MouseEvent.clientY</code></a>, <a href="#events-Events-MouseEvent-altKey"><code>MouseEvent.altKey</code></a>, <a href="#events-Events-MouseEvent-ctrlKey"><code>MouseEvent.ctrlKey</code></a>, <a href="#events-Events-MouseEvent-shiftKey"><code>MouseEvent.shiftKey</code></a>, <a href="#events-Events-MouseEvent-metaKey"><code>MouseEvent.metaKey</code></a>, <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a>, and <a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> are in use. The <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> attribute indicates the <a href="#events-dt-current-click-count">current click count</a> incremented by one.</td></tr>
+ <tr class="assert must"><th>Context info</th><td><a href="#events-Events-MouseEvent-screenX"><code>MouseEvent.screenX</code></a>, <a href="#events-Events-MouseEvent-screenY"><code>MouseEvent.screenY</code></a>, <a href="#events-Events-MouseEvent-clientX"><code>MouseEvent.clientX</code></a>, <a href="#events-Events-MouseEvent-clientY"><code>MouseEvent.clientY</code></a>, <a href="#events-Events-MouseEvent-altKey"><code>MouseEvent.altKey</code></a>, <a href="#events-Events-MouseEvent-ctrlKey"><code>MouseEvent.ctrlKey</code></a>, <a href="#events-Events-MouseEvent-shiftKey"><code>MouseEvent.shiftKey</code></a>, <a href="#events-Events-MouseEvent-metaKey"><code>MouseEvent.metaKey</code></a>, <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a>, <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a>, and <a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> are in use. The <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> attribute indicates the <a href="#events-dt-current-click-count">current click count</a> incremented by one.</td></tr>
</table>
<p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a pointing device button is released over an element.</p>
</dd>
@@ -2907,7 +2957,7 @@
<tr class="assert must"><th>Target</th><td><a class="def" href="#glossary-defaultView"><code>defaultView</code></a>, <code>Document</code>, <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>scroll (or zoom) the document</td></tr>
- <tr class="assert must"><th>Context info</th><td><a href="#events-Events-WheelEvent-deltaX"><code>WheelEvent.deltaX</code></a>, <a href="#events-Events-WheelEvent-deltaY"><code>WheelEvent.deltaY</code></a>, <a href="#events-Events-WheelEvent-deltaZ"><code>WheelEvent.deltaZ</code></a>, <a href="#events-Events-MouseEvent-altKey"><code>MouseEvent.altKey</code></a>, <a href="#events-Events-MouseEvent-ctrlKey"><code>MouseEvent.ctrlKey</code></a>, <a href="#events-Events-MouseEvent-shiftKey"><code>MouseEvent.shiftKey</code></a>, <a href="#events-Events-MouseEvent-metaKey"><code>MouseEvent.metaKey</code></a>, and <a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> are in use. <a href="#events-Events-MouseEvent-screenX"><code>MouseEvent.screenX</code></a>, <a href="#events-Events-MouseEvent-screenY"><code>MouseEvent.screenY</code></a>, <a href="#events-Events-MouseEvent-clientX"><code>MouseEvent.clientX</code></a>, <a href="#events-Events-MouseEvent-clientY"><code>MouseEvent.clientY</code></a>, and <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a> are in use if the wheel is associated to a pointing device. <a href="#events-Events-MouseEvent-relatedTarget"><code>MouseEvent.relatedTarget</code></a> indicates the <a class="def" href="#glossary-event-target">event target</a> the pointing device is pointing at, if any. <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> is not in use.</td></tr>
+ <tr class="assert must"><th>Context info</th><td><a href="#events-Events-WheelEvent-deltaX"><code>WheelEvent.deltaX</code></a>, <a href="#events-Events-WheelEvent-deltaY"><code>WheelEvent.deltaY</code></a>, <a href="#events-Events-WheelEvent-deltaZ"><code>WheelEvent.deltaZ</code></a>, <a href="#events-Events-MouseEvent-altKey"><code>MouseEvent.altKey</code></a>, <a href="#events-Events-MouseEvent-ctrlKey"><code>MouseEvent.ctrlKey</code></a>, <a href="#events-Events-MouseEvent-shiftKey"><code>MouseEvent.shiftKey</code></a>, <a href="#events-Events-MouseEvent-metaKey"><code>MouseEvent.metaKey</code></a>, and <a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a> are in use. <a href="#events-Events-MouseEvent-screenX"><code>MouseEvent.screenX</code></a>, <a href="#events-Events-MouseEvent-screenY"><code>MouseEvent.screenY</code></a>, <a href="#events-Events-MouseEvent-clientX"><code>MouseEvent.clientX</code></a>, <a href="#events-Events-MouseEvent-clientY"><code>MouseEvent.clientY</code></a>, and <a href="#events-Events-MouseEvent-button"><code>MouseEvent.button</code></a>, <a href="#events-Events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a> are in use if the wheel is associated to a pointing device. <a href="#events-Events-MouseEvent-relatedTarget"><code>MouseEvent.relatedTarget</code></a> indicates the <a class="def" href="#glossary-event-target">event target</a> the pointing device is pointing at, if any. <a href="#events-Events-UIEvent-detail"><code>UIEvent.detail</code></a> is not in use.</td></tr>
</table>
<p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a mouse wheel has been rotated around any axis, or when an equivalent input device (such as a mouse-ball, certain tablets or touchpads, etc.) has emulated such an action.</p>
<p>The typical default action of the <a class="eventtype" href="#event-type-wheel"><code>wheel</code></a> event type is to scroll (or in some cases, zoom) the document by the indicated amount. If this event is canceled, the implementation must not scroll or zoom the document (or perform whatever other implementation-specific default action is associated with this event type).</p>
@@ -3314,8 +3364,7 @@
</li>
<li><a class="eventtype" href="#event-type-keypress"><code>keypress</code></a> (only for keys which produce a <a class="def" href="#glossary-character-value">character value</a>)</li>
<li>If a <a class="def" href="#glossary-character-value">character value</a> is produced, <a class="eventtype" href="#event-type-textInput"><code>textInput</code></a></li>
- <li>If the key is depressed for a sustained period, the following events may repeat at an environment-dependent rate:
- <!-- and the key should seek counseling -->
+ <li>If the key is depressed for a sustained period,<!-- the key should seek counseling, and --> the following events may repeat at an environment-dependent rate:
<ul>
<li><a class="eventtype" href="#event-type-keydown"><code>keydown</code></a> (with <a href="#events-Events-KeyboardEvent-repeat">repeat</a> attribute set to <code class="value">true</code>)</li>
<li><a class="eventtype" href="#event-type-keypress"><code>keypress</code></a> (with <a href="#events-Events-KeyboardEvent-repeat">repeat</a> attribute set to <code class="value">true</code>; only for keys which produce a <a class="def" href="#glossary-character-value">character value</a>)</li>
@@ -3554,7 +3603,7 @@
<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>, and <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code></a>.</td></tr>
</table>
- <p>A <a class="def" href="#glossary-user-agent">user agent</a> should dispatch this event when a <a class="def" href="#glossary-text-composition-system">text composition system</a> updates its active text passage with a new character, which is added to the string in <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code></a>. Note that some <a class="def" href="#glossary-text-composition-system">text composition systems</a> may not expose this information to the DOM, in which case this event will not fire during the composition process. If the composition session is canceled, this event will be fired immediately before the <a class="eventtype" href="#event-type-compositionend"><code>compositionend</code></a> event, and the <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code> attribute will be set to <code>null</code><i class="issue" id="issue-null_vs_empty-string">(<strong>Issue:</strong> "null" or "empty string"? What's the distinction?)</i>.</a></p>
+ <p>A <a class="def" href="#glossary-user-agent">user agent</a> should dispatch this event when a <a class="def" href="#glossary-text-composition-system">text composition system</a> updates its active text passage with a new character, which is added to the string in <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code></a>. Note that some <a class="def" href="#glossary-text-composition-system">text composition systems</a> may not expose this information to the DOM, in which case this event will not fire during the composition process. If the composition session is canceled, this event will be fired immediately before the <a class="eventtype" href="#event-type-compositionend"><code>compositionend</code></a> event, and the <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code></a> attribute will be set to <code>null</code>.</p>
</dd>
</dl>
</div>