UI Events

W3C Working Draft 12 June 2014

This version:
Latest published version:
Latest editor's draft:
Previous version:
Gary Kacmarcik, Google, Inc. (Dec 2012 - present)
Travis Leithead, Microsoft Corp. (Dec 2012 - present)


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 edited in place on 23 June 2014 to fix a wrong "Previous Version" link.

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.

This document was published by the Web Applications Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to www-dom@w3.org (subscribe, archives). All comments are welcome.

Publication as a 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.

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

3.1 Interface KeyboardEvent

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

3.1.1 Attributes

locale of type DOMString, readonly

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

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

codeDOMStringThe code for the key, as defined in the [DOM Level 3 KeyboardEvent code Values] spec.

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 1

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 2

Getting the current keycap for 'KeyA'

queryKeyCap('KeyA', queryLocale())

A. References

A.1 Normative references

A. Phillips; M. Davis. Tags for Identifying Languages. September 2009. IETF Best Current Practice. URL: http://tools.ietf.org/html/bcp47
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