States ​

States are defined with the macro evil-define-state, which takes care to define the necessary hooks, keymaps and variables, as well as a toggle function evil-NAME-state and a predicate function evil-NAME-state-p for checking whether the state is active.

Emacs Lisp Autofunction: (evil-define-state STATE DOC [[KEY VAL]...] BODY...) ​

Define an Evil state `STATE'. `DOC' is a general description and shows up in all docstrings; the first line of the string should be the full name of the state.

`BODY' is executed each time the state is enabled or disabled.

Optional keyword arguments:

  • :tag - the mode line indicator, e.g. “<T>”.
  • :message - string shown in the echo area when the state is activated.
  • :cursor - default cursor specification.
  • :enable - list of other state keymaps to enable when in this state.
  • :entry-hook - list of functions to run when entering this state.
  • :exit-hook - list of functions to run when exiting this state.
  • :suppress-keymap - if non-nil, effectively disables bindings to self-insert-command by making evil-suppress-map the parent of the global state keymap.

The global keymap of this state will be evil-test-state-map, the local keymap will be evil-test-state-local-map, and so on.

For example:

emacs-lisp
(evil-define-state test
  "Test state."
  :tag " <T> "
  (message (if (evil-test-state-p)
               "Enabling test state."
             "Disabling test state.")))