W3C

UI Events

W3C First Public Working Draft

This version:
http://www.w3.org/TR/2013/WD-uievents-20130725/
Latest published version:
http://www.w3.org/TR/uievents/
Previous version:
None
Latest editor's draft:
https://dvcs.w3.org/hg/d4e/raw-file/tip/source_respec.htm
Editors:
Travis Leithead, Microsoft Corp.
Gary Kacmarcik, Google, Inc.

Abstract

This specification extends the events and features defined in DOM Events Level 3.

Status of This Document

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.

Table of Contents

1. Conformance

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]:

2. Goals

UI Events builds on the event model defined in DOM Level 3 Events (and also DOM4). Features in scope for this specification are:

3. Event Constructors

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.

Example 1

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);
        
Example 2

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].

3.1 UIEvent Constructor

[Constructor(DOMString type, optional UIEventInit eventInitDict)]
partial interface UIEvent : Event {
};
dictionary UIEventInit : EventInit {
    Window? view = null;
    long    detail = 0;
};

3.1.1 Dictionary UIEventInit Members

detail of type long, defaulting to 0
This value is initialized to a number that is application-specific.
view of type Window, nullable, defaulting to null
Should be initialized to the Window object of the global environment in which this event will be dispatched. If this event will be dispatched to an element, the view property should be set to the Window object containing the element's ownerDocument.

3.2 FocusEvent Constructor

[Constructor(DOMString typeArg, optional FocusEventInit focusEventInitDict)]
partial interface FocusEvent {
};
dictionary FocusEventInit : UIEventInit {
    EventTarget? relatedTarget = null;
};

3.2.1 Dictionary FocusEventInit Members

relatedTarget of type EventTarget, nullable, defaulting to null
The relatedTarget 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).

3.3 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;
};

3.3.1 Dictionary MouseEventInit Members

altKey of type boolean, defaulting to false
Initializes the altKey attribute of the MouseEvent object to true if the altKey modifier key is to be considered depressed, false otherwise.
button of type unsigned short, defaulting to 0
Initializes the 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

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 of type unsigned short, defaulting to 0
Initializes the 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

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.

Example 3

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 0
See clientY (substituting "horizontal" for "vertical")
clientY of type long, defaulting to 0
Initializes the clientY 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 1

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 false
Initializes the ctrlKey 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 false
Initializes the metaKey attribute of the MouseEvent object to true if the metaKey modifier key is to be considered depressed, false otherwise.
relatedTarget of type EventTarget, nullable, defaulting to null
The 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 0
See screenY (substituting "horizontal" for "veritcal")
screenY of type long, defaulting to 0
Initializes the screenY 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 false
Initializes the shiftKey attribute of the MouseEvent object to true if the shiftKey modifier key is to be considered depressed, false otherwise.

3.4 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;
};

3.4.1 Dictionary WheelEventInit Members

deltaMode of type unsigned long, defaulting to 0
Initializes the deltaMode 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.0
See deltaZ attribute.
deltaY of type double, defaulting to 0.0
See deltaZ attribute.
deltaZ of type double, defaulting to 0.0
Initializes the deltaZ 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.

3.5 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 = "";
};

3.5.1 Dictionary KeyboardEventInit Members

altKey of type boolean, defaulting to false
Initializes the altKey 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 ""
Initializes the 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 ""
Initializes the 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 false
Initializes the ctrlKey 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 ""
Initializes the 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 ""
Initializes the 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 0
Initializes the location 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 false
Initializes the metaKey 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 false
Initializes the repeat 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 false
Initializes the shiftKey attribute of the KeyboardEvent object to true if the shiftKey modifier key is to be considered depressed, false otherwise.

3.6 CompositionEvent Constructor

[Constructor(DOMString typeArg, optional CompositionEventInit compositionEventInitDict)]
partial interface CompositionEvent {
};
dictionary CompositionEventInit : UIEventInit {
    DOMString? data = "";
    DOMString  locale = "";
};

3.6.1 Dictionary CompositionEventInit Members

data of type DOMString, nullable, defaulting to ""
Initializes the data attribute of the CompositionEvent object to the characters generated by the IME composition.
locale of type DOMString, defaulting to ""
Initializes the 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.

4. Keyboard Events

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.

4.1 Interface KeyboardEvent

partial interface KeyboardEvent : UIEvent {
    readonly    attribute DOMString code;
    static DOMString queryKeyCap (DOMString code, optional DOMString locale);
    static DOMString queryLocale ();
};

4.1.1 Attributes

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).

4.1.2 Methods

queryKeyCap, static

Given 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.

ParameterTypeNullableOptionalDescription
codeDOMStringThe code for the key, as defined in the Key Codes section below.
localeDOMString

If specified, this should be a [BCP47] tag (like 'en-US') that identifies the keyboard layout in which to interpret the code parameter.
If not specified, then the code value is interpreted in the context of the 'en-US' locale.

Return type: DOMString
queryLocale, static

Returns 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.

No parameters.
Return type: DOMString
Example 4

Calling 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.

Example 5

Getting the current keycap for 'KeyA'

queryKeyCap('KeyA', queryLocale())

4.2 Key codes

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.

4.2.1 Motivation for Adding the code Attribute

As 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.

4.2.2 The Relationship Between char, key and code

char
The char 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).
key
The key 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).
code
The code 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).
Example 6

Handling the Left and Right Alt Keys

Keyboard LayoutcharkeycodeNotes
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.

Example 7

Handling the Single Quote Key

Keyboard LayoutcharkeycodeNotes
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.

Example 8

Handling the '2' Key (with and without Shift pressed)

Keyboard LayoutcharkeycodeNotes
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.

Example 9

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 LayoutEventcharkeycodeNotes
USkeydown'''Shift''ShiftLeft'DOM_KEY_LOCATION_LEFT
USkeydown'@''@''Digit2'shiftKey
USkeypress'@''@'''
USkeyup'@''@''Digit2'shiftKey
USkeyup'''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 LayoutEventcharkeycodeNotes
USkeydown'''Shift''ShiftLeft'DOM_KEY_LOCATION_LEFT
USkeydown'@''@''Digit2'shiftKey
USkeypress'@''@'''
USkeyup'''Shift''ShiftLeft'DOM_KEY_LOCATION_LEFT
USkeyup'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.

4.3 Keyboards

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.

4.3.1 Keyboard Sections

This section is informative

When discussing keyboard layouts, it is convenient to divide the standard keyboard into distinct sections and to label each row.

Fig. 1 The five general sections of a standard keyboard.

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.

4.3.2 Standard Keyboard Layouts

This section is informative

This section describes the physical layouts found on commonly available keyboards.

4.3.2.1 Standard "101" Keyboard Layout

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.

Fig. 2 Standard '101' keyboard layout showing unmodified US key values.

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.

4.3.2.2 Alternate "101" Keyboard Layout

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 '\'.

Fig. 3 Alternate '101' keyboard layout showing unmodified Russian key values.

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.

4.3.2.3 Standard "102" Keyboard Layout

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.

Fig. 4 Standard '102' keyboard layout showing unmodified French key values.

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.

4.3.2.4 Korean "103" Keyboard Layout

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).

Fig. 5 Korean '103' keyboard layout showing unmodified Korean key values.

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.

4.3.2.5 Brazilian "104" Keyboard Layout

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 ,.

Fig. 6 Standard '104' keyboard layout showing unmodified Brazilian key values.

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.

4.3.2.6 Japanese "106" Keyboard Layout

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).

Fig. 7 Standard '106' keyboard layout showing unmodified Japanese key values.

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.

4.3.2.7 Apple Keyboard Layout

In general, Apple keyboards follow the same layout as PC keyboards, but there are some differences as noted in the following figure.

Fig. 8 Apple extended keyboard layout showing unmodified English key values.

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.

4.3.2.8 Laptop Keyboard Layouts

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.

Fig. 9 Apple laptop keyboard layout.

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.

Fig. 10 Sample PC laptop keyboard layout.

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.

4.3.3 Key Codes for Standard Keyboards

This section describes the various keyboard sections in more detail and defines the code values that should be used for each key.

4.3.3.1 Alphanumeric Section

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.

Writing System Keys

The "writing system" keys are those that change meaning based on the current keyboard layout.

Fig. 11 The writing system keys in the alphanumeric section.

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.

List of code values for writing system keys in the Alphanumeric section.
Code ValueUSB 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' 0x2aLabelled 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' 0x270 and ) on a US keyboard.
'Digit1' 0x1e1 and ! on a US keyboard.
'Digit2' 0x1f2 and @ on a US keyboard.
'Digit3' 0x203 and # on a US keyboard.
'Digit4' 0x214 and $ on a US keyboard.
'Digit5' 0x225 and % on a US keyboard.
'Digit6' 0x236 and ^ on a US keyboard.
'Digit7' 0x247 and & on a US keyboard.
'Digit8' 0x258 and * on a US keyboard.
'Digit9' 0x269 and ( on a US keyboard.
'Equal' 0x2e= and + on a US keyboard.
'IntlBackslash' 0x64Located between the 'ShiftLeft' and 'KeyZ' keys. The \ and | key on a UK keyboard.
'IntlHash' 0x32Located between the 'Quote' and 'Enter' keys on row E of the keyboard. The # and ~ key on a UK keyboard.
'IntlRo' 0x87Located between the 'Slash' and 'ShiftRight' keys. The \ and (ro) key on a Japanese keyboard.
'IntlYen' 0x89Located between the 'Equal' and 'Backspace' keys. The ¥ (yen) key on a Japanese keyboard. The \ and / key on a Russian keyboard.
'KeyA' 0x04a on a US keyboard. Labelled q on an AZERTY (e.g., French) keyboard.
'KeyB' 0x05b on a US keyboard.
'KeyC' 0x06c on a US keyboard.
'KeyD' 0x07d on a US keyboard.
'KeyE' 0x08e on a US keyboard.
'KeyF' 0x09f on a US keyboard.
'KeyG' 0x0ag on a US keyboard.
'KeyH' 0x0bh on a US keyboard.
'KeyI' 0x0ci on a US keyboard.
'KeyJ' 0x0dj on a US keyboard.
'KeyK' 0x0ek on a US keyboard.
'KeyL' 0x0fl on a US keyboard.
'KeyM' 0x10m on a US keyboard.
'KeyN' 0x11n on a US keyboard.
'KeyO' 0x12o on a US keyboard.
'KeyP' 0x13p on a US keyboard.
'KeyQ' 0x14q on a US keyboard. Labelled a on an AZERTY (e.g., French) keyboard.
'KeyR' 0x15r on a US keyboard.
'KeyS' 0x16s on a US keyboard.
'KeyT' 0x17t on a US keyboard.
'KeyU' 0x18u on a US keyboard.
'KeyV' 0x19v on a US keyboard.
'KeyW' 0x1aw on a US keyboard. Labelled z on an AZERTY (e.g., French) keyboard.
'KeyX' 0x1bx on a US keyboard.
'KeyY' 0x1cy on a US keyboard. Labelled z on a QWERTZ (e.g., German) keyboard.
'KeyZ' 0x1dz 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.
Functional Keys

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.

Fig. 12 The standard set of functional keys in the alphanumeric section.
List of code values for functional keys in the Alphanumeric section.
Code ValueUSB Usage ID
Page 0x07
(Informative)
Notes (Informative)
'AltLeft' 0xe2Labelled Alt or Option.
'AltRight' 0xe6Labelled Alt or Option. This is the AltGr key on many keyboard layouts.
'CapsLock' 0x39
'ContextMenu' 0x65The application context menu key, which is typically found between the right OS key and the right Control key.
'ControlLeft' 0xe0
'ControlRight' 0xe4
'Enter' 0x28Labelled Enter and Return on Macintosh keyboards.
'OSLeft' 0xe3The Windows, , Command or other OS symbol key.
'OSRight' 0xe7The Windows, , Command or other OS symbol key.
'ShiftLeft' 0xe1
'ShiftRight' 0xe5
'Space' 0x2cThe   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.

Fig. 13 Comparison of the lower row of functional keys on different keyboards.
List of code values for functional keys found on Japanese and Korean keyboards.
Code ValueUSB Usage ID
Page 0x07
(Informative)
Notes (Informative)
'Convert' 0x8aJapanese: 変換 (henkan)
'HangulMode' 0x90Korean: 한/영 (han/yeong)
'Hanja' 0x91Korean: 한자 (hanja)
'KanaMode' 0x88Japanese: カタカナ/ひらがな/ローマ字 (katakana/hiragana/romaji)
'NoConvert' 0x8bJapanese: 無変換 (muhenkan)

On Apple keyboards, some keys on the bottom row are omitted and others are arranged in a different order.

4.3.3.2 Control Pad Section

The Control Pad contains keys for navigating and editing documents.

Fig. 14 Standard Control Pad layouts
List of code values for keys in the ControlPad section.
Code ValueUSB Usage ID
Page 0x07
(Informative)
Notes (Informative)
'Delete' 0x4c
'End' 0x4d
'Help' 0x75Not present on standard PC keyboards.
'Home' 0x4a
'Insert' 0x49Not 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.

4.3.3.3 Arrow Pad Section

The Arrow Pad section contains the 4 arrow keys.

Fig. 15 Standard Arrow Pad layout
List of code values for keys in the ArrowPad section.
Code ValueUSB Usage ID
Page 0x07
(Informative)
Notes (Informative)
'ArrowDown' 0x51
'ArrowLeft' 0x50
'ArrowRight' 0x4f
'ArrowUp' 0x52
4.3.3.4 Numpad Section

The Numpad Section contains numeric and mathematical operator keys arranged in a calculator-grid to facilitate numeric data entry.

Fig. 16 Standard Numpad layouts

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.

List of code values for keys in the Numpad section.
Code ValueUSB Usage ID
Page 0x07
(Informative)
Notes (Informative)
'NumLock' 0x53
'Numpad0' 0x620 and Insert
'Numpad1' 0x591 and End
'Numpad2' 0x5a2 and ArrowDown
'Numpad3' 0x5b3 and PageDown
'Numpad4' 0x5c4 and ArrowLeft
'Numpad5' 0x5d5
'Numpad6' 0x5e6 and ArrowRight
'Numpad7' 0x5f7 and Home
'Numpad8' 0x608 and ArrowUp
'Numpad9' 0x619 and PageUp
'NumpadAdd' 0x57+
'NumpadBackspace' 0xbbFound 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.

4.3.3.5 Function Section

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.

List of code values for keys in the Function section.
Code ValueUSB 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' 0x46PrintScreen and SysReq
'ScrollLock' 0x47
'Pause' 0x48Pause 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.

4.3.3.6 Media Keys

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.

List of code values for media keys.
Code ValueNotes (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'
4.3.3.7 Legacy Keys

These keys are not found on modern keyboards. They are listed here are for reference purposes.

List of code values for legacy keys.
Code ValueNotes (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'

4.4 Non-Standard Keyboards and Other Input Devices

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.

4.4.1 Media Remote Controls

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.

4.4.2 Virtual Keyboards

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.

4.4.3 Chording Keyboards

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.

4.4.4 Other Devices

Other devices that generate key events should be supported in the manner described above in the Media Remote Controls section:

  • If the button or key always produces the same key value, then the code should simply be duplicated from the key.
  • If the button of key can produce different 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).

A. References

A.1 Normative references

[BCP47]
A. Phillips; M. Davis. Tags for Identifying Languages. September 2009. IETF Best Current Practice. URL: http://tools.ietf.org/html/bcp47
[DOM-LEVEL-3-EVENTS]
Travis Leithead; Jacob Rossi; Doug Schepers; Björn Höhrmann; Philippe Le Hégaret; Tom Pixley. Document Object Model (DOM) Level 3 Events Specification. 06 September 2012. W3C Working Draft. URL: http://www.w3.org/TR/DOM-Level-3-Events/
[DOM4]
Anne van Kesteren; Aryeh Gregor; Lachlan Hunt; Ms2ger. DOM4. 6 December 2012. W3C Working Draft. URL: http://www.w3.org/TR/dom/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt