Add locale attribute to keyboard and composition events.
authorGary Kacmarcik <garykac@google.com>
Sun, 03 Nov 2013 18:44:20 -0800
changeset 58 e611d19b1659
parent 57 392f6e89d50f
child 59 4e830478592e
Add locale attribute to keyboard and composition events.

These were migrated over from DOM3.
source_respec.htm
--- a/source_respec.htm	Wed Oct 23 13:40:53 2013 -0700
+++ b/source_respec.htm	Sun Nov 03 18:44:20 2013 -0800
@@ -421,13 +421,40 @@
         </section>
     </section>
 
+    <section id="composition-events">
+        <h1>Composition Events</h1>
+        <p>The DOM Level 3 Events specification introduced composition events. This document extends
+            composition events by adding a <code>locale</code> attribute.
+        </p>
+
+        <section id="keyboard-event-interface">
+            <h1>Interface <code>KeyboardEvent</code></h1>
+
+            <dl class="idl" title="partial interface KeyboardEvent : UIEvent">
+                <dt>readonly attribute DOMString locale</dt>
+                <dd>
+                    <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"><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>
+
+                    <p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>""</code> (the empty string).</p>
+                </dd>
+            </dl>
+            
+    </section>
+
     <section id="keyboard-events">
         <h1>Keyboard Events</h1>
         <p>The DOM Level 3 Events specification defines keyboard events that include <code>char</code> and <code>key</code>
            attributes to replace the legacy keyboard event attributes <code>keycode</code> and <code>charCode</code>.
         </p>
         <p>This document extends the DOM Level 3 keyboard event by adding a <code>code</code> attribute
-           (to help identify the key being pressed on the keyboard) and methods to identify the <code>char</code>
+           (to help identify the physical key being pressed on the keyboard) and methods to identify the <code>char</code>
            associated with a given key.
         </p>
 
@@ -482,6 +509,20 @@
                     </dl>
                 </dd>
 
+                <dt>readonly attribute DOMString locale</dt>
+                <dd>
+                    <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"><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>
+
+                    <p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>""</code> (the empty string).</p>
+                </dd>
+
                 <dt>static DOMString queryLocale()</dt>
                 <dd>
                     <p>Returns the current keyboard locale as a [[!BCP47]] string, such as 'en-US' or 'fr-FR'.