mirror of
https://github.com/wez/wezterm.git
synced 2024-12-28 07:55:03 +03:00
78 lines
3.5 KiB
Markdown
78 lines
3.5 KiB
Markdown
# Keyboard Encoding
|
|
|
|
When input that doesn't match a key assignment is processed, it is encoded into
|
|
a byte stream and sent to the PTY associated with the program that is running
|
|
in the active pane.
|
|
|
|
The default encoding scheme used by wezterm is xterm compatible, but there are
|
|
some configuration options that can modify the encoding.
|
|
|
|
The standard xterm compatible encoding generates events for key presses (but
|
|
not releases) and can represent the set of keys that existed on terminal
|
|
hardware of the 1980's.
|
|
|
|
That scheme has worked well for quite some time, but has some ambiguity due
|
|
to the way that the Control modifier "shifts" the ASCII representation of
|
|
keypresses like `Control-I` to be ASCII Tab, as an example.
|
|
|
|
## xterm `modifyOtherKeys`
|
|
|
|
{{since('20221119-145034-49b9839f')}}
|
|
|
|
When wezterm receives the sequence `CSI >4;Nm`, where `N` is `0`, `1` or `2`,
|
|
the keyboard encoding is changed according to
|
|
[modifyOtherKeys](https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:modifyOtherKeys),
|
|
which causes certain modified keys to be encoded as [described in xterms
|
|
docs](https://invisible-island.net/xterm/modified-keys.html), making it
|
|
possible for applications to distinguish between the modified and unmodified
|
|
key presses.
|
|
|
|
Note that [enable_csi_u_key_encoding](lua/config/enable_csi_u_key_encoding.md)
|
|
and [allow_win32_input_mode](lua/config/allow_win32_input_mode.md) both take
|
|
precedence over this behavior.
|
|
|
|
## CSI-u/fixterms/libtickit
|
|
|
|
[Fix Keyboard Input on Terminals](http://www.leonerd.org.uk/hacks/fixterms/) is
|
|
an attempt at resolving the ambiguous encoding and doing a better job at
|
|
representing more modifiers. It's not a perfect attempt as there are [a number
|
|
of issues with
|
|
it](https://sw.kovidgoyal.net/kitty/keyboard-protocol/#bugs-in-fixterms).
|
|
|
|
You can enable support for this encoding by setting `enable_csi_u_key_encoding
|
|
= true`, however, it is not recommended as it does change the behavior of some
|
|
keys in backwards incompatible ways and there isn't a way for applications to
|
|
detect or request this behavior.
|
|
|
|
See also: [enable_csi_u_key_encoding](lua/config/enable_csi_u_key_encoding.md).
|
|
|
|
Note that [allow_win32_input_mode](lua/config/allow_win32_input_mode.md) takes
|
|
precedence over this option.
|
|
|
|
## Kitty Keyboard Protocol
|
|
|
|
The Kitty terminal extended and enhanced the CSI-u based encoding scheme with
|
|
its [Comprehensive keyboard handling
|
|
protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/).
|
|
|
|
The kitty protocol allows applications to request varying degrees of
|
|
enhancement over the standard encoding scheme and also allows for more modifier
|
|
keys (notably: `CMD`/`Super`/`Windows`) to be reported to the application.
|
|
|
|
[enable_kitty_keyboard](lua/config/enable_kitty_keyboard.md) controls whether
|
|
wezterm will honor the application requests to modify the keyboard encoding.
|
|
|
|
## Windows
|
|
|
|
On Windows, [allow_win32_input_mode](lua/config/allow_win32_input_mode.md)
|
|
defaults to `true` which causes wezterm to listen for an escape sequence
|
|
generated by the ConPTY layer of Windows to enable [Win32 Input Mode](https://github.com/microsoft/terminal/blob/main/doc/specs/%234999%20-%20Improved%20keyboard%20handling%20in%20Conpty.md).
|
|
|
|
In this mode, key release events as well as events that can distinguish between
|
|
positional (left/right) modifier keys are generated and this mode provides the
|
|
best compatibility with win32 console applications such as Far Manager.
|
|
|
|
`allow_win32_input_mode` takes precedence over
|
|
[enable_csi_u_key_encoding](lua/config/enable_csi_u_key_encoding.md).
|
|
|