Keycodes
The Windows keyboard layout is used to translate alphanumeric and symbol key presses into characters, which means that the keyboard layout can be switched using the standard Windows mechanisms for that purpose. AltGr combinations, dead keys, and input method editors (IMEs) are all supported.
Windows support for dead key combinations is limited to ANSI character ranges; mintty extends that to Unicode by supporting combinations like ẃ.
Should the available keyboard layouts lack required features, Microsoft's Keyboard Layout Creator can be used to create custom keyboard layouts.
Mintty also provides a Compose key, configurable to Control, Shift or Alt, using X11 compose data. For a separate compose key solution, the most seamless and stable Compose Key for Windows is WinCompose.
For other keys and key combinations, mintty sends xterm keycodes, with a few minor changes and some additions. Below, Caret notation is used to show control characters.
A number of options are available to customize the keyboard behaviour, including user-defined function and keypad keys and Ctrl+Shift+key shortcuts. See the manual page for options and details.
As is customary with PC keyboards, the Alt key acts as the so-called Meta modifier key. When it is held down while pressing a key or key combination, the keycode is prefixed with an escape character, unless noted otherwise in the keycode tables in the following sections.
Encoding the meta modifier by setting the top bit of a character instead of prefixing it with the escape character is not supported, because that does not work for character codes beyond 7-bit ASCII.
Note that there is some confusion between the Alt and Meta modifier functions as historically Meta was in use first and later implemented by the Alt key of keyboards; however, both are also available separately in X11 and xterm. Mintty provides separate Alt and Meta modifier functions, as well as additional ones (Super and Hyper from X11). See section Modifier key encodings below.
The right Alt key, which is labelled AltGr on most non-US keyboards, allows to type additional characters on many keyboard layouts. When the keyboard layout does not have a keycode for an AltGr combination, the AltGr key is treated as Alt instead.
The CtrlAltIsAltGr setting (Ctrl+LeftAlt is AltGr in the Options dialog)
allows combinations of either Ctrl key with the left Alt key to also be treated as AltGr.
The AltGrIsAlsoAlt setting enables fallback of the AltGr key to the
function of the Alt modifier for those keys that do not have an AltGr
mapping in the keyboard layout.
For key combinations involving Ctrl, the key combination's character code without the Ctrl is looked up in the Windows keyboard layout (whereby AltGr or Shift may be involved). If the resulting character corresponds to a control character, the control character will be sent to the application. For example, Ctrl+] sends ^].
If the keyboard layout does not yield a character from the table below, the key's "virtual keycode" is tried instead, which usually corresponds to the US keyboard layout. This allows control characters to be entered when using a non-Latin keyboard layout.
If Shift is held in addition to a control character combination, the corresponding character from the so-called C1 control character set is sent (unless the resulting combination corresponds to a different control character in the first place). If the control character combination already contained a Shift, the second Shift key needs to be pressed to achieve this.
The C1 control characters are shown as Unicode codepoints in the table below. How exactly C1 control characters are sent depends on the selected character encoding. In ISO-8859 encodings, they are encoded as single bytes, e.g. \x81 for U+0081. With UTF-8, they are encoded as two-byte sequences, which effectively means that the character code is prefixed with a \xC2 byte, so for example U+0081 becomes \xC2\x81. C1 codepoints that are not supported by the selected character encoding are sent by prefixing the corresponding ASCII control character with an ESC character, so U+0081 would be sent as ^[^A.
The Ctrl+Shift combinations are overridden by the CtrlShiftShortcuts setting (Ctrl+Shift+letter shortcuts in Options menu, Keys section).
Note that Ctrl+Shift+letter assignments can also be redefined with option KeyFunctions.
| Char | Ctrl | Ctrl+Shift[+Shift] |
|---|---|---|
| @ | ^@ |
U+0080 |
| a | ^A |
U+0081 |
| b | ^B |
U+0082 |
| ... | ||
| y | ^Y |
U+0099 |
| z | ^Z |
U+009A |
| [ | ^[ |
U+009B |
| \ | ^\ |
U+009C |
| ] | ^] |
U+009D |
| ^ | ^^ |
U+009E |
| _ | ^_ |
U+009F |
| / | ^_ |
U+009F |
| ? | ^? |
The keys here send the usual control characters, but there are a few mintty-specific additions that make combinations with modifier keys available as separate keycodes.
The Ctrl+Tab assignments are overridden by the SwitchShortcuts setting (Switch window in Options menu, Keys section).
The former Ctrl assignments for the Enter key are dropped with mintty 3.2.1.
The special assignments for Escape, Break and Pause are deprecated.
Note that key assignments can also be redefined with option KeyFunctions.
| Key | plain | Shift | Ctrl | Ctrl+Shift |
|---|---|---|---|---|
| Tab | ^I |
^[[Z |
^[[1;5I |
^[[1;6I |
| Space | SP | SP | ^@ |
U+0080 |
| Back (*) | ^? |
^? |
^H |
^H |
| Enter | ^M |
^J |
||
| Escape | ^[ |
U+009B | ||
| Break | ^\ |
U+009C | ||
| Pause | ^] |
U+009D | ||
| Back (**) | ^_ |
|||
| Enter (**) | ^^ |
(*) Note: With setting BackspaceSendsBS=yes, ^? and ^H mappings are reversed.
(**) Note: To restore special key assignments of previous mintty versions, use either of these settings:
OldModifyKeys=33KeyFunctions=C+Back:^_;C+Enter:^^
Pause and Break usually share a key, whereby Ctrl has to be pressed to get the Break function.
See the previous section for how Unicode codepoints such as U+009B are encoded.
Mintty supports up to 6 key modifiers. Where the modifier keys Shift, Alt and Ctrl are not handled as described in the sections above, they are encoded as a number that becomes part of the keycode (escape sequence). The additional Meta modifier is implemented by the Win key and encoded as documented for xterm. Further modifiers Super and Hyper can be configured as user-defined key functions. To obtain the actual number encoding a modifier combination, add the numbers for each pressed modifier to 1:
| Modifier | m |
|---|---|
| Shift | 1 |
| Alt | 2 |
| Ctrl | 4 |
| Meta (Win key) | 8 |
| Super (configurable key) | 16 |
| Hyper (configurable key) | 32 |
For example, Shift+Ctrl would be encoded as the number 6 (1 plus 1 for Shift plus 4 for Ctrl). Modifiers are not double-counted if, for example, both Shift keys are pressed. In the following sections, modifier codes are shown as m.
Super and Hyper modifiers can be configured with option KeyFunctions, e.g.:
KeyFunctions=*CapsLock:super
Number and symbol key combinations that are not handled either by the Windows keyboard layout or by the Ctrl key processing described above, are assigned the keycodes shown here.
| Key | modified | appl keypad modified |
|---|---|---|
| / |
^[[1;mo
|
^[Omo
|
* |
^[[1;mj
|
^[Omj
|
| - |
^[[1;mm
|
^[Omm
|
| + |
^[[1;mk
|
^[Omk
|
| Enter |
^[OmM
|
|
| , |
^[[1;ml
|
|
| VT220 appl keypad modified | ||
| . |
^[[1;mn
|
^[Omn
|
| 0 |
^[[1;mp
|
^[Omp
|
| 1 |
^[[1;mq
|
^[Omq
|
| ... | ||
| 8 |
^[[1;mx
|
^[Omx
|
| 9 |
^[[1;my
|
^[Omy
|
(These are VT220 application keypad codes with added modifier.)
Cursor keycodes without modifier keys depend on whether "application cursor key mode" (controlled by the DECCKM sequence) is enabled. Application cursor mode is ignored if any modifier keys are down, and the modifier code is inserted into the keycode as shown.
By default, the Home and End keys are considered cursor keys. If VT220 keyboard mode is enabled, they are treated as editing keys instead. See the next section for their keycodes in that case.
| Key | plain | app | modified |
|---|---|---|---|
| Up | ^[[A |
^[OA |
^[[1;mA
|
| Down | ^[[B |
^[OB |
^[[1;mB
|
| Left | ^[[D |
^[OD |
^[[1;mD
|
| Right | ^[[C |
^[OC |
^[[1;mC
|
| Home | ^[[H |
^[OH |
^[[1;mH
|
| End | ^[[F |
^[OF |
^[[1;mF
|
There is no special application mode for the keys in the block that's usually above the arrow keys.
| Key | plain | modified |
|---|---|---|
| Ins | ^[[2~ |
^[[2;m~
|
| Del | ^[[3~ |
^[[3;m~
|
| PgUp | ^[[5~ |
^[[5;m~
|
| PgDn | ^[[6~ |
^[[6;m~
|
| Home | ^[[1~ |
^[[1;m~
|
| End | ^[[4~ |
^[[4;m~
|
As mentioned in the cursor keys section, the Home and End keycodes shown here are only used if VT220 keyboard mode is enabled.
F1 through F4 send numpad-style keycodes, because they emulate the four PF keys above the number pad on the VT100 terminal. The remaining function keys send codes that were introduced with the VT220 terminal.
| Key | plain | modified |
|---|---|---|
| F1 | ^[OP |
^[[1;mP
|
| F2 | ^[OQ |
^[[1;mQ
|
| F3 | ^[OR |
^[[1;mR
|
| F4 | ^[OS |
^[[1;mS
|
| F5 | ^[[15~ |
^[[15;m~
|
| F6 | ^[[17~ |
^[[17;m~
|
| F7 | ^[[18~ |
^[[18;m~
|
| F8 | ^[[19~ |
^[[19;m~
|
| F9 | ^[[20~ |
^[[20;m~
|
| F10 | ^[[21~ |
^[[21;m~
|
| F11 | ^[[23~ |
^[[23;m~
|
| F12 | ^[[24~ |
^[[24;m~
|
| F13 | ^[[25~ |
^[[25;m~
|
| F14 | ^[[26~ |
^[[26;m~
|
| F15 | ^[[28~ |
^[[28;m~
|
| F16 | ^[[29~ |
^[[29;m~
|
| F17 | ^[[31~ |
^[[31;m~
|
| F18 | ^[[32~ |
^[[32;m~
|
| F19 | ^[[33~ |
^[[33;m~
|
| F20 | ^[[34~ |
^[[34;m~
|
The numbers in the keycodes really are that irregular. Only twelve function keys are usually available on a PC keyboard, but in VT220 keyboard mode, the Ctrl modifier adds 10 to the function key number, so that for example Ctrl+F3 sends the F13 keycode.
In application scrollbar mode, the following keys or sequences are generated: The relative scrollbar reports can have a second parameter which encodes the modifiers like for other function keys.
| Event | sequence | note |
|---|---|---|
| Page Up | ^[[5#e |
|
| Page Down | ^[[6#e |
|
| Scroll Up | ^[[65#e |
also mouse wheel on scrollbar |
| Scroll Down | ^[[66#e |
also mouse wheel on scrollbar |
| Scroll Here |
^[[pos#d
|
pos between 1 and virtual size |
| Top | ^[[0#d |
|
| Bottom |
^[[size#d
|
configured virtual size |
See the screenshots for an illustration of the meaning of pos vs size values.
The position of the viewport (the marked area of the scrollbar) is
measured at its top. So when setting up position 50 in size 100 (^[[50;100;20#t),
the viewport is not centered but begins in the middle of the scrollbar.
Also, when the viewport is dragged to the bottom, it ends at the total size
but the reported position is its beginning (81 in the example, mouse button
still held). So the maximum position reported after pulling or dragging the
viewport is size − height + 1, but the position reported when placing it
directly to the bottom (from the scrollbar menu) will yet be full size.
(Likewise the minimum position reported when dragging is 1 but the position
reported for placing to the top is 0.)
Note also that after dragging and releasing the mouse button, the viewport position flips back to its previous place until the application interprets the report and sets the position. (This is to prevent looping interference with updated positions triggering additional system events.)
For the sequences to set up application scrollbar mode and change its parameters see Control Sequences – Application scrollbar.
In xterm mouse tracking modes, the mousewheel is treated is a pair of mouse buttons. However, the mousewheel can also be used for scrolling in applications such as less that do not support xterm mouse reporting but that do use the alternate screen. Under those circumstances, mousewheel events are encoded as cursor up/down and page up/down keys. See the sections on the cursor keys and editing keys for details.
The number of line up/down events sent per mousewheel notch depends on the relevant Windows setting on the Wheel tab of the Mouse control panel. Page up/down codes can be sent by holding down Shift while scrolling. The Windows wheel setting can also be set to always scroll by a whole screen at a time.