13 April 2006

Appendix A: Keyboard events and key identifiers

Editors:
Björn Höhrmann
Philippe Le Hégaret, W3C (until November 2003)

Table of Contents

This section contains necessary information regarding keyboard events:

Note: This section uses serbian and kanji characters which are not always available (or are misrepresented) in the alternative versions or printed versions of this specification.

A.1 Introduction

Each keyboard event references a key using a DOMString key identifier. The set contained in this appendix is based on the sets of keycodes from:

While implementations are recommended to use the most relevant identifier for a key independently of the platform or keyboard layout mappings, DOM applications should not make assumption on the ability of keyboard devices to generate them. When using keyboard events, "consider using numbers and function keys (F4, F5, and so on) instead of letters in shortcut-key combinations" ([DWW95]) given that most keyboard layouts will provide keys for those.

"U+0000", "U+0001", ..., "U+10FFFF" are Unicode based key identifiers ([Unicode]). When a key cannot be mapped to Unicode, a specific identifier is used (see also Guidelines for defining key identifiers). In any case, no assumption should be made between the sequence of keyboard events and the text events. The following three examples illustrate the concept of keyboard layout mappings and its relation with keyboard events (following the Guidelines for defining key identifiers, the 'Q' key is mapped to the Latin Capital Letter Q key).

The keystroke "U+0051" (Latin Capital Letter Q key) will produce (on a PC/AT US keyboard using a US keyboard layout mapping and without any modifier activated) the Unicode character q (Latin Small Letter Q):

  1. "keydown": "U+0051" (Latin Capital Letter Q key)
  2. "textInput": "q"
  3. "keyup": "U+0051"

If the keyboard layout mapping is switched to a french mapping, pressing the same key will produce:

  1. "keydown": "U+0041" (Latin Capital Letter A key)
  2. "textInput": "a"
  3. "keyup": "U+0041"

If the keyboard layout mapping is switched to a serbian (cyrillic) mapping, pressing the same key will produce:

  1. "keydown": "U+0409" (Cyrillic Capital Letter LJE)
  2. "textInput": "љ"
  3. "keyup": "U+0409"

Note: The order between the text event and keyboard events may differ depending on the keyboard devices.

A.1.1 Modifier keys

Keyboard input uses modifier keys to change the normal behavior of a key. Keys associated with modifiers generate, like other keys, keydown and keyup events as shown in the example below. Some modifiers are activated while the key is being pressed down or maintained pressed such as "Alt", "Control", "Shift", "AltGraph", or "Meta". Others modifiers are activated depending on their state such as "CapsLock", "NumLock", or "Scroll". Change in the state happens when the modifier key is being pressed down. The KeyboardEvent interface provides convenient attributes for some common modifiers keys: KeyboardEvent.ctrlKey, KeyboardEvent.shiftKey, KeyboardEvent.altKey, KeyboardEvent.metaKey. Some operating systems simulate the "AltGraph" modifier key with the combination of the "Alt and "Control" modifier keys. Implementations are encouraged to use the "AltGraph" modifier key.

The following example describes a possible sequence of keys to generate the Unicode character Q (Latin Capital Letter Q) on a PC/AT US keyboard using a US mapping:

  1. "keydown": "Shift", shiftKey
  2. "keydown": "U+0051" (Latin Capital Letter Q key), shiftKey
  3. "textInput": "Q"
  4. "keyup": "U+0051", shiftKey
  5. "keyup": "Shift"

The following example describes a possible sequence of keys that does not generate a Unicode character (using the same configuration):

  1. "keydown": "Control", ctrlKey
  2. "keydown": "U+0056" (Latin Capital Letter V key), ctrlKey
  3. "keyup": "U+0056", ctrlKey
  4. "keyup": "Control"

A.1.2 Dead keys

Keyboard input uses dead keys 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 dead key is pressed and emit the character(s) only when one of a limited number of "legal" base character is entered.

The dead keys are represented in the key identifiers set using combining diacritical marks. The sequence of keystrokes "U+0302" (Combining Circumflex Accent key) and "U+0045" (Latin Capital Letter E key) 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 NFC:

  1. "keydown": "U+0302" (Combining Circumflex Accent key)
  2. "keyup": "U+0302"
  3. "keydown": "U+0045" (Latin Capital Letter E key)
  4. "textInput": "é"
  5. "keyup": "U+0045"

A.1.3 Input Method Editors

Also known as front end processor, an input method editor (IME) is an application that performs the conversion between keystrokes and ideographs or other characters, usually by user-guided dictionary lookup.

This specification does not provide a representation of the input method editor (IME) events, i.e. the IME's functions and the IME context are not represented in this set. As an example, receiving a keydown for the "Accept" key identifier does not necessarily imply that the text currently selected in the IME is being accepted. It only indicates that a keystroke happened, disconnected from the IME Accept functionality. Depending on the device in use, the IME Accept functionality can be obtain using the Accept key or the Return key. Keyboard events cannot be used to determine the current state of the input method editor.

Keyboard events correspond to the events generated by the input device after the keyboard layout mapping but before the processing of the input method editor.

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 "Convert" and "Accept" may be replaced by others depending on the input device in use and the configuration of the IME, e.g. it could be respectively "U+0020" (Space key) and "Enter".

  1. "keydown": "U+0053" (Latin Capital Letter S key)
  2. "keyup": "U+0053" (Latin Capital Letter S key)
  3. "keydown": "U+0049" (Latin Capital Letter I key)
  4. "keyup": "U+0049" (Latin Capital Letter I key)
  5. "keydown": "Convert"
  6. "keyup": "Convert"
  7. "keydown": "Accept"
  8. "textInput": "市"
  9. "keyup": "Accept"

A.1.4 Default actions and cancelable keyboard events

Canceling the default action of a keydown event does not affect its respective keyup event; it will however prevent the respective textInput event from being generated. The following example describes a possible sequence of keys to generate the Unicode character Q (Latin Capital Letter Q) on a PC/AT US keyboard using a US mapping:

  1. "keydown": "U+0051" (Latin Capital Letter Q key), shiftKey
    the default action of the keydown event is prevented, e.g. by invoking Event.preventDefault() during the dispatch of the keydown event object.
  2. No "textInput" is generated.
  3. "keyup": "U+0051", shiftKey

If the key is a modifier key, the keystroke is taken into account for the modifiers states. The following example describes a possible sequence of keys to generate the Unicode character Q (Latin Capital Letter Q) on a PC/AT US keyboard using a US mapping:

  1. "keydown": "Shift", shiftKey
    the default action of the keydown event is prevented.
  2. "keydown": "U+0051" (Latin Capital Letter Q key), shiftKey
  3. "textInput": "Q"
  4. "keyup": "U+0051", shiftKey
  5. "keyup": "Shift"

If the key is part of a sequence of several keystrokes, whether it is a dead key or it is contributing to an Input Method Editor sequence, the keystroke is ignored (not taken into account) only if the default action is canceled on the keydown event. Canceling a dead key on a keyup event has not effect on textInput events. The following example uses the keystrokes "U+0302" (Combining Circumflex Accent key) and "U+0045" (Latin Capital Letter E key) (on a PC/AT french keyboard using a french mapping and without any modifier activated):

  1. "keydown": "U+0302" (Combining Circumflex Accent key)
    the default action of the keydown event is prevented
  2. "keyup": "U+0302"
  3. "keydown": "U+0045" (Latin Capital Letter E key)
  4. "textInput": "a"
  5. "keyup": "U+0045"

A.1.5 Guidelines for defining key identifiers

Note: This section is non-normative.

The list of key identifiers contained in this appendix is not exhaustive and input devices may have to define their own key identifiers. Here is a algorithm to determine which key identifier to use:

  1. Determine a representation for the key by looking at the keyboard layout mapping in use (and not the keyboard device in use). This representation should be unique, as human friendly as possible, platform independent, and consistent. For example, on PC/AT US keyboards with a US mapping, the 'Q' key is mapped to the key identifier "U+0051" (Latin Capital Letter Q key), the '1/!' key is mapped to the key identifier "U+0031" (Digit One key), the key '`/~' is mapped to the key identifier "U+0060" (Grave Accent key), and the 'Enter' key is mapped to the key identifier "Enter".
  2. Find an appropriate mapping in the Unicode character set. There might not always be an appropriate and obvious mapping: the Unicode set contains characters and symbols, the key might generate different characters depending on the operating system, ... In general, unless the representation of the key can be mapped to a unique Unicode character, it is better to create a new one.
  3. If no appropriate mapping was found, create a key identifier as human friendly as possible. The key identifier must not contain white spaces. As an example, the Enter key is mapped to the key identifier "Enter" and not to "U+000A" (Line Feed), given that this key generates the character "U+000A" on Unix operating systems and the characters "U+000D" and "U+000A" on Windows operating systems.

A.2 Key identifiers set

Note: The keycodes Multiply, Add, Substract, Decimal, Separator, Divide, NumPad0, NumPad1, NumPad2, NumPad3, NumPad4, NumPad5, NumPad6, NumPad7, NumPad8, and NumPad9 are not part of this set. Use KeyboardEvent.keyLocation to know if a key originated from the numeric keypad.

"Accept"
The Accept (Commit) key.
"Again"
The Again key.
"AllCandidates"
The All Candidates key.
"Alphanumeric"
The Alphanumeric key.
"Alt"
The Alt (Menu) key.
"AltGraph"
The Alt-Graph key.
"Apps"
The Application key.
"Attn"
The ATTN key.
"BrowserBack"
The Browser Back key.
"BrowserFavorites"
The Browser Favorites key.
"BrowserForward"
The Browser Forward key.
"BrowserHome"
The Browser Home key.
"BrowserRefresh"
The Browser Refresh key.
"BrowserSearch"
The Browser Search key.
"BrowserStop"
The Browser Stop key.
"CapsLock"
The Caps Lock (Capital) key.
"Clear"
The Clear key.
"CodeInput"
The Code Input key.
"Compose"
The Compose key.
"Control"
The Control (Ctrl) key.
"Crsel"
The Crsel key.
"Convert"
The Convert key.
"Copy"
The Copy key.
"Cut"
The Cut key.
"Down"
The Down Arrow key.
"End"
The End key.
"Enter"
The Enter key.

Note: This key identifier is also used for the Return (Macintosh numpad) key.

"EraseEof"
The Erase EOF key.
"Execute"
The Execute key.
"Exsel"
The Exsel key.
"F1"
The F1 key.
"F2"
The F2 key.
"F3"
The F3 key.
"F4"
The F4 key.
"F5"
The F5 key.
"F6"
The F6 key.
"F7"
The F7 key.
"F8"
The F8 key.
"F9"
The F9 key.
"F10"
The F10 key.
"F11"
The F11 key.
"F12"
The F12 key.
"F13"
The F13 key.
"F14"
The F14 key.
"F15"
The F15 key.
"F16"
The F16 key.
"F17"
The F17 key.
"F18"
The F18 key.
"F19"
The F19 key.
"F20"
The F20 key.
"F21"
The F21 key.
"F22"
The F22 key.
"F23"
The F23 key.
"F24"
The F24 key.
"FinalMode"
The Final Mode (Final) key used on some asian keyboards.
"Find"
The Find key.
"FullWidth"
The Full-Width Characters key.
"HalfWidth"
The Half-Width Characters key.
"HangulMode"
The Hangul (Korean characters) Mode key.
"HanjaMode"
The Hanja (Korean characters) Mode key.
"Help"
The Help key.
"Hiragana"
The Hiragana (Japanese Kana characters) key.
"Home"
The Home key.
"Insert"
The Insert (Ins) key.
"JapaneseHiragana"
The Japanese-Hiragana key.
"JapaneseKatakana"
The Japanese-Katakana key.
"JapaneseRomaji"
The Japanese-Romaji key.
"JunjaMode"
The Junja Mode key.
"KanaMode"
The Kana Mode (Kana Lock) key.
"KanjiMode"
The Kanji (Japanese name for ideographic characters of Chinese origin) Mode key.
"Katakana"
The Katakana (Japanese Kana characters) key.
"LaunchApplication1"
The Start Application One key.
"LaunchApplication2"
The Start Application Two key.
"LaunchMail"
The Start Mail key.
"Left"
The Left Arrow key.
"Meta"
The Meta key.
"MediaNextTrack"
The Media Next Track key.
"MediaPlayPause"
The Media Play Pause key.
"MediaPreviousTrack"
The Media Previous Track key.
"MediaStop"
The Media Stok key.
"ModeChange"
The Mode Change key.
"Nonconvert"
The Nonconvert (Don't Convert) key.
"NumLock"
The Num Lock key.
"PageDown"
The Page Down (Next) key.
"PageUp"
The Page Up key.
"Paste"
The Paste key.
"Pause"
The Pause key.
"Play"
The Play key.
"PreviousCandidate"
The Previous Candidate function key.
"PrintScreen"
The Print Screen (PrintScrn, SnapShot) key.
"Process"
The Process key.
"Props"
The Props key.
"Right"
The Right Arrow key.
"RomanCharacters"
The Roman Characters function key.
"Scroll"
The Scroll Lock key.
"Select"
The Select key.
"SelectMedia"
The Select Media key.
"Shift"
The Shift key.
"Stop"
The Stop key.
"Up"
The Up Arrow key.
"Undo"
The Undo key.
"VolumeDown"
The Volume Down key.
"VolumeMute"
The Volume Mute key.
"VolumeUp"
The Volume Up key.
"Win"
The Windows Logo key.
"Zoom"
The Zoom key.
"U+0008"
The Backspace (Back) key.
"U+0009"
The Horizontal Tabulation (Tab) key.
"U+0018"
The Cancel key.
"U+001B"
The Escape (Esc) key.
"U+0020"
The Space (Spacebar) key.
"U+0021"
The Exclamation Mark (Factorial, Bang) key (!).
"U+0022"
The Quotation Mark (Quote Double) key (").
"U+0023"
The Number Sign (Pound Sign, Hash, Crosshatch, Octothorpe) key (#).
"U+0024"
The Dollar Sign (milreis, escudo) key ($).
"U+0026"
The Ampersand key (&).
"U+0027"
The Apostrophe (Apostrophe-Quote, APL Quote) key (').
"U+0028"
The Left Parenthesis (Opening Parenthesis) key (().
"U+0029"
The Right Parenthesis (Closing Parenthesis) key ()).
"U+002A"
The Asterix (Star) key (*).
"U+002B"
The Plus Sign (Plus) key (+).
"U+002C"
The Comma (decimal separator) sign key (,).
"U+002D"
The Hyphen-minus (hyphen or minus sign) key (-).
"U+002E"
The Full Stop (period, dot, decimal point) key (.).
"U+002F"
The Solidus (slash, virgule, shilling) key (/).
"U+0030"
The Digit Zero key (0).
"U+0031"
The Digit One key (1).
"U+0032"
The Digit Two key (2).
"U+0033"
The Digit Three key (3).
"U+0034"
The Digit Four key (4).
"U+0035"
The Digit Five key (5).
"U+0036"
The Digit Six key (6).
"U+0037"
The Digit Seven key (7).
"U+0038"
The Digit Eight key (8).
"U+0039"
The Digit Nine key (9).
"U+003A"
The Colon key (:).
"U+003B"
The Semicolon key (;).
"U+003C"
The Less-Than Sign key (<).
"U+003D"
The Equals Sign key (=).
"U+003E"
The Greater-Than Sign key (>).
"U+003F"
The Question Mark key (?).
"U+0040"
The Commercial At (@) key.
"U+0041"
The Latin Capital Letter A key (A).
"U+0042"
The Latin Capital Letter B key (B).
"U+0043"
The Latin Capital Letter C key (C).
"U+0044"
The Latin Capital Letter D key (D).
"U+0045"
The Latin Capital Letter E key (E).
"U+0046"
The Latin Capital Letter F key (F).
"U+0047"
The Latin Capital Letter G key (G).
"U+0048"
The Latin Capital Letter H key (H).
"U+0049"
The Latin Capital Letter I key (I).
"U+004A"
The Latin Capital Letter J key (J).
"U+004B"
The Latin Capital Letter K key (K).
"U+004C"
The Latin Capital Letter L key (L).
"U+004D"
The Latin Capital Letter M key (M).
"U+004E"
The Latin Capital Letter N key (N).
"U+004F"
The Latin Capital Letter O key (O).
"U+0050"
The Latin Capital Letter P key (P).
"U+0051"
The Latin Capital Letter Q key (Q).
"U+0052"
The Latin Capital Letter R key (R).
"U+0053"
The Latin Capital Letter S key (S).
"U+0054"
The Latin Capital Letter T key (T).
"U+0055"
The Latin Capital Letter U key (U).
"U+0056"
The Latin Capital Letter V key (V).
"U+0057"
The Latin Capital Letter W key (W).
"U+0058"
The Latin Capital Letter X key (X).
"U+0059"
The Latin Capital Letter Y key (Y).
"U+005A"
The Latin Capital Letter Z key (Z).
"U+005B"
The Left Square Bracket (Opening Square Bracket) key ([).
"U+005C"
The Reverse Solidus (Backslash) key (\).
"U+005D"
The Right Square Bracket (Closing Square Bracket) key (]).
"U+005E"
The Circumflex Accent key (^).
"U+005F"
The Low Sign (Spacing Underscore, Underscore) key (_).
"U+0060"
The Grave Accent (Back Quote) key (`).
"U+007B"
The Left Curly Bracket (Opening Curly Bracket, Opening Brace, Brace Left) key ({).
"U+007C"
The Vertical Line (Vertical Bar, Pipe) key (|).
"U+007D"
The Right Curly Bracket (Closing Curly Bracket, Closing Brace, Brace Right) key (}).
"U+007F"
The Delete (Del) Key.
"U+00A1"
The Inverted Exclamation Mark key (¡).
"U+0300"
The Combining Grave Accent (Greek Varia, Dead Grave) key.
"U+0301"
The Combining Acute Accent (Stress Mark, Greek Oxia, Tonos, Dead Eacute) key.
"U+0302"
The Combining Circumflex Accent (Hat, Dead Circumflex) key.
"U+0303"
The Combining Tilde (Dead Tilde) key.
"U+0304"
The Combining Macron (Long, Dead Macron) key.
"U+0306"
The Combining Breve (Short, Dead Breve) key.
"U+0307"
The Combining Dot Above (Derivative, Dead Above Dot) key.
"U+0308"
The Combining Diaeresis (Double Dot Abode, Umlaut, Greek Dialytika, Double Derivative, Dead Diaeresis) key.
"U+030A"
The Combining Ring Above (Dead Above Ring) key.
"U+030B"
The Combining Double Acute Accent (Dead Doubleacute) key.
"U+030C"
The Combining Caron (Hacek, V Above, Dead Caron) key.
"U+0327"
The Combining Cedilla (Dead Cedilla) key.
"U+0328"
The Combining Ogonek (Nasal Hook, Dead Ogonek) key.
"U+0345"
The Combining Greek Ypogegrammeni (Greek Non-Spacing Iota Below, Iota Subscript, Dead Iota) key.
"U+20AC"
The Euro Currency Sign key (€).
"U+3099"
The Combining Katakana-Hiragana Voiced Sound Mark (Dead Voiced Sound) key.
"U+309A"
The Combining Katakana-Hiragana Semi-Voiced Sound Mark (Dead Semivoiced Sound) key.