mirror of
https://github.com/wez/wezterm.git
synced 2024-11-22 22:42:48 +03:00
docs: add info about key tables. break key binding apart
The keys section was way too big; this splits it up into more manageable pieces, adds a nice flow chart to show how key events are processed and adds an example of using the new key tables feature.
This commit is contained in:
Wez Furlong
parent
53cae843c8
commit
327984d1d1
@ -134,7 +134,10 @@ TOC = [
|
||||
Page("Launching Programs", "config/launch.md"),
|
||||
Page("Fonts", "config/fonts.md"),
|
||||
Page("Font Shaping", "config/font-shaping.md"),
|
||||
Page("Keyboard Concepts", "config/keyboard-concepts.md"),
|
||||
Page("Key Binding", "config/keys.md"),
|
||||
Page("Key Tables", "config/key-tables.md"),
|
||||
Page("Default Key Assignments", "config/default-keys.md"),
|
||||
Page("Mouse Binding", "config/mouse.md"),
|
||||
Page("Colors & Appearance", "config/appearance.md"),
|
||||
GenColorScheme("Color Schemes", "colorschemes"),
|
||||
|
||||
@ -12,6 +12,7 @@ usually the best available version.
|
||||
As features stabilize some brief notes about them will accumulate here.
|
||||
|
||||
#### New
|
||||
* [Key Tables](config/key-tables.md) feature for powerful modal key assignments
|
||||
#### Changed
|
||||
* Default key assignments are `mapped:` again. A new [key_map_preference](config/lua/config/key_map_preference.md) option allows the defaults to use `"Mapped"` or `"Physical"`.
|
||||
* Disabled ligatures for `"Monaco"` and `"Menlo"` fonts, as those ligatures match even for words such as `find`. [#1786](https://github.com/wez/wezterm/issues/1786) [#1736](https://github.com/wez/wezterm/issues/1736)
|
||||
|
||||
89
docs/config/default-keys.md
Normal file
89
docs/config/default-keys.md
Normal file
@ -0,0 +1,89 @@
|
||||
## Default Shortcut / Key Binding Assignments
|
||||
|
||||
The default key assignments are:
|
||||
|
||||
| Modifiers | Key | Action |
|
||||
| --------- | --- | ------ |
|
||||
| `SUPER` | `c` | `CopyTo="Clipboard"` |
|
||||
| `SUPER` | `v` | `PasteFrom="Clipboard"` |
|
||||
| `CTRL+SHIFT` | `c` | `CopyTo="Clipboard"` |
|
||||
| `CTRL+SHIFT` | `v` | `PasteFrom="Clipboard"` |
|
||||
| | `Copy` | `CopyTo="Clipboard"` |
|
||||
| | `Paste` | `PasteFrom="Clipboard"` |
|
||||
| `CTRL` | `Insert` | `CopyTo="PrimarySelection"` (*since: 20210203-095643-70a364eb*) |
|
||||
| `SHIFT` | `Insert` | `PasteFrom="PrimarySelection"` |
|
||||
| `SUPER` | `m` | `Hide` |
|
||||
| `SUPER` | `n` | `SpawnWindow` |
|
||||
| `CTRL+SHIFT` | `n` | `SpawnWindow` |
|
||||
| `ALT` | `Enter` | `ToggleFullScreen` |
|
||||
| `SUPER` | `-` | `DecreaseFontSize` |
|
||||
| `CTRL` | `-` | `DecreaseFontSize` |
|
||||
| `SUPER` | `=` | `IncreaseFontSize` |
|
||||
| `CTRL` | `=` | `IncreaseFontSize` |
|
||||
| `SUPER` | `0` | `ResetFontSize` |
|
||||
| `CTRL` | `0` | `ResetFontSize` |
|
||||
| `SUPER` | `t` | `SpawnTab="CurrentPaneDomain"` |
|
||||
| `CTRL+SHIFT` | `t` | `SpawnTab="CurrentPaneDomain"` |
|
||||
| `SUPER+SHIFT` | `T` | `SpawnTab="DefaultDomain"` |
|
||||
| `SUPER` | `w` | `CloseCurrentTab{confirm=true}` |
|
||||
| `SUPER` | `1` | `ActivateTab=0` |
|
||||
| `SUPER` | `2` | `ActivateTab=1` |
|
||||
| `SUPER` | `3` | `ActivateTab=2` |
|
||||
| `SUPER` | `4` | `ActivateTab=3` |
|
||||
| `SUPER` | `5` | `ActivateTab=4` |
|
||||
| `SUPER` | `6` | `ActivateTab=5` |
|
||||
| `SUPER` | `7` | `ActivateTab=6` |
|
||||
| `SUPER` | `8` | `ActivateTab=7` |
|
||||
| `SUPER` | `9` | `ActivateTab=-1` |
|
||||
| `CTRL+SHIFT` | `w` | `CloseCurrentTab{confirm=true}` |
|
||||
| `CTRL+SHIFT` | `1` | `ActivateTab=0` |
|
||||
| `CTRL+SHIFT` | `2` | `ActivateTab=1` |
|
||||
| `CTRL+SHIFT` | `3` | `ActivateTab=2` |
|
||||
| `CTRL+SHIFT` | `4` | `ActivateTab=3` |
|
||||
| `CTRL+SHIFT` | `5` | `ActivateTab=4` |
|
||||
| `CTRL+SHIFT` | `6` | `ActivateTab=5` |
|
||||
| `CTRL+SHIFT` | `7` | `ActivateTab=6` |
|
||||
| `CTRL+SHIFT` | `8` | `ActivateTab=7` |
|
||||
| `CTRL+SHIFT` | `9` | `ActivateTab=-1` |
|
||||
| `SUPER+SHIFT` | `[` | `ActivateTabRelative=-1` |
|
||||
| `CTRL+SHIFT` | `Tab` | `ActivateTabRelative=-1` |
|
||||
| `CTRL` | `PageUp` | `ActivateTabRelative=-1` |
|
||||
| `SUPER+SHIFT` | `]` | `ActivateTabRelative=1` |
|
||||
| `CTRL` | `Tab` | `ActivateTabRelative=1` |
|
||||
| `CTRL` | `PageDown` | `ActivateTabRelative=1` |
|
||||
| `CTRL+SHIFT` | `PageUp` | `MoveTabRelative=-1` |
|
||||
| `CTRL+SHIFT` | `PageDown` | `MoveTabRelative=1` |
|
||||
| `SHIFT` | `PageUp` | `ScrollByPage=-1` |
|
||||
| `SHIFT` | `PageDown` | `ScrollByPage=1` |
|
||||
| `SUPER` | `r` | `ReloadConfiguration` |
|
||||
| `CTRL+SHIFT` | `R` | `ReloadConfiguration` |
|
||||
| `SUPER` | `h` | `HideApplication` (macOS only) |
|
||||
| `SUPER` | `k` | `ClearScrollback="ScrollbackOnly"` |
|
||||
| `CTRL+SHIFT` | `K` | `ClearScrollback="ScrollbackOnly"` |
|
||||
| `CTRL+SHIFT` | `L` | `ShowDebugOverlay` (*Since: 20210814-124438-54e29167*)|
|
||||
| `SUPER` | `f` | `Search={CaseSensitiveString=""}` |
|
||||
| `CTRL+SHIFT` | `F` | `Search={CaseSensitiveString=""}` |
|
||||
| `CTRL+SHIFT` | `X` | `ActivateCopyMode` |
|
||||
| `CTRL+SHIFT` | ` ` (`Space`) | `QuickSelect` (*since: 20210502-130208-bff6815d*) |
|
||||
| `CTRL+SHIFT+ALT` | `"` | `SplitVertical={domain="CurrentPaneDomain"}` |
|
||||
| `CTRL+SHIFT+ALT` | `%` | `SplitHorizontal={domain="CurrentPaneDomain"}` |
|
||||
| `CTRL+SHIFT+ALT` | `LeftArrow` | `AdjustPaneSize={"Left", 1}` |
|
||||
| `CTRL+SHIFT+ALT` | `RightArrow` | `AdjustPaneSize={"Right", 1}` |
|
||||
| `CTRL+SHIFT+ALT` | `UpArrow` | `AdjustPaneSize={"Up", 1}` |
|
||||
| `CTRL+SHIFT+ALT` | `DownArrow` | `AdjustPaneSize={"Down", 1}` |
|
||||
| `CTRL+SHIFT` | `LeftArrow` | `ActivatePaneDirection="Left"` |
|
||||
| `CTRL+SHIFT` | `RightArrow` | `ActivatePaneDirection="Right"` |
|
||||
| `CTRL+SHIFT` | `UpArrow` | `ActivatePaneDirection="Up"` |
|
||||
| `CTRL+SHIFT` | `DownArrow` | `ActivatePaneDirection="Down"` |
|
||||
| `CTRL+SHIFT` | `Z` | `TogglePaneZoomState` |
|
||||
|
||||
If you don't want the default assignments to be registered, you can
|
||||
disable all of them with this configuration; if you chose to do this,
|
||||
you must explicitly register every binding.
|
||||
|
||||
```lua
|
||||
return {
|
||||
disable_default_key_bindings = true,
|
||||
}
|
||||
```
|
||||
|
||||
123
docs/config/key-tables.md
Normal file
123
docs/config/key-tables.md
Normal file
@ -0,0 +1,123 @@
|
||||
## Key Tables
|
||||
|
||||
*Since: nightly builds only*
|
||||
|
||||
In addition to the default key table defined by the `keys` configuration
|
||||
option, `wezterm` supports defining additional named key tables using the
|
||||
`key_tables` configuration option.
|
||||
|
||||
On its own, a named table doesn't do anything, but when paired with the
|
||||
`ActivateKeyTable` action, some powerful keyboard customization is possible.
|
||||
|
||||
As a motivating example, let's consider working with panes. In the default
|
||||
config `CTRL+SHIFT+ArrowKey` will activate a pane in the direction of the arrow
|
||||
key, while `CTRL+SHIFT+ALT+ArrowKey` will resize a pane in the direction of the
|
||||
arrow key. Our goal is to avoid holding down so many keys at once, or even
|
||||
having to remember so many key combinations, so what we'd like to do is use
|
||||
`CTRL-SHIFT-SPACE` as a leader prefix to select between resize and activation
|
||||
modes, using `r` for resize and `a` for activation:
|
||||
|
||||
```lua
|
||||
local wezterm = require 'wezterm';
|
||||
|
||||
-- Show which key table is active in the status area
|
||||
wezterm.on("update-right-status", function(window, pane)
|
||||
local name = window:active_key_table()
|
||||
if name then
|
||||
name = "TABLE: " .. name
|
||||
end
|
||||
window:set_right_status(name or "")
|
||||
end);
|
||||
|
||||
return {
|
||||
leader = {key="Space", mods="CTRL|SHIFT"},
|
||||
keys = {
|
||||
-- CTRL|SHIFT+Space, followed by 'r' will put us in resize-pane
|
||||
-- mode until we cancel that mode.
|
||||
{key="r", mods="LEADER", action=wezterm.action{
|
||||
ActivateKeyTable={
|
||||
name="resize_pane",
|
||||
one_shot=false,
|
||||
}
|
||||
},
|
||||
|
||||
-- CTRL|SHIFT+Space, followed by 'a' will put us in activate-pane
|
||||
-- mode until we press some other key or until 1 second (1000ms)
|
||||
-- of time elapses
|
||||
{key="a", mods="LEADER", action=wezterm.action{
|
||||
ActivateKeyTable={
|
||||
name="activate_pane"
|
||||
timeout_milliseconds=1000,
|
||||
}
|
||||
},
|
||||
},
|
||||
|
||||
key_tables = {
|
||||
-- Defines the keys that are active in our resize-pane mode.
|
||||
-- Since we're likely to want to make multiple adjustments,
|
||||
-- we made the activation one_shot=false. We therefore need
|
||||
-- to define a key assignment for getting out of this mode.
|
||||
-- 'resize_pane' here corresponds to the name="resize_pane" in
|
||||
-- the key assignments above.
|
||||
resize_pane = {
|
||||
{key="LeftArrow", action=wezterm.action{AdjustPaneSize={"Left", 1}}},
|
||||
{key="h", action=wezterm.action{AdjustPaneSize={"Left", 1}}},
|
||||
|
||||
{key="RightArrow", action=wezterm.action{AdjustPaneSize={"Right", 1}}},
|
||||
{key="l", action=wezterm.action{AdjustPaneSize={"Right", 1}}},
|
||||
|
||||
{key="UpArrow", action=wezterm.action{AdjustPaneSize={"Up", 1}}},
|
||||
{key="k", action=wezterm.action{AdjustPaneSize={"Up", 1}}},
|
||||
|
||||
{key="DownArrow", action=wezterm.action{AdjustPaneSize={"Down", 1}}},
|
||||
{key="j", action=wezterm.action{AdjustPaneSize={"Down", 1}}},
|
||||
|
||||
-- Cancel the mode by pressing escape
|
||||
{key="Escape", action="PopKeyTable"},
|
||||
|
||||
},
|
||||
|
||||
-- Defines the keys that are active in our activate-pane mode.
|
||||
-- 'activate_pane' here corresponds to the name="activate_pane" in
|
||||
-- the key assignments above.
|
||||
activate_pane = {
|
||||
{key="LeftArrow", action=wezterm.action{ActivatePaneDirection="Left"}},
|
||||
{key="h", action=wezterm.action{ActivatePaneDirection="Left"}},
|
||||
|
||||
{key="RightArrow", action=wezterm.action{ActivatePaneDirection="Right"}},
|
||||
{key="l", action=wezterm.action{ActivatePaneDirection="Right"}},
|
||||
|
||||
{key="UpArrow", action=wezterm.action{ActivatePaneDirection="Up"}},
|
||||
{key="k", action=wezterm.action{ActivatePaneDirection="Up"}},
|
||||
|
||||
{key="DownArrow", action=wezterm.action{ActivatePaneDirection="Down"}},
|
||||
{key="j", action=wezterm.action{ActivatePaneDirection="Down"}},
|
||||
},
|
||||
|
||||
},
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Key Table Activation Stack
|
||||
|
||||
Each `wezterm` GUI window maintains a stack of activations, which allows you to
|
||||
create complex layering of keyboard customization.
|
||||
|
||||
The [ActivateKeyTable](lua/keyassignment/ActivateKeyTable.md) action will push
|
||||
an entry to the stack, and provides `one_shot` and `timeout_milliseconds`
|
||||
fields to affect when/how it will pop itself from the stack, and
|
||||
`replace_current` to implicitly pop the current entry from the stack.
|
||||
|
||||
The [PopKeyTable](lua/keyassignment/PopKeyTable.md) action will explicitly pop
|
||||
an entry from the stack.
|
||||
|
||||
The [ClearKeyTableStack](lua/keyassignment/ClearKeyTableStack.md) action will
|
||||
clear the entire stack.
|
||||
|
||||
The stack is also cleared when the configuration is reloaded, so if you're
|
||||
working on a complex key table setup and get stuck, you may be able to unstick
|
||||
yourself by re-saving your wezterm configuration to trigger a reload.
|
||||
|
||||
|
||||
|
||||
176
docs/config/keyboard-concepts.md
Normal file
176
docs/config/keyboard-concepts.md
Normal file
@ -0,0 +1,176 @@
|
||||
## Keyboard Concepts
|
||||
|
||||
`wezterm` allows assigning action(s) to specific key events, and comes
|
||||
pre-configured with a number of commonly useful assignments.
|
||||
|
||||
This page describes how key presses are handled and turned into actions
|
||||
or sent to the terminal as text.
|
||||
|
||||
It's important to understand these concepts when considering keyboard input;
|
||||
first, some operating system concepts:
|
||||
|
||||
* *Input Method Editor* (IME) - An OS-provided service which allows
|
||||
for rich composition of input, often with a pop-over candidate
|
||||
selection window. This is commonly used for Asian input, but on
|
||||
some systems the IME may also be responsible for emoji input or
|
||||
dead keys. The IME may have multiple modes per language and those
|
||||
modes can be changed dynamically.
|
||||
* *Keyboard Layout* - An OS configuration that describes how to translate
|
||||
physical key button presses into inputs appropriate to the user's
|
||||
preferred input locale. The mapping performed by the layout is
|
||||
largely opaque to applications and, on most systems, can be changed
|
||||
dynamically.
|
||||
* *Dead Key* - a keyboard layout may define these modal keys
|
||||
which don't immediately produce output (and thus appears to be "dead"),
|
||||
but instead holds some state that will compose with a subsequently
|
||||
pressed key. Most commonly used for example in European layouts to
|
||||
produce accented versions of the plain latin alphabet.
|
||||
* *Physical Key* - a way to identify a key based on its hardware-dependent location. `wezterm` can refer to keys based on code they would emit if configured to use an ANSI US English keyboard layout (even if that layout is not currently active), or based on its raw scan code.
|
||||
* *Mapped key* - a way to identify a key after the keyboard layout has been applied by the OS.
|
||||
* *Modifier* - A key such as `SHIFT`, `CTRL`, `CMD`, `ALT` that can be held simultaneously while other keys are pressed. Modifier keys are special because keyboard hardware traditionally only supports those four modifiers, and that detail is ingrained into most OS input APIs.
|
||||
|
||||
And then some wezterm concepts:
|
||||
|
||||
* *Key Assignment* - an action assigned to a matching key and modifier combination.
|
||||
* *Key Table* - a grouping of key assignments. For each window, `wezterm` maintains a stack of table activations, allowing for rich modal keyboard input customization
|
||||
|
||||
|
||||
## Keyboard Processing Flow
|
||||
|
||||
This schematic depicts the processing flow for keyboard events in `wezterm`:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[OS Generates a Key Event]
|
||||
A --> B{{Is IME enabled?}}
|
||||
B -->|Yes| C[Deliver event to IME] --> C1{{IME Response}}
|
||||
B -->|No| F
|
||||
C1 -->|Composed| D[Make RawKeyEvent from<br/> Composed text] --> RAW1
|
||||
C1 -->|Composing| E[Render composing status]
|
||||
C1 -->|Continue| F[Make RawKeyEvent] --> RAW1
|
||||
RAW3 -->|No| DEAD1{{Does RawKeyEvent complete a dead-key?}}
|
||||
DEAD1 -->|Yes| I[Make KeyEvent from<br/>expanded dead key] --> KEY1
|
||||
DEAD1 -->|No| DEAD2{{Does RawKeyEvent start a dead-key?}}
|
||||
DEAD2 -->|Yes| DEADCOMP[Render composing status]
|
||||
DEAD2 -->|No| J[Make KeyEvent from RawKeyEvent] --> KEY1
|
||||
KEY3 -->|No| M[Send key to terminal]
|
||||
|
||||
RAW1{{match a phys: mapping?}}
|
||||
RAW1 -->|Yes| RAWDONE[Perform assignment action]
|
||||
RAW1 -->|No| RAW2{{match a raw: mapping?}}
|
||||
RAW2 -->|Yes| RAWDONE
|
||||
RAW2 -->|No| RAW3{{match a mapped: mapping?}}
|
||||
RAW3 -->|Yes| RAWDONE2[Perform assignment action]
|
||||
|
||||
KEY1{{match a phys: mapping?}}
|
||||
KEY1 -->|Yes| KEYDONE[Perform assignment action]
|
||||
KEY1 -->|No| KEY2{{match a raw: mapping?}}
|
||||
KEY2 -->|Yes| KEYDONE
|
||||
KEY2 -->|No| KEY3{{match a mapped: mapping?}}
|
||||
KEY3 -->|Yes| KEYDONE2[Perform assignment action]
|
||||
|
||||
```
|
||||
|
||||
## Alt / Option Key Behavior & Composed Keys
|
||||
|
||||
The operating system has its own user selectable keymap that is sometimes at
|
||||
odds with old-school terminal emulation that pre-dates internationalization as
|
||||
a concept. WezTerm tries to behave reasonably by default, but also give you
|
||||
control in other situations.
|
||||
|
||||
### Layouts with an AltGr key
|
||||
|
||||
If you have, for example, a European keyboard layout with an AltGr key then
|
||||
wezterm will respect the composition effects of AltGr produced by the system.
|
||||
For example, in a German keymap, `AltGr <` will produce `|`.
|
||||
|
||||
If your physical keyboard doesn't match the keyboard layout (eg: using a US
|
||||
keyboard with DEU selected in the OS), then the right hand `Alt` key is often
|
||||
re-interpreted as having the `AltGr` function with behavior as described above.
|
||||
|
||||
The left `Alt` will be treated as a modifier with no composition effects.
|
||||
|
||||
### Microsoft Windows and Ctrl-Alt <-> AltGr
|
||||
|
||||
If you are using VNC and a keyboard layout with dead keys, then you may wish to
|
||||
enable
|
||||
[treat_left_ctrlalt_as_altgr](lua/config/treat_left_ctrlalt_as_altgr.md).
|
||||
|
||||
### macOS Left and Right Option Key
|
||||
|
||||
*since: 20200620-160318-e00b076c*
|
||||
|
||||
The default behavior is to treat the left `Option` key as the `Alt` modifier
|
||||
with no composition effects, while the right `Option` key performs composition
|
||||
(making it approximately equivalent to `AltGr` on other operating systems).
|
||||
|
||||
You can control this behavior in your configuration:
|
||||
|
||||
```lua
|
||||
return {
|
||||
send_composed_key_when_left_alt_is_pressed=false,
|
||||
send_composed_key_when_right_alt_is_pressed=true,
|
||||
}
|
||||
```
|
||||
|
||||
If you're running an earlier release the options were a bit more limited;
|
||||
both left and right `Option` keys behave identically and composition
|
||||
behavior was influenced for both of them via the `send_composed_key_when_alt_is_pressed`
|
||||
configuration option.
|
||||
|
||||
*since: 20210203-095643-70a364eb*
|
||||
|
||||
WezTerm is now able to perform dead-key expansion when `use_ime = false`. Dead
|
||||
keys are treated as composition effects, so with the default settings of
|
||||
`send_composed_key_when_left_alt_is_pressed` and
|
||||
`send_composed_key_when_right_alt_is_pressed` above, in a US layout, `Left-Opt
|
||||
n` will produce `Alt N` and `Right-Opt n` will will for a subsequent key press
|
||||
before generating an event; `Right-Opt n SPACE` will emit `~` whereas `Right-Opt n
|
||||
n` will emit `ñ`.
|
||||
|
||||
You may also set `use_dead_keys = false` to skip the hold state; continuing
|
||||
the example above, `Right-Opt n` will then immediately produce `~`.
|
||||
|
||||
### Input Method Editor (IME)
|
||||
|
||||
WezTerm has support for using the operating system Input Method Editor (IME) on
|
||||
some operating systems.
|
||||
|
||||
[The `use_ime` docs have more information](lua/config/use_ime.md).
|
||||
|
||||
### Dead Keys
|
||||
|
||||
*since: 20201031-154415-9614e117*
|
||||
|
||||
By default, if you are using a layout with *dead keys* (eg: US International
|
||||
layout, or a number of European layouts such as German or French) pressing
|
||||
a dead key in wezterm will "hold" the dead key until the next character is
|
||||
pressed, resulting in a combined character with a diacritic. For example,
|
||||
pressing `^` and then `e` will produce `ê`. Pressing `^` then `SPACE`
|
||||
will produce `^` on its own.
|
||||
|
||||
If you are a heavy user of Vi style editors then you may wish to disable
|
||||
dead key processing so that `^` can be used with a single keypress.
|
||||
|
||||
You can tell WezTerm to disable dead keys by setting this in your configuration
|
||||
file:
|
||||
|
||||
```lua
|
||||
return {
|
||||
use_dead_keys = false
|
||||
}
|
||||
```
|
||||
|
||||
Note that for X11 systems with `use_ime=true`, depending on the configured IME,
|
||||
the IME may handle dead key processing implicitly. There is no way for
|
||||
`wezterm` to prevent it from doing that, short of disabling the IME.
|
||||
|
||||
### Defining Assignments for key combinations that may be composed
|
||||
|
||||
When a key combination produces a composed key result, wezterm will look up
|
||||
both the composed and uncomposed versions of the keypress in your key mappings.
|
||||
If either lookup matches your assignment, that will take precedence over
|
||||
the normal key processing.
|
||||
|
||||
|
||||
|
||||
@ -1,198 +1,8 @@
|
||||
Keyboard bindings are configurable.
|
||||
|
||||
The assignments are based around a triggering keypress which may be combined
|
||||
with a set of modifier keys to produce an action.
|
||||
|
||||
## Alt / Option Key Behavior & Composed Keys
|
||||
|
||||
The operating system has its own user selectable keymap that is sometimes at
|
||||
odds with old-school terminal emulation that pre-dates internationalization as
|
||||
a concept. WezTerm tries to behave reasonably by default, but also give you
|
||||
control in other situations.
|
||||
|
||||
### Layouts with an AltGr key
|
||||
|
||||
If you have, for example, a European keyboard layout with an AltGr key then
|
||||
wezterm will respect the composition effects of AltGr produced by the system.
|
||||
For example, in a German keymap, `AltGr <` will produce `|`.
|
||||
|
||||
If your physical keyboard doesn't match the keyboard layout (eg: using a US
|
||||
keyboard with DEU selected in the OS), then the right hand `Alt` key is often
|
||||
re-interpreted as having the `AltGr` function with behavior as described above.
|
||||
|
||||
The left `Alt` will be treated as a modifier with no composition effects.
|
||||
|
||||
### macOS Left and Right Option Key
|
||||
|
||||
*since: 20200620-160318-e00b076c*
|
||||
|
||||
The default behavior is to treat the left `Option` key as the `Alt` modifier
|
||||
with no composition effects, while the right `Option` key performs composition
|
||||
(making it approximately equivalent to `AltGr` on other operating systems).
|
||||
|
||||
You can control this behavior in your configuration:
|
||||
|
||||
```lua
|
||||
return {
|
||||
send_composed_key_when_left_alt_is_pressed=false,
|
||||
send_composed_key_when_right_alt_is_pressed=true,
|
||||
}
|
||||
```
|
||||
|
||||
If you're running an earlier release the options were a bit more limited;
|
||||
both left and right `Option` keys behave identically and composition
|
||||
behavior was influenced for both of them via the `send_composed_key_when_alt_is_pressed`
|
||||
configuration option.
|
||||
|
||||
*since: 20210203-095643-70a364eb*
|
||||
|
||||
WezTerm is now able to perform dead-key expansion when `use_ime = false`. Dead
|
||||
keys are treated as composition effects, so with the default settings of
|
||||
`send_composed_key_when_left_alt_is_pressed` and
|
||||
`send_composed_key_when_right_alt_is_pressed` above, in a US layout, `Left-Opt
|
||||
n` will produce `Alt N` and `Right-Opt n` will will for a subsequent key press
|
||||
before generating an event; `Right-Opt n SPACE` will emit `~` whereas `Right-Opt n
|
||||
n` will emit `ñ`.
|
||||
|
||||
You may also set `use_dead_keys = false` to skip the hold state; continuing
|
||||
the example above, `Right-Opt n` will then immediately produce `~`.
|
||||
|
||||
### Input Method Editor (IME)
|
||||
|
||||
WezTerm has support for using the operating system Input Method Editor (IME) on
|
||||
some operating systems.
|
||||
|
||||
[The `use_ime` docs have more information](lua/config/use_ime.md).
|
||||
|
||||
### Microsoft Windows and Dead Keys
|
||||
|
||||
*since: 20201031-154415-9614e117*
|
||||
|
||||
By default, if you are using a layout with *dead keys* (eg: US International
|
||||
layout, or a number of European layouts such as German or French) pressing
|
||||
a dead key in wezterm will "hold" the dead key until the next character is
|
||||
pressed, resulting in a combined character with a diacritic. For example,
|
||||
pressing `^` and then `e` will produce `ê`. Pressing `^` then `SPACE`
|
||||
will produce `^` on its own.
|
||||
|
||||
If you are a heavy user of Vi style editors then you may wish to disable
|
||||
dead key processing so that `^` can be used with a single keypress.
|
||||
|
||||
You can tell WezTerm to disable dead keys by setting this in your configuration
|
||||
file:
|
||||
|
||||
```lua
|
||||
return {
|
||||
use_dead_keys = false
|
||||
}
|
||||
```
|
||||
|
||||
### Microsoft Windows and Ctrl-Alt <-> AltGr
|
||||
|
||||
If you are using VNC and a keyboard layout with dead keys, then you may wish to enable [treat_left_ctrlalt_as_altgr](lua/config/treat_left_ctrlalt_as_altgr.md).
|
||||
|
||||
|
||||
### Defining Assignments for key combinations that may be composed
|
||||
|
||||
When a key combination produces a composed key result, wezterm will look up
|
||||
both the composed and uncomposed versions of the keypress in your key mappings.
|
||||
If either lookup matches your assignment, that will take precedence over
|
||||
the normal key processing.
|
||||
|
||||
## Default Shortcut / Key Binding Assignments
|
||||
|
||||
The default key bindings are:
|
||||
|
||||
| Modifiers | Key | Action |
|
||||
| --------- | --- | ------ |
|
||||
| `SUPER` | `c` | `CopyTo="Clipboard"` |
|
||||
| `SUPER` | `v` | `PasteFrom="Clipboard"` |
|
||||
| `CTRL+SHIFT` | `c` | `CopyTo="Clipboard"` |
|
||||
| `CTRL+SHIFT` | `v` | `PasteFrom="Clipboard"` |
|
||||
| | `Copy` | `CopyTo="Clipboard"` |
|
||||
| | `Paste` | `PasteFrom="Clipboard"` |
|
||||
| `CTRL` | `Insert` | `CopyTo="PrimarySelection"` (*since: 20210203-095643-70a364eb*) |
|
||||
| `SHIFT` | `Insert` | `PasteFrom="PrimarySelection"` |
|
||||
| `SUPER` | `m` | `Hide` |
|
||||
| `SUPER` | `n` | `SpawnWindow` |
|
||||
| `CTRL+SHIFT` | `n` | `SpawnWindow` |
|
||||
| `ALT` | `Enter` | `ToggleFullScreen` |
|
||||
| `SUPER` | `-` | `DecreaseFontSize` |
|
||||
| `CTRL` | `-` | `DecreaseFontSize` |
|
||||
| `SUPER` | `=` | `IncreaseFontSize` |
|
||||
| `CTRL` | `=` | `IncreaseFontSize` |
|
||||
| `SUPER` | `0` | `ResetFontSize` |
|
||||
| `CTRL` | `0` | `ResetFontSize` |
|
||||
| `SUPER` | `t` | `SpawnTab="CurrentPaneDomain"` |
|
||||
| `CTRL+SHIFT` | `t` | `SpawnTab="CurrentPaneDomain"` |
|
||||
| `SUPER+SHIFT` | `T` | `SpawnTab="DefaultDomain"` |
|
||||
| `SUPER` | `w` | `CloseCurrentTab{confirm=true}` |
|
||||
| `SUPER` | `1` | `ActivateTab=0` |
|
||||
| `SUPER` | `2` | `ActivateTab=1` |
|
||||
| `SUPER` | `3` | `ActivateTab=2` |
|
||||
| `SUPER` | `4` | `ActivateTab=3` |
|
||||
| `SUPER` | `5` | `ActivateTab=4` |
|
||||
| `SUPER` | `6` | `ActivateTab=5` |
|
||||
| `SUPER` | `7` | `ActivateTab=6` |
|
||||
| `SUPER` | `8` | `ActivateTab=7` |
|
||||
| `SUPER` | `9` | `ActivateTab=-1` |
|
||||
| `CTRL+SHIFT` | `w` | `CloseCurrentTab{confirm=true}` |
|
||||
| `CTRL+SHIFT` | `1` | `ActivateTab=0` |
|
||||
| `CTRL+SHIFT` | `2` | `ActivateTab=1` |
|
||||
| `CTRL+SHIFT` | `3` | `ActivateTab=2` |
|
||||
| `CTRL+SHIFT` | `4` | `ActivateTab=3` |
|
||||
| `CTRL+SHIFT` | `5` | `ActivateTab=4` |
|
||||
| `CTRL+SHIFT` | `6` | `ActivateTab=5` |
|
||||
| `CTRL+SHIFT` | `7` | `ActivateTab=6` |
|
||||
| `CTRL+SHIFT` | `8` | `ActivateTab=7` |
|
||||
| `CTRL+SHIFT` | `9` | `ActivateTab=-1` |
|
||||
| `SUPER+SHIFT` | `[` | `ActivateTabRelative=-1` |
|
||||
| `CTRL+SHIFT` | `Tab` | `ActivateTabRelative=-1` |
|
||||
| `CTRL` | `PageUp` | `ActivateTabRelative=-1` |
|
||||
| `SUPER+SHIFT` | `]` | `ActivateTabRelative=1` |
|
||||
| `CTRL` | `Tab` | `ActivateTabRelative=1` |
|
||||
| `CTRL` | `PageDown` | `ActivateTabRelative=1` |
|
||||
| `CTRL+SHIFT` | `PageUp` | `MoveTabRelative=-1` |
|
||||
| `CTRL+SHIFT` | `PageDown` | `MoveTabRelative=1` |
|
||||
| `SHIFT` | `PageUp` | `ScrollByPage=-1` |
|
||||
| `SHIFT` | `PageDown` | `ScrollByPage=1` |
|
||||
| `SUPER` | `r` | `ReloadConfiguration` |
|
||||
| `CTRL+SHIFT` | `R` | `ReloadConfiguration` |
|
||||
| `SUPER` | `h` | `HideApplication` (macOS only) |
|
||||
| `SUPER` | `k` | `ClearScrollback="ScrollbackOnly"` |
|
||||
| `CTRL+SHIFT` | `K` | `ClearScrollback="ScrollbackOnly"` |
|
||||
| `CTRL+SHIFT` | `L` | `ShowDebugOverlay` (*Since: 20210814-124438-54e29167*)|
|
||||
| `SUPER` | `f` | `Search={CaseSensitiveString=""}` |
|
||||
| `CTRL+SHIFT` | `F` | `Search={CaseSensitiveString=""}` |
|
||||
| `CTRL+SHIFT` | `X` | `ActivateCopyMode` |
|
||||
| `CTRL+SHIFT` | ` ` (`Space`) | `QuickSelect` (*since: 20210502-130208-bff6815d*) |
|
||||
| `CTRL+SHIFT+ALT` | `"` | `SplitVertical={domain="CurrentPaneDomain"}` |
|
||||
| `CTRL+SHIFT+ALT` | `%` | `SplitHorizontal={domain="CurrentPaneDomain"}` |
|
||||
| `CTRL+SHIFT+ALT` | `LeftArrow` | `AdjustPaneSize={"Left", 1}` |
|
||||
| `CTRL+SHIFT+ALT` | `RightArrow` | `AdjustPaneSize={"Right", 1}` |
|
||||
| `CTRL+SHIFT+ALT` | `UpArrow` | `AdjustPaneSize={"Up", 1}` |
|
||||
| `CTRL+SHIFT+ALT` | `DownArrow` | `AdjustPaneSize={"Down", 1}` |
|
||||
| `CTRL+SHIFT` | `LeftArrow` | `ActivatePaneDirection="Left"` |
|
||||
| `CTRL+SHIFT` | `RightArrow` | `ActivatePaneDirection="Right"` |
|
||||
| `CTRL+SHIFT` | `UpArrow` | `ActivatePaneDirection="Up"` |
|
||||
| `CTRL+SHIFT` | `DownArrow` | `ActivatePaneDirection="Down"` |
|
||||
| `CTRL+SHIFT` | `Z` | `TogglePaneZoomState` |
|
||||
|
||||
If you don't want the default assignments to be registered, you can
|
||||
disable all of them with this configuration; if you chose to do this,
|
||||
you must explicitly register every binding.
|
||||
|
||||
```lua
|
||||
return {
|
||||
disable_default_key_bindings = true,
|
||||
}
|
||||
```
|
||||
|
||||
## Configuring Key Assignments
|
||||
|
||||
|
||||
These can be overridden using the `keys` section in your `~/.wezterm.lua` config file.
|
||||
For example, you can disable a default assignment like this:
|
||||
The default key table assignments can be overridden or extended using the
|
||||
`keys` section in your `~/.wezterm.lua` config file. For example, you can
|
||||
disable a default assignment like this:
|
||||
|
||||
```lua
|
||||
local wezterm = require 'wezterm';
|
||||
@ -218,6 +28,7 @@ Possible Modifier labels are:
|
||||
* `SHIFT` - The shift key. Left and right are equivalent.
|
||||
* `ALT`, `OPT`, `META` - these are all equivalent: on macOS the `Option` key,
|
||||
on other systems the `Alt` or `Meta` key. Left and right are equivalent.
|
||||
* `LEADER` - a special modal modifier state managed by `wezterm`. See [Leader Key](#leader-key) for more information.
|
||||
* `VoidSymbol` - This keycode is emitted in special cases where the original
|
||||
function of the key has been removed. Such as in Linux and using `setxkbmap`.
|
||||
`setxkbmap -option caps:none`. The `CapsLock` will no longer function as
|
||||
@ -248,6 +59,8 @@ all of these are meaningful on all platforms:
|
||||
Alternatively, a single unicode character can be specified to indicate
|
||||
pressing the corresponding key.
|
||||
|
||||
Pay attention to the case of the text that you use and the state of the `SHIFT` modifier, as `key="A"` will match
|
||||
|
||||
### Physical vs Mapped Key Assignments
|
||||
|
||||
*Since: 20220319-142410-0fcdea07*
|
||||
@ -284,6 +97,23 @@ default), then `mapped:` is assumed. If `key_map_preference = "Physical"` then
|
||||
|
||||
The default key assignments will respect `key_map_preference`.
|
||||
|
||||
### Raw Key Assignments
|
||||
|
||||
In some cases, `wezterm` may not know how to represent a key event in either
|
||||
its `phys:` or `mapped:` forms. In that case, you may wish to define an
|
||||
assignment in terms of the underlying operating system key code, using a `raw:`
|
||||
prefix.
|
||||
|
||||
Similar in concept to the `phys:` mapping described above, the `raw:` mapping
|
||||
is independent of the OS keyboard layout. Raw codes are hardware and windowing system dependent, so there is no portable way to list which key does what.
|
||||
|
||||
To discover these values, you can set [debug_key_events =
|
||||
true](lua/config/debug_key_events.md) and press the keys of
|
||||
interest.
|
||||
|
||||
You can specify a raw key value of 123 by using `key="raw:123"` in your config
|
||||
rather than one of the other key values.
|
||||
|
||||
### Leader Key
|
||||
|
||||
*Since: 20201031-154415-9614e117*
|
||||
@ -344,66 +174,6 @@ return {
|
||||
}
|
||||
```
|
||||
|
||||
### Using Raw/Scan Codes for key bindings
|
||||
|
||||
In some cases it is desirable to assign keys based on their
|
||||
physical position rather than their mapped value--perhaps you
|
||||
regularly switch between different regional keymaps but you always
|
||||
want CTRL-SHIFT plus a number to switch to a tab by ordinal
|
||||
position, and you don't want to define the mapping in terms of `!`,
|
||||
`@` etc. in the US map and whatever those keys are in some other
|
||||
regional keymap.
|
||||
|
||||
You can achieve this by matching the `raw_key` value for the key.
|
||||
`raw_key` values are hardware and windowing system dependent
|
||||
values, so there is no portable way to list which key does what.
|
||||
To discover these values, you can set [debug_key_events =
|
||||
true](lua/config/debug_key_events.md) and press the keys of
|
||||
interest.
|
||||
|
||||
You can specify a raw key value of 123 by using `key="raw:123"` in your config
|
||||
rather than one of the other key values.
|
||||
|
||||
On my linux system the number key row produces sequential raw key values so I
|
||||
use configuration like this to enable this key binding; notice how the numbers
|
||||
are different between wayland and X11 on the same system!
|
||||
|
||||
```lua
|
||||
local wezterm = require 'wezterm';
|
||||
local keys = {};
|
||||
local enable_wayland = false;
|
||||
|
||||
if wezterm.target_triple == "x86_64-unknown-linux-gnu" then
|
||||
-- rebind CTRL+SHIFT+<number> to switch to a tab.
|
||||
if os.getenv("WAYLAND_DISPLAY") and enable_wayland then
|
||||
local tab_no = 0
|
||||
for i = 2, 9 do
|
||||
table.insert(keys, {
|
||||
key="raw:"..tostring(i),
|
||||
mods="CTRL|SHIFT",
|
||||
action=wezterm.action{ActivateTab=tab_no},
|
||||
})
|
||||
tab_no = tab_no + 1
|
||||
end
|
||||
else
|
||||
local tab_no = 0
|
||||
for i = 10, 20 do
|
||||
table.insert(keys, {
|
||||
key="raw:"..tostring(i),
|
||||
mods="CTRL|SHIFT",
|
||||
action=wezterm.action{ActivateTab=tab_no},
|
||||
})
|
||||
tab_no = tab_no + 1
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
return {
|
||||
keys = keys,
|
||||
enable_wayland = enable_wayland,
|
||||
}
|
||||
```
|
||||
|
||||
# Available Actions
|
||||
|
||||
See the [`KeyAssignment` reference](lua/keyassignment/index.md) for information
|
||||
|
||||
@ -19,7 +19,6 @@ used.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%%{wrap}%%
|
||||
X[Determine current working directory for new pane] --> A{{Is initial window?}}
|
||||
A -->|Yes| B[Opened with CLI and --cwd flag?]
|
||||
A -->|No| C[New pane, tab or window.]
|
||||
|
||||
14
docs/config/lua/keyassignment/ActivateKeyTable.md
Normal file
14
docs/config/lua/keyassignment/ActivateKeyTable.md
Normal file
@ -0,0 +1,14 @@
|
||||
# ActivateKeyTable
|
||||
|
||||
*Since: nightly builds only*
|
||||
|
||||
Activates a named key table.
|
||||
|
||||
See [Key Tables](../../key-tables.md) for a detailed example.
|
||||
|
||||
The following parameters are possible:
|
||||
|
||||
* `name` - the name of the table to activate. The name must match up to an entry in the `key_tables` configuration.
|
||||
* `timeout_milliseconds` - an optional duration expressed in milliseconds. If specified, then the activation will automatically expire and pop itself from the key table stack once that duration elapses. If omitted, this activation will not expire due to time.
|
||||
* `one_shot` - an optional boolean that controls whether the activation will pop itself after a single additional key press. The default if left unspecified is `one_shot=true`. When set to `false`, pressing a key will not automatically pop the activation and you will need to use either a timeout or an explicit key assignment that triggers [PopKeyTable](PopKeyTable.md) to cancel the activation.
|
||||
* `replace_current` - an optional boolean. If set to true then behave as though [PopKeyTable](PopKeyTable.md) was triggered before pushing this new activation on the stack. This is most useful for key assignments in a table that was activated using `one_shot=false`.
|
||||
7
docs/config/lua/keyassignment/ClearKeyTableStack.md
Normal file
7
docs/config/lua/keyassignment/ClearKeyTableStack.md
Normal file
@ -0,0 +1,7 @@
|
||||
# ClearKeyTableStack
|
||||
|
||||
*Since: nightly builds only*
|
||||
|
||||
Clears the entire key table stack.
|
||||
|
||||
Note that this is triggered implicitly when the configuration is reloaded.
|
||||
7
docs/config/lua/keyassignment/PopKeyTable.md
Normal file
7
docs/config/lua/keyassignment/PopKeyTable.md
Normal file
@ -0,0 +1,7 @@
|
||||
# PopKeyTable
|
||||
|
||||
*Since: nightly builds only*
|
||||
|
||||
Pops the current key table, if any, from the activation stack.
|
||||
|
||||
See [Key Tables](../../key-tables.md) for a detailed example.
|
||||
7
docs/config/lua/window/active_key_table.md
Normal file
7
docs/config/lua/window/active_key_table.md
Normal file
@ -0,0 +1,7 @@
|
||||
# window:active_key_table()
|
||||
|
||||
*Since: nightly builds only*
|
||||
|
||||
Returns a string holding the top of the current key table activation stack, or `nil` if the stack is empty.
|
||||
|
||||
See [Key Tables](../../key-tables.md) for a detailed example.
|
||||
@ -1,4 +1,4 @@
|
||||
# wezterm:composition_status()
|
||||
# window:composition_status()
|
||||
|
||||
*Since: 20220319-142410-0fcdea07*
|
||||
|
||||
@ -18,7 +18,7 @@ wezterm.on("update-right-status", function(window, pane)
|
||||
if compose then
|
||||
compose = "COMPOSING: " .. compose
|
||||
end
|
||||
window:set_right_status(compose)
|
||||
window:set_right_status(compose or "")
|
||||
end);
|
||||
|
||||
return {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user