UI Events KeyboardEvent key Values

W3C Candidate Recommendation Snapshot,

More details about this document
This version:
https://www.downtownmelody.com/_x/d3d3LnczLm9yZw/TR/2023/CR-uievents-key-20230530/
Latest published version:
https://www.downtownmelody.com/_x/d3d3LnczLm9yZw/TR/uievents-key/
Editor's Draft:
https://www.downtownmelody.com/_x/dzNjLmdpdGh1Yi5pbw/uievents-key/
Previous Versions:
History:
https://www.downtownmelody.com/_x/d3d3LnczLm9yZw/standards/history/uievents-key
Implementation Report:
https://www.downtownmelody.com/_x/dzNjLmdpdGh1Yi5pbw/uievents-key/impl-report.html
Feedback:
GitHub
Editors:
(Google)
(Invited Expert)

Copyright © 2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

Abstract

This specification defines the key attribute values that must be used for KeyboardEvent's key attribute, which is defined as part of the UI Events Specification [UIEvents].

Status of this document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.downtownmelody.com/_x/d3d3LnczLm9yZw/TR/.

This document was published by the Web Applications Working Group as a Candidate Recommendation Snapshot using the Recommendation track.

Publication as a Candidate Recommendation does not imply endorsement by W3C and its Members. A Candidate Recommendation Snapshot has received wide review, is intended to gather implementation experience, and has commitments from Working Group members to royalty-free licensing for implementations.

This Candidate Recommendation is not expected to advance to Proposed Recommendation any earlier than 27 June 2023.

This document was produced by a group operating under the 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.

This document is governed by the 2 November 2021 W3C Process Document.

1. Introduction

This document specifies the set of valid key attribute values that MUST be used in the KeyboardEvent's key attribute to encode the key’s meaning. Note that the key value for a particular key will differ based on the user’s current locale setting. For a value that is based only on the key’s physical location on the keyboard and does not vary based on locale, see code described in [UIEvents-Code].

1.1. Stylistic Conventions

This specification uses the following conventions:

2. Keyboard Event key Attribute Values

A key attribute value is defined as being a DOMString that contains one of the following:

A key attribute value MUST always contain a value that falls into one of these two categories (even if the value is "Unidentified").

It is acceptable for multiple keys on a keyboard to generate the same key attribute value. For example, on an EN-US keyboard layout, the keys on the numeric keypad (e.g., the keypad 1 key) will generate the same key attribute values as their non-keypad counterparts (e.g., the 1 key in the main part of the keyboard). The KeyboardEvent's location attribute can be used to determine if a key originated from the numeric keypad.

2.1. Unicode Values

Almost every Unicode character can be used as a valid key attribute value, but there is a small set of Unicode characters which MUST NOT be used. We introduce the concept of a key string to identify the set of Unicode strings that are appropriate for use as a key attribute value.

A key string is a string containing a 0 or 1 non-control characters ("base" characters) followed by 0 or more combining characters. The string MUST be in Normalized Form C (NFC) as described in [UAX15].

A non-control character is any valid Unicode character except those that are part of the "Other, Control" ("Cc") General Category.

A combining character is any valid Unicode character in the "Mark, Spacing Combining" ("Mc") General Category or with a non-zero Combining Class.

The following are some examples of simple key strings:
With the exception of Tab and Enter (see § 2.1.1 Control Characters), all non-control whitespace Unicode characters are considered to be valid key strings.
The following are some examples of key strings with combining characters:

2.1.1. Control Characters

A small number of characters in the Unicode "Cc" General Category are supported as named key attribute values. These named values are as follows:

2.2. Selecting key Attribute Values

A glyph modifier key is any of the following modifier keys: Shift, CapsLock or AltGr.

2.2.1. select an appropriate key attribute value

To select an appropriate key attribute value to store in a KeyboardEvent's key attribute, run these steps:

  1. Let key be a DOMString initially set to "Unidentified".

  2. If there exists an appropriate named key attribute value for this key event, then

    1. Set key to that named key attribute value.

  3. Else, if the key event generates a valid key string, then

    1. Set key to that key string value.

  4. Else, if the key event has any modifier keys other than glyph modifier keys, then

    1. Set key to the key string that would have been generated by this event if it had been typed with all modifer keys removed except for glyph modifier keys.

  5. Return key as the key attribute value for this key event.

On a standard US keyboard, the key attribute value for the key labeled Q is "q" (or "Q" if the Shift modifier key is also held).

On a standard US keyboard, key attribute value for Control + Q is "q".

On a US keyboard with a right-handed Dvorak key mapping, the key attribute value for the key labeled Q is "5" (or "%" with Shift modifier).

On the same US Dvorak keyboard layout as the previous example, the key attribute value for Control + Q is "5".

On a Bolnagri keyboard layout, the key attribute value for the key labeled Q is a string containing the single Unicode character U+200C (ZWNJ or Zero Width Non-Joining Space).

On a French PC keyboard with a standard French mapping, the ^ key acts as a dead key for the combining circumflex diacritical mark. The key attribute value for this keyboard event is "Dead".

Also on a French keyboard with a standard French mapping, the key attribute value for the é key (which corresponds to the 2 key on a US keyboard) is "é" (U+00E9).

On a Korean PC keyboard with a standard Korean mapping, the primary function of the Ha/En key is to switch between Hangul and English input. There is an entry for this key as a named key attribute value, "HangulMode", so that should be used as the key attribute value.

3. Named key Attribute Values

A named key attribute value is any of the values given in the key attribute value column of any of the tables in this section of the specification.

The named key attribute values defined here are based in part on the sets of keycodes from the java.awt.event.KeyEvent interface of the Java Platform, Standard Edition 6 API Specification [KeyEventJava], and the System.Windows.Forms.Keys key enumeration of the Microsoft .NET Framework 4.0 Class Library [KeysNet]. Additional information in this spec comes from Microsoft’s WM_APPCOMMAND messages [WmAppCommand], and other more specialized specifications as noted in this document.

A conforming implementation of the KeyboardEvent interface MUST support this set of values for use in the key attributes, although not all values may be available on all platforms or devices.

Future versions of this specification may include key values not included here, which have become common since the publication of this specification.

Note: While every attempt has been made to make this list of values as complete as possible, new values will periodically need to be defined as new input devices are introduced. Rather than allowing user agents to define their own named key attribute values (which are unlikely to be consistent across multiple user agents), bugs SHOULD be filed so that this specification can be updated.

3.1. Special Keys

Implementations that are unable to identify a key MUST use "Unidentified" as the the key attribute value.

key attribute value Required Typical Usage (Non-normative)
"Unidentified" Yes This key value is used when an implementation is unable to identify another key value, due to either hardware, platform, or software constraints.

Conforming implementations MUST only use