[DOM3Events] Comments on DOM Level 3 key events

Hi all,

While reviewing the current DOM Level 3 key event spec, we discovered a
problem in that you cannot reliably match a keyup event with the
corresponding keydown event (even if you assume no events are lost due to
loss-of-focus). This is because the values used in the event's |key| and
|char| fields change depending on the current modifier key state.

To address this problem, I wrote up a brief proposal to enhance the current
DOM Level 3 key events by adding USB keycodes. The primary benefit of this
is that it provides a value that is consistent for keydown/keyup events
regardless of the modifier keys. This consistency makes it possible to
reliably match keyup events with the corresponding keydown events (as long
as events are not lost due to loss-of-focus). One useful side-effect of
this approach is that it enables keys to be identified based on their
keyboard position.

I originally sent this proposal to public-webapps@, and there was a brief
discussion which can be seen starting at:

The proposal document can be found at:

The rest of this message contains a text-ified version of the proposal doc.

-Gary Kacmarcik (garykac@chromium.org)


Proposal for enhancing the current DOM Level 3 key events with USB scancodes

Status: DRAFT
Authors: Gary Kacmarcik, James Weatherall

The current DOM Level 3 key event spec improves considerably upon the
"legacy" HTML4 key events that are currently used by most browsers.
The HTML4 events have always been problematic because the lack of a
detailed specification for the events led to implementation
inconsistencies on the various platform/browser combinations. The DOM
Level 3 proposal seeks to address this problem by specifying exactly
how these key events should be encoded.

However, there are still cases where the current proposal does not
provide enough information about the key event to perform desirable
tasks. In some cases, the legacy event values actually provide more
(internally) consistent information about the events.

Problems with the current DOM Level 3 key events

Problem 1: Matching keydown and keyup events

The main problem with the current proposal is that it doesn't provide
enough information so that keyup events can be matched with their
corresponding keydown event. In this regard, it is unlike the legacy
events, where the keyCode value was usually sufficient to match the
keydown/keyup events.

For examples of why this is a problem, consider the following scenarios:

* Games and other applications which treat the keyboard as a large
collection of buttons need to be able to keep track of which keys are
currently being held down. Since there is no API to query the current
keyboard state, it is crucial that apps be able to match every keyup
event with the originating keydown event.

* Applications that provide remote access functionality often need to
keep track of the sequence of events that generated a particular
character. This is so that they can handle the case where the local
and remote systems have different keyboard layouts (since they may
require a different sequence of keys or modifiers to be injected on
the remote machine).

Appendix A (at the end of this document) contains some sample key
event sequences that demonstrate this problem. The simple case of
typing a shifted character (the '@' sign) works fine in the normal
case, but if the Shift key is released too early then the keyup will
have a different value than the original keydown. This inconsistency
makes it difficult to match the keyup with the originating keydown.

Note that since these event values are dependent on the current
keyboard layout, there is no simple mapping table between the shifted
and unshifted version of each key. The international keyboard layout
examples in Appendix A demonstrate this complication.

Problem 2: Identifying keys by their position

While not as critical as the first problem, another common task for
some applications (typically games) is to handle key events based on
the key's position on the keyboard. For example, a game may want to
detect when the key next to the CapsLock key is pressed so it can be
associated with some player action. With a US keyboard, this would be
the key with the 'A' keycap, but on an AZERTY keyboard, this key would
have a 'Q' keycap.

A layout-independent way of identifying keys would be useful to games,
music/beatbox players, and other apps that prefer to consider the
keyboard as a set of buttons. A touch-typing app could also use
information to this target lessons for the home row or for the
left/right hand.

(Note that some implementations of HTML4 key events suffer from this
problem as well. For example, the keycodes in WebKit-based browsers
are based on Windows VKEY values, which are layout-dependent.)


Our proposal to address these problems is to add a new field that
contains the USB Usage Page and Usage ID codes for keydown and keyup

In this proposal, the KeyboardEvent would be extended to include:

   interface KeyboardEvent : UIEvent
      readonly attribute unsigned long usbUsage;

The usbUsage field is a combination of the USB Usage Page (upper
16-bits) and the USB Usage ID (lower 16-bits).  Some example usbUsage
codes are given in Appendix B, but a complete list can be found in the
USB HID Usage Tables documentation (see References).

The vast majority of these codes would come from Usage Page 0x07,
which contains Keyboard/Keypad values. However, many modern keyboards
contain specialized "media" keys which would have values defined in
other Usage Pages.

Providing this information in addition to the currently specified
fields would be address the problems described earlier:

Solving Problem 1 : Easy to match keydown with keyup

Since the USB key values are associated with the individual keys, the
value would not depend on the current state of the modifier keys.
Thus, the keydown and keyup events would have a value consistent
across all events generated by the same physical key.

Solving Problem 2 : Can identify key by position on keyboard

While the USB Usage IDs are given names based on the US keyboard
layout, the values are effectively scancodes, identifying the physical
key position on the keyboard. This makes it possible to write code
that can detect keys based on their position without needing to worry
about the current keyboard layout.

Appendix A - Key event sequence examples

Notes about these examples:
* Test machine: Windows 7 using a US keyboard.
* The legacy HTML4 keyCodes listed here are Windows VKEY codes used by
IE and WebKit-based browsers. They were captured on Chrome 19 /
Internet Explorer 9. Other browsers and platforms may have different
* The DOM3 events were captured on Internet Explorer 9.
* Note that not all of the key event fields are shown and textInput
events are ignored.
* The ↓ symbol following a key name is used to denote keydown events;
↑ is used to for keyup events.

Proposed USB Usage values are included for reference. The upper 2
bytes are the "Usage Page ID" (always 0x7 in these examples) and the
lower 2 bytes (the "Usage ID") contains the code for the individual

Example 1: Typing "@" as shift ↓, 2 ↓, 2 ↑, shift ↑ (US Keyboard layout)

The simple case that works. The DOM3 key field matches for the keydown
and keyup. Likewise for the legacy keyCode field.

                         |   Legacy  |         DOM3         |  USB  |
                         | key |char |  key  | char |  loc  | Usage |
   keydown      Shift       16    0    Shift   null   LEFT   0x700E1
   keydown        2         50    0      @       @      0    0x7001F
   keypress                 64   64      @       @      0
   keyup          2         50    0      @       @      0    0x7001F
   keyup        Shift       16    0    Shift   null   LEFT   0x700E1

Example 2: Typing "@" as shift ↓, 2 ↓, shift ↑, 2 ↑ (US Keyboard layout)

Note that the DOM3 key field does not match for the keydown and keyup.
However, the legacy keyCode field does match.

                         |   Legacy  |         DOM3         |  USB  |
                         | key |char |  key  | char |  loc  | Usage |
   keydown      Shift       16    0    Shift   null   LEFT   0x700E1
   keydown        2         50    0      @       @      0    0x7001F
   keypress                 64   64      @       @      0
   keyup        Shift       16    0    Shift   null   LEFT   0x700E1
   keyup          2         50    0      2       2      0    0x7001F

Example 3: Typing " as shift ↓, 2 ↓, shift ↑, 2 ↑ (UK Keyboard layout)

With a UK keyboard layout, the same problem occurs, but with different
DOM3 key values.

                         |   Legacy  |         DOM3         |  USB  |
                         | key |char |  key  | char |  loc  | Usage |
   keydown      Shift       16    0    Shift   null   LEFT   0x700E1
   keydown        2         50    0      "       "      0    0x7001F
   keypress                 34   34      "       "      0
   keyup        Shift       16    0    Shift   null   LEFT   0x700E1
   keyup          2         50    0      2       2      0    0x7001F

Example 4: Typing 2 as shift ↓, 2 ↓, shift ↑, 2 ↑ (French Keyboard layout)

Similar issue with French keyboard. The un-shifted "2" key is not always a

                         |   Legacy  |         DOM3         |  USB  |
                         | key |char |  key  | char |  loc  | Usage |
   keydown      Shift       16    0    Shift   null   LEFT   0x700E1
   keydown        2         50    0      2       2      0    0x7001F
   keypress                 50   50      2       2      0
   keyup        Shift       16    0    Shift   null   LEFT   0x700E1
   keyup          2         50    0      é       é      0    0x7001F

Example 5: Pressing NumLock between keydown keyup (US Keyboard layout)

A more extreme example, but this demonstrates that the legacy keyCode
field was not immune to these problems. In this case, neither the DOM3
key field nor the legacy keyCode field match between the keydown and
keyup events.

                         |   Legacy  |         DOM3         |  USB  |
                         | key |char |  key  | char |  loc  | Usage |
   keydown   Keypad 8/Up    38    0     Up     null  KEYPAD  0x70060
   keydown     NumLock     144    0   NumLock  null     0    0x70053
   keyup       NumLock     144    0   NumLock  null     0    0x70053
   keyup     Keypad 8/Up   104    0      8     null  KEYPAD  0x70060

Example 6: Autorepeating keys: shift ↓, 2 ↓, shift ↑, 2 ↑ (US Keyboard

Unsurprisingly, the same issue occurs with autorepeating keys. Press
and hold shift, press and hold "2", release shift, wait and release
"2". Events marked with an asterisk (*) are repeat key event.

                         |   Legacy  |         DOM3         |  USB  |
                         | key |char |  key  | char |  loc  | Usage |
   keydown      Shift       16    0    Shift   null   LEFT   0x700E1
   * keydown    Shift       16    0    Shift   null   LEFT   0x700E1
   keydown        2         50    0      @       @      0    0x7001F
   keypress                 64   64      @       @      0
   * keydown      2         50    0      @       @      0    0x7001F
   * keypress               64   64      @       @      0
   keyup        Shift       16    0    Shift   null   LEFT   0x700E1
   * keydown      2         50    0      2       2      0    0x7001F
   * keypress               50   50      2       2      0
   keyup          2         50    0      2       2      0    0x7001F

Appendix B - USB Usage Examples

   USB    USB
  Usage  Usage   Windows
   Page    ID   Scancode  Name
   0007   0004     1e     Keyboard a and A (qQ on French keyboard)
   0007   0005     30     Keyboard b and B
   0007   0006     2e     Keyboard c and C
   ...    ...     ...     ...
   0007   001c     15     Keyboard y and Y (zZ on German keyboard)
   ...    ...     ...     ...
   0007   00e0     1d     Keyboard LeftControl
   0007   00e1     2a     Keyboard LeftShift
   0007   00e2     38     Keyboard LeftAlt
   0007   00e3     5b     Keyboard Left GUI (Win or Cmd key)
   ...    ...     ...     ...
   000c   00b5    e019    ScanNextTrack
   000c   00b6    e010    ScanPreviousTrack
   000c   00b7    e024    Stop
   000c   00b8    e02c    Eject
   000c   00cd    e022    Play/Pause

A more complete mapping table between USB usage codes and
platform-specific scancodes can be found in the Chromium source code


Document Object Model (DOM) Level 3 Events Specification
W3C Working Draft 14 June 2012

Universal Serial Bus HID Usage Tables
Version 1.11 6/27/2001

Received on Tuesday, 25 September 2012 17:00:46 UTC