104 lines
3.9 KiB
Plaintext
104 lines
3.9 KiB
Plaintext
|
= Modes
|
||
|
|
|
||
|
|
== Description
|
||
|
|
|
||
|
|
Kakoune is a modal editor which means that keys have different effects depending
|
||
|
|
on the current mode. Therefore, modes can be conceptualized as a way to group
|
||
|
|
related behaviors together during a text editing workflow.
|
||
|
|
|
||
|
|
By default Kakoune starts in Normal mode. A few keys let users enter other
|
||
|
|
modes where they can focus on a specific task before going back to Normal mode
|
||
|
|
explicitly with `<esc>` or automatically in the case of *one shot* modes.
|
||
|
|
|
||
|
|
Modes are stored in a stack with the top of the stack being the active mode.
|
||
|
|
So in some scenarios, the Normal mode may feel *nested* in another one.
|
||
|
|
The `ModeChange` hook is triggered each time a mode is popped or pushed
|
||
|
|
on this stack. See <<hooks#,`:doc hooks`>>
|
||
|
|
|
||
|
|
To get a comprehensive list of commands available for each modes,
|
||
|
|
see <<keys#,`:doc keys`>>.
|
||
|
|
Most of them are described in *info* boxes in real-time if the `autoinfo` option is set.
|
||
|
|
|
||
|
|
To customize key mappings in various modes, refer to <<mapping#,`:doc mapping`>>.
|
||
|
|
|
||
|
|
== Builtin modes
|
||
|
|
|
||
|
|
=== Normal mode
|
||
|
|
|
||
|
|
Normal mode is the starting mode mainly dedicated to move, extend or create
|
||
|
|
selections where users spend most of their time (besides inserting content).
|
||
|
|
It also serves as a *basecamp* to access other modes.
|
||
|
|
|
||
|
|
See normal commands <<keys#movement,`:doc keys movement`>>.
|
||
|
|
|
||
|
|
=== Insert mode
|
||
|
|
|
||
|
|
In Insert mode, typing keys add content to the current buffer like in many other
|
||
|
|
text editors. There are several ways to reach Insert Mode and start editing at
|
||
|
|
common locations for maximum efficiency (after cursor, at the beginning of the line…).
|
||
|
|
See changes <<keys#changes,`:doc keys changes`>>.
|
||
|
|
|
||
|
|
Use `<esc>` to go back to Normal Mode: it pops Insert mode from the modes stack.
|
||
|
|
Use `<a-;>` to temporary enable Normal mode for one command: in this case, this quick
|
||
|
|
Normal Mode is pushed on the modes stack.
|
||
|
|
|
||
|
|
See insert commands <<keys#insert-mode,`:doc keys insert-mode`>>.
|
||
|
|
|
||
|
|
=== Goto mode
|
||
|
|
|
||
|
|
Default keys: `g`, `G`
|
||
|
|
Goto mode groups commands dedicated to jump inside a buffer (top, bottom…).
|
||
|
|
See goto commands <<keys#goto-commands,`:doc keys goto-commands`>>.
|
||
|
|
|
||
|
|
=== View mode
|
||
|
|
|
||
|
|
Default keys: `v`, `V`
|
||
|
|
View mode let users center and scroll the current window.
|
||
|
|
See view commands <<keys#view-commands,`:doc keys view-commands`>>.
|
||
|
|
|
||
|
|
=== Menu mode
|
||
|
|
|
||
|
|
Mode entered when a menu is displayed with the *menu* command or by autocompletion.
|
||
|
|
Mappings are used to choose and select intended items.
|
||
|
|
|
||
|
|
=== Prompt mode
|
||
|
|
|
||
|
|
Mode entered with `:`, `/` or the `:prompt` command.
|
||
|
|
The commands defined in this mode help editing.
|
||
|
|
See prompt commands <<keys#prompt-commands,`:doc keys prompt-commands`>>.
|
||
|
|
|
||
|
|
=== Object mode
|
||
|
|
|
||
|
|
Mode entered with `<a-i>`, `<a-a>` and various combinations of `[]{}` keys.
|
||
|
|
It aims at crafting semantic selections, often called *text-objects*.
|
||
|
|
See object commands <<keys#object-commands,`:doc keys object-commands`>>.
|
||
|
|
|
||
|
|
=== User mode
|
||
|
|
|
||
|
|
Default key: `,`
|
||
|
|
The user mode is empty by default and is the opportunity to store custom mappings
|
||
|
|
with no risk to shadow builtin ones. The context of execution is always the Normal mode.
|
||
|
|
|
||
|
|
== User modes
|
||
|
|
|
||
|
|
The following two commands are useful in advanced use cases, when the builtin User mode
|
||
|
|
gets too crowded by mappings competing for the same key that deserves to be split
|
||
|
|
in more meaningful collections. It's mostly useful for plugin authors who want
|
||
|
|
to bind their new commands in extensible menus.
|
||
|
|
|
||
|
|
--------------------------------
|
||
|
|
declare-user-mode <scope> <name>
|
||
|
|
--------------------------------
|
||
|
|
|
||
|
|
Declare a new custom mode that can later be referred by the *map* command.
|
||
|
|
For example a `grep` custom mode to attach keys like `n` or `p` to skim
|
||
|
|
through the output results.
|
||
|
|
|
||
|
|
-------------------------------
|
||
|
|
enter-user-mode <scope> <name>
|
||
|
|
-------------------------------
|
||
|
|
|
||
|
|
Enable the designated mode for the next key. Docstrings are shown in the automatic
|
||
|
|
info box to increase discoverability. To keep illustrating the aforementioned
|
||
|
|
fictional `grep` mode, a normal mapping on `<a-g>` could be used to enter this mode.
|