This specification extends the events and features defined in DOM Events Level 3.
Comments submitted in regard to this document should have their subject
line prefixed with the string
[uievents] to help facilitate
tracking on the
There is a
bug tracker for this specification.
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.
UI Events builds on the event model defined in DOM Level 3 Events (and also DOM4). Features in scope for this specification are:
This section extends the KeyboardEvent interface defined in DOM Level 3 by adding methods for querying the keyboard state without requiring a Keyboard event to be dispatched, and by providing locale information during the dispatch of a Keyboard event.
code corresponding to a key on a standard keyboard and a [[!BCP47]]
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.
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
key always returns 'AltRight', even though some locales have this key labeled
Dead keys should return the combining accent character.
The value 'Undefined' is returned if the
locale's keyboard does not contain the key
If specified, this should be a [[!BCP47]] tag (like 'en-US') that identifies the
keyboard layout in which to interpret the
If not specified, then the
value is interpreted in the context of the 'en-US' locale.
DOMString attribute contains a [[!BCP47]] tag indicating the locale for which the keyboard originating
the event is configured, e.g.
locale MAY be the empty string when inapplicable
or unknown, e.g. when this information is not exposed by the underlying platform.
locale does not necessarily indicate the locale of the data or the context in which
it is being entered. For example, a French user often might not switch to an English keyboard setting when typing English, in which case the
will still indicate French. Nor can it be used to definitively calculate the
virtual key associated with the event, or the character
printed on that key.
The un-initialized value of this attribute MUST be
"" (the empty string).
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
queryKeycap for various keys
'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') =>
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
or if it is equal to the
code that was passed in to the method.
Getting the current keycap for