Command System

Arcus commands operate on command execution context. During dispatch, execute-command binds a command target view, available via current-view. defcommand defines zero-argument command functions and registers metadata used by help and pickers.

Commands invoked outside direct key handling (help, menus, command dialog) are executed through execute-command, which can bind an explicit target view. execute-command also accepts call forms ((fn &rest args)). Use current-buffer-view to resolve the main editor target when invoking from overlays.

Defining commands

(defcommand duplicate-line
    (:category :editing
     :bindings (((buffer-view :normal) . (:d :ctrl))))
  "Duplicate the current line."
  (let* ((view (current-view))
         (buf (buffer view))
         (sel (selection view))
         (pos (selection-cursor sel)))
    (multiple-value-bind (line _col) (buffer-pos-to-line-col buf pos)
      (declare (ignore _col))
      (let* ((text (buffer-line buf line))
             (end (buffer-line-end buf line)))
        (buffer-insert buf (1+ end) (format nil "~%~A" text))))))

defcommand stores:

  • name
  • description (from docstring)
  • category
  • bindings

Binding keys

Use define-key to bind commands to:

  • :global
  • a view class (for default state): 'search-panel
  • a class/state target: '(buffer-view :normal), '(interactive-view :output-focus)
  • an explicit keymap symbol (for legacy/static keymap objects like popups)

Key format is either a keyword like :escape or a key/modifier list like (:tab :ctrl :shift).

(define-key '(buffer-view :normal) '(:s :ctrl) 'write-file)
(define-key '(buffer-view :insert) :escape 'insert-exit-to-normal)
(define-key :global '(:tab :ctrl) 'focus-cycle-floating)

Buffer-mode target bindings:

(define-buffer-mode-key 'markdown-mode '(buffer-view :insert) :return
  (make-guarded-command :predicate #'md-on-list-line-p
                        :command #'md-continue-list-command))

Remove bindings with undefine-key.

Command palette

open-command-dialog opens a searchable command list using command registry metadata.