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 www-dom mailing list. 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.

Goals

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

Keyboard Events

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.

Interface KeyboardEvent

static DOMString queryKeyCap()

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.

DOMString code
The code for the key, as defined in the [DOM Level 3 KeyboardEvent code Values] spec.
optional DOMString locale

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.

readonly attribute DOMString locale

The locale DOMString attribute contains a [[!BCP47]] tag indicating the locale for which the keyboard originating the event is configured, e.g. "en-US". The locale MAY be the empty string when inapplicable or unknown, e.g. when this information is not exposed by the underlying platform.

Note: 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 locale will still indicate French. Nor can it be used to definitively calculate the physical or 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).

static DOMString queryLocale()

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.

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.

Getting the current keycap for 'KeyA' 

queryKeyCap('KeyA', queryLocale())