Function: evil-define-key

evil-define-key is a macro defined in evil-core.el.

Signature

(evil-define-key STATE KEYMAP KEY DEF &rest BINDINGS)

Documentation

Create a STATE binding from KEY to DEF for KEYMAP.

STATE is one of normal, insert, visual, replace, operator, motion, emacs, or a list of one or more of these. Omitting a state by using nil corresponds to a standard Emacs binding using define-key. The remaining arguments are like those of define-key. For example:

    (evil-define-key 'normal foo-map "a" 'bar)

This creates a binding from a to bar in normal state, which is active whenever foo-map is active. Using nil for the state, the following lead to identical bindings:

    (evil-define-key nil foo-map "a" 'bar)
    (define-key foo-map "a" 'bar)

It is possible to specify multiple states and/or bindings at once:

    (evil-define-key '(normal visual) foo-map
      "a" 'bar
      "b" 'foo)

If foo-map has not been initialized yet, this macro adds an entry to after-load-functions, delaying execution as necessary.

KEYMAP may also be a quoted symbol. If the symbol is global, the global evil keymap corresponding to the state(s) is used, meaning the following lead to identical bindings:

    (evil-define-key 'normal 'global "a" 'bar)
    (evil-global-set-key 'normal "a" 'bar)

The symbol local may also be used, which corresponds to using evil-local-set-key. If a quoted symbol is used that is not global or local, it is assumed to be the name of a minor mode, in which case evil-define-minor-mode-key is used.

KEY is an internal Emacs representation of a key, as for define-key. To bind key sequences that use modifier keys such as "C-a" or "M-a", convert the key sequences using kbd. For example:

    (evil-define-key 'normal foo-map (kbd "C-a") 'bar)

Aliases

evil-declare-key

Source Code

;; Defined in ~/.emacs.d/elpa/evil-20251108.138/evil-core.el
(defmacro evil-define-key (state keymap key def &rest bindings)
  "Create a STATE binding from KEY to DEF for KEYMAP.
STATE is one of `normal', `insert', `visual', `replace',
`operator', `motion', `emacs', or a list of one or more of
these. Omitting a state by using `nil' corresponds to a standard
Emacs binding using `define-key'. The remaining arguments are
like those of `define-key'. For example:

    (evil-define-key \\='normal foo-map \"a\" \\='bar)

This creates a binding from `a' to `bar' in normal state, which
is active whenever `foo-map' is active. Using nil for the state,
the following lead to identical bindings:

    (evil-define-key nil foo-map \"a\" \\='bar)
    (define-key foo-map \"a\" \\='bar)

It is possible to specify multiple states and/or bindings at
once:

    (evil-define-key \\='(normal visual) foo-map
      \"a\" \\='bar
      \"b\" \\='foo)

If `foo-map' has not been initialized yet, this macro adds an
entry to `after-load-functions', delaying execution as necessary.

KEYMAP may also be a quoted symbol. If the symbol is `global', the
global evil keymap corresponding to the state(s) is used, meaning
the following lead to identical bindings:

    (evil-define-key \\='normal \\='global \"a\" \\='bar)
    (evil-global-set-key \\='normal \"a\" \\='bar)

The symbol `local' may also be used, which corresponds to using
`evil-local-set-key'. If a quoted symbol is used that is not
`global' or `local', it is assumed to be the name of a minor
mode, in which case `evil-define-minor-mode-key' is used.

KEY is an internal Emacs representation of a key, as for
`define-key'. To bind key sequences that use modifier keys such
as \"C-a\" or \"M-a\", convert the key sequences using `kbd'.
For example:

    (evil-define-key \\='normal foo-map (kbd \"C-a\") \\='bar)"
  (declare (indent defun))
  (cond
   ((member keymap '('global 'local))
    `(evil-define-key* ,state ,keymap ,key ,def ,@bindings))
   ((eq (car-safe keymap) 'quote)
    `(evil-define-minor-mode-key ,state ,keymap ,key ,def ,@bindings))
   (t `(evil-with-delay ,(if (symbolp keymap)
                             ;; BEWARE: Can't work for lexically scoped vars
                             `(and (boundp ',keymap) (keymapp ,keymap))
                           `(keymapp ,keymap))
           (after-load-functions
            t nil ,(format "evil-define-key-in-%s"
                           (if (symbolp keymap) keymap 'keymap)))
         (with-demoted-errors "Error in evil-define-key: %S"
           (evil-define-key* ,state ,keymap ,key ,def ,@bindings))))))