--- a/html/DOM3-Events.html Sat Mar 03 07:07:35 2012 +0900
+++ b/html/DOM3-Events.html Sat Mar 03 07:11:08 2012 +0900
@@ -353,16 +353,16 @@
<p><strong>This section is normative.</strong></p>
<p>Within this specification, the key words
- “MUST”,
- “MUST NOT”,
- “REQUIRED”,
- “SHALL”,
- “SHALL NOT”,
- “SHOULD”,
- “SHOULD NOT”,
- “RECOMMENDED”,
- “MAY”, and
- “OPTIONAL” are to be interpreted as
+ <q>MUST</q>,
+ <q>MUST NOT</q>,
+ <q>REQUIRED</q>,
+ <q>SHALL</q>,
+ <q>SHALL NOT</q>,
+ <q>SHOULD</q>,
+ <q>SHOULD NOT</q>,
+ <q>RECOMMENDED</q>,
+ <q>MAY</q>, and
+ <q>OPTIONAL</q> are to be interpreted as
described in <a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>
[<a href="#ref-rfc2119">RFC2119</a>].
However, for readability, these words do not necessarily appear in uppercase in this specification.</p>
@@ -372,7 +372,7 @@
<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, 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-value">key values</a> in the <a href="#key-values">Key Values Set</a> (subject to platform availability), 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-EventTarget">EventTarget</a> when the conditions defined for that <a class="def" href="#glossary-event-type">event type</a> have been met.</p>
+ <p>A dynamic or interactive <a class="def" href="#glossary-user-agent">user agent</a>, referred to here as a <q>browser</q> (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-value">key values</a> in the <a href="#key-values">Key Values Set</a> (subject to platform availability), 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-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>
@@ -403,20 +403,20 @@
<p><em>This section is normative</em></p>
<p>A conforming DOM Level 3 Events <a class="def" href="#glossary-user-agent">user agent</a> must implement the <a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-5CED94D7"><code>DOMImplementation.hasFeature()</code></a> method to allow content authors to detect for support of features defined in this specification. Refer to <a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMFeatures"><em>DOM Features</em></a> in [<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>] for additional information on feature strings.</p>
- <p class="note" id="_0"><strong>Note:</strong> The <a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-5CED94D7"><code>DOMImplementation.hasFeature()</code></a> method has been of limited utility to content authors in some instances, because of imprecision in conformance criteria in some specifications, and insufficient granularity of feature strings, leading to implementations misrepresenting the degree of support for a class of features. This specification seeks to remedy that in the context of <a class="def" href="#glossary-user-agent">user agents</a> conforming to DOM Level 3 Events by providing discrete feature strings and clear guidelines for the circumstances under which a <a class="def" href="#glossary-user-agent">user agent</a> must or must not report in a positive manner when queried for support of the feature which that feature string represents.</p>
+ <p class="note" id="_0"><strong>Note:</strong> The <a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-5CED94D7"><code>DOMImplementation.hasFeature()</code></a> method has been of limited utility to content authors in some instances, because of imprecision in conformance criteria in some specifications, and insufficient granularity of feature strings, leading to implementations misrepresenting the degree of support for a class of features. This specification seeks to remedy that in the context of <a class="def" href="#glossary-user-agent">user agents</a> conforming to DOM Level 3 Events by providing discrete feature strings and clear guidelines for the circumstances under which a <a class="def" href="#glossary-user-agent">user agent</a> responds when queried for support of the feature which that feature string represents.</p>
<p>DOM Level 3 Events introduces compositional feature strings, which are base feature strings combined with extended feature strings, a new mechanism for testing support for each specific feature, rather than relying on modules-level feature strings. A <a class="def" href="#glossary-user-agent">user agent</a> conforming to DOM Level 3 Events must also implement the following feature string convention for describing DOM3 Events feature support:</p>
<ul>
- <li id="base-feature-string">The primary base feature string for DOM Level 3 Events must be “<code>Events</code>”, with the optional version string “<code>3.0</code>”, indicating that the <a class="def" href="#glossary-user-agent">user agent</a> supports the <a href="#conform-arch">DOM Level 3 Events Architecture</a> in the manner described in the appropriate conformance section.
+ <li id="base-feature-string">The primary base feature string for DOM Level 3 Events must be "<code>Events</code>", with the optional version string "<code>3.0</code>", indicating that the <a class="def" href="#glossary-user-agent">user agent</a> supports the <a href="#conform-arch">DOM Level 3 Events Architecture</a> in the manner described in the appropriate conformance section.
<ul>
<li><span class="assert must">Since DOM Level 3 Events is built on top of DOM Level 2 Events [<cite><a class="normative" href="#references-DOM2Events">DOM2 Events</a></cite>], an implementation that returns <code>true</code> for <code>"Events"</code> and <code>"3.0"</code> must also return <code>true</code> for the parameters <code>"Events"</code> and <code>"2.0"</code>.</span></li>
<li><span class="assert mustnot">If the version parameter is omitted, the <a class="def" href="#glossary-user-agent">user agent</a> must not differentiate between the <a href="#conform-arch">DOM Events Architecture</a> as described in DOM Level 3 Events and DOM Level 2 Events, in terms of reporting support for the features indicated by the base feature string.</span></li>
</ul>
</li>
- <li id="extended-feature-string">The extended feature string for each event type defined in DOM Level 3 Events must be the base feature string “<code>Events</code>”, followed by the period character ("."), followed by the name of that event type, with the optional version string “<code>3.0</code>”, indicating that the <a class="def" href="#glossary-user-agent">user agent</a> supports that specific event type in the manner described in the appropriate <a href="#conform-module">conformance section</a>. For example, the feature string for the <a class="eventtype" href="#event-type-textinput"><code>textinput</code></a> event would be “<code>Events.textinput</code>”, with the optional version string “<code>3.0</code>”.
+ <li id="extended-feature-string">The extended feature string for each event type defined in DOM Level 3 Events must be the base feature string "<code>Events</code>", followed by the period character ("."), followed by the name of that event type, with the optional version string "<code>3.0</code>", indicating that the <a class="def" href="#glossary-user-agent">user agent</a> supports that specific event type in the manner described in the appropriate <a href="#conform-module">conformance section</a>. For example, the feature string for the <a class="eventtype" href="#event-type-textinput"><code>textinput</code></a> event would be "<code>Events.textinput</code>", with the optional version string "<code>3.0</code>".
<ul>
- <li><span class="assert must">Because this specification does not retroactively define extended feature strings for DOM Level 2 Events, using the <a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-5CED94D7"><code>DOMImplementation.hasFeature()</code></a> method with extended feature strings with a version string “<code>2.0</code>” must return false.</span><span class="warning" id="_42"><strong>Warning!</strong> Because this mechanism for discrete feature strings was not defined in earlier DOM Events specifications, older user agents which support those specifications but not this one may report false negatives in terms of supporting particular features. For example, a browser which supports the <a class="eventtype" href="#event-type-click"><code>click</code></a> event type as defined in DOM Level 2 Events, but does not support this specification, is likely to return <code>false</code> to the method call <code>document.implementation.hasFeature("Events.click", "")</code>. The content author should not take this for definitive proof that the implementation does not support the <a class="eventtype" href="#event-type-click"><code>click</code></a> event type, but rather that other means of testing are required in that instance. This method is best used as a means to detect positive results, not negative ones. However, it is expected that this will prove of sufficient utility in many cases to justify its use.</span></li>
+ <li><span class="assert must">Because this specification does not retroactively define extended feature strings for DOM Level 2 Events, using the <a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-5CED94D7"><code>DOMImplementation.hasFeature()</code></a> method with extended feature strings with a version string "<code>2.0</code>" must return false.</span><span class="warning" id="_42"><strong>Warning!</strong> Because this mechanism for discrete feature strings was not defined in earlier DOM Events specifications, older user agents which support those specifications but not this one may report false negatives in terms of supporting particular features. For example, a browser which supports the <a class="eventtype" href="#event-type-click"><code>click</code></a> event type as defined in DOM Level 2 Events, but does not support this specification, is likely to return <code>false</code> to the method call <code>document.implementation.hasFeature("Events.click", "")</code>. The content author should not take this for definitive proof that the implementation does not support the <a class="eventtype" href="#event-type-click"><code>click</code></a> event type, but rather that other means of testing are required in that instance. This method is best used as a means to detect positive results, not negative ones. However, it is expected that this will prove of sufficient utility in many cases to justify its use.</span></li>
<li><span class="assert must">A <a class="def" href="#glossary-user-agent">user agent</a> which supports an event type in a manner conforming to DOM Level 2 Events but not conforming to DOM Level 3 Events must not report a positive result to that extended feature string, regardless of the value of the version string.</span></li>
- <li><span class="assert must">A specification or <a class="def" href="#glossary-host-language">host language</a> which <a href="#conf-specs">conforms</a> to DOM Level 3 Events, and which extends this specification in a manner consistent with the <a href="#conf-extend">extension conformance criteria</a>, may define extended feature strings for event types defined in that specification. These extended feature strings may be used with the feature string “<code>Events</code>”.<!-- These extended feature strings may be used with the <a href="#base-feature-string">base feature string</a> of that specification, or with the feature string "<code>Events</code>"; for example, support for the SVG <code>zoom</code> event type might be tested using the method call <code>document.implementation.hasFeature("Events.zoom", "")</code> or the hypothetical <code>document.implementation.hasFeature("SVG.events.zoom", "")</code>. --></span>
+ <li><span class="assert must">A specification or <a class="def" href="#glossary-host-language">host language</a> which <a href="#conf-specs">conforms</a> to DOM Level 3 Events, and which extends this specification in a manner consistent with the <a href="#conf-extend">extension conformance criteria</a>, may define extended feature strings for event types defined in that specification. These extended feature strings may be used with the feature string "<code>Events</code>".<!-- These extended feature strings may be used with the <a href="#base-feature-string">base feature string</a> of that specification, or with the feature string "<code>Events</code>"; for example, support for the SVG <code>zoom</code> event type might be tested using the method call <code>document.implementation.hasFeature("Events.zoom", "")</code> or the hypothetical <code>document.implementation.hasFeature("SVG.events.zoom", "")</code>. --></span>
<p class="example" id="example-zoom"><strong>Example:</strong> Support for the SVG <code>zoom</code> event type might be tested using the method call <code>document.implementation.hasFeature("Events.zoom", "")</code></p>
<!-- <ul>
<li><span class="assert may">A specification or <a class="def" href="#glossary-host-language">host language</a> which extends event types defined in this specification, but which adds functionality to be detected independently. </span></li>
@@ -424,7 +424,7 @@
</li>
</ul>
</li>
- <li>For backwards compatibility, each interface defined in DOM Level 3 Events also has a feature string, which may act as a base feature string or as an extended feature string. If used as a base feature string, it must follow the conventions of the <a href="#base-feature-string">primary base feature string</a> (e.g., “<code>KeyboardEvent</code>”, with the optional version string “<code>3.0</code>”); if used as an extended feature string, it must follow the conventions of the <a href="#extended-feature-string">extended feature strings for event types</a> (e.g., “<code>Events.KeyboardEvent</code>”, with the optional version string “<code>3.0</code>”). In either case, the <a class="def" href="#glossary-user-agent">user agent</a> must only report a positive result if it supports that specific interface and all associated event types in the manner described in the appropriate <a href="#conform-module">conformance section</a>. <span class="warning" id="_2"><strong>Warning!</strong> because this is not as specific as testing for a specific event type and may thus be less likely to be accurate, content authors are encouraged to use the feature strings for event types rather than interfaces.</span></li>
+ <li>For backwards compatibility, each interface defined in DOM Level 3 Events also has a feature string, which may act as a base feature string or as an extended feature string. If used as a base feature string, it must follow the conventions of the <a href="#base-feature-string">primary base feature string</a> (e.g., "<code>KeyboardEvent</code>", with the optional version string "<code>3.0</code>"); if used as an extended feature string, it must follow the conventions of the <a href="#extended-feature-string">extended feature strings for event types</a> (e.g., "<code>Events.KeyboardEvent</code>", with the optional version string "<code>3.0</code>"). In either case, the <a class="def" href="#glossary-user-agent">user agent</a> must only report a positive result if it supports that specific interface and all associated event types in the manner described in the appropriate <a href="#conform-module">conformance section</a>. <span class="warning" id="_2"><strong>Warning!</strong> because this is not as specific as testing for a specific event type and may thus be less likely to be accurate, content authors are encouraged to use the feature strings for event types rather than interfaces.</span></li>
</ul>
<p class="warning" id="_3"><strong>Warning!</strong> This specification does not provide a means to guarantee that any given element of a <a class="def" href="#glossary-host-language">host language</a> is capable of generating or dispatching an event of any given <a class="def" href="#glossary-event-type">event type</a> (e.g., an HTML <code>'img'</code> element may not dispatch a <a class="eventtype" href="#event-type-textinput"><code>textinput</code></a> event), or what the attributes of that event will be beyond those defined in this specification (e.g., the host language may add attributes to the event object). A <a class="def" href="#glossary-host-language">host language</a> may provide a different means to do so, including its own relevant feature strings.</p>
</div>
@@ -451,7 +451,7 @@
<p class="issue"><strong>Issue:</strong> This is an open issue.</p>
</div>
<p>Feedback on features at risk, new features, and open issues is especially appreciated.</p>
- <p>In addition, certain terms are used in this specification with particular meanings. The term “implementation” applies to a browser, content authoring tool, or other <a class="def" href="#glossary-user-agent">user agent</a> that implements this specification, while a content author is a person who writes script or code that takes advantage of the interfaces, methods, attributes, events, and other features described in this specification in order to make Web applications, and a user is the person who uses those Web applications in an implementation.</p>
+ <p>In addition, certain terms are used in this specification with particular meanings. The term <q>implementation</q> applies to a browser, content authoring tool, or other <a class="def" href="#glossary-user-agent">user agent</a> that implements this specification, while a content author is a person who writes script or code that takes advantage of the interfaces, methods, attributes, events, and other features described in this specification in order to make Web applications, and a user is the person who uses those Web applications in an implementation.</p>
</div>
<!-- div3 Conformance -->
</div>
@@ -479,9 +479,9 @@
<dt id="glossary-character-value"><dfn>character value</dfn></dt>
<dd>In the context of key values, a character value is a string representing one or more Unicode characters, such as a letter or symbol, or a set of letters.
- <span class="note" id="note_character-value-escapes"><strong>Note:</strong> in source code, some key values, such as non-graphic characters, may be represented using the character escape syntax of the programming language in use.</span>
+ <span class="note" id="note_character-value-escapes"><strong>Note:</strong> in source code, some key values, such as non-graphic characters, can be represented using the character escape syntax of the programming language in use.</span>
</dd>
- <!-- <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">U+0041</code> for the Latin Capital Letter A key, <code class="value charrep">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> -->
+ <!-- <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">U+0041</code> for the Latin Capital Letter A key, <code class="value charrep">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> -->
<dt id="glossary-dead-key"><dfn>dead key</dfn></dt>
<dd>A dead key is a key or combination of keys which produces no character by itself, but which in combination or sequence with another key produces a modified character, such as a character with diacritical marks (e.g., <code>ö</code>, <code>é</code>, <code>â</code>).</dd>
@@ -500,7 +500,7 @@
<dd>Features marked as deprecated are included in the specification as reference to older implementations or specifications, but are optional and discouraged. Only features which have existing or in-progress replacements must be deprecated in this specification. Implementations which do not already include support for the feature may implement deprecated features for reasons of backwards compatibility with existing content, but content authors creating content should not use deprecated features, unless there is no other way to solve a use case. Other specifications which reference this specification should not use deprecated features, but should point instead to the replacements of which the feature is deprecated in favor. Features marked as deprecated in this specification are expected to be dropped from future specifications.</dd>
<dt id="glossary-dispatch"><dfn>dispatch</dfn></dt>
- <dd>To create an event with attributes and methods appropriate to its type and context, and propagate it through the DOM tree in the specified manner. Interchangeable with the term “<a href="#glossary-fire">fire</a>", e.g., “fire a 'click' event” or “dispatch a 'load' event”.</dd>
+ <dd>To create an event with attributes and methods appropriate to its type and context, and propagate it through the DOM tree in the specified manner. Interchangeable with the term <q><a href="#glossary-fire">fire</a></q>, e.g., <q>fire a 'click' event</q> or <q>dispatch a 'load' event</q>.</dd>
<dt id="glossary-document"><dfn>document</dfn></dt>
<dd>An object instantiating the <a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#i-Document" title="Document Object Model Core"><code>Document</code> interface</a> [<cite><a class="normative" href="#references-DOMCore">DOM3 Core</a></cite>], representing the entire HTML or XML text document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data.</dd>
@@ -509,7 +509,7 @@
<dd>A DOM application is script or code, written by a content author or automatically generated, which takes advantage of the interfaces, methods, attributes, events, and other features described in this specification in order to make dynamic or interactive content, such as Web applications, exposed to users in a <a class="def" href="#glossary-user-agent">user agent</a>.</dd>
<dt id="glossary-DOM-Level-0"><dfn>DOM Level 0</dfn></dt>
- <dd>The term “DOM Level 0” refers to a mix of HTML document functionalities, often not formally specified but traditionally supported as de facto standards, implemented originally by Netscape Navigator version 3.0 or Microsoft Internet Explorer version 3.0. In many cases, attributes or methods have been included for reasons of backward compatibility with “DOM Level 0”.</dd>
+ <dd>The term <q>DOM Level 0</q> refers to a mix of HTML document functionalities, often not formally specified but traditionally supported as de facto standards, implemented originally by Netscape Navigator version 3.0 or Microsoft Internet Explorer version 3.0. In many cases, attributes or methods have been included for reasons of backward compatibility with <q>DOM Level 0</q>.</dd>
<dt id="glossary-empty-string"><dfn>empty string</dfn></dt>
<dd>The empty string is a value of type <code>DOMString</code> of length <code>0</code>, i.e., a string which contains no characters (neither printing nor control characters).</dd>
@@ -536,7 +536,7 @@
<dd>Focus is a special state of receptivity and concentration on an particular element or other <a class="def" href="#glossary-event-target">event target</a> within a document. Each element has different behavior when focused, depending on its functionality, such as priming the element for activation (as for a button or hyperlink) or toggling state (as for a checkbox), receiving text input (as for a text form field), or copying selected text. For more details, see <a href="#events-focusevent-doc-focus">Document Focus and Focus Context</a>.</dd>
<dt id="glossary-event-focus-ring"><dfn>focus ring</dfn></dt>
- <dd>A focus ring is a an ordered set of <a class="def" href="#glossary-event-focus">focus</a> targets within a document. A <a class="def" href="#glossary-host-language">host language</a> may define one or more ways to determine the order of targets, such as document order, a numerical index defined per focus target, explicit pointers between focus targets, or a hybrid of different models. Each document may contain multiple focus rings, or conditional focus rings. Typically, for document-order or indexed focus rings, focus “wraps around” from the last focus target to the first.</dd>
+ <dd>A focus ring is a an ordered set of <a class="def" href="#glossary-event-focus">focus</a> targets within a document. A <a class="def" href="#glossary-host-language">host language</a> may define one or more ways to determine the order of targets, such as document order, a numerical index defined per focus target, explicit pointers between focus targets, or a hybrid of different models. Each document may contain multiple focus rings, or conditional focus rings. Typically, for document-order or indexed focus rings, focus <q>wraps around</q> from the last focus target to the first.</dd>
<dt id="glossary-fire"><dfn>fire</dfn></dt>
<dd>A synonym for <a href="#glossary-dispatch">dispatch</a>.</dd>
@@ -564,7 +564,7 @@
<dd>A modifier key changes the normal behavior of a key, such as to produce a character of a different case (as with the <a href="#key-Shift"><code class="value keyname">'Shift'</code></a> key), or to alter what functionality the key triggers (as with the <a href="#key-Fn"><code class="value keyname">'Fn'</code></a> or <a href="#key-Alt"><code class="value keyname">'Alt'</code></a> keys). Refer to the <a href="#events-KeyboardEvent-getModifierState"><code>KeyboardEvent.getModifierState()</code></a> method for a list of modifier keys defined in this specification. See also <a href="#keys-Modifiers">Modifier keys</a>.</dd>
<dt id="glossary-namespaceURI"><dfn>namespace URI</dfn></dt>
- <dd>A <em>namespace URI</em> is a URI that identifies an XML namespace. This is called the namespace name in [<cite><a class="informative" href="#references-Namespaces10">XML Namespaces 1.0</a></cite>]. See also sections 1.3.2 "<a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#baseURIs-Considerations"><em>DOM URIs</em></a>" and 1.3.3 "<a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Namespaces-Considerations"><em>XML Namespaces</em></a>" regarding URIs and namespace URIs handling and comparison in the DOM APIs.</dd>
+ <dd>A <em>namespace URI</em> is a URI that identifies an XML namespace. This is called the namespace name in [<cite><a class="informative" href="#references-Namespaces10">XML Namespaces 1.0</a></cite>]. See also sections 1.3.2 <a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#baseURIs-Considerations"><em>DOM URIs</em></a> and 1.3.3 <a class="normative" href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Namespaces-Considerations"><em>XML Namespaces</em></a> regarding URIs and namespace URIs handling and comparison in the DOM APIs.</dd>
<dt id="glossary-phase"><dfn>phase</dfn></dt>
<dd>In the context of <a class="def" href="#glossary-event">events</a>, a phase is set of logical traversals from node to node along the DOM tree, from the <a class="def" href="#glossary-defaultView">defaultView</a> (window), to the <code>Document</code> object, <a class="def" href="#glossary-root-element">root element</a>, and down to the <a class="def" href="#glossary-event-target">event target</a> (<a class="def" href="#glossary-capture-phase">capture phase</a>), at the <a class="def" href="#glossary-event-target">event target</a> itself (<a class="def" href="#glossary-target-phase">target phase</a>), and back up the same chain (<a class="def" href="#glossary-bubbling-phase">bubbling phase</a>).</dd>
@@ -576,7 +576,7 @@
<dd>The proximal event target is the object representing the <a class="def" href="#glossary-event-target">event target</a> to which an <a class="def" href="#glossary-event">event</a> is targeted using the DOM event flow. The proximal event target is the value of the <a href="#events-event-type-target">Event.target</a> attribute.</dd>
<dt id="glossary-qwerty"><dfn>QWERTY</dfn></dt>
- <dd>QWERTY (pronounced "ˈkwɜrti") is a common keyboard layout, so named because the first five character keys on the top row of letter keys are Q, W, E, R, T, and Y. There are many other popular keyboard layouts (including the Dvorak and Colemak layouts), most designed for localization or ergonomics.</dd>
+ <dd>QWERTY (pronounced <q>ˈkwɜrti</q>) is a common keyboard layout, so named because the first five character keys on the top row of letter keys are Q, W, E, R, T, and Y. There are many other popular keyboard layouts (including the Dvorak and Colemak layouts), most designed for localization or ergonomics.</dd>
<dt id="glossary-root-element"><dfn>root element</dfn></dt>
<dd>The first element node of a document, of which all other elements are children; the document element.</dd>
@@ -600,7 +600,7 @@
<dd>The Unicode character categories, a subset of the complete Unicode general categories, comprise the categories <abbr title="Letter, Lowercase">Ll</abbr>, <abbr title="Letter, Modifier">Lm</abbr>, <abbr title="Letter, Other">Lo</abbr>, <abbr title="Letter, Titlecase">Lt</abbr>, <abbr title="Letter, Uppercase">Lu</abbr>, <abbr title="Number, Decimal Digit">Nd</abbr>, <abbr title="Number, Letter">Nl</abbr>, <abbr title="Number, Other">No</abbr>, <abbr title="Punctuation, Connector">Pc</abbr>, <abbr title="Punctuation, Dash">Pd</abbr>, <abbr title="Punctuation, Close">Pe</abbr>, <abbr title="Punctuation, Final quote">Pf</abbr>, <abbr title="Punctuation, Initial quote">Pi</abbr>, <abbr title="Punctuation, Other">Po</abbr>, <abbr title="Punctuation, Open">Ps</abbr>, <abbr title="Symbol, Currency">Sc</abbr>, <abbr title="Symbol, Modifier">Sk</abbr>, <abbr title="Symbol, Math">Sm</abbr>, and <abbr title="Symbol, Other">So</abbr>.</dd>
<dt id="glossary-unicode-code-point"><dfn>Unicode code point</dfn></dt>
- <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 charrep" href="#glossary-character-value">character value</a>.</dd>
+ <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 <code>\u</code> 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 charrep" 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 content authoring tool, normally running on a client machine, which acts on a user's behalf in retrieving, interpreting, executing, presenting, or creating content. 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> for details on the requirements for a <em>conforming</em> user agent.</dd>
@@ -679,10 +679,10 @@
<div>
<h3><a id="sync-async" href="#sync-async">3.3 Synchronous and asynchronous events</a></h3>
- <p>Events may be either synchronously or asynchronously .</p>
- <p>Events which are synchronous (<em>"sync events"</em>) must be treated as if they are in a virtual queue in a first-in-first-out model, ordered by sequence of temporal occurrence, with respect to other events, to changes in the DOM, and to user interaction. Each event in this virtual queue must be delayed until the previous event has completed its propagation behavior, or been canceled. Some sync events are driven by a specific device or process, such as mouse button events; these events are governed by the <a class="def" href="#glossary-event-order">event order</a> algorithms defined for that set of events, and a user agent must dispatch these events in the defined order.</p>
+ <p>Events may be dispatched either synchronously or asynchronously .</p>
+ <p>Events which are synchronous (<em><q>sync events</q></em>) must be treated as if they are in a virtual queue in a first-in-first-out model, ordered by sequence of temporal occurrence, with respect to other events, to changes in the DOM, and to user interaction. Each event in this virtual queue must be delayed until the previous event has completed its propagation behavior, or been canceled. Some sync events are driven by a specific device or process, such as mouse button events; these events are governed by the <a class="def" href="#glossary-event-order">event order</a> algorithms defined for that set of events, and a user agent must dispatch these events in the defined order.</p>
<p class="example" id="example-sync"><strong>Example:</strong> A user double-clicks a passage of text to select a word, then presses the <code class="value">'delete'</code> key to erase the word, triggering the following synchronous sequence of events: <a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a>, <a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a>, <a class="eventtype" href="#event-type-click"><code>click</code></a>, <a class="eventtype" href="#event-type-mousedown"><code>mousedown</code></a>, <a class="eventtype" href="#event-type-mouseup"><code>mouseup</code></a>, <a class="eventtype" href="#event-type-click"><code>click</code></a>, <a class="eventtype" href="#event-type-dblclick"><code>dblclick</code></a>, <a class="eventtype" href="#event-type-select"><code>select</code></a>, <a class="eventtype" href="#event-type-keydown"><code>keydown</code></a>, <a class="eventtype" href="#event-type-DOMCharacterDataModified"><code>DOMCharacterDataModified</code></a>. Each of these events are fired in the sequence initiated by the user's actions.</p>
- <p>Events which are asynchronous (<em>"async events"</em>) may be dispatched as the results of the action are completed, with no relation to other events, to other changes in the DOM, nor to user interaction.</p>
+ <p>Events which are asynchronous (<em><q>async events</q></em>) may be dispatched as the results of the action are completed, with no relation to other events, to other changes in the DOM, nor to user interaction.</p>
<p class="example" id="example-async"><strong>Example:</strong> During loading of a document, an inline script element is parsed and executed. The <a class="eventtype" href="#event-type-load"><code>load</code></a> event is queued to be fired asynchronously at the script element. However, because it is an async event, its order with relation to other synchronous events fired during load (such as the DOMContentLoaded event from <cite><a class="informative" href="#references-HTML5">HTML5</a></cite>).
</p>
</div>
@@ -693,7 +693,7 @@
<p>Most events take place in a sequential context. [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>] defines its event operations in terms of an event loop mechanism, in which events of all types are fed into different <em>task queues</em>. This specification does not define events in terms of this event loop mechanism, but it is compatible with this mechanism. Instead, this specification defines several operation-specific <a class="def" href="#glossary-event-order">event orders</a>.</p>
<p>Using the terminology of HTML5, each independent device, such as a mouse or keyboard, should be treated as a <em>task source</em> which feeds into the appropriate <em>task queue</em>, in the order defined by the <a class="def" href="#glossary-event-order">event order</a> associated with that device; each operation, such as a focus change or composition input, also acts as a <em>task source</em> for the appropriate <em>task queue</em>. The resolution of these event loops is handled in a manner conforming to the <a class="def" href="#glossary-host-language">host language</a>, such as HTML [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>].</p>
- <p class="warning" id="dropped-events"><strong>Warning!</strong> Certain events, such as “hotkeys” or controls keys pressed in a certain sequence, may be “swallowed” by the operating system or the application, interrupting the expected <a class="def" href="#glossary-event-order">event order</a>. Content authors should make appropriate checks for such occurrences.</p>
+ <p class="warning" id="dropped-events"><strong>Warning!</strong> Certain events, such as <q>hotkeys</q> or controls keys pressed in a certain sequence, can be <q>swallowed</q> by the operating system or the application, interrupting the expected <a class="def" href="#glossary-event-order">event order</a>. Content authors should make appropriate checks for such occurrences.</p>
</div>
@@ -714,7 +714,7 @@
<p>Certain <a class="def" href="#glossary-proximal-event-target">proximal event targets</a> (such as a link or button element) may have associated <a class="def" href="#glossary-activation-behavior">activation behavior</a> (such a following a link) that implementations perform in response to an <em><a class="def" href="#glossary-activation-trigger">activation trigger</a></em> (such as clicking a link).</p>
<p>A <a class="def" href="#glossary-host-language">host language</a> should indicate which, if any, elements have activation behavior, describe appropriate <a class="def" href="#glossary-activation-trigger">activation triggers</a>, and define the result of that activation behavior. An implementation which supports a <a class="def" href="#glossary-host-language">host language</a> should initiate these <a class="def" href="#glossary-activation-behavior">activation behavior</a> when the associated <a class="def" href="#glossary-activation-trigger">activation trigger</a> occurs.</p>
<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-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>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 <q>hotkey</q> or <q>access key</q>) 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 content 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 attribute or attribute value.</p>
<h4><a id="click-synthesis" href="#click-synthesis">3.5.1 Activation event synthesis</a></h4>
@@ -725,7 +725,7 @@
<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> has to 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> has to 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 might 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> Content 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, content 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>
+ <p class="note" id="authors-activation"><strong>Authoring Note:</strong> Don't 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>. 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>
<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.</p>
@@ -842,8 +842,8 @@
const unsigned short <a href="#events-BUBBLING_PHASE">BUBBLING_PHASE</a> = 3;
readonly attribute DOMString <a href="#events-event-type-type">type</a>;
- readonly attribute <a href="#events-EventTarget">EventTarget</a> <a href="#events-event-type-target">target</a>;
- readonly attribute <a href="#events-EventTarget">EventTarget</a> <a href="#events-event-type-currentTarget">currentTarget</a>;
+ readonly attribute <a href="#events-EventTarget">EventTarget</a>? <a href="#events-event-type-target">target</a>;
+ readonly attribute <a href="#events-EventTarget">EventTarget</a>? <a href="#events-event-type-currentTarget">currentTarget</a>;
readonly attribute unsigned short <a href="#events-event-type-eventPhase">eventPhase</a>;
readonly attribute boolean <a href="#events-event-type-canBubble">bubbles</a>;
readonly attribute boolean <a href="#events-event-type-canCancel">cancelable</a>;
@@ -1008,7 +1008,8 @@
<dl>
<dt><strong>Interface <em><a id="events-CustomEvent">CustomEvent</a></em></strong> (introduced in <strong class="since">DOM Level 3</strong>)</dt>
<dd>
- <p>The <a href="#events-CustomEvent"><code>CustomEvent</code></a> interface is the recommended interface for application-specific event types. Unlike the <a href="#events-Event"><code>Event</code></a> interface, it allows applications to provide contextual information about the event type. Application-specific event types should use a prefix string on the event type name to avoid clashes with future general-purpose event types.</p>
+ <p>The <a href="#events-CustomEvent"><code>CustomEvent</code></a> interface is the recommended interface for application-specific event types. Unlike the <a href="#events-Event"><code>Event</code></a> interface, it allows applications to provide contextual information about the event type.</p>
+ <p class="note"><strong>Authoring Note:</strong> Use a prefix string on the event type name for application-specific event types to avoid clashes with future general-purpose event types.</p>
<p>To create an instance of the <code>CustomEvent</code> interface, use the <a href="#events-DocumentEvent-createEvent"><code>DocumentEvent.createEvent("CustomEvent")</code></a> method call.</p>
<dl>
<dt>
@@ -1021,11 +1022,11 @@
<span class="comment">// Introduced in DOM Level 3:</span>
interface <a href="#events-CustomEvent">CustomEvent</a> : <a href="#events-Event">Event</a>
{
- readonly attribute any <a href="#events-CustomEvent-detail">detail</a>;
- void <a href="#events-event-type-initCustomEvent">initCustomEvent</a>(DOMString typeArg,
- boolean canBubbleArg,
- boolean cancelableArg,
- any detailArg);
+ readonly attribute any? <a href="#events-CustomEvent-detail">detail</a>;
+ void <a href="#events-event-type-initCustomEvent">initCustomEvent</a>(DOMString typeArg,
+ boolean canBubbleArg,
+ boolean cancelableArg,
+ any? detailArg);
};
</code></pre>
</dd>
@@ -1093,7 +1094,12 @@
<p>When used with the DOM event flow, this interface must be implemented by all <a class="def" href="#glossary-proximal-event-target">proximal event targets</a> and target ancestors, i.e., all DOM <code>Nodes</code> of the tree support this interface when the implementation conforms to DOM Level 3 Events and, therefore, this interface can be obtained by using binding-specific casting methods on an instance of the <code>Node</code> interface.</p>
<p>Invoking <code>addEventListener</code> repeatedly on the same <code>EventTarget</code> with the same values for the parameters <code>type</code>, <code>listener</code>, and <code>useCapture</code> has no effect. Doing so does not cause the <a href="#events-EventListener"><code>EventListener</code></a> to be called more than once and does not cause a change in the triggering order.</p>
- <p class="note" id="EventTarget-onfoo"><strong>Note:</strong> In addition to the <a href="#events-EventTarget-addEventListener">EventTarget.addEventListener</a> method, some <a class="def" href="#glossary-host-language">host languages</a> may allow a content author to register event listeners by the use of attributes, e.g., <em><code>onclick="handleClick()"</code></em>. Because the details of this are often language-specific, this type of event listener registration is not defined in this specification, but in general, any event type may be used as an attribute in this way by adding the prefix <em><code>on-</code></em> to the event type name, and events so dispatched should behave consistently with the event registration and propagation defined in this specification, with the same interfaces, properties, and methods.</p>
+ <p class="note" id="EventTarget-onfoo"><strong>Note:</strong> In addition to the <a href="#events-EventTarget-addEventListener">EventTarget.addEventListener</a> method, some
+ <a class="def" href="#glossary-host-language">host languages</a> allow a content author to register event listeners by the use of attributes, e.g.,
+ <em><code>onclick="handleClick()"</code></em>. Due to the language-specific details, this type of event listener registration is not defined in this
+ specification. In general, many event types can be used as an attribute in this way by adding the prefix <em><code>on-</code></em> to the event type name. Dispatching events
+ to these listeners is expected to behave consistently with the event registration and propagation defined in this specification, with the same interfaces, properties, and methods.
+ </p>
<dl>
<dt>
<br />
@@ -1107,10 +1113,10 @@
<span class="comment">// Modified in DOM Level 3:</span>
void <a href="#events-EventTarget-addEventListener">addEventListener</a>(DOMString type,
<a href="#events-EventListener">EventListener</a>? listener,
- <em>optional</em> boolean useCapture);
+ <em>optional</em> boolean useCapture = false);
void <a href="#events-EventTarget-removeEventListener">removeEventListener</a>(DOMString type,
<a href="#events-EventListener">EventListener</a>? listener,
- <em>optional</em> boolean useCapture);
+ <em>optional</em> boolean useCapture = false);
boolean <a href="#events-EventTarget-dispatchEvent">dispatchEvent</a>(<a href="#events-Event">Event</a> event);
};
</code></pre>
@@ -1135,16 +1141,18 @@
<dt><code class="parameter-name">listener</code> of type <a href="#events-EventListener"><code>EventListener</code></a></dt>
<dd>
- <p>The <code>listener</code> parameter must be either an object that implements the <a href="#events-EventListener"><code>EventListener</code></a> interface or a function. If <code>listener</code> is a function then it must be used as the callback for the event; otherwise, if <code>listener</code> implements <a href="#events-EventListener"><code>EventListener</code></a>, then its <a href="#events-EventListener-handleEvent">handleEvent</a> method must be used as the callback. If <code>listener</code> is a function that also has a <a href="#events-EventListener-handleEvent">handleEvent</a> method, the function itself must be used as the callback and not its <a href="#events-EventListener-handleEvent">handleEvent</a> method.</p>
- <p class="note" id="addEventListener_function"><strong>Note:</strong> If the <code>listener</code> is a function, then it may be a reference to a function object or an inline function object literal.</p>
+ <p>The <code>listener</code> parameter must be an object that implements the <a href="#events-EventListener"><code>EventListener</code></a> interface or a function. If <code>listener</code> is a function then it must be used as the callback for the event; otherwise, if <code>listener</code> implements <a href="#events-EventListener"><code>EventListener</code></a>, then its <a href="#events-EventListener-handleEvent">handleEvent</a> method must be used as the callback. If <code>listener</code> is a function that also has a <a href="#events-EventListener-handleEvent">handleEvent</a> method, the function itself must be used as the callback and not its <a href="#events-EventListener-handleEvent">handleEvent</a> method.</p>
+ <p class="note" id="addEventListener_function"><strong>Note:</strong> When a <code>listener</code> is a function, it can be either a function reference or an inline function object literal.</p>
</dd>
<dt><a id="addEventListener_useCapture"><code class="parameter-name">useCapture</code></a> of type <code>boolean</code></dt>
<dd>
<p>If true, <code>useCapture</code> indicates that the user wishes to add the event listener for the <a class="def" href="#glossary-capture-phase">capture</a> and <a class="def" href="#glossary-target-phase">target</a> phases only, i.e., this event listener will not be triggered during the <a class="def" href="#glossary-bubbling-phase">bubbling</a> phase. If <code>false</code>, the event listener must only be triggered during the <a class="def" href="#glossary-target-phase">target</a> and <a class="def" href="#glossary-bubbling-phase">bubbling</a> phases.</p>
<p>This parameter may be optional, on an implementation-specific basis. If not provided, the <a href="#events-EventTarget-addEventListener">EventTarget.addEventListener</a> method must behave as if <a href="#addEventListener_useCapture"><code class="parameter-name">useCapture</code></a> were specified to be <code>false</code>.</p>
- <p class="note" id="addEventListener_useCapture-java"><strong>Note:</strong> For programming languages which do not allow optional method parameters, such as Java, the implementation may provide two <a href="#events-EventTarget-addEventListener">EventTarget.addEventListener</a> methods, one with 2 parameters, and one with 3 parameters.</p>
- <p class="note" id="addEventListener_useCapture-author"><strong>Authoring Note:</strong> The <a href="#events-EventTarget-addEventListener"><code class="parameter-name">useCapture</code></a> parameter was required in DOM2 Events [<a href="#references-DOM2Events">DOM2 Events</a>], and omitting this parameter may cause an error in older implementations.</p>
+ <!-- WebIDL will/does clarify this for other language bindings - the note isn't needed anymore
+ <p class="note" id="addEventListener_useCapture-java"><strong>Note:</strong> For programming languages which do not allow optional method parameters, such as Java, the implementation may provide two <a href="#events-EventTarget-addEventListener">EventTarget.addEventListener</a> methods, one with 2 parameters, and one with 3 parameters.</p>
+ -->
+ <p class="note" id="addEventListener_useCapture-author"><strong>Authoring Note:</strong> The <a href="#events-EventTarget-addEventListener"><code class="parameter-name">useCapture</code></a> parameter was manditory in DOM2 Events [<a href="#references-DOM2Events">DOM2 Events</a>], and omitting this parameter could cause an error in older implementations.</p>
</dd>
</dl>
</div>
@@ -1174,10 +1182,13 @@
<dd><p>The <a href="#events-EventListener"><code>EventListener</code></a> to be removed.</p></dd>
<dt><code id="removeEventListener_useCapture" class="parameter-name">useCapture</code> of type <code>boolean</code></dt>
<dd>
- <p>Specifies whether the <a href="#events-EventListener"><code>EventListener</code></a> being removed was registered for the capture phase or not. If a listener was registered twice, once for the capture and target phases and once for the target and bubbling phases, each must be removed separately. Removal of an event listener registered for the capture and target phases does not affect the same event listener registered for the target and bubbling phases, and vice versa.</p>
+ <p>Specifies whether the <a href="#events-EventListener"><code>EventListener</code></a> being removed was registered for the capture phase or not.</p>
+ <p class="note"><strong>Authoring Note:</strong> If a listener was registered twice, once for the capture and target phases and once for the target and bubbling phases, this represents two unique registrations. Removal of an event listener registered for the capture and target phases does not affect the same event listener registered for the target and bubbling phases, and vice versa.</p>
<p>This parameter may be optional, on an implementation-specific basis. If not provided, the <a href="#events-EventTarget-removeEventListener">EventTarget.removeEventListener</a> method must behave as if <a href="#removeEventListener_useCapture"><code class="parameter-name">useCapture</code></a> were specified to be <code>false</code>, including the removal of event listeners which had an <a href="#events-EventTarget-addEventListener">EventTarget.addEventListener</a> <a href="#events-EventTarget-addEventListener"><code class="parameter-name">useCapture</code></a> value of <code>false</code>.</p>
- <p class="note" id="removeEventListener_useCapture-java"><strong>Note:</strong> For programming languages which do not allow optional method parameters, such as Java, the implementation may provide two <a href="#events-EventTarget-removeEventListener">EventTarget.removeEventListener</a> methods, one with 2 parameters, and one with 3 parameters.</p>
- <p class="note" id="removeEventListener_useCapture-author"><strong>Authoring Note:</strong> The <a href="#removeEventListener_useCapture"><code class="parameter-name">useCapture</code></a> parameter was required in DOM2 Events [<a href="#references-DOM2Events">DOM2 Events</a>], and omitting this parameter may cause an error in older implementations.</p>
+ <!-- WebIDL will/does clarify this for other language bindings - the note isn't needed anymore
+ <p class="note" id="removeEventListener_useCapture-java"><strong>Note:</strong> For programming languages which do not allow optional method parameters, such as Java, the implementation may provide two <a href="#events-EventTarget-removeEventListener">EventTarget.removeEventListener</a> methods, one with 2 parameters, and one with 3 parameters.</p>
+ -->
+ <p class="note" id="removeEventListener_useCapture-author"><strong>Authoring Note:</strong> The <a href="#removeEventListener_useCapture"><code class="parameter-name">useCapture</code></a> parameter was manditory in DOM2 Events [<a href="#references-DOM2Events">DOM2 Events</a>], and omitting this parameter could cause an error in older implementations.</p>
</dd>
</dl>
</div>
@@ -1232,7 +1243,9 @@
<dl>
<dt><strong>Interface <em><a id="events-EventListener">EventListener</a></em></strong> (introduced in <strong class="since">DOM Level 2</strong>)</dt>
<dd>
- <p>The <code>EventListener</code> interface is the primary way to handle events. Content authors must define on object, such as a function, which the <code>EventListener</code> interface and register their event listener on an <a href="#events-EventTarget"><code>EventTarget</code></a>. The content authors should also remove their <code>EventListener</code> from its <a href="#events-EventTarget"><code>EventTarget</code></a> after they have completed using the listener.</p>
+ <p>The <code>EventListener</code> interface is the primary way to handle events. <code>EventListener</code> represents the callback object that the user agent will invoke when dispatching an <code>Event</code> to an <a href="#events-EventTarget"><code>EventTarget</code></a>.</p>
+ <p class="note"><strong>Note:</strong> Authors define an object which implements the <code>EventListener</code> interface and register their event listener using <a href="#events-EventTarget-addEventListener">EventTarget.addEventListener</a>. In JavaScript, an <code>EventListener</code> can be either a function or an object with a <code>handleEvent</code> member function.</p>
+ <p class="note"><strong>Note:</strong> It is a best practice for authors to remove their <code>EventListener</code> from its <a href="#events-EventTarget"><code>EventTarget</code></a> after they have completed using the listener.</p>
<p>
<span class="assert must">Copying a <code>Node</code>, with methods such as <code>Node.cloneNode</code> or <code>Range.cloneContents</code>, must not copy the event listeners attached to it.</span>
<span class="assert must">Event listeners must be attached to the newly created <code>Node</code> afterwards, if so desired.</span>
@@ -1295,7 +1308,7 @@
<dl>
<dt><strong>Interface <em><a id="events-DocumentEvent">DocumentEvent</a></em></strong> (introduced in <strong class="since">DOM Level 2</strong>)</dt>
<dd>
- <p>The <code>DocumentEvent</code> interface provides a mechanism by which the user can create an <a href="#events-Event"><code>Event</code></a> object of a type supported by the implementation. If the feature “Events” is supported by the <code>Document</code> object, the <code>DocumentEvent</code> interface must be implemented on the same object. Language-specific type casting may be required.</p>
+ <p>The <code>DocumentEvent</code> interface provides a mechanism by which the user can create an <a href="#events-Event"><code>Event</code></a> object of a type supported by the implementation. If the feature string <code>"Events"</code> is supported by the <code>Document</code> object, the <code>DocumentEvent</code> interface must be implemented on the same object. Language-specific type casting might be required.</p>
<dl>
<dt>
<br />
@@ -1871,13 +1884,13 @@
<span class="comment">// Introduced in DOM Level 2:</span>
interface <a href="#events-UIEvent">UIEvent</a> : <a href="#events-Event">Event</a>
{
- readonly attribute AbstractView <a href="#events-UIEvent-view">view</a>;
- readonly attribute long <a href="#events-UIEvent-detail">detail</a>;
- void <a href="#events-event-type-initUIEvent">initUIEvent</a>(DOMString typeArg,
- boolean canBubbleArg,
- boolean cancelableArg,
- AbstractView viewArg,
- long detailArg);
+ readonly attribute AbstractView? <a href="#events-UIEvent-view">view</a>;
+ readonly attribute long <a href="#events-UIEvent-detail">detail</a>;
+ void <a href="#events-event-type-initUIEvent">initUIEvent</a>(DOMString typeArg,
+ boolean canBubbleArg,
+ boolean cancelableArg,
+ AbstractView? viewArg,
+ long detailArg);
};
</code></pre>
</dd>
@@ -1888,7 +1901,7 @@
<dt><code class="attribute-name"><a id="events-UIEvent-detail">detail</a></code> of type <code>long</code>, readonly</dt>
<dd><p>Specifies some detail information about the <a href="#events-Event"><code>Event</code></a>, depending on the type of event.</p></dd>
- <dt><code class="attribute-name"><a id="events-UIEvent-view">view</a></code> of type <code>views::AbstractView</code>, readonly</dt>
+ <dt><code class="attribute-name"><a id="events-UIEvent-view">view</a></code> of type <code>AbstractView</code>, readonly</dt>
<dd><p>The <code>view</code> attribute identifies the <code>AbstractView</code> from which the event was generated.</p></dd>
</dl>
@@ -1918,7 +1931,7 @@
<dt><code class="parameter-name">cancelableArg</code> of type <code>boolean</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initEvent"><code>Event.initEvent()</code></a> method for a description of this parameter.</p></dd>
- <dt><code class="parameter-name">viewArg</code> of type <code>views::AbstractView</code></dt>
+ <dt><code class="parameter-name">viewArg</code> of type <code>AbstractView</code></dt>
<dd><p>Specifies <a href="#events-UIEvent-view"><code>UIEvent.view</code></a>. This value may be <code>null</code>.</p></dd>
<dt><code class="parameter-name">detailArg</code> of type <code>long</code></dt>
@@ -2166,9 +2179,9 @@
<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 a content 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, 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" id="note-get-select"><strong>Note:</strong> In order to access to user-selected content, content authors will 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" id="note-select-na"><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 can be dispatched only on form <code>input</code> and <code>textarea</code> elements. Implementations can 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 class="note" id="note-select-na"><strong>Note:</strong> The <a class="eventtype" href="#event-type-select"><code>select</code></a> event might 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 can be dispatched only on form <code>input</code> and <code>textarea</code> elements. Implementations can 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>
@@ -2203,7 +2216,7 @@
<p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a document view has been resized. This event type is dispatched after all effects for that occurrence of resizing of that particular <a class="def" href="#glossary-event-target">event target</a> have been executed by the <a class="def" href="#glossary-user-agent">user agent</a>.</p>
<p><a class="def" href="#glossary-user-agent">User agents</a> which support continuous reflow of the document's layout during user-initiated resizing must dispatch this event synchronously after each reflow of the document.</p>
<p>The <a class="def" href="#glossary-defaultView"><code>defaultView</code></a> object should always be resizable. A <a class="def" href="#glossary-host-language">host language</a> may define certain elements to be resizable, and under what conditions (e.g., specific elements like <code class="element">iframe</code>, or elements with particular characteristics like width and height); however, this specification does not define the behavior for elements.</p>
- <p class="note" id="note-resize-zoom"><strong>Note:</strong> The <a class="eventtype" href="#event-type-resize"><code>resize</code></a> event is distinct from the SVG <code class="eventtype">zoom</code> event types, though both may occur at the same time, or as the consequence of the same user action. In particular, browser “font zooming” or “page zooming” should not necessarily trigger a <a class="eventtype" href="#event-type-resize"><code>resize</code></a> event.</p>
+ <p class="note" id="note-resize-zoom"><strong>Note:</strong> The <a class="eventtype" href="#event-type-resize"><code>resize</code></a> event is distinct from the SVG <code class="eventtype">zoom</code> event types, though both can occur at the same time, or as the consequence of the same user action. In particular, browser <q>font zooming</q> or <q>page zooming</q> will not necessarily trigger a <a class="eventtype" href="#event-type-resize"><code>resize</code></a> event.</p>
<p class="note" id="note-resize-bubbling"><strong>Note:</strong> In previous DOM Events specifications, the <a class="eventtype" href="#event-type-resize"><code>resize</code></a> event type was defined to have a <a class="def" href="#glossary-bubbling-phase">bubbling phase</a>, but for performance reasons, this was not implemented in most user agents, and this specification removes the <a class="def" href="#glossary-bubbling-phase">bubbling phase</a> for this event.</p>
</dd>
</dl>
@@ -2267,13 +2280,13 @@
<span class="comment">// Introduced in DOM Level 3:</span>
interface <a href="#events-FocusEvent">FocusEvent</a> : <a href="#events-UIEvent">UIEvent</a>
{
- readonly attribute <a href="#events-EventTarget">EventTarget</a> <a href="#events-FocusEvent-relatedTarget">relatedTarget</a>;
- void <a href="#events-event-type-initFocusEvent">initFocusEvent</a>(DOMString typeArg,
- boolean canBubbleArg,
- boolean cancelableArg,
- AbstractView viewArg,
- long detailArg,
- <a href="#events-EventTarget">EventTarget</a> relatedTargetArg);
+ readonly attribute <a href="#events-EventTarget">EventTarget</a>? <a href="#events-FocusEvent-relatedTarget">relatedTarget</a>;
+ void <a href="#events-event-type-initFocusEvent">initFocusEvent</a>(DOMString typeArg,
+ boolean canBubbleArg,
+ boolean cancelableArg,
+ AbstractView? viewArg,
+ long detailArg,
+ <a href="#events-EventTarget">EventTarget</a>? relatedTargetArg);
};
</code></pre>
</dd>
@@ -2320,7 +2333,7 @@
<dt><code class="parameter-name">cancelableArg</code> of type <code>boolean</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
- <dt><code class="parameter-name">viewArg</code> of type <code>views::AbstractView</code></dt>
+ <dt><code class="parameter-name">viewArg</code> of type <code>AbstractView</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
<dt><code class="parameter-name">detailArg</code> of type <code>long</code></dt>
@@ -2523,7 +2536,7 @@
</tr>
</table>
<p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when an <a class="def" href="#glossary-event-target">event target</a> is about to receive focus. This event type must be dispatched before the element is given focus. The <a class="def" href="#glossary-event-target">event target</a> must be the element which is about to receive focus. This event type is similar to <a class="eventtype" href="#event-type-focus"><code>focus</code></a>, but is dispatched before focus is shifted, and does bubble.</p>
- <p class="note" id="_9"><strong>Note:</strong> When using this event type, the content author may use the event's <code class="attribute-name"><a href="#events-FocusEvent-relatedTarget">FocusEvent.relatedTarget</a></code> attribute (or a host-language-specific method or means) to get the currently focused element before the focus shifts to the next focus <a class="def" href="#glossary-event-target">event target</a>, thus having optional access to both the element losing focus and the element gaining focus without the use of the <a class="eventtype" href="#event-type-blur"><code>blur</code></a> or <a class="eventtype" href="#event-type-focusout">focusout</a> event types.</p>
+ <p class="note" id="_9"><strong>Note:</strong> When using this event type, the content author can use the event's <code class="attribute-name"><a href="#events-FocusEvent-relatedTarget">FocusEvent.relatedTarget</a></code> attribute (or a host-language-specific method or means) to get the currently focused element before the focus shifts to the next focus <a class="def" href="#glossary-event-target">event target</a>, thus having optional access to both the element losing focus and the element gaining focus without the use of the <a class="eventtype" href="#event-type-blur"><code>blur</code></a> or <a class="eventtype" href="#event-type-focusout">focusout</a> event types.</p>
</dd>
</dl>
</div>
@@ -2572,9 +2585,10 @@
<dt><strong>Interface <em><a id="events-MouseEvent">MouseEvent</a></em></strong> (introduced in <strong class="since">DOM Level 2</strong>)</dt>
<dd>
<p>The <code>MouseEvent</code> interface provides specific contextual information associated with Mouse events.</p>
- <p>In the case of nested elements mouse events are always targeted at the most deeply nested element. Ancestors of the targeted element may use bubbling to obtain notification of mouse events which occur within their descendent elements.</p>
+ <p>In the case of nested elements, mouse events are always targeted at the most deeply nested element.</p>
+ <p class="note"><strong>Note:</strong> Ancestors of the targeted element can use event bubbling to obtain notifications of mouse events which occur within their descendent elements.</p>
<p>To create an instance of the <code>MouseEvent</code> interface, use the <a href="#events-DocumentEvent-createEvent"><code>DocumentEvent.createEvent("MouseEvent")</code></a> method call.</p>
- <p class="note" id="_10"><strong>Note:</strong> When initializing <code>MouseEvent</code> objects using <code>initMouseEvent</code> or <code>initMouseEventNS</code>, implementations should use the client coordinates <code>clientX</code> and <code>clientY</code> for calculation of other coordinates (such as target coordinates exposed by <a class="def" href="#glossary-DOM-Level-0">DOM Level 0</a> implementations or other proprietary attributes, e.g., <code>pageX</code>).</p>
+ <p class="note" id="_10"><strong>Note:</strong> When initializing <code>MouseEvent</code> objects using <code>initMouseEvent</code> or <code>initMouseEventNS</code>, implementations can use the client coordinates <code>clientX</code> and <code>clientY</code> for calculation of other coordinates (such as target coordinates exposed by <a class="def" href="#glossary-DOM-Level-0">DOM Level 0</a> implementations or other proprietary attributes, e.g., <code>pageX</code>).</p>
<dl>
<dt>
<br />
@@ -2594,11 +2608,11 @@
readonly attribute boolean <a href="#events-MouseEvent-metaKey">metaKey</a>;
readonly attribute unsigned short <a href="#events-MouseEvent-button">button</a>;
readonly attribute unsigned short <a href="#events-MouseEvent-buttons">buttons</a>;
- readonly attribute <a href="#events-EventTarget">EventTarget</a> <a href="#events-MouseEvent-relatedTarget">relatedTarget</a>;
+ readonly attribute <a href="#events-EventTarget">EventTarget</a>? <a href="#events-MouseEvent-relatedTarget">relatedTarget</a>;
void <a href="#events-event-type-initMouseEvent">initMouseEvent</a>(DOMString typeArg,
boolean canBubbleArg,
boolean cancelableArg,
- AbstractView viewArg,
+ AbstractView? viewArg,
long detailArg,
long screenXArg,
long screenYArg,
@@ -2609,7 +2623,7 @@
boolean shiftKeyArg,
boolean metaKeyArg,
unsigned short buttonArg,
- <a href="#events-EventTarget">EventTarget</a> relatedTargetArg);
+ <a href="#events-EventTarget">EventTarget</a>? relatedTargetArg);
<span class="comment">// Introduced in DOM Level 3:</span>
boolean <a href="#events-MouseEvent-getModifierState">getModifierState</a>(DOMString keyArg);
};
@@ -2631,11 +2645,11 @@
<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>
+ <p>Some pointing devices 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-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> must be used to indicate which combination of mouse buttons are currently being pressed, expressed as a bitmask. <span class="note" id="_11"><strong>Note:</strong> This should not be confused with the <a href="#events-MouseEvent-button">button</a> attribute.</span>
+ <dd>During mouse events caused by the depression or release of a mouse button, <code>buttons</code> must be used to indicate which combination of mouse buttons are currently being pressed, expressed as a bitmask. <span class="note" id="_11"><strong>Note:</strong> Not to be confused with the <a href="#events-MouseEvent-button">button</a> attribute.</span>
<p>The value of the <a href="#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>
@@ -2643,7 +2657,7 @@
<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>
+ <p>Some pointing devices 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>
<p class="note" id="buttons-mask"><strong>Note:</strong> Because the sum of any set of button values is a unique number, a content 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>
@@ -2718,7 +2732,7 @@
<dt><code class="parameter-name">cancelableArg</code> of type <code>boolean</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
- <dt><code class="parameter-name">viewArg</code> of type <code>views::AbstractView</code></dt>
+ <dt><code class="parameter-name">viewArg</code> of type <code>AbstractView</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
<dt><code class="parameter-name">detailArg</code> of type <code>long</code></dt>
@@ -2934,7 +2948,7 @@
</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" id="_13"><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 class="note" id="_13"><strong>Note:</strong> Canceling the <a class="eventtype" href="#event-type-click"><code>click</code></a> event does 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-MouseEvent-button"><code>MouseEvent.button</code></a> or <a href="#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-MouseEvent-button"><code>MouseEvent.button</code></a> value is <code>0</code>, <a href="#events-MouseEvent-buttons"><code>MouseEvent.buttons</code></a> value is <code>1</code>):
@@ -3247,7 +3261,7 @@
<h3><a id="events-wheelevents" href="#events-wheelevents">5.2.4 Wheel Event Types</a></h3>
<p>This module defines the feature WheelEvents 3.0 and depends on the feature MouseEvents 3.0.</p>
- <p>Wheels are devices that can be rotated in one or more spatial dimensions, and which may or may not be associated with a pointer device. The coordinate system depends on the environment configuration. As an example, the environment might be configured to associate vertical scrolling with rotation along the y-axis, horizontal scrolling with rotation along the x-axis, and zooming with rotation along the z-axis. The deltax, deltaY, and deltaX attributes of <a href="#events-WheelEvent"><code>WheelEvent</code></a> objects indicate the distance of the rotation, as specified in the <a class="def" href="#glossary-delta">delta</a> definition. <!--The delta attributes of <a href='#events-WheelEvent'><code>WheelEvent</code></a> objects indicate the distance of the rotation. The measurement unit depends on the environment configuration. The sign of the delta value should indicate the direction of the rotation.--></p>
+ <p>Wheels are devices that can be rotated in one or more spatial dimensions, and which can be associated with a pointer device. The coordinate system depends on the environment configuration. As an example, the environment might be configured to associate vertical scrolling with rotation along the y-axis, horizontal scrolling with rotation along the x-axis, and zooming with rotation along the z-axis. The deltax, deltaY, and deltaX attributes of <a href="#events-WheelEvent"><code>WheelEvent</code></a> objects indicate the distance of the rotation, as specified in the <a class="def" href="#glossary-delta">delta</a> definition. <!--The delta attributes of <a href='#events-WheelEvent'><code>WheelEvent</code></a> objects indicate the distance of the rotation. The measurement unit depends on the environment configuration. The sign of the delta value should indicate the direction of the rotation.--></p>
<dl>
<dt><strong>Interface <em><a id="events-WheelEvent">WheelEvent</a></em></strong> (introduced in <strong class="since">DOM Level 3</strong>)</dt>
<dd>
@@ -3275,14 +3289,14 @@
void <a href="#events-event-type-initWheelEvent">initWheelEvent</a>(DOMString typeArg,
boolean canBubbleArg,
boolean cancelableArg,
- AbstractView viewArg,
+ AbstractView? viewArg,
long detailArg,
long screenXArg,
long screenYArg,
long clientXArg,
long clientYArg,
unsigned short buttonArg,
- <a href="#events-EventTarget">EventTarget</a> relatedTargetArg,
+ <a href="#events-EventTarget">EventTarget</a>? relatedTargetArg,
DOMString modifiersListArg,
float deltaXArg,
float deltaYArg,
@@ -3355,7 +3369,7 @@
<dt><code class="parameter-name">cancelableArg</code> of type <code>boolean</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
- <dt><code class="parameter-name">viewArg</code> of type <code>views::AbstractView</code></dt>
+ <dt><code class="parameter-name">viewArg</code> of type <code>AbstractView</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
<dt><code class="parameter-name">detailArg</code> of type <code>long</code></dt>
@@ -3450,8 +3464,8 @@
</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. Depending on the platform and input device, diagonal wheel deltas may be delivered either as a single wheel event with multiple non-zero axes or as separate wheel events for each non-zero axis.</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>
- <p class="note" id="note-delta-speed"><strong>Note:</strong> In some <a class="def" href="#glossary-user-agent">user agents</a>, or with some input devices, the speed that the wheel has been turned may affect the <a href="#glossary-delta"><code>delta</code></a> values, with a faster speed producing a higher <a href="#glossary-delta"><code>delta</code></a> value.</p>
- <p class="note" id="note-no-scroll-default"><strong>Note:</strong> The <a class="def" href="#glossary-default-action">default action</a> of a <a class="eventtype" href="#event-type-wheel"><code>wheel</code></a> event may be to scroll or zoom.</p>
+ <p class="note" id="note-delta-speed"><strong>Note:</strong> In some <a class="def" href="#glossary-user-agent">user agents</a>, or with some input devices, the speed that the wheel has been turned can affect the <a href="#glossary-delta"><code>delta</code></a> values, with a faster speed producing a higher <a href="#glossary-delta"><code>delta</code></a> value.</p>
+ <p class="note" id="note-no-scroll-default"><strong>Note:</strong> The <a class="def" href="#glossary-default-action">default action</a> of a <a class="eventtype" href="#event-type-wheel"><code>wheel</code></a> event can result in a scroll or zoom.</p>
</dd>
</dl>
</div>
@@ -3496,7 +3510,7 @@
void <a href="#events-event-type-initTextEvent">initTextEvent</a>(DOMString typeArg,
boolean canBubbleArg,
boolean cancelableArg,
- AbstractView viewArg,
+ AbstractView? viewArg,
DOMString dataArg,
unsigned long inputMethod,
DOMString localeArg);
@@ -3559,7 +3573,7 @@
<dt><code class="attribute-name"><a id="events-TextEvent-locale">locale</a></code> of type <code>DOMString</code>, readonly</dt>
<dd>
- <p>The <code>locale</code> attribute contains a BCP-47 tag [<a href="#ref-BCP-47">BCP-47</a>] indicating the locale for which the origin of the event (whether keyboard, IME, handwriting recognition software, or other input mode) is configured, e.g. "en-US". May be the <a class="def" href="#glossary-empty-string">empty string</a> when inapplicable or unknown, e.g. for pasted text, or when this information is not exposed by the underlying platform.</p>
+ <p>The <code>locale</code> <code>DOMString</code> attribute contains a BCP-47 tag [<a href="#ref-BCP-47">BCP-47</a>] indicating the locale for which the origin of the event (whether keyboard, IME, handwriting recognition software, or other input mode) is configured, e.g. <code>"en-US"</code>. The <code>locale</code> may be the <a class="def" href="#glossary-empty-string">empty string</a> when inapplicable or unknown, e.g. for pasted text, or when this information is not exposed by the underlying platform.</p>
<p class="note" id="note_TextEvent-locale"><strong>Note:</strong> <code>locale</code> does not necessarily indicate the locale of the data or the context in which it is being entered. For example, a French user often might not switch to an English keyboard setting when typing English, in which case the <code>locale</code> will still indicate French, even though the data is actually English.</p>
</dd>
@@ -3590,7 +3604,7 @@
<dt><code class="parameter-name">cancelableArg</code> of type <code>boolean</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
- <dt><code class="parameter-name">viewArg</code> of type <code>views::AbstractView</code></dt>
+ <dt><code class="parameter-name">viewArg</code> of type <code>AbstractView</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
<dt><code class="parameter-name">dataArg</code> of type <code>DOMString</code></dt>
@@ -3646,7 +3660,7 @@
</td>
</tr>
</table>
- <p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when one or more characters have been entered. These characters may originate from a variety of sources, e.g., characters resulting from a key being pressed or released on a keyboard device, from the processing of an <a class="def" href="#glossary-ime">input method editor</a>, or resulting from a voice command. Where a “paste” operation generates a simple sequence of characters, i.e., a text passage without any structure or style information, this event type should be generated as well.</p>
+ <p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when one or more characters have been entered. These characters may originate from a variety of sources, e.g., characters resulting from a key being pressed or released on a keyboard device, from the processing of an <a class="def" href="#glossary-ime">input method editor</a>, or resulting from a voice command. Where a <q>paste</q> operation generates a simple sequence of characters, i.e., a text passage without any structure or style information, this event type should be generated as well.</p>
</dd>
</dl>
</div>
@@ -3656,7 +3670,7 @@
<h3><a id="events-keyboardevents" href="#events-keyboardevents">5.2.6 Keyboard Event Types</a></h3>
<p>This module defines the feature KeyboardEvents 3.0 and depends on the feature UIEvents 3.0.</p>
- <p>Keyboard events are device dependent, i.e., they rely on the capabilities of the input devices and how they are mapped in the operating systems. It is therefore highly recommended to rely on <a href="#events-TextEvent">Text event types</a> when dealing with character input. Refer to <a href="#keys">Keyboard events and key values</a> for more details, including examples on how Keyboard Events are used in combination with Composition Events. Depending on the character generation device, keyboard events may or may not be generated.</p>
+ <p>Keyboard events are device dependent, i.e., they rely on the capabilities of the input devices and how they are mapped in the operating systems. It is therefore highly recommended to rely on <a href="#events-TextEvent">Text event types</a> when dealing with character input. Refer to <a href="#keys">Keyboard events and key values</a> for more details, including examples on how Keyboard Events are used in combination with Composition Events. Depending on the character generation device, keyboard events might not be generated.</p>
<dl>
<dt><strong>Interface <em><a id="events-KeyboardEvent">KeyboardEvent</a></em></strong> (introduced in <strong class="since">DOM Level 3</strong>)</dt>
<dd>
@@ -3694,7 +3708,7 @@
void <a href="#events-KeyboardEvent-initKeyboardEvent">initKeyboardEvent</a>(DOMString typeArg,
boolean canBubbleArg,
boolean cancelableArg,
- AbstractView viewArg,
+ AbstractView? viewArg,
DOMString charArg,
DOMString keyArg,
unsigned long locationArg,
@@ -3766,7 +3780,7 @@
<dt><code class="attribute-name"><a id="events-KeyboardEvent-metaKey">metaKey</a></code> of type <code>boolean</code>, readonly</dt>
<dd><code>true</code> if the meta (Meta) key modifier was active.
- <p class="note" id="_26"><strong>Note:</strong> The <code>'Command'</code> key modifier on Macintosh systems must be represented using this key modifier.</p>
+ <p class="note" id="_26"><strong>Note:</strong> The <code>'Command'</code> key modifier on Macintosh systems is represented using this key modifier.</p>
</dd>
<dt><code class="attribute-name"><a id="events-KeyboardEvent-shiftKey">shiftKey</a></code> of type <code>boolean</code>, readonly</dt>
@@ -3777,8 +3791,8 @@
<dt><code class="attribute-name"><a id="events-KeyboardEvent-locale">locale</a></code> of type <code>DOMString</code>, readonly</dt>
<dd>
- <p>The <code>locale</code> attribute contains a BCP-47 tag [<a href="#ref-BCP-47">BCP-47</a>] indicating the locale for which the keyboard originating the event is configured, e.g. "en-US". May be the <a class="def" href="#glossary-empty-string">empty string</a> when inapplicable or unknown, e.g. when this information is not exposed by the underlying platform.</p>
- <p class="note" id="note_KeyboardEvent-locale"><strong>Note:</strong> <code>locale</code> does not necessarily indicate the locale of the data or the context in which it is being entered. For example, a French user often might not switch to an English keyboard setting when typing English, in which case the <code>locale</code> will still indicate French. Nor can it be used to definitively calculate the "physical" or "virtual" key associated with the event, or the character printed on that key.</p>
+ <p>The <code>locale</code> <code>DOMString</code> attribute contains a BCP-47 tag [<a href="#ref-BCP-47">BCP-47</a>] indicating the locale for which the keyboard originating the event is configured, e.g. <code>"en-US"</code>. The <code>locale</code> may be the <a class="def" href="#glossary-empty-string">empty string</a> when inapplicable or unknown, e.g. when this information is not exposed by the underlying platform.</p>
+ <p class="note" id="note_KeyboardEvent-locale"><strong>Note:</strong> <code>locale</code> does not necessarily indicate the locale of the data or the context in which it is being entered. For example, a French user often might not switch to an English keyboard setting when typing English, in which case the <code>locale</code> will still indicate French. Nor can it be used to definitively calculate the <q>physical</q> or <q>virtual</q> key associated with the event, or the character printed on that key.</p>
</dd>
</dl>
@@ -3848,7 +3862,7 @@
<dt><code class="parameter-name">cancelableArg</code> of type <code>boolean</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
- <dt><code class="parameter-name">viewArg</code> of type <code>views::AbstractView</code></dt>
+ <dt><code class="parameter-name">viewArg</code> of type <code>AbstractView</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
<dt><code class="parameter-name">charArg</code> of type <code>DOMString</code></dt>
@@ -3884,8 +3898,17 @@
</dl>
</dd>
</dl>
- <p class="warning" id="keycode-charcode"><strong>Warning!</strong> Legacy keyboard event implementations may include three additional attributes, <code>keyCode</code>, <code>charCode</code>, and <code>which</code>. The <code>keyCode</code> attribute indicates a numeric value associated with a particular key on a computer keyboard, while the <code>charCode</code> attribute indicates the <acronym title="American Standard Code for Information Interchange">ASCII</acronym> value of the character associated with that key (which may or may not be the same as the <code>keyCode</code> value) and is applicable only to keys that produce a <a class="def" href="#glossary-character-value">character value</a>. In practice, <code>keyCode</code> and <code>charCode</code> are inconsistent across platforms and even the same implementation on different operating systems or using different localizations. DOM Level 3 Events does not define values for either <code>keyCode</code> or <code>charCode</code>, or behavior for <code>charCode</code>; content authors should use <a href="#events-KeyboardEvent-key"><code>KeyboardEvent.key</code></a> or <a href="#events-KeyboardEvent-char"><code>KeyboardEvent.char</code></a> instead, in conforming DOM Level 3 Events implementations. <em>For more information, see the informative appendix on <a href="#legacy-key-attributes">Legacy key attributes: keyCode, charCode, and which</a>.</em></p>
- <p class="note" id="note-virtual-keyboards"><strong>Note:</strong> For compatibility with existing content, virtual keyboards, such as software keyboards on screen-based input devices, should produce the normal range of keyboard events, even though they do not possess physical keys.</p>
+ <p class="warning" id="keycode-charcode"><strong>Warning!</strong> Legacy keyboard event implementations include three additional attributes, <code>keyCode</code>,
+ <code>charCode</code>, and <code>which</code>. The <code>keyCode</code> attribute indicates a numeric value associated with a particular key on a computer keyboard,
+ while the <code>charCode</code> attribute indicates the <acronym title="American Standard Code for Information Interchange">ASCII</acronym> value of the character
+ associated with that key (which might be the same as the <code>keyCode</code> value) and is applicable only to keys that produce a
+ <a class="def" href="#glossary-character-value">character value</a>. In practice, <code>keyCode</code> and <code>charCode</code> are inconsistent across platforms
+ and even the same implementation on different operating systems or using different localizations. DOM Level 3 Events does not define values for either
+ <code>keyCode</code> or <code>charCode</code>, or behavior for <code>charCode</code>; content authors can use <a href="#events-KeyboardEvent-key"><code>KeyboardEvent.key</code></a>
+ or <a href="#events-KeyboardEvent-char"><code>KeyboardEvent.char</code></a> instead, in conforming DOM Level 3 Events implementations. <em>For more information, see
+ the informative appendix on <a href="#legacy-key-attributes">Legacy key attributes: keyCode, charCode, and which</a>.</em>
+ </p>
+ <p class="note" id="note-virtual-keyboards"><strong>Note:</strong> For compatibility with existing content, virtual keyboards, such as software keyboards on screen-based input devices, are expected to produce the normal range of keyboard events, even though they do not possess physical keys.</p>
<p class="note" id="key-IME-suppress"><strong>Note:</strong> In some implementations or system configurations, some key events, or their values, might be suppressed by the <a class="def" href="#glossary-ime">IME</a> in use.</p>
@@ -3936,13 +3959,13 @@
<a class="eventtype" href="#event-type-keyup"><code>keyup</code></a>
</li>
</ol>
- <p class="note" id="key-default"><strong>Note:</strong> Typically, any <a class="def" href="#glossary-default-action">default actions</a> associated with any particular key must be completed before the <a class="eventtype" href="#event-type-keyup"><code>keyup</code></a> event is dispatched, which may delay the <a class="eventtype" href="#event-type-keyup"><code>keyup</code></a> event slightly (though this is not likely to be a perceptible delay).</p>
+ <p class="note" id="key-default"><strong>Note:</strong> Typically, any <a class="def" href="#glossary-default-action">default actions</a> associated with any particular key are completed before the <a class="eventtype" href="#event-type-keyup"><code>keyup</code></a> event is dispatched; this might delay the <a class="eventtype" href="#event-type-keyup"><code>keyup</code></a> event slightly (though this is not likely to be a perceptible delay).</p>
- <p class="warning" id="_28"><strong>Warning!</strong> Because of hardware limitations, on some keyboard devices, the order between the text event and keyboard events may differ. For example, some mobile devices might dispatch the <a class="eventtype" href="#event-type-textinput"><code>textinput</code></a> event after the <a class="eventtype" href="#event-type-keyup"><code>keyup</code></a> event.</p>
+ <p class="warning" id="_28"><strong>Warning!</strong> Because of hardware limitations, on some keyboard devices, the order between the text event and keyboard events can differ. For example, some mobile devices might dispatch the <a class="eventtype" href="#event-type-textinput"><code>textinput</code></a> event after the <a class="eventtype" href="#event-type-keyup"><code>keyup</code></a> event.</p>
<p>The <a class="def" href="#glossary-event-target">target</a> of a key event is the currently focused element which is processing the keyboard activity; this is often an HTML <code>input</code> element or a textual element which is editable, but may be an element defined by the <a class="def" href="#glossary-host-language">host language</a> to accept keyboard input for non-text purposes, such as the activation of a hotkey or trigger of some other behavior; if no suitable element is in focus, the event target will be the root element.</p>
- <p class="note" id="key-focus"><strong>Note:</strong> The <a class="def" href="#glossary-event-target">event target</a> may change between different key events; for example, a <a class="eventtype" href="#event-type-keydown"><code>keydown</code></a> event on the <a href="#key-Tab"><code class="value keyname">'Tab'</code></a> key will likely have a different <a class="def" href="#glossary-event-target">event target</a> than the <a class="eventtype" href="#event-type-keyup"><code>keyup</code></a> event on the same keystroke.</p>
+ <p class="note" id="key-focus"><strong>Note:</strong> The <a class="def" href="#glossary-event-target">event target</a> might change between different key events; for example, a <a class="eventtype" href="#event-type-keydown"><code>keydown</code></a> event on the <a href="#key-Tab"><code class="value keyname">'Tab'</code></a> key will likely have a different <a class="def" href="#glossary-event-target">event target</a> than the <a class="eventtype" href="#event-type-keyup"><code>keyup</code></a> event on the same keystroke.</p>
<!-- keydown -->
<div class="event-definition assert must">
@@ -4033,7 +4056,7 @@
</table>
<p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a key is pressed down, if and only if that key normally produces a <a class="def" href="#glossary-character-value">character value</a>. The <a class="eventtype" href="#event-type-keypress"><code>keypress</code></a> event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. This event type must be generated after the <a class="def" href="#glossary-key-mapping">key mapping</a>. It must not be fired when using an <a class="def" href="#glossary-ime">input method editor</a>. This event type must be dispatched after the <a class="eventtype" href="#event-type-keydown"><code>keydown</code></a> event and before the <a class="eventtype" href="#event-type-keyup"><code>keyup</code></a> event associated with the same key.</p>
<p>The default action of the <a class="eventtype" href="#event-type-keypress"><code>keypress</code></a> event must be to dispatch a <a class="eventtype" href="#event-type-textinput"><code>textinput</code></a> event with the <a href="#events-TextEvent-data"><code class="attribute-name">data</code></a> attribute set to the value of the <a href="#events-KeyboardEvent-char"><code class="attribute-name">char</code></a> attribute of the <a class="eventtype" href="#event-type-keypress"><code>keypress</code></a> event.</p>
- <p class="note" id="_31"><strong>Note:</strong> the <a class="eventtype" href="#event-type-keypress"><code>keypress</code></a> event is traditionally associated with detecting a <a class="def" href="#glossary-character-value">character value</a> rather than a physical key, and may not be available on all keys in some configurations.</p>
+ <p class="note" id="_31"><strong>Note:</strong> the <a class="eventtype" href="#event-type-keypress"><code>keypress</code></a> event is traditionally associated with detecting a <a class="def" href="#glossary-character-value">character value</a> rather than a physical key, and might not be available on all keys in some configurations.</p>
<p class="warning" id="_32"><strong>Warning!</strong> the <a class="eventtype" href="#event-type-keypress"><code>keypress</code></a> event type 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 <a class="eventtype" href="#event-type-textinput"><code>textinput</code></a> event type.</p>
</dd>
</dl>
@@ -4084,9 +4107,9 @@
<h3><a id="events-compositionevents" href="#events-compositionevents">5.2.7 Composition Event Types</a></h3>
<p>This module defines the feature CompositionEvents 3.0 and depends on the feature UIEvents 3.0.</p>
- <p>Composition Events provide a means for inputing text in a supplementary or alternate manner than by Keyboard Events, in order to allow the use of characters that may not be commonly available on keyboard. For example, Composition events might be used to add accents to characters despite their absence from standard US keyboards, to build up logograms of many Asian languages from their base components or categories, to select word choices from a combination of key presses on a mobile device keyboard, or to convert voice commands into text using a speech recognition processor. Refer to <a href="#keys">Keyboard events and key values</a> for examples on how Composition Events are used in combination with keyboard events.</p>
- <p>Conceptually, a composition session consists of one <a class="eventtype" href="#event-type-compositionstart"><code>compositionstart</code></a> event, one or more <a class="eventtype" href="#event-type-compositionupdate"><code>compositionupdate</code></a> events, and one <a class="eventtype" href="#event-type-compositionend"><code>compositionend</code></a> event, with the value of the <a href="#events-CompositionEvent-data">data</a> attribute persisting between each “stage” of this event chain during each session. While a composition session is active, keyboard events should not be dispatched to the DOM (i.e., the <a class="def" href="#glossary-text-composition-system">text composition system</a> “swallows” the keyboard events), and only <a class="eventtype" href="#event-type-compositionupdate"><code>compositionupdate</code></a> events may be dispatched to indicate the composition process.</p>
- <p>Not all <a class="def" href="#glossary-ime">IME</a> systems or devices expose the necessary data to the DOM, so the active composition string (the “Reading Window” or “candidate selection menu option”) may not be available through this interface, in which case the selection may be represented by the <a class="def" href="#glossary-empty-string">empty string</a>.</p>
+ <p>Composition Events provide a means for inputing text in a supplementary or alternate manner than by Keyboard Events, in order to allow the use of characters that might not be commonly available on keyboard. For example, Composition events might be used to add accents to characters despite their absence from standard US keyboards, to build up logograms of many Asian languages from their base components or categories, to select word choices from a combination of key presses on a mobile device keyboard, or to convert voice commands into text using a speech recognition processor. Refer to <a href="#keys">Keyboard events and key values</a> for examples on how Composition Events are used in combination with keyboard events.</p>
+ <p>Conceptually, a composition session consists of one <a class="eventtype" href="#event-type-compositionstart"><code>compositionstart</code></a> event, one or more <a class="eventtype" href="#event-type-compositionupdate"><code>compositionupdate</code></a> events, and one <a class="eventtype" href="#event-type-compositionend"><code>compositionend</code></a> event, with the value of the <a href="#events-CompositionEvent-data">data</a> attribute persisting between each <q>stage</q> of this event chain during each session. While a composition session is active, keyboard events should not be dispatched to the DOM (i.e., the <a class="def" href="#glossary-text-composition-system">text composition system</a> <q>swallows</q> the keyboard events), and only <a class="eventtype" href="#event-type-compositionupdate"><code>compositionupdate</code></a> events are dispatched to indicate the composition process.</p>
+ <p>Not all <a class="def" href="#glossary-ime">IME</a> systems or devices expose the necessary data to the DOM, so the active composition string (the <q>Reading Window</q> or <q>candidate selection menu option</q>) may not be available through this interface, in which case the selection may be represented by the <a class="def" href="#glossary-empty-string">empty string</a>.</p>
<dl>
<dt><strong>Interface <em><a id="events-CompositionEvent">CompositionEvent</a></em></strong> (introduced in <strong class="since">DOM Level 3</strong>)</dt>
<dd>
@@ -4102,14 +4125,14 @@
<span class="comment">// Introduced in DOM Level 3:</span>
interface <a href="#events-CompositionEvent">CompositionEvent</a> : <a href="#events-UIEvent">UIEvent</a>
{
- readonly attribute DOMString <a href="#events-CompositionEvent-data">data</a>;
- readonly attribute DOMString <a href="#events-CompositionEvent-locale">locale</a>;
- void <a href="#events-event-type-initCompositionEvent">initCompositionEvent</a>(DOMString typeArg,
- boolean canBubbleArg,
- boolean cancelableArg,
- AbstractView viewArg,
- DOMString dataArg,
- DOMString localeArg);
+ readonly attribute DOMString? <a href="#events-CompositionEvent-data">data</a>;
+ readonly attribute DOMString <a href="#events-CompositionEvent-locale">locale</a>;
+ void <a href="#events-event-type-initCompositionEvent">initCompositionEvent</a>(DOMString typeArg,
+ boolean canBubbleArg,
+ boolean cancelableArg,
+ AbstractView? viewArg,
+ DOMString? dataArg,
+ DOMString localeArg);
};
</code></pre>
</dd>
@@ -4122,8 +4145,8 @@
<dt><code class="attribute-name"><a id="events-CompositionEvent-locale">locale</a></code> of type <code>DOMString</code>, readonly</dt>
<dd>
- <p>The <code>locale</code> attribute contains a BCP-47 tag [<a href="#ref-BCP-47">BCP-47</a>] indicating the locale for which the IME originating the event is configured, e.g. "ja", "zh-Hans", "ko". May be the <a class="def" href="#glossary-empty-string">empty string</a> when inapplicable or unknown, e.g. when this information is not exposed by the underlying platform or application.</p>
- <p class="note" id="note_CompositionEvent-locale"><strong>Note:</strong> <code>locale</code> does not necessarily indicate the locale of the data or the context in which it is being entered. For example, a French user often might not switch to an English keyboard setting when typing English, in which case the <code>locale</code> will still indicate French, even though the data is actually English. Similarly, an IME application may not distinguish between the locale of Chinese and Kanji characters.</p>
+ <p>The <code>locale</code> <code>DOMString</code> attribute contains a BCP-47 tag [<a href="#ref-BCP-47">BCP-47</a>] indicating the locale for which the IME originating the event is configured, e.g. <code>"ja"</code>, <code>"zh-Hans"</code>, <code>"ko"</code>. May be the <a class="def" href="#glossary-empty-string">empty string</a> when inapplicable or unknown, e.g. when this information is not exposed by the underlying platform or application.</p>
+ <p class="note" id="note_CompositionEvent-locale"><strong>Note:</strong> <code>locale</code> does not necessarily indicate the locale of the data or the context in which it is being entered. For example, a French user often might not switch to an English keyboard setting when typing English, in which case the <code>locale</code> will still indicate French, even though the data is actually English. Similarly, an IME application could fail to distinguish between the locale of Chinese and Kanji characters.</p>
</dd>
</dl>
@@ -4152,7 +4175,7 @@
<dt><code class="parameter-name">cancelableArg</code> of type <code>boolean</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
- <dt><code class="parameter-name">viewArg</code> of type <code>views::AbstractView</code></dt>
+ <dt><code class="parameter-name">viewArg</code> of type <code>AbstractView</code></dt>
<dd><p>Refer to the <a href="#events-event-type-initUIEvent"><code>UIEvent.initUIEvent()</code></a> method for a description of this parameter.</p></dd>
<dt><code class="parameter-name">dataArg</code> of type <code>DOMString</code></dt>
@@ -4302,7 +4325,7 @@
<div>
<h4><a id="handwriting" href="#handwriting">5.2.7.2 Handwriting Recognition Systems</a></h4>
- <p>The following example describes a possible sequence of events when composing a text passage “text” with a handwriting recognition system, such as on a pen tablet, as modeled using Composition Events.</p>
+ <p>The following example describes a possible sequence of events when composing a text passage <q>text</q> with a handwriting recognition system, such as on a pen tablet, as modeled using Composition Events.</p>
<div class="example" id="example-composition-selection">
<p><strong>Example:</strong></p>
<ol>
@@ -4347,7 +4370,7 @@
const unsigned short <a href="#events-ADDITION">ADDITION</a> = 2;
const unsigned short <a href="#events-REMOVAL">REMOVAL</a> = 3;
- readonly attribute Node <a href="#events-MutationEvent-relatedNode">relatedNode</a>;
+ readonly attribute Node? <a href="#events-MutationEvent-relatedNode">relatedNode</a>;
readonly attribute DOMString <a href="#events-MutationEvent-prevValue">prevValue</a>;
readonly attribute DOMString <a href="#events-MutationEvent-newValue">newValue</a>;
readonly attribute DOMString <a href="#events-MutationEvent-attrName">attrName</a>;
@@ -4355,7 +4378,7 @@
void <a href="#events-event-type-initMutationEvent">initMutationEvent</a>(DOMString typeArg,
boolean canBubbleArg,
boolean cancelableArg,
- Node relatedNodeArg,
+ Node? relatedNodeArg,
DOMString prevValueArg,
DOMString newValueArg,
DOMString attrNameArg,
@@ -4564,7 +4587,7 @@
</table>
<p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event type when a node other than an <code>Attr</code> node has been added as a child of another node. A <a class="def" href="#glossary-user-agent">user agent</a> may dispatch this event when an <code>Attr</code> node has been added to an <code>Element</code> node (see <a href="#DOMNodeInserted-attr">note</a> below). This event must be dispatched after the insertion has taken place. The <a class="def" href="#glossary-proximal-event-target">proximal event target</a> of this event must be the node being inserted.</p>
- <p class="note" id="DOMNodeInserted-attr"><strong>Note:</strong> for detecting attribute insertion, the <a href="#event-type-DOMAttrModified">DOMAttrModified</a> event type should be used instead.</p>
+ <p class="note" id="DOMNodeInserted-attr"><strong>Note:</strong> for detecting attribute insertion, use the <a href="#event-type-DOMAttrModified">DOMAttrModified</a> event type instead.</p>
<p class="warning" id="_36"><strong>Warning!</strong> the <a class="eventtype" href="#event-type-DOMNodeInserted"><code>DOMNodeInserted</code></a> event type 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.</p>
</dd>
</dl>
@@ -4636,7 +4659,7 @@
</table>
<p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a node other than an <code>Attr</code> node is being removed from its parent node. A <a class="def" href="#glossary-user-agent">user agent</a> may dispatch this event when an <code>Attr</code> node is being removed from its <code>ownerElement</code> (see <a href="#DOMNodeRemoved-attr">note</a> below). This event must be dispatched before the removal takes place. The <a class="def" href="#glossary-proximal-event-target">proximal event target</a> of this event must be the node being removed.</p>
- <p class="note" id="DOMNodeRemoved-attr"><strong>Note:</strong> for reliably detecting attribute removal, the <a href="#event-type-DOMAttrModified">DOMAttrModified</a> event type should be used instead.</p>
+ <p class="note" id="DOMNodeRemoved-attr"><strong>Note:</strong> for reliably detecting attribute removal, use the <a href="#event-type-DOMAttrModified">DOMAttrModified</a> event type instead.</p>
<p class="warning" id="_37"><strong>Warning!</strong> the <a class="eventtype" href="#event-type-DOMNodeRemoved"><code>DOMNodeRemoved</code></a> event type 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.</p>
</dd>
</dl>
@@ -4672,7 +4695,7 @@
</table>
<p>A <a class="def" href="#glossary-user-agent">user agent</a> must dispatch this event when a node is being removed from a document, either through direct removal of the node or removal of a subtree in which it is contained; a <a class="def" href="#glossary-user-agent">user agent</a> may optionally treat an <code>Attr</code> node as part of an <code>Element</code>'s subtree. This event must be dispatched before the removal takes place. The <a class="def" href="#glossary-proximal-event-target">proximal event target</a> of this event type must be the node being removed. If the node is being directly removed, the event type <a class="eventtype" href="#event-type-DOMNodeRemoved"><code>DOMNodeRemoved</code></a> must occur before this event type.</p>
- <p class="note" id="DOMNodeRemovedFromDocument-attr"><strong>Note:</strong> for reliably detecting attribute removal, the <a href="#event-type-DOMAttrModified">DOMAttrModified</a> event type should be used instead.</p>
+ <p class="note" id="DOMNodeRemovedFromDocument-attr"><strong>Note:</strong> for reliably detecting attribute removal, use the <a href="#event-type-DOMAttrModified">DOMAttrModified</a> event type instead.</p>
<p class="warning" id="_38"><strong>Warning!</strong> the <a class="eventtype" href="#event-type-DOMNodeRemovedFromDocument"><code>DOMNodeRemovedFromDocument</code></a> event type 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.</p>
</dd>
</dl>
@@ -4743,7 +4766,7 @@
void <a href="#events-event-type-initMutationNameEvent">initMutationNameEvent</a>(DOMString typeArg,
boolean canBubbleArg,
boolean cancelableArg,
- Node relatedNodeArg,
+ Node? relatedNodeArg,
DOMString prevNamespaceURIArg,
DOMString prevNodeNameArg);
};
@@ -4894,7 +4917,7 @@
<li>Relations between keyboard events, their default actions, and text events.</li>
<li>The set of key values, and guidelines on how to extend this set.</li>
</ul>
- <p class="note" id="_49"><strong>Note:</strong> This section uses Serbian and Kanji characters which may be misrepresented or unavailable in the PDF version or printed version of this specification.</p>
+ <p class="note" id="_49"><strong>Note:</strong> This section uses Serbian and Kanji characters which could be misrepresented or unavailable in the PDF version or printed version of this specification.</p>
<div>
<h3><a id="keyboard-input" href="#keyboard-input">6.1 Keyboard Input</a></h3>
@@ -4909,7 +4932,7 @@
<h4><a id="key-legends" href="#key-legends">6.1.1 Key Legends</a></h4>
<p><em>This section is informative</em></p>
- <p>The visual markings normally consist of one or more characters which a keystroke on that key will produce (such as <code class="value">'F'</code>, <code class="value">'8'</code>, or <code class="value">'ш'</code>), or names or symbols which indicate that key's function (such as an upward-pointing arrow ⇧ indicating <code class="value">'Shift'</code>, or the string <code class="value">'Enter'</code>). Keys are often referred to by this marking (e.g., “Press the <code class="value">'Shift'</code> and <code class="value">'F'</code> keys.”). However, the visual appearance of the key has no bearing on its digital representation, and in many configurations may be completely inaccurate; even the control and function keys, such as <code class="value">'Enter'</code>, may be mapped to different functionality, or even mapped as character keys.</p>
+ <p>The visual markings normally consist of one or more characters which a keystroke on that key will produce (such as <code class="value">'F'</code>, <code class="value">'8'</code>, or <code class="value">'ш'</code>), or names or symbols which indicate that key's function (such as an upward-pointing arrow ⇧ indicating <code class="value">'Shift'</code>, or the string <code class="value">'Enter'</code>). Keys are often referred to by this marking (e.g., <q>Press the <code class="value">'Shift'</code> and <code class="value">'F'</code> keys.</q>). However, the visual appearance of the key has no bearing on its digital representation, and in many configurations may be completely inaccurate; even the control and function keys, such as <code class="value">'Enter'</code>, may be mapped to different functionality, or even mapped as character keys.</p>
<p>For historical reasons, the character keys are typically marked with the capital-letter equivalents of the character value they produce, e.g., the <code class="value">'F'</code> key (the key marked with the glyph <code class="value">'F'</code>), will produce the character value <code class="value">'f'</code> when pressing without an active modifier key (<code class="value">'Shift'</code>) or modifier state (<code class="value">'CapsLock'</code>).</p>
<p>Note that the key legends for function keys do not normally produce any characters, although the symbol may have a Unicode equivalent; for example, the <code class="value">'Shift'</code> key might bear the symbol ⇧, which has the <a class="def" href="#glossary-unicode-code-point">Unicode code point</a> <code class="value">'21E7'</code>, but pressing the <code class="value">'Shift'</code> key will not produce this character value, and there is no <a class="def" href="#glossary-unicode-code-point">Unicode code point</a> for <code class="value">'Shift'</code>.</p>
<h4><a id="keyboard-layout" href="#keyboard-layout">6.1.2 Keyboard Layout</a></h4>
@@ -4918,13 +4941,13 @@
<p>As with the key labels, the physical layout of the keys on the keyboard does not not affect the digital key value for any given key. It is outside the scope of this specification to provide key values based on keyboard layout, particularly since there are so many possible layouts for a keyboard, and since users can change the mapping of keys in their operating system, e.g., by selecting a Dvorak <a class="def" href="#glossary-key-mapping">key mapping</a>.</p>
<p>To illustrate the concept of keyboard layout mappings and its relation with keyboard events and key values, on the same keyboard (a PC/AT US keyboard), pressing the key labeled <code>Q</code> (with no modifier key activated) will produce different key values based on the mapping. With a typical US <a class="def" href="#glossary-qwerty">QWERTY</a> keyboard layout mapping, it will produce the character <code class="value">'q'</code> (<code class="value">U+0071</code>, Latin Small Letter Q). If the keyboard layout mapping is switched to a French mapping, pressing the same key will produce the character <code class="value">'a'</code> (<code class="value">U+0041</code>, Latin Capital Letter A). If the keyboard layout mapping is switched to a Serbian (Cyrillic) mapping, pressing the same key will produce the character <code class="value">'љ'</code> (<code class="value">U+0459</code>, Cyrillic Small Letter LJE).</p>
<p>However, the physical layout of the keys may be of interest to content authors developing games or other applications in which the location of the keys has an ergonomic relationship as the desired user interface controls, with little or no attention paid to the representational value of the key itself. For example, many games might use the keys <code class="value">'A'</code>, <code class="value">'S'</code>, <code class="value">'D'</code>, and <code class="value">'W'</code> for <code class="value">'left'</code>, <code class="value">'down'</code>, <code class="value">'right'</code>, and <code class="value">'up'</code> respectively. Content authors should provide a means for the user to assign such controller keys to a custom setting appropriate to their keyboard configurations. Implementations may provide a means for the user to more comprehensively map the keyboard to their customized keyboard layout, but this is beyond the scope of this specification.</p>
- <p class="note" id="_60"><strong>Note:</strong> Key values should not be confused with <em>scan codes</em>, which are the low-level hexadecimal signals produced for each key by the keyboard driver software, and which are mapped at the operating system to a <acronym title="Virtual Key">VK</acronym> ("virtual key"), which in turn may be mapped to the user-defined key configuration. Key values are a high-level abstraction of that final mapping.</p>
+ <p class="note" id="_60"><strong>Note:</strong> Don't confuse key values with <em>scan codes</em>, which are the low-level hexadecimal signals produced for each key by the keyboard driver software. <em>Scan codes</em> are mapped at the operating system to a <acronym title="Virtual Key">VK</acronym> (<q>virtual key</q>), which in turn might be mapped to the user-defined key configuration. Key values are a high-level abstraction of that final mapping.</p>
<div id="keyboard-desktop-section">
<h5><a id="keyboard-desktop" href="#keyboard-desktop">6.1.2.1 Desktop and Laptop Keyboards</a></h5>
<p>In the case where a content author wishes to rely on the mechanical layout of a desktop or laptop keyboard, this specification suggests the keyboard configuration specified in ISO/IEC 9995, parts 2 and 3 [<cite><a class="informative" href="#references-ISO-9995-2-3">ISO-9995-2/3</a></cite>], which defines a common layout for primary, secondary, and auxiliary <a class="def" href="#glossary-key-mapping">key mappings</a> on a typical alphanumeric keyboard, as a common layout appropriate to some international uses.</p>
- <p class="note" id="_51"><strong>Note:</strong> This keyboard layout is still, in essence, a <a class="def" href="#glossary-qwerty">QWERTY</a> keyboard, and will not match the keyboards or configurations of many users. Content authors cannot rely upon any particular configuration, and should create content in an internationalized and localizable manner.</p>
+ <p class="note" id="_51"><strong>Note:</strong> This keyboard layout is still, in essence, a <a class="def" href="#glossary-qwerty">QWERTY</a> keyboard, and will not match the keyboards or configurations of many users. Content authors cannot rely upon any particular configuration, and are expected to create content in an internationalized and localizable manner.</p>
<div id="figure-keyboard" class="figure" style="text-align: center">
<object type="image/svg+xml" data="images/ISOIEC-9995-3-FCD-2009A.svg" width="900" height="300">
<img src="images/ISOIEC-9995-3-FCD-2009A.png" alt="A graphical depiction of an ISO standard defining layouts of computer keyboards, ISO/IEC 9995, parts 2 and 3" />
@@ -4950,7 +4973,7 @@
<h5><a id="keyboard-mobile" href="#keyboard-mobile">6.1.2.2 Mobile Keypads</a></h5>
<p>In the case where a content author wishes to rely on the mechanical layout of a mobile keypad, this specification suggests the keyboard configuration specified in ISO/IEC 9995-8:2006 [<cite><a class="informative" href="#references-ISO-9995-8">ISO-9995-8</a></cite>], which defines a numeric keypad layout and secondary assignment of Unicode characters in the range <abbr title="a-z">\u0061..\u007A</abbr> to the number keys <code>2</code> through <code>9</code>, as a common layout appropriate to some international uses.</p>
- <p class="note" id="_52"><strong>Note:</strong> This keypad layout, and in particular the distribution of letters is for English devices, and will not match the keypads or configurations of many users. Content authors cannot rely upon any particular configuration, and should create content in an internationalized and localizable manner.</p>
+ <p class="note" id="_52"><strong>Note:</strong> This keypad layout, and in particular the distribution of letters is for English devices, and will not match the keypads or configurations of many users. Content authors cannot rely upon any particular configuration, and are expected to create content in an internationalized and localizable manner.</p>
</div>
@@ -4998,7 +5021,7 @@
<p>Key values can be used to detect the value of a key which has been pressed, using the <a href="#events-KeyboardEvent-key"><code>KeyboardEvent.key</code></a> or <a href="#events-KeyboardEvent-char"><code>KeyboardEvent.char</code></a> attributes. Content authors can retrieve the <a class="def" href="#glossary-character-value">character value</a> of upper- or lower-case letters, number, symbols, or other character-producing keys, and also the <a class="def" href="#glossary-key-value">key value</a> of control keys, modifier keys, function keys, or other keys that do not generate characters; these values can be used for monitoring particular input strings, for detecting and acting on modifier key input in combination with other inputs (such as a mouse), for creating virtual keyboards, or for any number of other purposes.</p>
<p>Key values can also be used by content authors in string comparisons, as values for markup attributes (such as the HTML <code>accesskey</code>) in conforming <a class="def" href="#glossary-host-language">host languages</a>, or for other related purposes. A conforming <a class="def" href="#glossary-host-language">host language</a> should allow content authors to use either of the two equivalent string values for a key value: the <a class="def" href="#glossary-character-value">character value</a>, or the <a class="def" href="#glossary-key-value">key value</a>.</p>
<!-- <p class="issue"><strong>Issue:</strong> mention that content author should use case-insensitive matching to capture both "t" and "T" for hotkeys, etc.?</p> -->
- <p class="note" id="_53"><strong>Note:</strong> While implementations are recommended to use the most relevant value for a key independently of the platform or keyboard layout mappings, content authors should not make assumption on the ability of keyboard devices to generate them. When using keyboard events and key values for shortcut-key combinations, content authors should <q>consider using numbers and function keys (F4, F5, and so on) instead of letters</q> ([<cite><a class="informative" href="#references-DWW95">DWW95</a></cite>]) given that most keyboard layouts will provide keys for those.</p>
+ <p class="note" id="_53"><strong>Note:</strong> While implementations will use the most relevant value for a key independently of the platform or keyboard layout mappings, content authors can not make assumptions on the ability of keyboard devices to generate them. When using keyboard events and key values for shortcut-key combinations, content authors can <q>consider using numbers and function keys (F4, F5, and so on) instead of letters</q> ([<cite><a class="informative" href="#references-DWW95">DWW95</a></cite>]) given that most keyboard layouts will provide keys for those.</p>
<!-- , and where the key used should default to the most appropriate key for the function, language, operating system, device, and other environmental factors (such as <code>ctrl+c</code> for copy operations) -->
<p>It is important to note that a key value does not indicate a specific key on the physical keyboard, nor does it reflect the character printed on the key; a key value indicates the current value of the event with consideration to the current state of all active keys and key input modes (including shift modes and <a class="def" href="#glossary-dead-key">dead keys</a>), as reflected in the operating-system mapping of the keyboard and reported to the implementation. In other words, the key value for the key marked <code>'O'</code> on a <a class="def" href="#glossary-qwerty">QWERTY</a> keyboard has the key value <code>'o'</code> in an unshifted state, <code>'O'</code> in a shifted state, <code>'ö'</code> in an unshifted state during a dead-key operation to add an umlaut diacritic, and <code>'Ö'</code> in a shifted state during a dead-key operation to add an umlaut diacritic. Because a user can map their keyboard to an arbitrary custom configuration, the content author is encouraged not to assume that a relationship exists between the shifted and unshifted states of a key and the majuscule form (uppercase or capital letters) and minuscule form (lowercase or small letters) of a character representation, but is encouraged instead to use the value of the <a href="#events-KeyboardEvent-key"><code>KeyboardEvent.key</code></a> or <a href="#events-KeyboardEvent-char"><code>KeyboardEvent.char</code></a> attributes. The keyboard depicted in <a href="#figure-keyboard">Figure 3</a> illustrates one possible set of <a class="def" href="#glossary-key-mapping">key mappings</a> on one possible keyboard layout; many others exist, both standard and idiosyncratic.</p>
<p>It is also important to note that there is not a one-to-one relationship between key event states and key values. A particular key value might be associated with multiple keys; for example, many standard keyboards contain more than one key with the <code class="value">'Shift'</code> key value (normally distinguished by the <a href="#events-KeyboardEvent-location"><code>KeyboardEvent.location</code></a> values <a href="#events-DOM_KEY_LOCATION_LEFT"><code class="constant-name">DOM_KEY_LOCATION_LEFT</code></a> and <a href="#events-DOM_KEY_LOCATION_RIGHT"><code class="constant-name">DOM_KEY_LOCATION_RIGHT</code></a>) or <code class="value">'8'</code> key value (normally distinguished by the <a href="#events-KeyboardEvent-location"><code>KeyboardEvent.location</code></a> values <a href="#events-DOM_KEY_LOCATION_STANDARD"><code class="constant-name">DOM_KEY_LOCATION_STANDARD</code></a> and <a href="#events-DOM_KEY_LOCATION_NUMPAD"><code class="constant-name">DOM_KEY_LOCATION_NUMPAD</code></a>), and user-configured custom keyboard layouts may duplicate any key value in multiple key-state scenarios (note that <a href="#events-KeyboardEvent-location"><code>KeyboardEvent.location</code></a> is intended for standard keyboard layouts, and cannot always indicate a meaningful distinction).</p>
@@ -5060,7 +5083,7 @@
<div>
<h4><a id="keys-Modifiers" href="#keys-Modifiers">6.2.2 Modifier keys</a></h4>
- <p>Keyboard input uses modifier keys to change the normal behavior of a key. Like other keys, modifier keys generate <a class="eventtype" href="#event-type-keydown"><code>keydown</code></a> and <a class="eventtype" href="#event-type-keyup"><code>keyup</code></a> events, as shown in the example below. Some modifiers are activated while the key is being pressed down or maintained pressed such as <code class="value">'Alt'</code>, <code class="value">'Control'</code>, <code class="value">'Shift'</code>, <code class="value">'AltGraph'</code>, or <code class="value">'Meta'</code>. Others modifiers are activated depending on their state such as <code class="value">'CapsLock'</code>, <code class="value">'NumLock'</code>, or <code class="value">'Scroll'</code>. Change in the state happens when the modifier key is being pressed down. The <a href="#events-KeyboardEvent"><code>KeyboardEvent</code></a> interface provides convenient attributes for some common modifiers keys: <a href="#events-KeyboardEvent-ctrlKey"><code>KeyboardEvent.ctrlKey</code></a>, <a href="#events-KeyboardEvent-shiftKey"><code>KeyboardEvent.shiftKey</code></a>, <a href="#events-KeyboardEvent-altKey"><code>KeyboardEvent.altKey</code></a>, <a href="#events-KeyboardEvent-metaKey"><code>KeyboardEvent.metaKey</code></a>. Some operating systems simulate the <code class="value">'AltGraph'</code> modifier key with the combination of the <code>"Alt</code> and <code class="value">'Control'</code> modifier keys. Implementations are encouraged to use the <code class="value">'AltGraph'</code> modifier key.</p>
+ <p>Keyboard input uses modifier keys to change the normal behavior of a key. Like other keys, modifier keys generate <a class="eventtype" href="#event-type-keydown"><code>keydown</code></a> and <a class="eventtype" href="#event-type-keyup"><code>keyup</code></a> events, as shown in the example below. Some modifiers are activated while the key is being pressed down or maintained pressed such as <code class="value">'Alt'</code>, <code class="value">'Control'</code>, <code class="value">'Shift'</code>, <code class="value">'AltGraph'</code>, or <code class="value">'Meta'</code>. Others modifiers are activated depending on their state such as <code class="value">'CapsLock'</code>, <code class="value">'NumLock'</code>, or <code class="value">'Scroll'</code>. Change in the state happens when the modifier key is being pressed down. The <a href="#events-KeyboardEvent"><code>KeyboardEvent</code></a> interface provides convenient attributes for some common modifiers keys: <a href="#events-KeyboardEvent-ctrlKey"><code>KeyboardEvent.ctrlKey</code></a>, <a href="#events-KeyboardEvent-shiftKey"><code>KeyboardEvent.shiftKey</code></a>, <a href="#events-KeyboardEvent-altKey"><code>KeyboardEvent.altKey</code></a>, <a href="#events-KeyboardEvent-metaKey"><code>KeyboardEvent.metaKey</code></a>. Some operating systems simulate the <code class="value">'AltGraph'</code> modifier key with the combination of the <code class="value">'Alt'</code> and <code class="value">'Control'</code> modifier keys. Implementations are encouraged to use the <code class="value">'AltGraph'</code> modifier key.</p>
<p>The following example describes a possible sequence of events associated with the generation of the Unicode character Q (Latin Capital Letter Q, <a class="def" href="#glossary-unicode-code-point">Unicode code point</a> <code class="value">U+0051</code>) on a PC/AT US keyboard using a US mapping:</p>
<!-- <p class="issue" id="issue-keyset-Modifiers-example"><strong>Issue:</strong> Reformat example as table with "Event", "Returned value", and "Keys involved", per <a href="http://lists.w3.org/Archives/Public/www-dom/2010JanMar/0052.html">Ishida</a>?</p> -->
<div class="example" id="example-keyvalue_Q">
@@ -5100,7 +5123,7 @@
<div>
<h4><a id="keys-DeadKeys" href="#keys-DeadKeys">6.2.3 Dead keys</a></h4>
- <p>Some keyboard input uses <a class="def" href="#glossary-dead-key">dead keys</a> for the input of composed character sequences. Unlike the handwriting sequence, in which users enter the base character first, keyboard input requires to enter a special state when a <a class="def" href="#glossary-dead-key">dead key</a> is pressed and emit the character(s) only when one of a limited number of “legal” base character is entered. (NOTE: the MacOS and Linux operating systems use input methods to process <a class="def" href="#glossary-dead-key">dead keys</a>.)</p>
+ <p>Some keyboard input uses <a class="def" href="#glossary-dead-key">dead keys</a> for the input of composed character sequences. Unlike the handwriting sequence, in which users enter the base character first, keyboard input requires to enter a special state when a <a class="def" href="#glossary-dead-key">dead key</a> is pressed and emit the character(s) only when one of a limited number of <q>legal</q> base character is entered. (NOTE: the MacOS and Linux operating systems use input methods to process <a class="def" href="#glossary-dead-key">dead keys</a>.)</p>
<p>The <a class="def" href="#glossary-dead-key">dead keys</a> are represented in the key values set using combining diacritical marks. While Unicode combining characters always follow the handwriting sequence, with the combining character trailing the corresponding letter, typical deadkey input may reverse the sequence, with the combining character before the corresponding letter; for example, the word <em>naïve</em>, using the combining diacritic <em>¨</em>, would be represented sequentially in Unicode as <em>nai¨ve</em>, but may be typed <em>na¨ive</em>. The sequence of keystrokes <code>'\u0302'</code> (Combining Circumflex Accent key) and <code>'\u0065'</code> (key marked with the Latin Small Letter E) will likely produce (on a PC/AT french keyboard using a french mapping and without any modifier activated) the Unicode character ê (Latin Small Letter E With Circumflex), as preferred by the Unicode Normalization Form <em>NFC</em>:</p>
<div class="example" id="example-deadkey">
<p><strong>Example:</strong></p>
@@ -5141,7 +5164,7 @@
<p>This specification includes a model for <a class="def" href="#glossary-ime">input method editors (IMEs)</a>, through the <a href="#events-compositionevents">CompositionEvent</a> interface and events. However, composition events and keyboard events do not necessarily map as a one-to-one relationship. As an example, receiving a <a class="eventtype" href="#event-type-keydown"><code>keydown</code></a> for the <a href="#key-Accept"><code class="value keyname">'Accept'</code></a> key value does not necessarily imply that the text currently selected in the <a class="def" href="#glossary-ime">IME</a> is being accepted, but indicates only that a keystroke happened, disconnected from the <a class="def" href="#glossary-ime">IME</a> Accept functionality (which would normally result in a <a class="eventtype" href="#event-type-compositionend"><code>compositionend</code></a> event in most <a class="def" href="#glossary-ime">IME</a> systems). Keyboard events cannot be used to determine the current state of the input method editor, which can be obtained through the <a href="#events-CompositionEvent-data"><code>data</code></a> attribute of the <a href="#events-compositionevents">CompositionEvent</a> interface. Additionally, <a class="def" href="#glossary-ime">IME</a> systems and devices vary in their functionality, and in which keys are used for activating that functionality, such that the <code class="value">'Convert'</code> and <code class="value">'Accept'</code> keys may be represented by other available keys. Keyboard events correspond to the events generated by the input device after the keyboard layout mapping.</p>
<p class="note" id="key-IME-suppress"><strong>Note:</strong> In some implementations or system configurations, some key events, or their values, might be suppressed by the <a class="def" href="#glossary-ime">IME</a> in use.</p>
- <p>The following example describes a possible sequence of keys to generate the Unicode character 市 (Kanji character, part of CJK Unified Ideographs) using Japanese input methods. This example assumes that the input method editor is activated and in the Japanese-Romaji input mode. The keys <code class="value">'Convert'</code> and <code class="value">'Accept'</code> may be replaced by others depending on the input device in use and the configuration of the IME, e.g., it can be respectively <code class="value">U+0020</code> (Space key) and <code class="value">'Enter'</code>. <span class="note" id="_54"><strong>Note:</strong><code class="value">'詩'</code> ("poem") and <code class="value">'市'</code> ("city") are homophones, both pronounced “shi”, so the user would use the <code class="value">'Convert'</code> key to select the proper option.</span></p>
+ <p>The following example describes a possible sequence of keys to generate the Unicode character 市 (Kanji character, part of CJK Unified Ideographs) using Japanese input methods. This example assumes that the input method editor is activated and in the Japanese-Romaji input mode. The keys <code class="value">'Convert'</code> and <code class="value">'Accept'</code> may be replaced by others depending on the input device in use and the configuration of the IME, e.g., it can be respectively <code class="value">U+0020</code> (Space key) and <code class="value">'Enter'</code>. <span class="note" id="_54"><strong>Note:</strong><code class="value">'詩'</code> (<q>poem</q>) and <code class="value">'市'</code> (<q>city</q>) are homophones, both pronounced <q>shi</q>, so the user would use the <code class="value">'Convert'</code> key to select the proper option.</span></p>
<div class="example" id="example-compo">
<p><strong>Example:</strong></p>
<ol>
@@ -5162,7 +5185,7 @@
<li><a class="eventtype" href="#event-type-keyup"><code>keyup</code></a>: <code class="value">'Accept'</code></li>
</ol>
</div>
- <p>IME composition can also be canceled as in the following example, with conditions identical to the previous example. The key <a href="#key-Cancel"><code class="value keyname">'Cancel'</code></a> might also be replaced by others depending on the input device in use and the configuration of the IME, e.g., it could be "\u001B" (Escape key).</p>
+ <p>IME composition can also be canceled as in the following example, with conditions identical to the previous example. The key <a href="#key-Cancel"><code class="value keyname">'Cancel'</code></a> might also be replaced by others depending on the input device in use and the configuration of the IME, e.g., it could be <code>"\u001B"</code> (Escape key).</p>
<div class="example" id="example-compo_cancel">
<p><strong>Example:</strong></p>
<ol>
@@ -5254,7 +5277,7 @@
<div>
<h4><a id="keys-Guide" href="#keys-Guide">6.2.6 Guidelines for selecting and defining key values</a></h4>
- <p class="note" id="_55"><strong>Note:</strong> This section is normative.</p>
+ <p><strong>This section is normative.</strong></p>
<p>The list of key values contained in this specification is not exhaustive, and input devices may have to define their own key values. Consider the current function of the key (i.e., with modifiers), taking into consideration the keyboard layout mapping in use, to determine if the key is represented by the set of defined key values, if a corresponding Unicode character exists from which a key value may be derived, or if a new key value must be defined. The following algorithm determines the <em>key value</em> and <em>character value</em> to use:</p>
<ol class="algo" id="key-algorithm">
@@ -5320,19 +5343,19 @@
The <a class="def" href="#glossary-character-value">character values</a> defined in this specification are derived from the Unicode standard [<a href="#references-Unicode">Unicode</a>].</p>
- <p class="note" id="_56"><strong>Note:</strong> The key names <code class="value">'NumPad0'</code>, <code class="value">'NumPad1'</code>, <code class="value">'NumPad2'</code>, <code class="value">'NumPad3'</code>, <code class="value">'NumPad4'</code>, <code class="value">'NumPad5'</code>, <code class="value">'NumPad6'</code>, <code class="value">'NumPad7'</code>, <code class="value">'NumPad8'</code>, and <code class="value">'NumPad9'</code>, found in some keyboard enumeration sets, are not distinguished from other numerical key values in this set; a content author may use the <a href="#events-KeyboardEvent-location"><code>KeyboardEvent.location</code></a> attribute to discover if a key originated from the numeric keypad.</p>
+ <p class="note" id="_56"><strong>Note:</strong> The key names <code class="value">'NumPad0'</code>, <code class="value">'NumPad1'</code>, <code class="value">'NumPad2'</code>, <code class="value">'NumPad3'</code>, <code class="value">'NumPad4'</code>, <code class="value">'NumPad5'</code>, <code class="value">'NumPad6'</code>, <code class="value">'NumPad7'</code>, <code class="value">'NumPad8'</code>, and <code class="value">'NumPad9'</code>, found in some keyboard enumeration sets, are not distinguished from other numerical key values in this set; a content author could use the <a href="#events-KeyboardEvent-location"><code>KeyboardEvent.location</code></a> attribute to discover if a key originated from the numeric keypad.</p>
<p>Future versions of this specification may include key values not included here, which have become common since the publication of this specification.</p>
<!-- <p>Javascript escaped characters may have issues because they are based on UTF-16 encoding, in that it uses surrogate pairs for values outside the Basic Multilingual Plane.</p> -->
<p>In the following list, character values for printing control characters are described as a character escape, for convenience, using the JavaScript notation for escapes.</p>
<div id="js-escape" class="note">
- <p><strong>Note:</strong> There are special internationalization considerations for ECMAScript escaped characters. CharMod conformance [<cite><a class="normative" href="#references-charmod">CharMod</a></cite>] <a href="http://www.w3.org/TR/charmod/#C045">expects</a> the use of code points rather than surrogate pairs in escapes; ECMAScript escaped characters use surrogate pairs for characters outside the Basic Multilingual Plane ("\uD84E\uDDC2" for 𣧂, a Chinese character meaning “untidy”), rather than C-style fixed-length characters ("\U000239c2" for 𣧂) or delimited escapes such as Numeric Character References ("&#x239C2;"). Characters escaped in this manner:</p>
+ <p><strong>Note:</strong> There are special internationalization considerations for ECMAScript escaped characters. CharMod conformance [<cite><a class="normative" href="#references-charmod">CharMod</a></cite>] <a href="http://www.w3.org/TR/charmod/#C045">expects</a> the use of code points rather than surrogate pairs in escapes; ECMAScript escaped characters use surrogate pairs for characters outside the Basic Multilingual Plane (<code>"\uD84E\uDDC2"</code> for 𣧂, a Chinese character meaning <q>untidy</q>), rather than C-style fixed-length characters (<code>"\U000239c2"</code> for 𣧂) or delimited escapes such as Numeric Character References (<code>"&#x239C2;"</code>). Characters escaped in this manner:</p>
<ul>
<li>are based on UTF-16 encoding, in that it uses surrogate pairs for values outside the Basic Multilingual Plane</li>
- <li>are expressed using surrogate pairs, which makes it difficult for a human to look up the value, and may require unnecessary overhead for machine processing; this can also cause problems with software written in the incorrect belief that Unicode is a 16-bit character set</li>
- <li>are problematic for characters on supplementary planes (emoji, or Chinese characters on plane 2), some of which may be expected to be input using a keyboard</li>
- <li>may not be suitable for Java or C, which use different escaping mechanisms (could be solved with a normalizing method)</li>
+ <li>are expressed using surrogate pairs, which makes it difficult for a human to look up the value, and might require unnecessary overhead for machine processing; this can also cause problems with software written in the incorrect belief that Unicode is a 16-bit character set</li>
+ <li>are problematic for characters on supplementary planes (emoji, or Chinese characters on plane 2), some of which are expected to be input using a keyboard</li>
+ <li>are not be suitable for Java or C, which use different escaping mechanisms (could be solved with a normalizing method)</li>
</ul>
</div>
@@ -5595,7 +5618,7 @@
<td><code id="key-Enter" class="value keyname">'Enter'</code></td>
<td> </td>
<td>The Enter key, to activate current selection or accept current input.
- <span class="note" id="_58"><strong>Note:</strong> This key value also must be used for the <code>Return</code> (Macintosh numpad) key.</span></td>
+ <span class="note" id="_58"><strong>Note:</strong> This key value is also used for the <code>Return</code> (Macintosh numpad) key.</span></td>
<td class="category">UI</td>
</tr>
<tr>
@@ -5689,7 +5712,7 @@
<td><code id="key-Multiply" class="value keyname">'Multiply'</code></td>
<td><a id="key-U-002A"><code class="value charval">'\u002A'</code></a></td>
<td>The Multiply key, or multiplication sign (<code class="value charrep">'*'</code>).
- <span class="note" id="note-Multiply"><strong>Note:</strong> This key value may be represented by different characters depending on context, including <code class="value charval">'\u002A' (ASTERISK, '*')</code> or <code id="key-U-00D7" class="value charval">'\u00D7' (MULTIPLICATION SIGN, '×')</code>.</span>
+ <span class="note" id="note-Multiply"><strong>Note:</strong> This key value can be represented by different characters depending on context, including <code class="value charval">'\u002A' (ASTERISK, '*')</code> or <code id="key-U-00D7" class="value charval">'\u00D7' (MULTIPLICATION SIGN, '×')</code>.</span>
</td>
<td class="category">Character / Math</td>
</tr>
@@ -5709,7 +5732,7 @@
<td><code id="key-Decimal" class="value keyname">'Decimal'</code></td>
<td><a id="key-U-2396"><code class="value charval">'\u2396'</code></a></td>
<td>The Decimal key, or decimal separator key symbol (<code class="value charrep">'.'</code>).
- <span class="note" id="note-decimal"><strong>Note:</strong> This key value may be represented by different characters due to localization, such as <code id="key-U-002E" class="value charval">'\u002E' (FULL STOP, '.')</code> or <code id="key-U-00B7" class="value charval">'\u00B7' (MIDDLE DOT, '·')</code>.</span>
+ <span class="note" id="note-decimal"><strong>Note:</strong> This key value can be represented by different characters due to localization, such as <code id="key-U-002E" class="value charval">'\u002E' (FULL STOP, '.')</code> or <code id="key-U-00B7" class="value charval">'\u00B7' (MIDDLE DOT, '·')</code>.</span>
</td>
<td class="category">Character / Math</td>
</tr>
@@ -5742,7 +5765,7 @@
<td><code id="key-Power" class="value keyname">'Power'</code></td>
<td> </td>
<td>Toggle power state.
- <span class="note" id="note-key-power"><strong>Note:</strong> Some devices may not expose this key to the operating environment.</span></td>
+ <span class="note" id="note-key-power"><strong>Note:</strong> Some devices might not expose this key to the operating environment.</span></td>
<td class="category">Device</td>
</tr>
<tr>
@@ -5905,7 +5928,7 @@
<tr>
<td><code id="key-Del" class="value keyname">'Del'</code></td>
<td><a id="key-U-007F"><code class="value charval">'\u007F'</code></a></td>
- <td>The Delete (Del) Key. <span class="note" id="_63"><strong>Note:</strong> This key value also must be used for the key labeled <code class="value">'delete'</code> MacOS keyboards when modified by the <code class="value">'Fn'</code> key.</span></td>
+ <td>The Delete (Del) Key. <span class="note" id="_63"><strong>Note:</strong> This key value is also used for the key labeled <code class="value">'delete'</code> on MacOS keyboards when modified by the <code class="value">'Fn'</code> key.</span></td>
<td class="category">Edit</td>
</tr>
<tr>
@@ -6110,7 +6133,7 @@
<tr>
<td><code id="key-OS" class="value keyname">'OS'</code></td>
<td> </td>
- <td>The operating system key (e.g. the "Windows Logo" key).</td>
+ <td>The operating system key (e.g. the <q>Windows Logo</q> key).</td>
<td class="category">Modifier</td>
</tr>
<tr>
@@ -6414,7 +6437,7 @@
<tr>
<td><code id="key-Dimmer" class="value keyname">'Dimmer'</code></td>
<td> </td>
- <td>Adjust brightness of device, may toggle between or cycle through states.</td>
+ <td>Adjust brightness of device, or toggle between or cycle through states.</td>
<td class="category">Media</td>
</tr>
<tr>
@@ -6722,9 +6745,9 @@
<p>Therefore, this specification does not normatively define the <code class="attr-name">charCode</code>, <code class="attr-name">keyCode</code>, or <code class="attr-name">which</code> attributes on the <a href="#events-KeyboardEvent">KeyboardEvent</a> interface, though they may be present in <a class="def" href="#glossary-user-agent">user agents</a> for compatibility with legacy content. Authors should use the <a href="#events-KeyboardEvent-char"><code>KeyboardEvent.char</code></a> and <a href="#events-KeyboardEvent-key"><code>KeyboardEvent.key</code></a> attributes instead of the <code class="attr-name">charCode</code> and <code class="attr-name">keyCode</code> attributes, respectively.</p>
- <p>However, for the purpose of documenting the current state of these attributes and their relation to equivalent key values, this section describes an informative supplemental Web IDL for <a href="#events-KeyboardEvent">KeyboardEvent</a> containing these attributes, and informative definitions for determining their attribute values.</p>
-
- <p>For implementations which do support these attributes, it is suggested to use this supplemental <a href="#events-KeyboardEvent-supplemental">KeyboardEvent</a> Web IDL.</p>
+ <p>However, for the purpose of documenting the current state of these attributes and their relation to equivalent key values, this section describes an informative Web IDL partial interface for <a href="#events-KeyboardEvent">KeyboardEvent</a> containing these attributes, and informative definitions for determining their attribute values.</p>
+
+ <p>For implementations which do support these attributes, it is suggested to use this partial <a href="#events-KeyboardEvent-supplemental">KeyboardEvent</a> interface.</p>
<h3 id="KeyboardEvent-supplemental-interface">A.1 Legacy KeyboardEvent supplemental interface</h3>
<dl>
@@ -6733,10 +6756,10 @@
</dt>
<dd>
<p>
- The supplemental <code>KeyboardEvent</code> interface is a non-normative extension of the <a href="#events-KeyboardEvent">KeyboardEvent</a> interface, which adds the <a href="#events-KeyboardEvent-supplemental-charCode">charCode</a>, <a href="#events-KeyboardEvent-supplemental-keyCode">keyCode</a>, and <a href="#events-KeyboardEvent-supplemental-which">which</a> attributes.
+ The partial <code>KeyboardEvent</code> interface is a non-normative extension of the <a href="#events-KeyboardEvent">KeyboardEvent</a> interface, which adds the <a href="#events-KeyboardEvent-supplemental-charCode">charCode</a>, <a href="#events-KeyboardEvent-supplemental-keyCode">keyCode</a>, and <a href="#events-KeyboardEvent-supplemental-which">which</a> attributes.
</p>
<p>
- To create an instance of the <code>KeyboardEvent (supplemental)</code> interface, use the <a href="#events-DocumentEvent-createEvent"><code>DocumentEvent.createEvent("KeyboardEvent")</code></a> method call, though this does not take the values of the <a href="#events-KeyboardEvent-supplemental-charCode">charCode</a>, <a href="#events-KeyboardEvent-supplemental-keyCode">keyCode</a>, or <a href="#events-KeyboardEvent-supplemental-which">which</a> attributes as parameters.
+ The partial <code>KeyboardEvent</code> interface must be obtained by using the <a href="#events-DocumentEvent-createEvent"><code>DocumentEvent.createEvent("KeyboardEvent")</code></a> method call in implementations that support this extension.
</p>
<dl>
<dt>
@@ -6775,7 +6798,7 @@
</dt>
<dd>
<p>
- <code class="attr-name">keyCode</code> holds a system- and implementation-dependent numerical code signifying the unmodified identifier associated with the key pressed. Unlike the <a href="#events-KeyboardEvent-key"><code>KeyboardEvent.key</code></a> or <a href="#events-KeyboardEvent-char"><code>KeyboardEvent.char</code></a> attributes, the set of possible values are not normatively defined in this specification; typically, these value of the <code class="attr-name">keyCode</code> should represent the decimal codepoint in ASCII [<a href="#ref-rfc20">RFC20</a>][<a href="#ref-US-ASCII">US-ASCII</a>] or Windows 1252 [<a href="#ref-WIN1252">WIN1252</a>], but may be drawn from a different appropriate character set. Implementations that are unable to identify a key must use the key value <code class="value">0</code>.
+ <code class="attr-name">keyCode</code> holds a system- and implementation-dependent numerical code signifying the unmodified identifier associated with the key pressed. Unlike the <a href="#events-KeyboardEvent-key"><code>KeyboardEvent.key</code></a> or <a href="#events-KeyboardEvent-char"><code>KeyboardEvent.char</code></a> attributes, the set of possible values are not normatively defined in this specification; typically, these value of the <code class="attr-name">keyCode</code> should represent the decimal codepoint in ASCII [<a href="#ref-rfc20">RFC20</a>][<a href="#ref-US-ASCII">US-ASCII</a>] or Windows 1252 [<a href="#ref-WIN1252">WIN1252</a>], but may be drawn from a different appropriate character set. Implementations that are unable to identify a key use the key value <code class="value">0</code>.
</p>
<p>See <a href="#legacy-key-models">Legacy key models</a> for more details on how to determine the values for <code class="attr-name">keyCode</code>.</p>
</dd>
@@ -6891,7 +6914,7 @@
<p>A script author may wish to define an application in terms of functional components, with event types that are meaningful to the application architecture. The content author can use the <a href="#events-CustomEvent"><code>CustomEvent</code></a> interface to create their own events appropriate to the level of abstraction they are using.</p>
<div class="example" id="example-custom-events">
- <p><strong>Example:</strong> A content author might have created an application which features a dynamically generated bar chart. This bar chart is meant to be updated every 5 minutes, or when a feed shows new information, or when the user refreshes it manually by clicking a button. There are several handlers that have to be called when the chart needs to be updated: the application has to fetch the most recent data, show an icon to the user that the event is being updated, and rebuild the chart. To manage this, the content author can choose to create a custom "updateChart" event, which is fired whenever one of the trigger conditions is met:</p>
+ <p><strong>Example:</strong> A content author might have created an application which features a dynamically generated bar chart. This bar chart is meant to be updated every 5 minutes, or when a feed shows new information, or when the user refreshes it manually by clicking a button. There are several handlers that have to be called when the chart needs to be updated: the application has to fetch the most recent data, show an icon to the user that the event is being updated, and rebuild the chart. To manage this, the content author can choose to create a custom <q>updateChart</q> event, which is fired whenever one of the trigger conditions is met:</p>
<pre><code>
var chartData = ...;
var evt = document.createEvent("CustomEvent");
@@ -6901,11 +6924,11 @@
</div>
<h2><a id="extending_events-Impl_Extensions" href="#extending_events-Impl_Extensions">B.3 Implementation-Specific Extensions</a></h2>
- <p>While a new event is being designed and prototyped, or when an event is intended for implementation-specific functionality, it is desirable to distinguish it from standardized events. Implementors should prefix event types specific to their implementations with a short string to distinguish it from the same event in other implementations and from standardized events. This is similar to the <a href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords" title="CSS 2.1: Syntax and basic data types">vendor-specific keyword prefixes</a> in CSS, though without the dashes ("-") used in CSS, since that can cause problems when used as an attribute name in Javascript.</p>
+ <p>While a new event is being designed and prototyped, or when an event is intended for implementation-specific functionality, it is desirable to distinguish it from standardized events. Implementors should prefix event types specific to their implementations with a short string to distinguish it from the same event in other implementations and from standardized events. This is similar to the <a href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords" title="CSS 2.1: Syntax and basic data types">vendor-specific keyword prefixes</a> in CSS, though without the dashes (<code>"-"</code>) used in CSS, since that can cause problems when used as an attribute name in Javascript.</p>
<div class="example" id="example-impl-extensions">
- <p><strong>Example:</strong> A particular browser vendor, "FooCorp", might wish to introduce a new event, "<code>jump</code>". This vendor implements "<code>fooJump</code>" in their browser, using their vendor-specific prefix, <code class="value">foo</code>. Early adopters start experimenting with the event, using <code>someElement.addEventListener( "fooJump", doJump, false )</code>, and provide feedback to FooCorp, who change the behavior of "<code>fooJump</code>" accordingly.</p>
- <p>After some time, another vendor, "BarOrg", decides they also want the functionality, but implement it slightly differently, so they use their own vendor-specific prefix, <code class="value">bar</code> in their event type name, "<code>barJump</code>". Content authors experimenting with this version of the "<code>jump</code>" event type register events with BarOrg's event type name. Content authors who wish to write code that accounts for both browsers can either register each event type separately with specific handlers, or use the same handler and switch on the name of the event type; thus, early experiments in different codebases do not conflict, and the early adopter is able to write easily-maintained code for multiple implementations.</p>
- <p>Eventually, as the feature matures, the behavior of both browsers stabilize and might converge due to content author and user feedback or through formal standardization; as this stabilization occurs, and risk of conflicts decrease, content authors can remove the forked code, and use the "<code>jump</code>" event type name (even before it is formally standardized) using the same event handler and the more generic registration method <code>someElement.addEventListener( "jump", doJump, false )</code>.</p>
+ <p><strong>Example:</strong> A particular browser vendor, <q>FooCorp</q>, might wish to introduce a new event, <code>"jump"</code>. This vendor implements <code>"fooJump"</code> in their browser, using their vendor-specific prefix, <code class="value">foo</code>. Early adopters start experimenting with the event, using <code>someElement.addEventListener( "fooJump", doJump, false )</code>, and provide feedback to FooCorp, who change the behavior of <code>"fooJump"</code> accordingly.</p>
+ <p>After some time, another vendor, <q>BarOrg</q>, decides they also want the functionality, but implement it slightly differently, so they use their own vendor-specific prefix, <code class="value">bar</code> in their event type name, <code>"barJump"</code>. Content authors experimenting with this version of the <code>"jump"</code> event type register events with BarOrg's event type name. Content authors who wish to write code that accounts for both browsers can either register each event type separately with specific handlers, or use the same handler and switch on the name of the event type; thus, early experiments in different codebases do not conflict, and the early adopter is able to write easily-maintained code for multiple implementations.</p>
+ <p>Eventually, as the feature matures, the behavior of both browsers stabilize and might converge due to content author and user feedback or through formal standardization; as this stabilization occurs, and risk of conflicts decrease, content authors can remove the forked code, and use the <code>"jump"</code> event type name (even before it is formally standardized) using the same event handler and the more generic registration method <code>someElement.addEventListener( "jump", doJump, false )</code>.</p>
</div>
<h4><a id="extending_events-prefixes" href="#extending_events-prefixes">B.3.1 Known Implementation-Specific Prefixes</a></h4>
@@ -7021,7 +7044,7 @@
<p>Despite its status only as a W3C Note, rather than an official Recommendation, DOM 3 Events saw some implementation, and reference by other specifications, so care is being taken to cause minimal disruption, while still adapting the specification to the current environment.</p>
<p>This specification has been reordered significantly from the earlier W3C Note form, and from the structure of DOM2 Events, in order to clarify the material. New diagrams have been put in place to represent hierarchies and events flows more clearly. Here are some of the more important changes between drafts:</p>
<ul>
- <li>The "key identifier" feature has been renamed "key value" to disambiguate them from unique identifiers for keys.</li>
+ <li>The <q>key identifier</q> feature has been renamed <q>key value</q> to disambiguate them from unique identifiers for keys.</li>
<li>The <code>change</code>, <code>submit</code>, and <code>reset</code> events were removed, since they were specific to HTML forms, and are specified in HTML5.</li>
<li>Namespaced events have been removed.</li>
<li>Updated to use WebIDL.</li>