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.
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:
java.awt.event.KeyEvent of the Java
2 Platform v1.4 [KeyEvent for Java];
System.Windows.Forms.Keys of the
Microsoft .NET Framework 1.0 [Keys enumeration for .Net].
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+FFFFFF" 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):
{"http://www.w3.org/2001/xml-events", "keydown"}:
"U+0051" (Latin Capital Letter Q key){"http://www.w3.org/2001/xml-events", "textInput"}:
"q"{"http://www.w3.org/2001/xml-events", "keyup"}:
"U+0051"If the keyboard layout mapping is switched to a french mapping, pressing the same key will produce:
{"http://www.w3.org/2001/xml-events", "keydown"}:
"U+0041" (Latin Capital Letter A key){"http://www.w3.org/2001/xml-events", "textInput"}:
"a"{"http://www.w3.org/2001/xml-events", "keyup"}:
"U+0041"If the keyboard layout mapping is switched to a serbian (cyrillic) mapping, pressing the same key will produce:
{"http://www.w3.org/2001/xml-events", "keydown"}:
"U+0409" (Cyrillic Capital Letter LJE){"http://www.w3.org/2001/xml-events", "textInput"}:
"љ"{"http://www.w3.org/2001/xml-events", "keyup"}:
"U+0409"Note: The order between the text event and keyboard events may differ depending on the keyboard devices.
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:
{"http://www.w3.org/2001/xml-events", "keydown"}:
"Shift", shiftKey{"http://www.w3.org/2001/xml-events", "keydown"}:
"U+0051" (Latin Capital Letter Q key), shiftKey{"http://www.w3.org/2001/xml-events", "textInput"}:
"Q"{"http://www.w3.org/2001/xml-events", "keyup"}:
"U+0051", shiftKey{"http://www.w3.org/2001/xml-events", "keyup"}:
"Shift"The following example describes a possible sequence of keys that does not generate a Unicode character (using the same configuration):
{"http://www.w3.org/2001/xml-events", "keydown"}:
"Control", ctrlKey{"http://www.w3.org/2001/xml-events", "keydown"}:
"U+0056" (Latin Capital Letter V key), ctrlKey{"http://www.w3.org/2001/xml-events", "keyup"}:
"U+0056", ctrlKey{"http://www.w3.org/2001/xml-events", "keyup"}:
"Control"Preventing a keydown or keyup event with a modifier does affect the subsequent
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:
{"http://www.w3.org/2001/xml-events", "keydown"}:
"U+0302" (Combining Circumflex Accent key){"http://www.w3.org/2001/xml-events", "keyup"}:
"U+0302"{"http://www.w3.org/2001/xml-events", "keydown"}:
"U+0045" (Latin Capital Letter E key){"http://www.w3.org/2001/xml-events", "textInput"}:
"é"{"http://www.w3.org/2001/xml-events", "keyup"}:
"U+0045"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, e.g. representing the input context, i.e. the IME's functions 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".
{"http://www.w3.org/2001/xml-events", "keydown"}:
"U+0053" (Latin Capital Letter S key){"http://www.w3.org/2001/xml-events", "keyup"}:
"U+0053" (Latin Capital Letter S key){"http://www.w3.org/2001/xml-events", "keydown"}:
"U+0049" (Latin Capital Letter I key){"http://www.w3.org/2001/xml-events", "keyup"}:
"U+0049" (Latin Capital Letter I key){"http://www.w3.org/2001/xml-events", "keydown"}:
"Convert"{"http://www.w3.org/2001/xml-events", "keyup"}:
"Convert"{"http://www.w3.org/2001/xml-events", "keydown"}:
"Accept"{"http://www.w3.org/2001/xml-events", "textInput"}:
"市"{"http://www.w3.org/2001/xml-events", "keyup"}:
"Accept"Note: This section is informative.
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:
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 KeyBoard.keyLocation to know if a key
originated from the numeric keypad.
Note: This key identifier is also used for the Return (Macintosh numpad) key.