145 lines
4.1 KiB
Plaintext
145 lines
4.1 KiB
Plaintext
= Mapping
|
|
|
|
== Description
|
|
|
|
Creating and removing shortcuts boils down to the following commands,
|
|
respectively:
|
|
|
|
---------------------------------------
|
|
map [switches] <scope> <mode> <key> <keys>
|
|
unmap <scope> <mode> <key> [<expected>]
|
|
---------------------------------------
|
|
|
|
The *map* command makes *key* behave as if the *keys* sequence was typed.
|
|
|
|
*mode* dictates in what context the mapping will be available:
|
|
|
|
*insert*::
|
|
insert mode
|
|
|
|
*normal*::
|
|
normal mode
|
|
|
|
*prompt*::
|
|
prompts, such as when entering a command through *:*, or a regex through */*
|
|
|
|
*menu*::
|
|
mode entered when a menu is displayed with the 'menu' command
|
|
|
|
*user*::
|
|
mode entered when the user prefix is hit (default: ',')
|
|
|
|
*goto*::
|
|
mode entered when the goto key is hit (default: 'g')
|
|
|
|
*view*::
|
|
mode entered when the view key is hit (default: 'v')
|
|
|
|
*object*::
|
|
mode entered when an object selection is triggered (e.g. '<a-i>')
|
|
|
|
The context of execution of the above modes is always the current one at the
|
|
time of execution of the mapping, except for *user* mode (always executed
|
|
in a 'normal' context). Refer to <<modes#,`:doc modes`>> for more details.
|
|
|
|
An optional *-docstring* switch followed by a string can be used
|
|
to describe what the mapping does. This docstring will be used
|
|
in autoinfo boxes.
|
|
|
|
The *unmap* command removes a mapping of *key* in the given *scope* and
|
|
*mode*. If *expected* is specified, the mapping is removed only if it is
|
|
set to the same sequence of keys passed using the *expected* argument.
|
|
|
|
For more information about the values of the *scope* parameter, refer to
|
|
<<scopes#,`:doc scopes`>>.
|
|
|
|
== Mapping commands
|
|
|
|
It's common to use a normal-mode or user-mode mapping to trigger a command,
|
|
like this:
|
|
|
|
----
|
|
map global user n ': make-next-error<ret>'
|
|
----
|
|
|
|
Note the space between the `:` and the command. This prevents Kakoune from
|
|
adding this command to the prompt history, so the user won't have to scroll
|
|
past it to review commands they actually typed.
|
|
|
|
If you make a normal-mode mapping, you can prefix it with a count or a register
|
|
name like any other normal-mode key. You can forward this information to the
|
|
command you invoke with the `%val{count}` and `%val{register}` expansions
|
|
(See <<expansions#`:doc expansions`>>). For example:
|
|
|
|
----
|
|
map global normal = ': echo Got count %val{count} and reg %val{register}<ret>'
|
|
----
|
|
|
|
== Mappable keys
|
|
|
|
See <<keys#,`:doc keys`>> to discover the list of default bindings.
|
|
|
|
For *key* and *keys* in the *map* command, the following key names can
|
|
be used:
|
|
|
|
*x*, *<x>*::
|
|
Most keys, especially alphabetic keys, represent themselves.
|
|
Keys can also be wrapped in angle-brackets for consistency
|
|
with the non-alphabetic keys below.
|
|
|
|
*<c-x>*::
|
|
Holding down Control while pressing the *x* key.
|
|
|
|
*<a-x>*::
|
|
Holding down Alt while pressing the *x* key.
|
|
|
|
*<s-x>*, *X*, *<X>*, *<s-X>*::
|
|
Holding down Shift while pressing the *x* key.
|
|
*<s-x>*, *<s-X>* and *<X>* are treated as the same key. The *s-* modifier
|
|
only works with ASCII letters and cannot be used with other printable keys
|
|
(non-ASCII letters, digits, punctuation) because their shift behaviour
|
|
depends on your keyboard layout. The *s-* modifier _can_ be used with
|
|
special keys like *<up>* and *<tab>*.
|
|
|
|
*<c-a-x>*::
|
|
Holding down Control and Alt while pressing the *x* key.
|
|
|
|
*<lt>*, *<gt>*::
|
|
The *<* and *>* characters.
|
|
|
|
*<plus>*, *<minus>*::
|
|
The *+* and *-* characters.
|
|
|
|
*<ret>*::
|
|
The Return or Enter key.
|
|
|
|
*<space>*::
|
|
The space bar.
|
|
|
|
*<tab>*::
|
|
The Tab key.
|
|
|
|
*<backspace>*::
|
|
The Backspace (delete to the left) key.
|
|
|
|
*<del>*::
|
|
The Delete (to the right) key.
|
|
|
|
*<esc>*::
|
|
The Escape key.
|
|
|
|
*<up>*, *<down>*, *<left>*, *<right>*::
|
|
*<pageup>*, *<pagedown>*, *<home>*, *<end>*::
|
|
The usual cursor-movement keys.
|
|
|
|
*<ins>*::
|
|
The Insert key.
|
|
|
|
*<F1>*, *<F2>*, ...*<F12>*::
|
|
Function keys.
|
|
|
|
NOTE: Although Kakoune allows many key combinations to be mapped, not every
|
|
possible combination can be triggered. For example, due to limitations in
|
|
the way terminals handle control characters, mappings like *<c-s-a>* are
|
|
unlikely to work in Kakoune's terminal UI.
|