Commit 75cf4b0b authored by George Nachman's avatar George Nachman

Respond to comments

parent 6a66338e
......@@ -63,7 +63,7 @@ Client programs can query if the terminal emulator is in *full mode* by using
the standard [DECRQM](https://vt100.net/docs/vt510-rm/DECRQM.html) escape sequence.
Further, this specification reserves the numbers ``2019-2025`` for future
keyboard protocols.
keyboard protocols. 2017 is also reserved for Kitty's proprietary mode.
# Cases
......@@ -73,49 +73,65 @@ emulator.
1. **Reserved** Some keystrokes cause the application or operating system to
take an action. For example, Alt-F4 on Windows closes a window; Command-N on
macOS opens a new window. These keystrokes are never reported.
macOS opens a new window. These keystrokes are never reported. These are
implementation- and platform-defined.
2. **Direct text production** Keystrokes that produce text without an input
2. **Meta keys** Terminal emulators may offer the user the option to forego
the usual text processing (including input method editor) that the platform
uses when a particular user-configured modifier is pressed. When such a
modifier is pressed, go directly to **Modified keypress** and forego the
preceding cases.
3. **Direct text production** Keystrokes that produce text without an input
method editor. For example: 1) pressing a letter key on a US keyboard
without any modifiers; 2) pressing the `ü` key on a German keyboard without
modifiers; 3) pressing option-F on a US keyboard on macOS to produce the
character `ƒ`.; 4) pressing shift+`x` on a US keyboard to produce `X`.
character `ƒ`.; 4) pressing shift+`x` on a US keyboard to produce `X`;
pressing the space bar without modifiers produces a space, which is
considered text. Some keystrokes may produce multiple code points. These
would be considered diret text production as well.
3. **Indirect text production** Keypresses that are handled by an input method
4. **Indirect text production** Keypresses that are handled by an input method
editor and do not necessarily cause text to be output. These key presses
modify the IME's state and may not produce text. For example, pressing the
`w` key in a Hiragana keyboard layout; pressing a dead key, such as Option-e
`w` key in a Hiragana keyboard layout when using an IME that produces Wa
(わ) when `w` and then `a` are pressed; pressing a dead key, such as Option-e
on macOS on a US layout, which may add an acute accent to the character from
the next keypress. A keypress which does produce text due to an input
method editor falls in this category. For example, the two key-down events
of pressing a dead key followed by a base letter count as two *indirect text
the next keypress. A keypress which does produce text due to an input method
editor falls in this category. For example, the two key-down events of
pressing a dead key followed by a base letter count as two *indirect text
production* keystrokes.
4. **Function keys** Function keys have non-textual purposes. For example,
5. **Function keys** Function keys have non-textual purposes. For example,
F1...F12 (and beyond), arrow keys, page up, page down, home, delete,
and end. This list is not meant to be exhaustive. This category includes
function keys with or without modifiers.
5. **Backspace and Enter** When pressed without any modifier, these keys
6. **Backspace and Enter** When pressed without any modifier, these keys
receive special treatment for backward compatibility. When pressed with a
modifier these are treated as function keys.
6. **Modifier keys** Command, Alt, Option, Shift, Control, and so on.
7. **Modifier keys** Command, Alt, Option, Shift, Control, and so on.
These never produce text by themselves, but they may be reported.
7. **Modified keypress** Key presses while modifiers are pressed that are not
8. **Modified keypress** Key presses while modifiers are pressed that are not
direct or indirect text production. For example, Control-C on a US keyboard.
The user may choose to configure modifiers, such as one or both Alt/Option
keys to act as a modifier (rather than having the operating system or input
method editor process it to produce different text) for the purposes of this
protocol. This is an extension of current practice where the Alt key can be
configured to add ESC to a base key.
## Reserved
Reserved keys are handled by the terminal emulator or operating system and are
never reported.
# Meta Keys
In legacy systems, users often configure a modifier to send <ESC> + <character>,
as a way of emulating the even-more-legacy Meta modifier. Terminal emulators may
opt to allow the user to select a modifier to forego the usual text processing
and input method editor of its platform and to report the keypress directly. For
example, on macOS, Option+`B` on a US layout normally produces `∫`. If the user
configures the Option key to act as Meta, the terminal emulator will instead
report a **Modified keypress**.
## Direct Text Production
These keystrokes are sent the same as in *normal mode*. The user's keyboard
......@@ -127,8 +143,9 @@ Client programs not supporting *full mode* will still be able to understand
basic text entry. This makes it possible for the user to exit this mode by
issuing a `reset` command.
Key-up, autorepeat, and key-down events are not distinguishable for these
keypresses.
Only the produced text is sent: key-up is not reported. If the key
auto-repeats (which is platform-defined) that behaves like repeated direct
text production.
## Indirect Text Production
......@@ -174,9 +191,11 @@ sent.
The following control sequence will be sent in the circumstances described above:
```
<ESC>_K<type><modifiers><key><reserved><ESC>\
<ESC>_K<type>;<modifiers;><key>[;<platform-specific-key>[;<reserved>]]<ESC>\
```
Portions enclosed in square brackets are optional.
## Type
Describes the action. Takes one of these values:
......@@ -187,71 +206,90 @@ Describes the action. Takes one of these values:
## Modifiers
For key-down and auto-repeat events, this describes the modifiers that were
pressed during the event.
There are several cases to consider:
### Case 1: Key-Down for a Modifier Key
Gives the set of modifiers that are pressed. For example, if the user holds down
Control and then presses Alt, this field takes the value of Control + Alt.
### Case 2: Key-Up for a Modifier Key
For the key-up event of a non-modifier (e.g., releasing "C" after having
pressed Control-C) this describes the modifiers that remain pressed.
Gives the set of modifiers that are pressed. For example, if the user holds down
Control and and Alt and releases Control, this field takes the value of Alt.
For key-up of a modifier, it describes the modifier that was released. For
example, releasing Control after having pressed Control-C.
### Case 3: Key-Down, Key-Up, and Auto-Repeat of Non-Modifier Keys
Gives the set of modifiers that are pressed. In the following examples, this field
takes the value of `Control`:
1. Reporting the user pressed `C` while `Control` was held down.
2. Reporting auto-repeat because the user held down `C` while `Control` was held
down.
3. Reporting the user released `C` while `Control` was held down.
### Special Modifiers
A special modifier, "numeric keypad", is used to distinguish keys on the
numeric keypad from their doppelgangers not on the numeric keypad (e.g., equals
sign). It does not correspond to a physical modifier key.
### Numlock and Scroll Lock
Terminal emulators may choose to respect numlock state by sending function keys
with the Numeric Keypad modifier set when enabled and sending numbers with the
Numeric Keypad modifier set when disabled.
The Scroll Lock key is not supported.
Modifiers are assigned the following values:
### Values and Encoding
* Shift: 1
* Alt or Option: 2
* Control: 4
* Super: 8
* Numeric Keypad: 16
Modifiers are assigned the following values:
Sum the relevant values. The sum will fall between 0 and 31. Then map them into
a single character, which is what goes in the control sequence. The mapping is:
0-25 map to `A` through `Z`, and 26-31 map to `a` through `f`.
* Left Shift: 1
* Right Shift: 2
* Left Alt or Option: 4
* Right Alt or Option: 8
* Left Control: 16
* Right Control: 32
* Left Super: 64
* Right Super: 128
* Numeric Keypad: 256
For example:
If the terminal emulator cannot distinguish left vs right modifiers, it should
treat them as left.
* `A`: No modifiers
* `F`: Shift and Control
Sum the relevant values. The sum will fall between 0 and 511. Terminal emulators
should encode this number in network byte order (big-endian) and then base-64
encode it. For example, Left Control (16) + Numeric Keypad (256) = 288. In
network byte order, that is [ 0x1, 0x10 ]. The base-64 encoding is "ARA=".
## Key
This may be omitted if the event reported is the change of a modifier.
Gives the value of the key in hex omitting leading 0s and using upper case for
A-F.
For keys that have a corresponding Unicode code point, use its number as the
value.
For function keys, use the lookup table provided in this specification to
determine the value.
For function keys and modifier keys, use the lookup table provided in this
specification to determine the value.
Some keys can produce multiple characters. For example, on a US layout, the `A`
key may produce either `a` or `A` depending on the state of the Shift key.
Report the value that most closely matches the graphic on the physical keycap.
Terminal emulators should report the value ignoring all modifiers.
For example, if the user pressed the `A` key on a US keyboard, the reported
value for the `key` field is "41". Because the keycap shows an upper-case A, 41
is preferred to 61.
If the key would produce multiple code points delimit them with colons. For
example, a key that produces a red heart emoji would take the value `2764:FE0F`.
*Open question*: Are there any keystrokes that require multiple code points to
represent? How should we handle them?
If an application does not recognize a key that falls in the designated function
key range, it should ignore the entire control sequence.
## Reserved
For the purposes of future expansion, the `key` may be followed by a semicolon
and then zero or more alphanumeric ASCII characters. Clients should ignore
these if they are not recognized.
and then any characters prior to the `ST`. Clients should ignore the
unrecognized part.
# Error Handling
......@@ -264,47 +302,53 @@ in the terminfo database, in case querying for it via `DECQRM` is inconvenient.
# Function Key Codes
* BACKSPACE: E000
* CAPS LOCK: E001
* DELETE: E002
* DOWN: E003
* END: E004
* ENTER: E005
* ESCAPE: E006
* F1: E007
* F2: E008
* F3: E009
* F4: E00A
* F5: E00B
* F6: E00C
* F7: E00D
* F8: E00E
* F9: E00F
* F10: E010
* F11: E011
* F12: E012
* F13: E013
* F14: E014
* F15: E015
* F16: E016
* F17: E017
* F18: E018
* F19: E019
* F20: E01A
* F21: E01B
* F22: E01C
* F23: E01D
* F24: E01E
* F25: E01F
* HOME: E020
* INSERT: E021
* LEFT: E022
* PAGE DOWN: E023
* PAGE UP: E024
* PAUSE: E025
* PRINT SCREEN: E026
* RIGHT: E027
* SPACE: E028
* TAB: E029
* UP: E02A
}
The designated range for function key codes is 0xD800 through 0xDFFF. No
keyboard should produce these because they are defined only for UTF-16.
| Key | Code |
|---------------|------|
| BACKSPACE | D800 |
| DELETE | D801 |
| ENTER | D802 |
| ESCAPE | D803 |
| CAPS LOCK | D804 |
| UP | D805 |
| DOWN | D806 |
| LEFT | D807 |
| RIGHT | D808 |
| PAGE DOWN | D809 |
| PAGE UP | D80A |
| HOME | D80B |
| END | D80C |
| INSERT | D80D |
| PAUSE | D80E |
| PRINT SCREEN | D80F |
| F1 | D810 |
| F2 | D811 |
| F3 | D812 |
| F4 | D813 |
| F5 | D814 |
| F6 | D815 |
| F7 | D816 |
| F8 | D817 |
| F9 | D818 |
| F10 | D819 |
| F11 | D81A |
| F12 | D81B |
| F13 | D81C |
| F14 | D81D |
| F15 | D81E |
| F16 | D81F |
| F17 | D820 |
| F18 | D821 |
| F19 | D822 |
| F20 | D823 |
| F21 | D824 |
| F22 | D825 |
| F23 | D826 |
| F24 | D827 |
| F25 | D828 |
| SHIFT | D829 |
| ALT | D82A |
| CONTROL | D82B |
| SUPER | D82C |
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment