clarified composition events, esp wrt default actions
authorschepers
Thu, 10 Sep 2009 08:48:06 +0900
changeset 179 627c59ba689a
parent 178 23367a01a57b
child 180 35c195615b3d
clarified composition events, esp wrt default actions
html/DOM3-Events.html
--- a/html/DOM3-Events.html	Thu Sep 10 04:18:21 2009 +0900
+++ b/html/DOM3-Events.html	Thu Sep 10 08:48:06 2009 +0900
@@ -135,7 +135,7 @@
       <dl>
         <dt>This version:</dt>
         <dd>
-          <a href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.68">http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.68</a>
+          <a href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.69">http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.69</a>
         </dd>
         <dt>Latest stable version:</dt>
         <dd>
@@ -143,7 +143,7 @@
         </dd>
         <dt>Previous version:</dt>
         <dd>
-          <a href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.67">http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.67</a>
+          <a href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.68">http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.68</a>
         </dd>
         <dt>Editor's Draft:</dt>
         <dd>
@@ -3202,7 +3202,7 @@
         <h3 class="div3"><a id="events-compositionevents" href="#events-compositionevents">5.2.8 Composition Events 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 examples, Composition events may 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="#keyset">Keyboard events and key identifiers</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-Events-CompositionEvent-data">data</a> attribute persisting between each "stage" of this event chain during each session.</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-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 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 IME 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 empty string.</p>
         <dl>
           <dt><strong>Interface <em><a id="events-Events-CompositionEvent">CompositionEvent</a></em></strong> (introduced in <strong class="since">DOM Level 3</strong>)</dt>
@@ -3302,7 +3302,10 @@
               <a class="noxref" href="#event-type-compositionstart">compositionstart</a>
             </dt>
             <dd><table border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0"><tr class="assert must"><th>Type</th><td class="eventname"><strong><code>compositionstart</code></strong></td></tr><tr class="assert must"><th>Namespace</th><td><code>None</code></td></tr><tr class="assert must"><th>Interface</th><td><a href="#events-Events-CompositionEvent"><code>CompositionEvent</code></a></td></tr><tr class="assert must"><th>Cancelable</th><td>Yes</td></tr><tr class="assert must"><th>Bubbles</th><td>Yes</td></tr><tr class="assert must"><th>Target</th><td><code>Element</code></td></tr><tr class="assert must"><th>Context info</th><td><a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a>, and <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code></a>.</td></tr></table>
-              A user agent must dispatch this event when a <a href="#glossary-text-composition-system">text composition system</a> begins composing a passage of text.  This event type is device-dependent, and may rely upon the capabilities of the text conversion system and how it is mapped into the operating system.  When a keyboard is used to feed an input method editor, this event type is generated after a <code>keydown</code> event, but speech or handwriting recognition systems may send this event type without keyboard events.  Some implemenations may populate the <a href="#events-Events-CompositionEvent-data"><code>data</code></a> attribute of the <a class="eventtype" href="#event-type-compositionstart"><code>compositionstart</code></a> event with the text currently selected in the document (for editing and replacement); otherwise, the value of the <a href="#events-Events-CompositionEvent-data"><code>data</code></a> attribute shall be <code>null</code>.  (<span class="issue">@@ see <a href="http://lists.w3.org/Archives/Public/www-dom/2009JulSep/0143.html" title="Extra notes on composition events from Daniel Danilatos on 2009-08-07 ([email protected] from July to September 2009)">Extra notes on composition events</a> for more details.</span>)
+              A user agent must dispatch this event when a <a href="#glossary-text-composition-system">text composition system</a> is invoked in preparation for composing a passage of text.  This event type is device-dependent, and may rely upon the capabilities of the text conversion system and how it is mapped into the operating system.  When a keyboard is used to feed an input method editor, this event type is generated after a <code>keydown</code> event, but speech or handwriting recognition systems may send this event type without keyboard events.  Some implemenations may populate the <a href="#events-Events-CompositionEvent-data"><code>data</code></a> attribute of the <a class="eventtype" href="#event-type-compositionstart"><code>compositionstart</code></a> event with the text currently selected in the document (for editing and replacement); otherwise, the value of the <a href="#events-Events-CompositionEvent-data"><code>data</code></a> attribute shall be <code>null</code>.  
+              
+              <p>This event is dispatched immediately before a <a href="#glossary-text-composition-system">text composition system</a> is launched.  The default action of this event is to launch the appropriate <a href="#glossary-text-composition-system">text composition system</a>.  If this event is canceled, the <a href="#glossary-text-composition-system">text composition system</a> must not be launched.</p>
+              <p>(<span class="issue">@@ see <a href="http://lists.w3.org/Archives/Public/www-dom/2009JulSep/0143.html" title="Extra notes on composition events from Daniel Danilatos on 2009-08-07 ([email protected] from July to September 2009)">Extra notes on composition events</a> for more details.</span>)</p>
             </dd>
           </dl>
         </div>
@@ -3312,7 +3315,7 @@
             <dt id="event-type-compositionupdate">
               <a class="noxref" href="#event-type-compositionupdate">compositionupdate</a>
             </dt>
-            <dd><table border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0"><tr class="assert must"><th>Type</th><td class="eventname"><strong><code>compositionupdate</code></strong></td></tr><tr class="assert must"><th>Namespace</th><td><code>None</code></td></tr><tr class="assert must"><th>Interface</th><td><a href="#events-Events-CompositionEvent"><code>CompositionEvent</code></a></td></tr><tr class="assert must"><th>Cancelable</th><td>Yes</td></tr><tr class="assert must"><th>Bubbles</th><td>Yes</td></tr><tr class="assert must"><th>Target</th><td><code>Element</code></td></tr><tr class="assert must"><th>Context info</th><td><a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a>, and <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code></a>.</td></tr></table>
+            <dd><table border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0"><tr class="assert must"><th>Type</th><td class="eventname"><strong><code>compositionupdate</code></strong></td></tr><tr class="assert must"><th>Namespace</th><td><code>None</code></td></tr><tr class="assert must"><th>Interface</th><td><a href="#events-Events-CompositionEvent"><code>CompositionEvent</code></a></td></tr><tr class="assert must"><th>Cancelable</th><td>No</td></tr><tr class="assert must"><th>Bubbles</th><td>Yes</td></tr><tr class="assert must"><th>Target</th><td><code>Element</code></td></tr><tr class="assert must"><th>Context info</th><td><a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a>, and <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code></a>.</td></tr></table>
               A user agent must dispatch this event when a <a href="#glossary-text-composition-system">text composition system</a> updates its active text passage with a new character, which is added to the string in <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code></a>.  Note that some <a href="#glossary-text-composition-system">text composition systems</a> may not expose this information to the DOM, in which case this event will not fire during the composition process.  If the composition process is canceled, this event will be fired immediately before the <a class="noxref" href="#event-type-compositionend">compositionend</a> event, and the <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code> attribute will be set to <code>null</code><span class="issue">(@@ "null" or "empty string"? What's the distinction?)</span>.</a></dd>
           </dl>
         </div>
@@ -3324,7 +3327,8 @@
             </dt>
             <dd><table border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0"><tr class="assert must"><th>Type</th><td class="eventname"><strong><code>compositionend</code></strong></td></tr><tr class="assert must"><th>Namespace</th><td><code>None</code></td></tr><tr class="assert must"><th>Interface</th><td><a href="#events-Events-CompositionEvent"><code>CompositionEvent</code></a></td></tr><tr class="assert must"><th>Cancelable</th><td>Yes</td></tr><tr class="assert must"><th>Bubbles</th><td>Yes</td></tr><tr class="assert must"><th>Target</th><td><code>Element</code></td></tr><tr class="assert must"><th>Context info</th><td><a href="#events-Events-UIEvent-view"><code>UIEvent.view</code></a>, and <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code></a>.</td></tr></table>
               A user agent must dispatch this event when a <a href="#glossary-text-composition-system">text composition system</a> completes the composition of its active text passage, or cancels the composition process.  If the result of the <a href="#glossary-text-composition-system">text composition system</a> is not null and does not contain the empty string, this event type will be followed by a <a class="eventtype" href="#event-type-textInput"><code>textInput</code></a> event type with the appropriate <a href="#events-Events-TextEvent-inputMode">inputMode</a> value, such as <a href="#events-DOM_INPUT_METHOD_IME">DOM_INPUT_METHOD_IME</a>, <a href="#events-DOM_INPUT_METHOD_HANDWRITING">DOM_INPUT_METHOD_HANDWRITING</a>, <a href="#events-DOM_INPUT_METHOD_VOICE">DOM_INPUT_METHOD_VOICE</a>, or <a href="#events-DOM_INPUT_METHOD_MULTIMODAL">DOM_INPUT_METHOD_MULTIMODAL</a>.
-              <br />
+              
+              <p>This event is dispatched immediately after the <a href="#glossary-text-composition-system">text composition system</a> is completed (e.g. the <a href="#glossary-ime">IME</a> closed, minimized, switched out of focus, or otherwise dismissed, with the focus switched back to the user agent).  The default action of this event is to dispatch the <a class="eventtype" href="#event-type-textInput"><code>textInput</code></a> event type as described above.  If this event is canceled, the <a class="eventtype" href="#event-type-textInput"><code>textInput</code></a> event type must not be dispatch, no matter the value of the <a href="#events-Events-CompositionEvent-data"><code>CompositionEvent.data</code> attribute.  Note that canceling the <a class="eventtype" href="#event-type-compositionend"><code>compositionend</code></a> <em>event type</em> is distinct from canceling the <a href="#glossary-text-composition-system">text composition system</a> session (e.g. by hitting a cancel button or closing an <a href="#glossary-ime">IME</a> window).</p>
             </dd>
           </dl>
         </div>