1
1
mirror of https://github.com/mawww/kakoune.git synced 2024-12-25 04:24:48 +03:00
kakoune/doc/pages/mapping.asciidoc

162 lines
4.4 KiB
Plaintext
Raw Normal View History

= 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:
2017-11-02 12:37:39 +03:00
*insert*::
insert mode
2017-11-02 12:37:39 +03:00
*normal*::
normal mode
2017-11-02 12:37:39 +03:00
*prompt*::
prompts, such as when entering a command through *:*, or a regex through */*
2017-11-02 12:37:39 +03:00
*menu*::
mode entered when a menu is displayed with the 'menu' command
2017-11-02 12:37:39 +03:00
*user*::
mode entered when the user prefix is hit (default: ',')
2017-11-02 12:37:39 +03:00
*goto*::
mode entered when the goto key is hit (default: 'g')
2017-11-02 12:37:39 +03:00
*view*::
mode entered when the view key is hit (default: 'v')
2017-11-02 12:37:39 +03:00
*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
2018-02-23 16:31:28 +03:00
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
2017-11-06 12:08:59 +03:00
<<scopes#,`:doc scopes`>>.
2017-09-18 05:59:41 +03:00
== 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>
----
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
2017-09-18 05:59:41 +03:00
2018-02-23 16:31:28 +03:00
See <<keys#,`:doc keys`>> to discover the list of default bindings.
2017-09-18 05:59:41 +03:00
For *key* and *keys* in the *map* command, the following key names can
be used:
*x*, *<x>*::
2017-11-02 12:37:39 +03:00
Most keys, especially alphabetic keys, represent themselves.
Keys can also be wrapped in angle-brackets for consistency
with the non-alphabetic keys below.
2017-09-18 05:59:41 +03:00
*<c-x>*::
2017-11-02 12:37:39 +03:00
Holding down Control while pressing the *x* key.
2017-09-18 05:59:41 +03:00
*<a-x>*::
2017-11-02 12:37:39 +03:00
Holding down Alt while pressing the *x* key.
2017-09-18 05:59:41 +03:00
*<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>*.
2017-11-06 12:08:59 +03:00
*<c-a-x>*::
Holding down Control and Alt while pressing the *x* key.
2017-09-18 05:59:41 +03:00
*<lt>*, *<gt>*::
2017-11-02 12:37:39 +03:00
The *<* and *>* characters.
2017-09-18 05:59:41 +03:00
*<plus>*, *<minus>*::
The *+* and *-* characters.
2017-09-18 05:59:41 +03:00
*<ret>*::
2017-11-02 12:37:39 +03:00
The Return or Enter key.
2017-09-18 05:59:41 +03:00
*<space>*::
2017-11-02 12:37:39 +03:00
The space bar.
2017-09-18 05:59:41 +03:00
*<tab>*::
2017-11-02 12:37:39 +03:00
The Tab key.
2017-09-18 05:59:41 +03:00
*<backspace>*::
2017-11-02 12:37:39 +03:00
The Backspace (delete to the left) key.
2017-09-18 05:59:41 +03:00
*<del>*::
2017-11-02 12:37:39 +03:00
The Delete (to the right) key.
2017-09-18 05:59:41 +03:00
*<esc>*::
2017-11-02 12:37:39 +03:00
The Escape key.
2017-09-18 05:59:41 +03:00
2017-11-06 12:08:59 +03:00
*<up>*, *<down>*, *<left>*, *<right>*::
*<pageup>*, *<pagedown>*, *<home>*, *<end>*::
2017-11-02 12:37:39 +03:00
The usual cursor-movement keys.
2017-09-18 05:59:41 +03:00
2019-07-07 19:38:46 +03:00
*<ins>*::
The Insert key.
*<F1>*, *<F2>*, ...*<F12>*::
2017-11-02 12:37:39 +03:00
Function keys.
*<semicolon>*, *<percent>*::
The *;* and *%* characters, these keys allow reducing the amount of
backslash escaping in scripts (for example, `exec \%` becomes `exec
<percent>`)
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.
== Default mappings
Some mappings exist by default in the global scope:
In normal mode:
* `<left>` maps to `h`
* `<right>` maps to `l`
* `<up>` maps to `k`
* `<down>` maps to `j`
* `<home>` maps to `<a-h>`
* `<end>` maps to `<a-l>`
Shift version of those mappings exist as well
(for example `<s-left>` maps to `H`).