Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification extends the events and features defined in DOM Events Level 3.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document was published by the Web Applications Working Group as a First Public Working Draft.
If you wish to make comments regarding this document, please send them to
www-dom@w3.org
(subscribe,
archives)
using a subject prefix of [uievents]. All comments are welcome.
There is a
bug tracker
for this specification.
Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
Requirements phrased in the imperative as part of algorithms(such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.
Unless otherwise stated, string comparisons are done in a case-sensitive manner.
Implementations of this spec must also implement the following event constructor dictionary defined in [DOM4]:
EventInitUI Events builds on the event model defined in DOM Level 3 Events (and also DOM4). Features in scope for this specification are:
This section is informative
DOM Level 3 Events defines several events, but does not normatively provide a
mechanism for programmatically-creating those events. Traditionally, an
init*Event method was defined, but the parameter list to such
methods became cumbersome and required an explicit order that was hard to
maintain without the help of a tool.
For each event interface defined in [DOM-LEVEL-3-EVENTS], there exists an initialization method for synthesizing untrusted events. This mechanism does not scale well to event interfaces with many members. Event Constructors (introduced for the Event interface in [DOM4]) are a mechanism for creating and initializing untrusted event objects more easily.
Synthesizing an untrusted event using legacy initialization methods:
var event = document.createEvent("MouseEvent");
event.initMouseEvent("mouseover",
true,
true,
window,
null,
null,
null,
0,
0,
null,
null,
null,
null,
previousEventTarget);
eventTarget.dispatchEvent(event);
Synthesizing an untrusted event using constructors:
var event = new MouseEvent("mouseover",
{bubbles: true,
cancelable: true,
relatedTarget: previousEventTarget
});
eventTarget.dispatchEvent(event);In the above example, the author only has to set the event object properties
that he or she wants. Using legacy initialization methods, such as
initMouseEvent(), often requires the author to specify values
for numerous additional properties that are not needed.
The following sections define constructors for the interfaces from DOM3 Events [DOM-LEVEL-3-EVENTS].
UIEvent Constructor[Constructor(DOMString type, optional UIEventInit eventInitDict)]
partial interface UIEvent : Event {
};
dictionary UIEventInit : EventInit {
Window? view = null;
long detail = 0;
};UIEventInit Membersdetail of type long, defaulting to 0view of type Window, nullable, defaulting to nullownerDocument.
FocusEvent Constructor[Constructor(DOMString typeArg, optional FocusEventInit focusEventInitDict)]
partial interface FocusEvent {
};
dictionary FocusEventInit : UIEventInit {
EventTarget? relatedTarget = null;
};FocusEventInit MembersrelatedTarget should be initialized to the element
losing focus (in the case of a focus or focusin
event) or the element gaining focus (in the case of a blur
or focusout event).
MouseEvent Constructor[Constructor(DOMString typeArg, optional MouseEventInit mouseEventInitDict)]
partial interface MouseEvent {
};
dictionary MouseEventInit : UIEventInit {
long screenX = 0;
long screenY = 0;
long clientX = 0;
long clientY = 0;
boolean ctrlKey = false;
boolean shiftKey = false;
boolean altKey = false;
boolean metaKey = false;
unsigned short button = 0;
unsigned short buttons = 0;
EventTarget? relatedTarget = null;
};MouseEventInit MembersaltKey of type boolean, defaulting to falsealtKey attribute of the MouseEvent
object to true if the altKey modifier
key is to be considered depressed, false otherwise.
button attribute of the MouseEvent
object to a number representing one of the button(s) of the mouse
that is to be considered active.
Note: The value 0 is used to represent the primary mouse button, 1 is used to represent the auxillery/ middle mouse button, and 2 to represent the right mouse button. Numbers greater than 2 are also possible, but not well-defined in DOM Level 3 Events [DOM-LEVEL-3-EVENTS].
buttons attribute of the MouseEvent
object to a number representing one or more of the button(s) of the mouse
that are to be considered active.
Note: The buttons
attribute is a bit-field. To apply a value according to the
definition in DOM Level 3 Events [DOM-LEVEL-3-EVENTS], first, determine the
buttons that are to be considered active, then apply a bit-wise
OR operation the the result set. The value 1 is used to represent
the primary mouse button, 2 to represent the right mouse button,
and 4 to represent the auxillery/middle button. Numbers greater
than 4 are also possible and should be subsequent powers of 2 (8,
16, etc.), but these additional values are not well-defined in DOM
Level 3 Events.
In JavaScript, to initialize the
buttons attribute as if the right (2) and middle
button (4) were being pressed simultaneously, the buttons value
can be assigned as either:
{ buttons: 2 | 4 }
or:
{ buttons: 6 }
clientX of type long, defaulting to 0clientY (substituting "horizontal" for "vertical")clientY of type long, defaulting to 0clientY attribute of the MouseEvent
object to the desired vertical position of the mouse pointer
relative to the client window of the user's browser.
Initializing the event object to the given mouse position must not move the user's mouse pointer to the initialized position.
Issue: Some user agents automatically convert the values of clientX and clientY into other implementation- specific mouse pointer position properties, such as: offsetX, offsetY, pageX, pageY, x, and y.
ctrlKey of type boolean, defaulting to falsectrlKey attribute of the MouseEvent
object to true if the ctrlKey modifier
key is to be considered depressed, false otherwise.
metaKey of type boolean, defaulting to falsemetaKey attribute of the MouseEvent
object to true if the metaKey modifier
key is to be considered depressed, false otherwise.
relatedTarget should be initialized to the element
whose bounds the mouse pointer just left (in the case of a
mouseover or mouseenter event) or the element
whose bounds the mouse pointer is entering (in the case of a
mouseout or mouseleave
or focusout event). For other events, this value need not
be assigned (and will default to null).
screenX of type long, defaulting to 0screenY (substituting "horizontal" for "veritcal")screenY of type long, defaulting to 0screenY attribute of the MouseEvent
object to the desired vertical relative position of the mouse
pointer on the user's screen.
Initializing the event object to the given mouse position must not move the user's mouse pointer to the initialized position.
shiftKey of type boolean, defaulting to falseshiftKey attribute of the MouseEvent
object to true if the shiftKey modifier
key is to be considered depressed, false otherwise.
WheelEvent Constructor[Constructor(DOMString typeArg, optional WheelEventInit wheelEventInitDict)]
partial interface WheelEvent {
};
dictionary WheelEventInit {
double deltaX = 0.0;
double deltaY = 0.0;
double deltaZ = 0.0;
unsigned long deltaMode = 0;
};WheelEventInit MembersdeltaMode of type unsigned long, defaulting to 0deltaMode attribute on the WheelEvent
object to the enumerated values 0, 1, or 2, which represent the amount
of pixels scrolled (DOM_DELTA_PIXEL), lines scrolled (DOM_DELTA_LINE),
or pages scrolled (DOM_DELTA_PAGE) if the rotation of the wheel would
have resulted in scrolling.
deltaX of type double, defaulting to 0.0deltaZ attribute.deltaY of type double, defaulting to 0.0deltaZ attribute.deltaZ of type double, defaulting to 0.0deltaZ attribute of the WheelEvent object.
Relative positive values for this attribute (as well as the
deltaX and deltaY attributes) are given by
a right-hand coordinate system where the X, Y, and Z axes are
directed towards the right-most edge, bottom-most edge, and farthest
depth (away from the user) of the document, respectively. Negative
relative values are in the respective opposite directions.
KeyboardEvent Constructor[Constructor(DOMString typeArg, optional KeyboardEventInit keyboardEventInitDict)]
partial interface KeyboardEvent {
};
dictionary KeyboardEventInit : UIEventInit {
DOMString char = "";
DOMString key = "";
DOMString code = "";
unsigned long location = 0;
boolean ctrlKey = false;
boolean shiftKey = false;
boolean altKey = false;
boolean metaKey = false;
boolean repeat = false;
DOMString locale = "";
};KeyboardEventInit MembersaltKey of type boolean, defaulting to falsealtKey attribute of the KeyboardEvent
object to true if the altKey modifier
key is to be considered depressed, false otherwise.
char of type DOMString, defaulting to ""char attribute of the KeyboardEvent
object to the unicode character string representing a printable
character. If the related key value is not a printable
character, then this attribute should be assigned the empty string
(which is the default value).
code of type DOMString, defaulting to ""code attribute of the KeyboardEvent
object to the unicode character string representing the key that
was pressed, ignoring any keyboard modifications such as keyboard
layout.
This value should be one of the code values defined in the
Keyboard Events section.
ctrlKey of type boolean, defaulting to falsectrlKey attribute of the KeyboardEvent
object to true if the ctrlKey modifier
key is to be considered depressed, false otherwise.
key of type DOMString, defaulting to ""key attribute of the KeyboardEvent
object to the unicode character string representing the meaning of a
key after taking into account all keyboard modifications (such as
shift-state). This value is the final effective value of the key.
If the key is not a printable character, then it should be one of
the key values defined in [DOM-LEVEL-3-EVENTS].
locale of type DOMString, defaulting to ""locale attribute of the KeyboardEvent
object to a [BCP47] string. This string should reflect the current language
that the keyboard originaing this event is configured to, for example "en-US"
for a keyboard configured for US English input. This value may be the
empty string if the locale of the given input is unknown.
location of type unsigned long, defaulting to 0location attribute of the KeyboardEvent
object to one of the following location numerical constants:
KeyboardEvent.DOM_KEY_LOCATION_STANDARD (numerical value 0)KeyboardEvent.DOM_KEY_LOCATION_LEFT (numerical value 1)KeyboardEvent.DOM_KEY_LOCATION_RIGHT (numerical value 2)KeyboardEvent.DOM_KEY_LOCATION_NUMPAD (numerical value 3)KeyboardEvent.DOM_KEY_LOCATION_MOBILE (numerical value 4)KeyboardEvent.DOM_KEY_LOCATION_JOYSTICK (numerical value 5)metaKey of type boolean, defaulting to falsemetaKey attribute of the KeyboardEvent
object to true if the metaKey modifier
key is to be considered depressed, false otherwise.
repeat of type boolean, defaulting to falserepeat attribute of the KeyboardEvent
object to true if the the current KeyboardEvent is
considered part of a repeating sequence of similar events caused
by the long depression of any single key, false otherwise.
shiftKey of type boolean, defaulting to falseshiftKey attribute of the KeyboardEvent
object to true if the shiftKey modifier
key is to be considered depressed, false otherwise.
CompositionEvent Constructor[Constructor(DOMString typeArg, optional CompositionEventInit compositionEventInitDict)]
partial interface CompositionEvent {
};
dictionary CompositionEventInit : UIEventInit {
DOMString? data = "";
DOMString locale = "";
};CompositionEventInit Membersdata of type DOMString, nullable, defaulting to ""data attribute of the CompositionEvent
object to the characters generated by the IME composition.
locale of type DOMString, defaulting to ""locale attribute of the CompositionEvent
object to a [BCP47] string. This string should reflect the current language
that the IME originaing this event is configured to, for example "ja"
for an IME configured for Japanese input. This value may be the
empty string if the locale of the IME is unknown.
The DOM Level 3 Events specification defines keyboard events that include char and key
attributes to replace the legacy keyboard event attributes keycode and charCode.
This document extends the DOM Level 3 keyboard event by adding a code attribute
(to help identify the key being pressed on the keyboard) and methods to identify the char
associated with a given key.
KeyboardEventpartial interface KeyboardEvent : UIEvent {
readonly attribute DOMString code;
static DOMString queryKeyCap (DOMString code, optional DOMString locale);
static DOMString queryLocale ();
};code of type DOMString, readonly 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.
The un-initialized value of this attribute must be "" (the empty string).
queryKeyCap, staticGiven a code corresponding to a key on a standard keyboard and a [BCP47] locale,
the queryKeyCap method returns the character that would be generated if that key were
pressed (without modifiers or any special modes in effect) while the specified keyboard locale is in effect.
Assuming that locale matches the user's physical keyboard, then this value will
match the value printed on the keycap (the cap placed over the key switch) on the keyboard.
This method is intended to be used primarily for the
writing system keys because the values
generated by these keys vary based on the current keyboard locale. For keys not classified as
writing system keys or for keys that do not generate printable characters,
this function returns the code for the key (i.e., it
returns that same value that was passed in). Note that the 'AltRight'
key always returns 'AltRight', even though some locales have this key labeled
AltGr.
Dead keys should return the combining accent character.
The value 'Undefined' is returned if the locale's keyboard does not contain the key
specified by code.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| code | DOMString | ✘ | ✘ | The code for the key, as defined in the Key Codes section below. |
| locale | DOMString | ✘ | ✔ |
If specified, this should be a [BCP47] tag (like 'en-US') that identifies the
keyboard layout in which to interpret the |
DOMStringqueryLocale, staticReturns the current keyboard locale as a [BCP47] string, such as 'en-US' or 'fr-FR'.
The value returned here is encoded the same as the value in the KeyboardEvent locale
attribute.
DOMStringCalling queryKeycap for various keys
queryKeyCap('KeyA') => 'a' Default locale is 'en-US'
queryKeyCap('KeyA', 'en-US') => 'a'
queryKeyCap('KeyA', 'fr-FR') => 'q'
queryKeyCap('Digit2', 'en-US') => '2'
queryKeyCap('Digit2', 'fr-FR') => 'é' ('\u00e9')
queryKeyCap('IntlRo', 'en-US') => 'Undefined' Key doesn't exist in US keyboard
queryKeyCap('IntlRo', 'ja-JP') => 'ろ' ('\u308d')
queryKeyCap('Quote', 'nl-US') => '´' ('\u0301') Combining accent
queryKeyCap('Quote', 'ru-RU') => 'э' ('\u042d')
queryKeyCap('BackQuote', 'en-US') => '`'
queryKeyCap('BackQuote', 'ja-JP') => 'BackQuote' Non-printable Halfwidth/Fullwidth Mode key
queryKeyCap('Space') => 'Space' Non-printable
queryKeyCap('ShiftLeft') => 'ShiftLeft' Non-printable
The value returned by queryKeyCap is suitable to be presented to a user (for example, in a
preferences dialog that allows the user to customize the key mappings) unless the returned value is
'Undefined'
or if it is equal to the code that was passed in to the method.
Getting the current keycap for 'KeyA'
queryKeyCap('KeyA', queryLocale())
A key code is an attribute of a keyboard event that can be used to identify the physical
key associated with the keyboard event. It is similar to USB Usage IDs [***REF***] in that it provides
a low-level value (similar to a scancode) that is vendor-neutral.
The primary purpose of the code attribute is to provide a consistent and coherent way
to identify keys based on their physical location. In addition, it also provides a stable name
(unaffected by the current keyboard state) that uniquely identifies each key on the keyboard.
code AttributeAs 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 char and key 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
char or key values to check for. A real-world example of this is
a game that wants to use the
'W', 'A', 'S' and 'D'
keys to control player movement.
The code attribute solves this problem by providing
a stable value to check that is not affected by the current keyboard layout.
In addition, the values in the char and key attributes depend as well
on the current keyboard state. Because of this, the order in which keys are pressed and released
in relation to modifier keys
can affect the values stored in the char and key attributes.
The code attribute solves this problem by providing
a stable value that is not affected by the current keyboard state.
char, key and codecharchar attribute is intended for users who are interested only in the printable final character
that the user typed (or entered through some other means).
Example use case: Detecting character input (e.g., to validate the contents of a textbox after each character is entered).
keykey attribute is intended for users who are interested in the meaning of the key
bring pressed, taking into account the current keyboard layout (and IME and dead keys).
Example use case: Detecting modified keys or bare modifier keys (e.g., to perform an action in response to a keyboard shortcut).
codecode attribute is intended for users who are interested in the key that was pressed
by the user, without any layout modifications applied.
Example use case: Detecting WASD keys (e.g., for movement controls in a game) or trapping all keys
(e.g., in a remote desktop client to send all keys to the remote host).
Handling the Left and Right Alt Keys
| Keyboard Layout | char | key | code | Notes |
|---|---|---|---|---|
| US | '' | 'Alt' | 'AltLeft' | DOM_KEY_LOCATION_LEFT |
| French | '' | 'Alt' | 'AltLeft' | DOM_KEY_LOCATION_LEFT |
| US | '' | 'Alt' | 'AltRight' | DOM_KEY_LOCATION_RIGHT |
| French | '' | 'AltGr' | 'AltRight' | DOM_KEY_LOCATION_RIGHT |
In this example, checking the key attribute permits matching 'Alt' without worrying about which Alt key (left or right) was pressed.
Checking the code attribute permits matching the right Alt key ('AltRight') without worrying about which layout is currently in effect.
Note that, in the French example, the 'Alt' and
'AltGr' keys retain their left and right location, even through there
is only one of each key.
Handling the Single Quote Key
| Keyboard Layout | char | key | code | Notes |
|---|---|---|---|---|
| US | ''' | ''' | 'Quote' | |
| Japanese | ':' | ':' | 'Quote' | |
| US Intl | '' | 'DeadAcute' | 'Quote' |
This example shows how dead key values are encoded in the attributes. The char and
key values vary based on the current locale, whereas the code attribute
returns a consistent value.
Handling the '2' Key (with and without Shift pressed)
| Keyboard Layout | char | key | code | Notes |
|---|---|---|---|---|
| US | '2' | '2' | 'Digit2' | |
| US | '@' | '@' | 'Digit2' | shiftKey |
| UK | '2' | '2' | 'Digit2' | |
| UK | '"' | '"' | 'Digit2' | shiftKey |
| French | 'é' | 'é' | 'Digit2' | |
| French | '2' | '2' | 'Digit2' | shiftKey |
Regardless of the current locale or the modifier key state, pressing the key labelled 2
on a US keyboard always results in 'Digit2' in the code attribute.
Sequence of Keyboard Events : Shift and '2'
Compare the attribute values in the following two key event sequences. They both produce the
'@' character on a US keyboard, but differ in the order in which the
keys are released. In the first sequence, the order is Shift (down), 2 (down), 2 (up), Shift (up).
| Keyboard Layout | Event | char | key | code | Notes |
|---|---|---|---|---|---|
| US | keydown | '' | 'Shift' | 'ShiftLeft' | DOM_KEY_LOCATION_LEFT |
| US | keydown | '@' | '@' | 'Digit2' | shiftKey |
| US | keypress | '@' | '@' | '' | |
| US | keyup | '@' | '@' | 'Digit2' | shiftKey |
| US | keyup | '' | 'Shift' | 'ShiftLeft' | DOM_KEY_LOCATION_LEFT |
In the second sequence, the Shift is released before the 2, resulting in the following event order: Shift (down), 2 (down), Shift (up), 2 (up).
| Keyboard Layout | Event | char | key | code | Notes |
|---|---|---|---|---|---|
| US | keydown | '' | 'Shift' | 'ShiftLeft' | DOM_KEY_LOCATION_LEFT |
| US | keydown | '@' | '@' | 'Digit2' | shiftKey |
| US | keypress | '@' | '@' | '' | |
| US | keyup | '' | 'Shift' | 'ShiftLeft' | DOM_KEY_LOCATION_LEFT |
| US | keyup | '2' | '2' | 'Digit2' |
Note that the values contained in the char and key attributes do not match between
the keydown and keyup events for the '2' key. The code attribute provides a consistent value
that is not affected by the current modifier state.
Alphanumeric keyboards are the most common way for users to generate keyboard events, but properly detecting key events can be tricky because the OS may change the behavior of certain keys based on the current keyboard layout selected by the user.
This section provides an overview of standard keyboards and describes the code
attribute associated with each key.
This section is informative
When discussing keyboard layouts, it is convenient to divide the standard keyboard into distinct sections and to label each row.
The Alphanumeric section is the main part of the keyboard and is where most of the keyboard variation occurs. When a user selects a keyboard layout, it is the keys in this sections that are most affected.
The Control Pad and Arrow Pad sections contain the arrow keys and other editing keys.
The Numpad (also known as the "numeric keypad" or "number pad") contains number and math keys to make it easier to enter numeric data.
And finally, the Function section contains miscellaneous function keys and special keys like Escape.
To make it easier to identify keys, the rows on the keyboard are named starting with "A" for the bottom row up to "E" for the top row. The row of keys in the Function section are considered to be in row "K". These row names are consistent with those given in the ISO/IEC 9995-1 specification.
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 Media Keys section. Keys not covered in this document should be handled in the same manner as described in the Other Devices section.
This section is informative
This section describes the physical layouts found on commonly available keyboards.
The standard "101" keyboard (commonly referred to as the "US layout") is the only layout that uses the 'Backslash' code.
All the other layouts omit this key and expand the 'Enter' key to occupy
two-rows.
Modern standard "101"-layout keyboards actually contain 104 keys: 61 keys in the alphanumeric section
and 43 keys in the numpad, control pad, arrow pad and function sections.
The "101" name for this keyboard layout dates to the time when this standard keyboard did in fact contain
101 keys. The two 'OS' keys,
and the 'Menu' key were
added later to bring the total to 104 keys.
The alternate "101" keyboard removes the 'Backslash' key to create a
large 'Enter' key and shrinks the 'Backspace'
key to make room for the 'IntlYen' key (The 'IntlYen' name comes from the
Japanese layout — in the Russian layout shown above this key maps to a '\'.
Modern alternate "101"-layout keyboards contain 104 keys: 61 keys in the alphanumeric section and 43 keys in the numpad, control pad, arrow pad and function sections.
The standard "102" keyboard is common throughout Europe and adds two keys that don't exist on the
"101" layouts:
The 'IntlBackslash' key next to the left shift key,
and the 'IntlHash' key which is partially tucked under the
'Enter' key.
Modern "102"-layout keyboards contain 105 keys: 62 keys in the alphanumeric section and 43 keys in the numpad, control pad, arrow pad and function sections.
The Korean "103" keyboard is based on the alternate 101 layout and adds two additional keys
(one on each side of the spacebar) to handle Korean-specific input modes.
These keys are
'Hanja' (labelled 한자 hanja) and
'HangulMode' (labelled 한/영 han/yeong).
Modern "103"-layout keyboards contain 106 keys: 63 keys in the alphanumeric section and 43 keys in the numpad, control pad, arrow pad and function sections.
The "104" layout used in Brazil adds 4 new keys: the two non-US keys from the "102" layout
('IntlHash' and 'IntlBackslash')
plus the 'IntlRo' key (next to the right shift
key) and an extra key on the numeric keypad. This new keypad key is called
'KeypadComma' because it represents the thousands separator. On the
Brazilian key layout, this key has a keycap of . and the 'KeypadPeriod'
key has a keycap of ,.
Modern "104"-layout keyboards contain 107 keys: 63 keys in the alphanumeric section and 44 keys in the numpad, control pad, arrow pad and function sections. Some Brazilian keyboards lack the extra keypad key and have only 106 keys.
The Japanese "106" keyboard layout adds 3 new keys:
'IntlYen',
'IntlHash' and
'IntlRo'.
It also shrinks the 'Space' key to make room for 3 input mode keys:
'NoConvert' (labelled 無変換 muhenkan),
'Convert' (labelled 変換 henkan),
'KanaMode' (labelled カタカナ/ひらがな/ローマ字 katakana/hiragana/romaji).
Modern "106"-layout keyboards contain 109 keys: 66 keys in the alphanumeric section and 43 keys in the numpad, control pad, arrow pad and function sections.
In general, Apple keyboards follow the same layout as PC keyboards, but there are some differences as noted in the following figure.
In this figure, the green keys are those that have been moved to a new location while the blue keys indicate keys that have been added.
The limited space available on laptop keyboards often means that the physical key layout needs to be adjusted to fit all the required keys. The writing system keys in the Alphanumeric section tend to remain intact, but the other keyboard sections are usually combined with other keys or removed altogether.
In this Apple laptop keyboard, the right control key has been removed to make room for half-height
arrow keys and a 'Fn' key is added on the left.
PC laptop keyboards vary considerably, but this sample keyboard demonstrates some commonly found aspects. The control pad keys are added along the right-hand side with the arrow keys tucked in along the bottom. The right shift key is often shrunk to make room for the up arrow key and the right OS key is typically removed altogether.
This section describes the various keyboard sections in more detail and defines the code
values that should be used for each key.
The Alphanumeric section keys fall into two general categories: "writing system" keys whose meaning changes based on the current keyboard layout, and "functional" keys which are (mostly) the same for all layouts.
The "writing system" keys are those that change meaning based on the current keyboard layout.
This figure shows a hypothetical keyboard that combines all the writing system keys (shown in blue and green) found on the various keyboards. Blue keys are present on all standard keyboards while green keys are only available on some keyboards.
The name shown on each key is the code assigned to that key.
Wherever possible, the code names are based on the name for the US key
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.
| Code Value | USB Usage ID Page 0x07 (Informative) | Notes (Informative) |
|---|---|---|
'BackQuote' |
0x35 | ` and ~ on a US keyboard. This is the 半角/全角/漢字 (hankaku/zenkaku/kanji) key on Japanese keyboards |
'Backslash' |
0x31 | \ and | on a US keyboard. Found only on standard 101-key layouts. |
'Backspace' |
0x2a | Labelled Delete on Macintosh keyboards. |
'BracketLeft' |
0x2f | [ and { on a US keyboard. |
'BracketRight' |
0x30 | ] and } on a US keyboard. |
'Comma' |
0x36 | , and < on a US keyboard. |
'Digit0' |
0x27 | 0 and ) on a US keyboard. |
'Digit1' |
0x1e | 1 and ! on a US keyboard. |
'Digit2' |
0x1f | 2 and @ on a US keyboard. |
'Digit3' |
0x20 | 3 and # on a US keyboard. |
'Digit4' |
0x21 | 4 and $ on a US keyboard. |
'Digit5' |
0x22 | 5 and % on a US keyboard. |
'Digit6' |
0x23 | 6 and ^ on a US keyboard. |
'Digit7' |
0x24 | 7 and & on a US keyboard. |
'Digit8' |
0x25 | 8 and * on a US keyboard. |
'Digit9' |
0x26 | 9 and ( on a US keyboard. |
'Equal' |
0x2e | = and + on a US keyboard. |
'IntlBackslash' |
0x64 | Located between the 'ShiftLeft' and 'KeyZ' keys. The \ and | key on a UK keyboard. |
'IntlHash' |
0x32 | Located between the 'Quote' and 'Enter' keys on row E of the keyboard. The # and ~ key on a UK keyboard. |
'IntlRo' |
0x87 | Located between the 'Slash' and 'ShiftRight' keys. The \ and ろ (ro) key on a Japanese keyboard. |
'IntlYen' |
0x89 | Located between the 'Equal' and 'Backspace' keys. The ¥ (yen) key on a Japanese keyboard. The \ and / key on a Russian keyboard. |
'KeyA' |
0x04 | a on a US keyboard. Labelled q on an AZERTY (e.g., French) keyboard. |
'KeyB' |
0x05 | b on a US keyboard. |
'KeyC' |
0x06 | c on a US keyboard. |
'KeyD' |
0x07 | d on a US keyboard. |
'KeyE' |
0x08 | e on a US keyboard. |
'KeyF' |
0x09 | f on a US keyboard. |
'KeyG' |
0x0a | g on a US keyboard. |
'KeyH' |
0x0b | h on a US keyboard. |
'KeyI' |
0x0c | i on a US keyboard. |
'KeyJ' |
0x0d | j on a US keyboard. |
'KeyK' |
0x0e | k on a US keyboard. |
'KeyL' |
0x0f | l on a US keyboard. |
'KeyM' |
0x10 | m on a US keyboard. |
'KeyN' |
0x11 | n on a US keyboard. |
'KeyO' |
0x12 | o on a US keyboard. |
'KeyP' |
0x13 | p on a US keyboard. |
'KeyQ' |
0x14 | q on a US keyboard. Labelled a on an AZERTY (e.g., French) keyboard. |
'KeyR' |
0x15 | r on a US keyboard. |
'KeyS' |
0x16 | s on a US keyboard. |
'KeyT' |
0x17 | t on a US keyboard. |
'KeyU' |
0x18 | u on a US keyboard. |
'KeyV' |
0x19 | v on a US keyboard. |
'KeyW' |
0x1a | w on a US keyboard. Labelled z on an AZERTY (e.g., French) keyboard. |
'KeyX' |
0x1b | x on a US keyboard. |
'KeyY' |
0x1c | y on a US keyboard. Labelled z on a QWERTZ (e.g., German) keyboard. |
'KeyZ' |
0x1d | z on a US keyboard. Labelled w on an AZERTY (e.g., French) keyboard, and y on a QWERTZ (e.g., German) keyboard. |
'Minus' |
0x2d | - and _ on a US keyboard. |
'Period' |
0x37 | . and > on a US keyboard. |
'Quote' |
0x34 | ' and " on a US keyboard. |
'Semicolon' |
0x33 | ; and : on a US keyboard. |
'Slash' |
0x38 | / and ? on a US keyboard. |
The Functional keys (not to be confused with the Function keys described later) 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.
| Code Value | USB Usage ID Page 0x07 (Informative) | Notes (Informative) |
|---|---|---|
'AltLeft' |
0xe2 | Labelled Alt or Option. |
'AltRight' |
0xe6 | Labelled Alt or Option. This is the AltGr key on many keyboard layouts. |
'CapsLock' |
0x39 | |
'ContextMenu' |
0x65 | The application context menu key, which is typically found between the right OS key and the right Control key. |
'ControlLeft' |
0xe0 | |
'ControlRight' |
0xe4 | |
'Enter' |
0x28 | Labelled Enter and Return on Macintosh keyboards. |
'OSLeft' |
0xe3 | The Windows, ⌘, Command or other OS symbol key. |
'OSRight' |
0xe7 | The Windows, ⌘, Command or other OS symbol key. |
'ShiftLeft' |
0xe1 | |
'ShiftRight' |
0xe5 | |
'Space' |
0x2c | The key. |
'Tab' |
0x2b |
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 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 values.
| Code Value | USB Usage ID Page 0x07 (Informative) | Notes (Informative) |
|---|---|---|
'Convert' |
0x8a | Japanese: 変換 (henkan) |
'HangulMode' |
0x90 | Korean: 한/영 (han/yeong) |
'Hanja' |
0x91 | Korean: 한자 (hanja) |
'KanaMode' |
0x88 | Japanese: カタカナ/ひらがな/ローマ字 (katakana/hiragana/romaji) |
'NoConvert' |
0x8b | Japanese: 無変換 (muhenkan) |
On Apple keyboards, some keys on the bottom row are omitted and others are arranged in a different order.
The Control Pad contains keys for navigating and editing documents.
| Code Value | USB Usage ID Page 0x07 (Informative) | Notes (Informative) |
|---|---|---|
'Delete' |
0x4c | |
'End' |
0x4d | |
'Help' |
0x75 | Not present on standard PC keyboards. |
'Home' |
0x4a | |
'Insert' |
0x49 | Not present on Apple keyboards. |
'PageDown' |
0x4e | |
'PageUp' |
0x4b |
Note: The code for the 'Fn' key (found on
some Apple keyboards) is defined below in the Function Section.
The Arrow Pad section contains the 4 arrow keys.
| Code Value | USB Usage ID Page 0x07 (Informative) | Notes (Informative) |
|---|---|---|
'ArrowDown' |
0x51 | |
'ArrowLeft' |
0x50 | |
'ArrowRight' |
0x4f | |
'ArrowUp' |
0x52 |
The Numpad Section contains numeric and mathematical operator keys arranged in a calculator-grid to facilitate numeric data entry.
The standard Numpad is sometimes extended with additional keys for parentheses, operators, hexadecimal symbols, or calculator functions (like backspace). Some of the commonly added keys are listed in the table below.
| Code Value | USB Usage ID Page 0x07 (Informative) | Notes (Informative) |
|---|---|---|
'NumLock' |
0x53 | |
'Numpad0' |
0x62 | 0 and Insert |
'Numpad1' |
0x59 | 1 and End |
'Numpad2' |
0x5a | 2 and ArrowDown |
'Numpad3' |
0x5b | 3 and PageDown |
'Numpad4' |
0x5c | 4 and ArrowLeft |
'Numpad5' |
0x5d | 5 |
'Numpad6' |
0x5e | 6 and ArrowRight |
'Numpad7' |
0x5f | 7 and Home |
'Numpad8' |
0x60 | 8 and ArrowUp |
'Numpad9' |
0x61 | 9 and PageUp |
'NumpadAdd' |
0x57 | + |
'NumpadBackspace' |
0xbb | Found on the Microsoft Natural Keyboard. |
'NumpadClear' |
0xd8 | |
'NumpadClearEntry' |
0xd9 | |
'NumpadComma' |
0x85 | , (thousands separator). For locales where the thousands separator is a '.' (e.g., Brazil), this key may generate a '.'. |
'NumpadDecimal' |
0x63 | . (decimal separator) and Delete. For locales where the decimal separator is ',' (e.g., Brazil), this key may generate a ','. |
'NumpadDivide' |
0x54 | / |
'NumpadEnter' |
0x58 | |
'NumpadMemoryAdd' |
0xd3 | |
'NumpadMemoryClear' |
0xd2 | |
'NumpadMemoryRecall' |
0xd1 | |
'NumpadMemoryStore' |
0xd0 | |
'NumpadMemorySubtract' |
0xd4 | |
'NumpadMultiply' |
0x55 | * |
'NumpadParenLeft' |
0xb6 | ( Found on the Microsoft Natural Keyboard. |
'NumpadParenRight' |
0xb7 | ) Found on the Microsoft Natural Keyboard. |
'NumpadSubtract' |
0x56 | - |
For Numpads that provide keys not listed here, a code value string should be created by
starting with 'Numpad' and appending an appropriate description of the key.
The Function section runs along the top of the keyboard and contains the function keys and
a few additional special keys (for example, 'Esc' and
'PrintScreen').
On some keyboards (especially those found on laptops or other portable computers), the function keys
('F1' ... 'F12')
are defined to have other primary functions (like controlling display brightness or
audio volume) and require that a separate 'Fn' key
be pressed to make them act as function keys.
Unfortunately, the primary functions assigned to these keys varies widely from one manufacturer to the next.
Because of this, the code is always set to the function key name.
| Code Value | USB Usage ID Page 0x07 (Informative) | Notes (Informative) |
|---|---|---|
'Esc' |
0x29 | |
'F1' |
0x3a | |
'F2' |
0x3b | |
'F3' |
0x3c | |
'F4' |
0x3d | |
'F5' |
0x3e | |
'F6' |
0x3f | |
'F7' |
0x40 | |
'F8' |
0x41 | |
'F9' |
0x42 | |
'F10' |
0x43 | |
'F11' |
0x44 | |
'F12' |
0x45 | |
'Fn' |
This is typically a hardware key that does not generate a separate code. Most keyboards do not place this key in the Function section, but it is included here to keep with related keys. | |
'FLock' |
Found on the Microsoft Natural Keyboard. | |
'PrintScreen' |
0x46 | PrintScreen and SysReq |
'ScrollLock' |
0x47 | |
'Pause' |
0x48 | Pause and Break |
For keyboards that provide more than 12 function keys, the code value follows the pattern
shown above with 'F' followed by the function key number - 'F13', 'F14',
'F15', and so on.
Note: Apple keyboards may have 'Eject' or 'Power'
keys in the Function section. The code values
for these keys are defined in the Media Keys section.
Keys that fall outside the sections listed above are referred to as "media keys" since they commonly provide "media" functions like play, pause or volume control.
These are extra keys that many keyboard manufacturers add, but do not have a consistent location. These keys are often distinct from normal typing keys in appearance and may be recessed in the keyboard.
On laptop keyboards, these keys are often merged with the Function keys, with the "media" interpretation
being the primary function of the key and the "function key" interpretation requiring the
'Fn' key to be pressed at the same time. In this configuration the
code should be set to match the function key ('F1' ...
'F12'). When the keys are merged in this fashion, the code
values are taken from the function key value since the "media" value is not consistent across
keyboards.
| Code Value | Notes (Informative) |
|---|---|
'BrowserBack' |
Some laptops place this key to the left of the 'ArrowUp' key. |
'BrowserFavorites' |
|
'BrowserForward' |
Some laptops place this key to the right of the 'ArrowUp' key. |
'BrowserHome' |
|
'BrowserRefresh' |
|
'BrowserSearch' |
|
'BrowserStop' |
|
'Eject' |
This key is placed in the Function section on some Apple keyboards. |
'LaunchApp1' |
Sometimes labelled My Computer on the keyboard |
'LaunchApp2' |
Sometimes labelled Calculator on the keyboard |
'LaunchMail' |
|
'MediaNextTrack' |
|
'MediaPlayPause' |
|
'MediaPreviousTrack' |
|
'MediaSelect' |
|
'MediaStop' |
|
'Power' |
This key is placed in the Function section on some Apple keyboards, replacing the 'Eject' key. |
'Sleep' |
|
'VolumeDown' |
|
'VolumeMute' |
|
'VolumeUp' |
|
'WakeUp' |
These keys are not found on modern keyboards. They are listed here are for reference purposes.
| Code Value | Notes (Informative) |
|---|---|
'Abort' |
|
'Hyper' |
|
'Meta' |
Do not use 'Meta' as a key code. The key labelled Meta should be encoded as 'OSLeft'. |
'Resume' |
|
'Super' |
|
'Suspend' |
|
'Turbo' |
This section briefly describes how key input from non-standard keyboards and other
input devices should be handled with respect to the code attribute.
In general, these devices do not suffer from the complications found on
found on standard PC computers (modifier keys and support for multiple input layouts)
so the code attribute can be duplicated from the key
attribute or left empty.
Remote controls for media devices typically consist of a set of buttons that are used to directly control media functions on the device. These remote control buttons typically do not have modifier states so each button is assigned a single function (like "Play", "Pause", "Up", "Menu" or "Exit").
This simple arrangement where each button has one function means that the
code attribute will usually be exactly the same as the key
attribute for that button. It is only if the remote control has a mechanism
(like the "2nd" function button on a calculator) that allows buttons to produce
alternate key values that the code value will differ from
the key value.
In this case, the value of the code attribute should always be the value
that the button would produce when in its factory-reset condition.
When a virtual keyboard is mimicking the layout and functionality of a standard
keyboard, then it should also set the code attribute as appropriate.
Otherwise, it can leave this field blank.
A chording keyboard is a keyboard with a small number of physical keys that requires the user to hold a number of keys simultaneously (or press them in sequence) to produce a single key input event. The advantage of chording keyboards is that they require a small number of distinct keys and can usually be operated with a single hand.
If implemented properly, the system should be unaware that the user is entering text
using a chording keyboard, so the code that translates the chord combinations to
regular key events should fabricate appropriate code values.
Other devices that generate key events should be supported in the manner described above in the Media Remote Controls section:
key value, then the
code should simply be duplicated from the key.
key values based on some
modifier state, then the code value should be the key value
generated when the button is pressed while the device is in its factory-reset state.
When there isn't an appropriate code value already defined and a new
value needs to be chosen, the string value should be constructed so that descriptive
(avoid names that are ambiguous or too short) and wherever possible, related buttons
should share a common prefix (like the Numpad keys).