[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12. Miscellaneous Commands

The following is a list of commands that don’t really fit in any other section.

Command: emacs

Start emacs unless it is already running, in which case focus it.

Command: banish &optional where

Warp the mouse the lower right corner of the current head.

Command: ratwarp x y

Warp the mouse to the specified location.

Command: ratrelwarp dx dy

Warp the mouse by the specified amount from its current position.

Command: ratclick &optional (button 1)

Simulate a pointer button event at the current pointer location. Note: this function is unlikely to work unless your X server and CLX implementation support XTEST.

Command: echo-date

Display the date and time.

Command: eval-line cmd

Evaluate the s-expression and display the result(s).

Command: window-send-string string &optional (window (current-window))

Send the string of characters to the current window as if they’d been typed.

Command: reload

Reload StumpWM using asdf.

Command: loadrc

Reload the ‘~/.stumpwmrc’ file.

Command: keyboard-quit
Command: quit

Quit StumpWM.

Command: restart-hard

Restart stumpwm. This is handy if a new stumpwm executable has been made and you wish to replace the existing process with it.

Any run-time customizations will be lost after the restart.

Command: restart-soft

Soft restart StumpWM. The lisp process isn’t restarted. Instead, control jumps to the very beginning of the stumpwm program. This differs from RESTART, which restarts the unix process.

Since the process isn’t restarted, existing customizations remain after the restart.

Command: getsel

Echo the X selection.

Command: putsel string

Stuff the string string into the X selection.

Command: command-mode

Command mode allows you to type StumpWM commands without needing the <C-t> prefix. Keys not bound in StumpWM will still get sent to the current window. To exit command mode, type <C-g>.

Command: copy-unhandled-error

When an unhandled error occurs, StumpWM restarts and attempts to continue. Unhandled errors should be reported to the mailing list so they can be fixed. Use this command to copy the unhandled error and backtrace to the X11 selection so you can paste in your email when submitting the bug report.

Command: commands

List all available commands.

Command: lastmsg

Display the last message. If the previous command was lastmsg, then continue cycling back through the message history.

Command: list-window-properties

List all the properties of the current window and their values, like xprop.

Command: show-window-properties

Shows the properties of the current window. These properties can be used for matching windows with run-or-raise or window placement rules.

Command: version

Print version information and compilation date.

Command: which-key-mode

Toggle which-key-mode

Function: run-commands &rest commands

Run each stumpwm command in sequence. This could be used if you’re used to ratpoison’s rc file and you just want to run commands or don’t know lisp very well. One might put the following in one’s rc file:

  "escape C-z"
  "exec firefox"
Macro: defcommand name (&rest args) (&rest interactive-args) &body body

Create a command function and store its interactive hints in *command-hash*. The local variable %interactivep% can be used to check if the command was called interactively. If it is non-NIL then it was called from a keybinding or from the colon command.

The NAME argument can be a string, or a list of two symbols. If the latter, the first symbol names the command, and the second indicates the type of group under which this command will be usable. Currently, tile-group and floating-group are the two possible values.

INTERACTIVE-ARGS is a list of the following form: ((TYPE PROMPT) (TYPE PROMPT) ...)

each element in INTERACTIVE-ARGS declares the type and prompt for the command’s arguments.

TYPE can be one of the following:


A yes or no question returning T or NIL.


A lisp variable


A lisp function


A stumpwm command as a string.


A key sequence starting from *TOP-MAP*


An existing window number


An integer number


A string


A single key chord


An existing window’s name


A direction symbol. One of :UP :DOWN :LEFT :RIGHT


A gravity symbol. One of :center :top :right :bottom :left :top-right :top-left :bottom-right :bottom-left


An existing group


A frame


A shell command


The rest of the input yet to be parsed.


An existing stumpwm module

Note that new argument types can be created with DEFINE-STUMPWM-TYPE.

PROMPT can be string. In this case, if the corresponding argument is missing from an interactive call, stumpwm will use prompt for its value using PROMPT. If PROMPT is missing or nil, then the argument is considered an optional interactive argument and is not prompted for when missing.

Alternatively, instead of specifying nil for PROMPT or leaving it out, an element can just be the argument type.

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

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) ...)

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

Macro: define-stumpwm-type type (input prompt) &body body

Create a new type that can be used for command arguments. type can be any symbol.

When body is evaluated input is bound to the argument-line. It is passed to argument-pop, argument-pop-rest, etc. prompt is the prompt that should be used when prompting the user for the argument.

(define-stumpwm-type :symbol (input prompt)
 (or (find-symbol (string-upcase
		     (or (argument-pop input)
                         ;; Whitespace messes up find-symbol.
		         (string-trim " "
		           (completing-read (current-screen)
					  ;; find all symbols in the
					  ;;  stumpwm package.
					  (let (acc)
					    (do-symbols (s (find-package "STUMPWM"))
					      (push (string-downcase (symbol-name s)) acc))
                      (throw 'error "Abort.")))
     (throw 'error "Symbol not in STUMPWM package")))

(defcommand "symbol" (sym) ((:symbol "Pick a symbol: "))
  (message "~a" (with-output-to-string (s)
	          (describe sym s))))

This code creates a new type called :symbol which finds the symbol in the stumpwm package. The command symbol uses it and then describes the symbol.

Function: run-or-raise cmd props &optional (all-groups *run-or-raise-all-groups*) (all-screens *run-or-raise-all-screens*)

Run the shell command, cmd, unless an existing window matches props. props is a property list with the following keys:


Match the window’s class.


Match the window’s instance or resource-name.


Match the window’s WM_WINDOW_ROLE.


Match the window’s title.

By default, the global *run-or-raise-all-groups* decides whether to search all groups or the current one for a running instance. all-groups overrides this default. Similarily for *run-or-raise-all-screens* and all-screens.

Function: run-or-pull cmd props &optional (all-groups *run-or-raise-all-groups*) (all-screens *run-or-raise-all-screens*)

Similar to run-or-raise, but move the matching window to the current frame instead of switching to the window.

Variable: *run-or-raise-all-groups*

When this is T the run-or-raise function searches all groups for a running instance. Set it to NIL to search only the current group.

Variable: *run-or-raise-all-screens*

When this is T the run-or-raise function searches all screens for a running instance. Set it to NIL to search only the current screen. If *run-or-raise-all-groups* is NIL this variable has no effect.

Function: restarts-menu err

Display a menu with the active restarts and let the user pick one. Error is the error being recovered from. If the user aborts the menu, the error is re-signalled.

Macro: with-restarts-menu &body body

Execute BODY. If an error occurs allow the user to pick a restart from a menu of possible restarts. If a restart is not chosen, resignal the error.

Variable: *startup-message*

This is the message StumpWM displays when it starts. Set it to NIL to suppress.

Variable: *suppress-abort-messages*

Suppress abort message when non-nil.

Variable: *default-package*

This is the package eval reads and executes in. You might want to set this to :stumpwm if you find yourself using a lot of internal stumpwm symbols. Setting this variable anywhere but in your rc file will have no effect.

Macro: defprogram-shortcut name &key (command (string-downcase (string name))) (props (quasiquote (quote (class #S(comma :expr (string-capitalize command) :kind 0))))) (map (quote *top-map*)) (key (quasiquote (kbd #S(comma :expr (concat H- (subseq command 0 1)) :kind 0)))) (pullp nil) (pull-name (intern1 (concat (string name) -PULL))) (pull-key (quasiquote (kbd #S(comma :expr (concat H-M- (subseq command 0 1)) :kind 0))))

Define a command and key binding to run or raise a program. If pullp is set, also define a command and key binding to run or pull the program.

Variable: *initializing*

True when starting stumpwm. Use this variable in your rc file to run code that should only be executed once, when stumpwm starts up and loads the rc file.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated on January 28, 2024 using texi2html 1.82.