StumpWM Manual: 3.2 Interactive Keymaps

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.2 Interactive Keymaps

Interactive keymaps are a special type of command that basically pushes another keymap on top of the current one. The new keymap will only be removed after an exit command is run. An example is iresize.

The macro define-interactive-keymap is used to define an interactive keymap. The first argument is the same as defcommand. The second argument is a list of extra configurations that can be used for controlling the command and the rest are the key bindings for the new command, optionally with a t appended; this tells define-interactive-keymap to exit the keymap upon use of that keybinding.

For instance, a simple interactive keymap:

(define-interactive-keymap my-new-command nil
  ((kbd "a") "execute-a-command")
  ((kbd "b") "execute-b-command" t))

This creates a command called my-new-command that, when called, will activate the interactive keymap mode. In this mode, the user can press “a” or “b” repeatedly, omitting any prefix. The default exit commands are RET, C-g and ESC.

This creates a command called my-new-command that, when called, will activate the interactive keymap mode. In this mode, the user can press “a” or “b”, omitting any prefix. The user can press “a” repeatedly, however pressing “b” exits the keymap. The default exit commands are RET, C-g and ESC.

The available configuration is on-enter, on-exit and abort-if:

(defun before-foo () (message "start foo"))
(defun after-foo () (message "end foo"))
(defun foo-p () (and *bar* *baz*))
(defparameter *custom-exit-keys* '((kbd "RET") (kbd "SPC")
                                   (kbd "C-g") (kbd "ESC")))

(define-interactive-keymap foo (:on-enter #'before-foo
                                :on-exit #'after-foo
                                :abort-if #'foo-p
                                :exit-on *custom-exit-keys*))

In the above example, the message “start foo” will appear before starting the interactive keymap, “end foo” will appear right after the command exits; We’ve added SPC as an exit key with custom exit keys. Also, the command executes only if the variables *bar* and *baz* are true.

Macro: define-interactive-keymap name( &key on-enter on-exit abort-if exit-on) &body key-bindings

Default Values:

  on-enter  nil
  on-exit   nil
  abort-if  nil
  exit-on   '((stumpwm:kbd "RET") (stumpwm:kbd "ESC")
              (stumpwm:kbd "C-g"))

Declare an interactive keymap mode. This can be used for developing interactive modes or command trees, such as iresize.

The NAME argument follows the same convention as in defcommand.

ON-ENTER and ON-EXIT are optional functions to run before and after the interactive keymap mode, respectively. If ABORT-IF is defined, the interactive keymap will only be activated if calling ABORT-IF returns true.

KEY-BINDINGS is a list of the following form: ((KEY COMMAND) (KEY COMMAND) ...) If one appends t to the end of a binding like so: ((kbd "n") "cmd" t) then the keymap is immediately exited after running the command.

Each element in KEY-BINDINGS declares a command inside the interactive keymap. Be aware that these commands won’t require a prefix to run.

Command: call-and-exit-kmap command exit-command: This command effectively calls two other commands in succession, via run-commands. it is designed for use in the define-interactive-keymap macro, to implement exiting the keymap on keypress.