Keymap¶
Keymap settings are named settings objects stored at $HOME/.config/qtermy/keymaps
. Keymaps can be edited from the Settings menu, the Manage Keymaps window, and various context menus, or by calling the EditKeymap
action. The files can also be edited directly in a text editor, but note that qtermy does not monitor for external changes to settings files. Use the reload files button in the Manage Keymaps window to load external changes and new files without restarting the application.
The keymap that is used in a terminal is specified by the terminal's profile. To change a terminal's keymap, its profile must be changed or the keymap setting
must be changed in its profile. Use the Keymap Tool to see a list of key bindings for the active terminal's keymap at a glance.
The format of qtermy keymap files is an extension of Konsole's keymap file format. The sections below describe the different rules that can appear in keymap files.
Rule Types
Keymap Description¶
Format: keyboard "description"
An optional brief description of the keymap, displayed in the Manage Keymaps window. Can be edited using the Keymap Options button in the Keymap Editor.
Keymap Inheritance¶
Format: inherit "name"
Specifies that the keymap inherits from the named keymap. This allows a keymap to make modifications to a parent keymap without having to redefine all of the parent keymap's rules. Only one inheritance statement is permitted per keymap. Multiple levels of inheritance are permitted.
To change a keymap's inheritance, use the Rename Keymap button in the Manage Keymaps window.
Keymap Option¶
Format: (enable|disable) optionname
Enable or disable the keymap option optionname
. The available options are:
- EscapeOnAlt: If enabled and an Alt key on the keyboard is pressed, an escape character (
0x1b
) will be prepended to the text string of all keypresses for which no explicit binding exists. For example, an Alt+A keypress will produce the input Escape+A (assuming there is no explicit binding for the A key). This option is enabled by default.- EscapeOnMeta: Like EscapeOnAlt, but for the Meta key instead of the Alt key. This option is disabled by default.
A keymap that does not explicitly enable or disable an option will inherit the option from its parent keymap, if applicable.
Literal Key Binding¶
Format: (key|digraph) keyname conditions: "string"
Defines a key binding for the key named keyname
that sends the string string
as input to the terminal. The given conditions
must be true for the binding to be used. A rule starting with digraph
instead of key
specifies the second keystroke of a two-keystroke combination binding and must follow a digraph opener specifying the first keystroke of the combination.
The key name is one of the following:
- The name of a key defined in the Qt::Key enumeration, without the
Key_
prefix.- The name
BackButton
,ForwardButton
, orTaskButton
, referring to the first three extended mouse buttons.- The name
MouseButtonN
whereN
is a number between 4 and 24 inclusive, referring to further extended mouse buttons beyondTaskButton
.
The conditions
is a list of condition names prefixed with plus (+) or minus (-) characters and joined together without spaces or punctuation. A positive condition must be true at the time of the keypress, while a negative condition must be false at the time of the keypress. All conditions in the list must be met for the key binding to be used. Multiple bindings for the same keyname
will be processed in order, with the first binding whose conditions are met being used. If no binding's conditions are met, the parent keymap will be searched, if applicable.
The conditions are as follows:
- Command: The application is in
command mode
. This mode exists to support vim-style keymaps that use a second input mode to avoid excessive use of modifier keys.- Selection: The application is in
selection mode
, which can be manually or automatically entered when a text selection is made in the active viewport. The default keymap has many bindings conditioned on this mode which are used to edit the active selection.- Shift: A Shift key on the keyboard is pressed.
- Control: A Control key on the keyboard is pressed.
- Alt: An Alt key on the keyboard is pressed.
- Meta: A Meta key on the keyboard is pressed.
- AnyMod: A Shift, Control, Alt, or Meta key on the keyboard is pressed.
- KeyPad: The key is located on the keypad portion of the keyboard. For example, the keypad Enter key as opposed to the regular Enter key.
- AppScreen: The alternate screen buffer is active in the terminal. This is a second terminal screen used by most fullscreen terminal applications such as vim. In the default keymap, certain scrolling action bindings are disabled in AppScreen mode since fullscreen terminal applications might use those keys.
- AppCuKeys: The terminal is in Application Cursor Keys mode, which can be enabled by terminal programs using an escape sequence. In the default keymap, this mode affects the strings produced by the arrow and navigation keys.
- AppKeyPad: The terminal is in Application Keypad mode, which can be enabled by terminal programs using an escape sequence.
- NewLine: The terminal is in Newline mode, which is enabled by default but can be disabled by terminal programs using an escape sequence. In the default keymap, this mode dictates whether the Return key produces a carriage return and newline or just a carriage return.
The string
surrounded by double quotes is the text to write to the terminal as input. It must be valid UTF-8. This field supports the following escapes:
\E
: an escape character,0x1b
.- The C language escapes
\a
,\b
,\t
,\n
,\v
,\f
,\r
.\xHH
: a character specified by two hexadecimal digits. For characters above 127, use\u
.\uHHHH
: a Unicode code point specified by between 2 and 5 hexadecimal digits. It will be encoded in UTF-8.*
: when an asterisk appears in a key binding that has a positive AnyMod condition, it will be replaced by a number indicating which modifier keys are pressed. The default keymap uses this feature to implement various literal bindings (such as function keys) that must report this information.Note
A non-empty text string generated by a keypress will be sent to directly to the terminal as input if no binding in the keymap (or its parent keymap, if applicable) matches the key and conditions. This means that literal bindings for plain character keys such as
A
are not required.
Action Key Binding¶
Format: (key|digraph) keyname conditions: action
Like a literal key binding, but instead of sending a string as input to the terminal, invokes an action using the action name and parameters specified by action
. Note the lack of double quotes around the action string.
Digraph Opener¶
Format: key keyname conditions: BeginDigraph
Opens a two-keystroke combination binding. The keyname
and conditions
are as specified in literal key binding.
Literal and action bindings of type digraph
immediately following this rule specify the second keystrokes of the combination binding.
Combination bindings may not be nested; BeginDigraph
is only accepted as a top-level key
binding.