--- a/source_respec.htm Mon Feb 11 10:14:38 2013 -0800
+++ b/source_respec.htm Fri Feb 22 17:53:33 2013 -0800
@@ -324,7 +324,7 @@
was pressed, ignoring any keyboard modifications such as keyboard
layout.
This value should be one of the code values defined in the
- [<a href="#keyboard-events">Keyboard Events</a>] section.
+ <a href="#keyboard-events">Keyboard Events</a> section.
</dd>
<dt>unsigned long location = 0</dt>
<dd>
@@ -406,15 +406,53 @@
intended to help identify the key being pressed on the keyboard.
</p>
- <section id="keyboard-event-code-attribute">
+ <section id="keyboard-event-interface">
<h2>Interface <code>KeyboardEvent</code></h2>
<dl class="idl" title="partial interface KeyboardEvent : UIEvent">
+
<dt>readonly attribute DOMString code</dt>
- <dd><p><code>code</code> holds a string that identifies the physical key being pressed.
- The value is not affected by the current keyboard layout or modifier state, so a particular
- key will always return the same value.
- </p><p>The un-initialized value of this attribute must be "" (the empty string).</p>
+ <dd>
+ <p><code>code</code> holds a string that identifies the physical key being pressed.
+ The value is not affected by the current keyboard layout or modifier state, so a particular
+ key will always return the same value.
+ </p>
+ <p>The un-initialized value of this attribute must be "" (the empty string).</p>
+ </dd>
+
+ <dt>DOMString queryKeyCap()</dt>
+ <dd>
+ <p>Given a <code>code</code> corresponding to a key on a standard keyboard and a [[!BCP47]] <code>locale</code>,
+ the <code>queryKeyCap</code> method returns the character that would be generated if that key were
+ pressed (without modifiers) while the specified <code>locale</code> is in effect.
+ Assuming that <code>locale</code> matches the user's physical keyboard, then this value will
+ match the value printed on the <em>keycap</em> (the cap placed over the key switch) on the keyboard.
+ </p>
+ <p>This method is intended to be used primarily for the
+ <em><a href="#key-alphanumeric-writing-system">writing system keys</a></em> because the values
+ generated by these keys vary based on the current keyboard locale. For keys not classified as
+ <em>writing system</em> keys, this function returns the <code>code</code> for the key (i.e., it
+ returns that same value that was passed in). Note that the <code class="key-code">'AltRight'</code>
+ key always returns 'AltRight', even though some locales have this key labeled
+ <code class="keycap">AltGr</code>.
+ </p>
+ <p>The value 'Undefined' is returned if the <code>locale</code>'s keyboard does not contain the key
+ specified by <code>code</code>.
+ For example, calling <code>queryKeyCap('IntlRo', 'en-US')</code> would return 'Undefined' because the
+ <code class="key-code">'IntlRo'</code> key isn't present on a US keyboard.
+ </p>
+ <dl class="parameters">
+ <dt>DOMString code</dt>
+ <dd>The code for the key, as defined in the <a href="#key-codes">Key Codes</a> section below.
+ </dd>
+ <dt>optional DOMString locale</dt>
+ <dd>If specified, this should be a [[!BCP47]] tag (like 'en-US') that identifies the
+ keyboard layout in which to interpret the <code>code</code> parameter.<br/>
+ If not specified, then the <code>code</code>
+ value is interpreted in the context of the 'en-US' locale.
+ </p>
+ </dd>
+ </dl>
</dd>
</dl>
</section>
@@ -433,7 +471,8 @@
<section id="key-event-motivation">
<h1>Motivation for Adding the <code>code</code> Attribute</h1>
<p>As discussed in more detail later in this document, the standard PC keyboard has a set of keys (which
- we refer to as "writing system" keys) that generate different <code>char</code> and <code>key</code> values
+ we refer to as <em><a href="#key-alphanumeric-writing-system">writing system keys</a></em>)
+ that generate different <code>char</code> and <code>key</code> values
based on the current keyboard layout selected by the user.
This situation makes it difficult to write code that detects keys based on their physical
location since the code would need to know which layout is in effect in order to know which
@@ -600,9 +639,9 @@
These row names are consistent with those given in the ISO/IEC 9995-1 specification.
</p>
<p>Note that many keyboards (both modern and legacy) have extra keys that do not fit neatly into the above sections.
- Some of these keys are covered in the [<a href="#key-media">Media Keys</a>] section.
+ Some of these keys are covered in the <a href="#key-media">Media Keys</a> section.
Keys not covered in this document should be handled in the same manner as described in the
- [<a href="#other-devices">Other Devices</a>] section.
+ <a href="#other-devices">Other Devices</a> section.
</p>
</section><!-- keyboard-sections -->
@@ -756,7 +795,7 @@
</p>
<p>The name shown on each key is the <code>code</code> assigned to that key.
Wherever possible, the <code>code</code> names are based on the name for the US key
- (i.e., based on the US keyboard layout) in that position. For keys that don't
+ in that position (i.e., they are based on the US keyboard layout). For keys that don't
exist on the US keyboard, names from the UK or Japanese layouts are used instead.
</p>
<table id="table-key-code-alphanumeric-writing-system" class="data-table full-width">
@@ -879,7 +918,8 @@
<section id="key-alphanumeric-functional">
<h1>Functional Keys</h1>
- <p>The Functional keys (<em>not to be confused with the Function Keys described later</em>) are those
+ <p>The Functional keys (<em>not to be confused with the
+ <a href="#key-function-section">Function keys</a> described later</em>) are those
keys in the Alphanumeric section that provide general editing functions that are common to all locales
(like Shift, Tab, Enter and Backspace).
With a few exceptions, these keys do not change meaning based on the current keyboard layout.
@@ -916,8 +956,8 @@
</tbody>
</table>
<p>On some keyboards (notably Japanese and Korean) the spacebar is reduced in size to make room
- for extra keys on the bottom row. These keys allow the users to change the current input
- mode. Even though these Japanese and Korean keys occupy the same physical location on the
+ for extra keys on the bottom row. These keys typically allow the users to change the current input
+ mode. Note that even though some of these Japanese and Korean keys occupy the same physical location on the
keyboard, they use different <code>code</code> values.
</p>
<object class="figure" data="functional-row-a.svg" type="image/svg+xml" width="700" height="160" title="Comparison of the lower row of functional keys on different keyboards."></object>
@@ -1294,7 +1334,7 @@
<section id="other-devices">
<h1>Other Devices</h1>
<p>Other devices that generate key events should be supported in the manner described above
- in the [<a href="#remote-controls">Media Remote Controls</a>] section:
+ in the <a href="#remote-controls">Media Remote Controls</a> section:
</p>
<ul>
<li>If the button or key always produces the same <code>key</code> value, then the