File: evil-core.el.html
Evil is defined as a globalized minor mode, enabled with the toggle
function evil-mode(var)/evil-mode(fun). This in turn enables evil-local-mode(var)/evil-local-mode(fun) in
every buffer, which sets up the buffer's state.
Each state has its own keymaps, and these keymaps have status as
"emulation keymaps" with priority over regular keymaps. Emacs
maintains the following keymap hierarchy (highest priority first):
* Overriding keymaps/overlay keymaps...
* Emulation mode keymaps...
- Evil keymaps...
* Minor mode keymaps...
* Local keymap (local-set-key)
* Global keymap (global-set-key)
Within this hierarchy, Evil arranges the keymaps for the current state as shown below:
* Intercept keymaps...
* Local state keymap
* Minor-mode keymaps...
* Auxiliary keymaps...
* Overriding keymaps...
* Global state keymap
* Keymaps for other states...
These keymaps are listed in evil-mode-map-alist, which is listed
in emulation-mode-map-alist.
Most of the key bindings for a state are stored in its global
keymap, which has a name such as evil-normal-state-map. (See the
file evil-maps.el, which contains all the default key bindings.) A
state also has a local keymap (evil-normal-state-local-map),
which may contain user customizations for the current buffer.
Furthermore, any Emacs mode may be assigned state bindings of its
own by passing the mode's keymap to the function evil-define-key
or evil-define-minor-mode-key. The former uses a specific map to
define the key in while the latter associates the key with a
particular mode. These mode-specific bindings are ultimately stored
in so-called auxiliary and minor-mode keymaps respectively, which
are sandwiched between the local keymap and the global keymap.
Finally, the state may also activate the keymaps of other states
(e.g., Normal state inherits bindings from Motion state).
For integration purposes, a regular Emacs keymap may be "elevated"
to emulation status by passing it to evil-make-intercept-map or
evil-make-overriding-map. An "intercept" keymap has priority over
all other Evil keymaps. (Evil uses this facility when debugging and
for handling the "ESC" key in the terminal.) More common is the
"overriding" keymap, which only has priority over the global state
keymap. (This is useful for adapting key-heavy modes such as Dired,
where all but a few keys should be left as-is and should not be
shadowed by Evil's default bindings.)
States are defined with the macro evil-define-state, which
creates a command for switching to the state. This command,
for example evil-normal-state for Normal state, performs
the following tasks:
* Setting evil-state to the new state.
* Refreshing the keymaps in evil-mode-map-alist.
* Updating the mode line.
- Normal state depends on evil-normal-state-tag.
* Adjusting the cursor's appearance.
- Normal state depends on evil-normal-state-cursor.
* Displaying a message in the echo area.
- Normal state depends on evil-normal-state-message.
* Running hooks.
- Normal state runs evil-normal-state-entry-hook when
entering, and evil-normal-state-exit-hook when exiting.
The various properties of a state can be accessed through their
respective variables, or by passing a keyword and the state's name
to the evil-state-property function. Evil defines the states
Normal state ("normal"), Insert state ("insert"), Visual state
("visual"), Replace state ("replace"), Operator-Pending state
("operator"), Motion state ("motion") and Emacs state ("emacs").
Defined variables (4)
evil-local-mode | Non-nil if Evil-Local mode is enabled. |
evil-local-mode-hook | Hook run after entering or leaving ‘evil-local-mode’. |
evil-mode | Non-nil if Evil mode is enabled. |
evil-mode-hook | Hook run after entering or leaving ‘evil-mode’. |