Merge remote-tracking branch 'Delapouite/modes'

This commit is contained in:
Maxime Coste 2018-03-01 14:09:20 +11:00
commit dcab629895
3 changed files with 108 additions and 1 deletions

View File

@ -741,6 +741,8 @@ This feature is tailored for scripting/macros, as it provides a more predictable
behaviour than leaving insert mode with `<esc>`, executing normal mode command behaviour than leaving insert mode with `<esc>`, executing normal mode command
and entering back insert mode (with which binding ?) and entering back insert mode (with which binding ?)
See <<doc/pages/modes#,`:doc modes`>>.
Highlighters Highlighters
~~~~~~~~~~~~ ~~~~~~~~~~~~

View File

@ -33,7 +33,7 @@ The *map* command makes *key* behave as if the *keys* sequence was typed.
The context of execution of the above modes is always the current one at the 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 time of execution of the mapping, except for *user* mode (always executed
in a 'normal' context). in a 'normal' context). Refer to <<modes#,`:doc modes`>> for more details.
An optional *-docstring* switch followed by a string can be used An optional *-docstring* switch followed by a string can be used
to describe what the mapping does. This docstring will be used to describe what the mapping does. This docstring will be used
@ -48,6 +48,8 @@ For more information about the values of the *scope* parameter, refer to
== Mappable keys == 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 For *key* and *keys* in the *map* command, the following key names can
be used: be used:

103
doc/pages/modes.asciidoc Normal file
View File

@ -0,0 +1,103 @@
= 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.