Function: evil-define-visual-selection

evil-define-visual-selection is a macro defined in evil-states.el.

Signature

(evil-define-visual-selection SELECTION DOC [[KEY VAL]...] BODY...)

Documentation

Define a Visual selection SELECTION.

Creates a command evil-visual-SELECTION for enabling the selection. DOC is the function's documentation string. The following keywords may be specified in BODY:

:message STRING Status message when enabling the selection.
:type TYPE Type to use (defaults to SELECTION).

Following the keywords is optional code which is executed each time the selection is enabled.

Source Code

;; Defined in ~/.emacs.d/elpa/evil-20251108.138/evil-states.el
;;; Visual state

;; Visual selections are implemented in terms of types, and are
;; compatible with the Emacs region. This is achieved by "translating"
;; the region to the selected text right before a command is executed.
;; If the command is a motion, the translation is postponed until a
;; non-motion command is invoked (distinguished by the :keep-visual
;; command property).
;;
;; Visual state activates the region, enabling Transient Mark mode if
;; not already enabled. This is only temporay: if Transient Mark mode
;; was disabled before entering Visual state, it is disabled when
;; exiting Visual state. This allows Visual state to harness the
;; "transient" behavior of many commands without overriding the user's
;; preferences in other states.

(defmacro evil-define-visual-selection (selection doc &rest body)
  "Define a Visual selection SELECTION.
Creates a command evil-visual-SELECTION for enabling the selection.
DOC is the function's documentation string. The following keywords
may be specified in BODY:

:message STRING         Status message when enabling the selection.
:type TYPE              Type to use (defaults to SELECTION).

Following the keywords is optional code which is executed each time
the selection is enabled.

\(fn SELECTION DOC [[KEY VAL]...] BODY...)"
  (declare (indent defun)
           (doc-string 2)
           (debug (&define name stringp
                           [&rest keywordp sexp]
                           def-body)))
  (let* ((name (intern (format "evil-visual-%s" selection)))
         (message (intern (format "%s-message" name)))
         (tagvar (intern (format "%s-tag" name)))
         (type selection)
         (tag " <V> ")
         arg key string)
    ;; collect keywords
    (while (keywordp (car-safe body))
      (setq key (pop body)
            arg (pop body))
      (cond
       ((eq key :message)
        (setq string arg))
       ((eq key :type)
        (setq type arg))
       ((eq key :tag)
        (setq tag arg))))
    ;; macro expansion
    `(progn
       (add-to-list 'evil-visual-alist (cons ',selection ',name))
       (defvar ,name ',type ,(format "*%s" doc))
       (defvar ,message ,string ,doc)
       (defvar ,tagvar ,tag ,doc)
       (evil-define-command ,name (&optional mark point type message)
         ,@(when doc `(,doc))
         :keep-visual t
         :repeat nil
         (interactive
          (list nil nil
                (if (and (evil-visual-state-p)
                         (eq evil-visual-selection ',selection))
                    'exit ,name) t))
         (setq evil--region-from-mouse nil)
         (if (eq type 'exit)
             (evil-exit-visual-state)
           (setq type (or type ,name)
                 evil-visual-selection ',selection)
           (evil-visual-make-region mark point type message)
           ,@body))
       ',selection)))