(This part of the specification is likely to be moved to a separate specification on keyboard events.)
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+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):
"keydown"
: "U+0051"
(Latin Capital Letter Q key)"textInput"
: "q"
"keyup"
: "U+0051"
If the keyboard layout mapping is switched to a french mapping, pressing the same key will produce:
"keydown"
: "U+0041"
(Latin Capital Letter A key)"textInput"
: "a"
"keyup"
: "U+0041"
If the keyboard layout mapping is switched to a serbian (cyrillic) mapping, pressing the same key will produce:
"keydown"
: "U+0409"
(Cyrillic Capital Letter LJE)"textInput"
: "љ"
"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:
"keydown"
: "Shift"
, shiftKey"keydown"
: "U+0051"
(Latin Capital Letter Q key), shiftKey"textInput"
: "Q"
"keyup"
: "U+0051"
, shiftKey"keyup"
: "Shift"
The following example describes a possible sequence of keys that does not generate a Unicode character (using the same configuration):
"keydown"
: "Control"
, ctrlKey"keydown"
: "U+0056"
(Latin Capital Letter V key), ctrlKey"keyup"
: "U+0056"
, ctrlKey"keyup"
: "Control"
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:
"keydown"
: "U+0302"
(Combining Circumflex Accent key)"keyup"
: "U+0302"
"keydown"
: "U+0045"
(Latin Capital Letter E key)"textInput"
: "é"
"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, 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".
"keydown"
: "U+0053"
(Latin Capital Letter S key)"keyup"
: "U+0053"
(Latin Capital Letter S key)"keydown"
: "U+0049"
(Latin Capital Letter I key)"keyup"
: "U+0049"
(Latin Capital Letter I key)"keydown"
: "Convert"
"keyup"
: "Convert"
"keydown"
: "Accept"
"textInput"
: "市"
"keyup"
: "Accept"
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:
"keydown"
: "U+0051"
(Latin Capital Letter Q key), shiftKeyEvent.preventDefault()
during the dispatch of the keydown event object."textInput"
is generated."keyup"
: "U+0051"
, shiftKeyIf 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:
"keydown"
: "Shift"
, shiftKey"keydown"
: "U+0051"
(Latin Capital Letter Q key), shiftKey"textInput"
: "Q"
"keyup"
: "U+0051"
, shiftKey"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):
"keydown"
: "U+0302"
(Combining Circumflex Accent key)"keyup"
: "U+0302"
"keydown"
: "U+0045"
(Latin Capital Letter E key)"textInput"
: "a"
"keyup"
: "U+0045"
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:
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.
Note: This key identifier is also used for the Return (Macintosh numpad) key.