Motions ​

A `motion' is a command which moves the cursor, such as w or e. Motions are defined with the macro evil-define-motion. Motions not defined in this way should be declared with evil-declare-motion.

Emacs Lisp Autofunction: (evil-declare-motion COMMAND) ​

Declare `COMMAND' to be a movement function. This ensures that it behaves correctly in visual state.

Emacs Lisp Autofunction: (evil-define-motion MOTION (COUNT ARGS...) DOC [[KEY VALUE]...] BODY...) ​

Define a motion command `MOTION'. `ARGS' is a list of arguments. Motions can have any number of arguments, but the first (if any) has the predefined meaning of count. `BODY' must execute the motion by moving point.

Optional keyword arguments are:

  • :type - determines how the motion works after an operator (one of inclusive, line, block and exclusive, or a self-defined motion type)
  • :jump - if non-nil, the previous position is stored in the jump list, so that it can be restored with C-o

For example, this is a motion that moves the cursor forward by a number of characters:

emacs-lisp
(evil-define-motion foo-forward (count)
  "Move to the right by COUNT characters."
  :type inclusive
  (forward-char (or count 1)))

The `type' of a motion determines how it works when used together with an operator. Inclusive motions include the endpoint in the range being operated on, while exclusive motions do not. Line motions extend the whole range to linewise positions, effectively behaving as if the endpoint were really at the end of the line. Blockwise ranges behave as a “rectangle” on screen rather than a contiguous range of characters.