Skip to content

Latest commit

 

History

History
119 lines (80 loc) · 4.25 KB

modes.asciidoc

File metadata and controls

119 lines (80 loc) · 4.25 KB

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.

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.

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 :doc hooks

To get a comprehensive list of commands available for each modes, see :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 :doc mapping.

Builtin modes

Normal mode

Normal mode is the default mode. It provides commands to manipulate selections, such as general movement, text object selection, searching, splitting, and commands to manipulate the text underlying the current selections, such as yanking, pasting, deleting…

It also provides commands to enter other modes.

See normal commands :doc keys movement.

Insert mode

Insert mode provides an efficient way to interactively write text into the buffer. Most keys will insert their corresponding characters before every selections cursors. It also provides completion support for inserted text along with some commands for basic movement.

Insert mode can be entered from Normal modes through a set of commands such as i to insert before selection, a to insert after selection, o to insert in a new line below selections… It can then be exited with <esc> to return to Normal mode.

See changes :doc keys changes.

From Insert mode, <a-;> provides a way to temporarily enter a new Normal mode for a single command, before returning to Insert mode.

See insert commands :doc keys insert-mode.

Goto mode

Goto mode provides commands dedicated to jumping either inside a buffer (such as jumping to buffer start/end, window top/bottom) or to another (such as jumping to the file whose path is currently selected).

See goto commands :doc keys goto-commands.

View mode

View mode provides commands dedicated to controlling the window, such as scrolling or centering the main selection cursor.

See view commands :doc keys view-commands.

Menu mode

Menu mode is entered when a menu is displayed with the menu command. Mappings are used to filter and select intended items.

Prompt mode

Mode entered with :, / or the :prompt command. During prompt mode a line of text is edited and then validated with <ret> or abandoned with <esc>.

See 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 :doc keys object-commands.

User mode

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 <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 <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.