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

13. 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: refresh-time-zone

Refresh the time zone information from the system.

If you change the system time zone while StumpWM is running you can run this command to make StumpWM notice the change.

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: argument-line-end-p input

Return T if we’re outta arguments from the input line.

Function: argument-pop input

Pop the next argument off.

Function: argument-pop-rest input

Return the remainder of the argument text.

Variable: *display*

The display for the X server

Variable: *editor-bindings*

A list of key-bindings for line editing.

Function: focus-window window &optional raise

Give the specified window keyboard focus and (optionally) raise.

Variable: *frame-indicator-text*

What appears in the frame indicator window?

Variable: *frame-indicator-timer*

Keep track of the timer that hides the frame indicator.

Variable: *frame-number-map*

Set this to a string to remap the frame numbers to more convenient keys. For instance,


would map frame 0 to 7 to be selectable by hitting the appropriate homerow key on a dvorak keyboard. Currently, only single char keys are supported. By default, the frame labels are the 36 (lower-case) alphanumeric characters, starting with numbers 0-9.

Function: gravity-coords gravity width height minx miny maxx maxy

Get the X and Y coordinates to place something of width WIDTH and height HEIGHT within an area defined by MINX MINY MAXX and MAXY, guided by GRAVITY.

Variable: *help-map*

Help related bindings hang from this keymap

Variable: *honor-window-moves*

Allow windows to move between frames.

Variable: *ignore-wm-inc-hints*

Set this to T if you never want windows to resize based on incremental WM_HINTs, like xterm and emacs.

Function: input-delete-region input start end

Delete the region between start and end in the input string

Function: input-goto-char input point

Move the cursor to the specified point in the string

Function: input-point input

Return the position of the cursor.

Function: input-substring input start end

Return a the substring in INPUT bounded by START and END.

Function: input-validate-region input start end

Return a value pair of numbers where the first number is < the second and neither excedes the bounds of the input string.

Variable: *last-command*

Set to the last interactive command run.

Function: list-directory dirname

Returns a fresh list of pathnames corresponding to the truenames of all files within the directory named by the non-wild pathname designator DIRNAME. The pathnames of sub-directories are returned in directory form - see PATHNAME-AS-DIRECTORY.

Function: lookup-command keymap command

Return a list of keys that are bound to command

Variable: *max-last-message-size*

how many previous messages to keep.

Variable: *module-dir*

The location of the contrib modules on your system.

Variable: *mouse-focus-policy*

The mouse focus policy decides how the mouse affects input focus. Possible values are :ignore, :sloppy, and :click. :ignore means stumpwm ignores the mouse. :sloppy means input focus follows the mouse; the window that the mouse is in gets the focus. :click means input focus is transfered to the window you click on.

Macro: move-to-head list elt

Move the specified element in in LIST to the head of the list.

Function: no-focus group last-win

don’t focus any window but still read keyboard events.

Variable: *numpad-map*

A keycode to keycode map to re-wire numpads when the numlock key is active

Variable: *record-last-msg-override*

assign this to T and messages won’t be recorded. It is recommended this is assigned using LET.

Variable: *resize-hides-windows*

Set to T to hide windows during interactive resize

Variable: *root-click-focuses-frame*

Set to NIL if you don’t want clicking the root window to focus the frame containing the pointer.

Macro: save-frame-excursion &body body

Execute body and then restore the current frame.

Function: set-module-dir dir

Sets the location of the for StumpWM to find modules

Function: split-string string &optional (separators

) Splits STRING into substrings where there are matches for SEPARATORS. Each match for SEPARATORS is a splitting point. The substrings between the splitting points are made into a list which is returned. ***If SEPARATORS is absent, it defaults to "[ ftnrv]+".

If there is match for SEPARATORS at the beginning of STRING, we do not include a null substring for that. Likewise, if there is a match at the end of STRING, we don’t include a null substring for that.

Modifies the match data; use ‘save-match-data’ if necessary.

Function: stumpwm &optional (display-str (or (getenv DISPLAY) :0))

Start the stump window manager.

Variable: *suppress-frame-indicator*

Set this to T if you never want to see the frame indicator.

Variable: *suppress-window-placement-indicator*

Set to T if you never want to see messages that windows were placed according to rules.

Variable: *text-color*

The color of message text.

Command: time &rest args


Variable: *timeout-frame-indicator-wait*

The amount of time a frame indicator timeout takes.

Variable: *top-level-error-action*

If an error is encountered at the top level, in STUMPWM-INTERNAL-LOOP, then this variable decides what action shall be taken. By default it will print a message to the screen and to *standard-output*.

Valid values are :message, :break, :abort. :break will break to the debugger. This can be problematic because if the user hit’s a mapped key the ENTIRE keyboard will be frozen and you will have to login remotely to regain control. :abort quits stumpwm.

Variable: *toplevel-io*

Top-level I/O loop

Function: update-decoration window

Update the window decoration.

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 (exit-on)) &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
         (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.

Macro: defcommand-alias alias original

Since interactive commands are functions and can conflict with package symbols. But for backwards compatibility this macro creates an alias name for the command that is only accessible interactively.

Macro: define-stumpwm-command name (&rest args) &body body

Deprecated. use ‘defcommand’ instead.

Variable: *executing-stumpwm-command*

True when executing external commands.

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: raise-window window

Bring the window to the top of the window stack.

Function: really-raise-window window

Really bring the window to the top of the window stack in group

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(sb-impl::comma :expr (string-capitalize command) :kind 0))))) (map (quote *top-map*)) (key (quasiquote (kbd #S(sb-impl::comma :expr (concat H- (subseq command 0 1)) :kind 0)))) (pullp nil) (pull-name (intern1 (concat (string name) -PULL))) (pull-key (quasiquote (kbd #S(sb-impl::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] [ ? ]

13.1 Menus

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

13.2 Menus

There are three different types of menus in StumpWM; single selection menus; interactive menus; and batch menus. Single-selection menus, as the name suggests, are used to pick a single item from a list. Interactive menus are used for marking multiple selections. Batch menus are used for performing actions on multiple menu items. Both batch and interactive menus share the same navigational keybindings, which are found in the table below. These can be customized by modifying the *menu-map* variable. Commands specific to each menu type can be modified by *single-menu-map* and *batch-menu-map*.


Highlight the previous menu option.


Highlight the next menu option.


Scroll the entire page down one entry.


Scroll the entire page up one entry.


Scroll up one page.


Scroll down one page.


Abort the menu.

In addition, you can customize the number of items shown at a time (a page) with the *menu-maximum-height* variable. The default value, nil, means that there is no limit to the page size.

Variable: *menu-map*

The keymap used by the interactive menu.

Function: menu-page-up menu

Move a whole page down in the menu

Function: menu-page-down menu

Move a whole page up in the menu

Function: menu-up menu

Move menu cursor up

Function: menu-down menu

Move menu cursor down

Function: menu-scroll-up menu

Scroll the menu up

Function: menu-scroll-down menu

Scroll the menu down

Function: menu-abort menu

What to do when exiting the menu without results. Must signal :menu-quit with the result.

Function: menu-backspace menu

What occurs when backspace is pressed in a menu

Function: menu-entry-apply menu-entry function

Apply FUNCTION to the data portion of the menu entry.

Function: menu-entry-display menu-entry

Generates a string suitable for displaying in a menu

Function: menu-finish menu

What to do when exiting the menu with results. Must signal :menu-quit with the result.

Function: command-menu screen items command-list &key (prompt Select:) (initial-selection 0) extra-keymap

Use batch-menu to make selections and run commands specified in command-list.

SCREEN: The screen to display the menu on.

ITEMS: The items to be shown in the list. This is expected to be a list of menu-items.

COMMAND-LIST: A list of entries defining the commands associated with each mark. Only marks that are defined are allowed in the menu. The format for these entries is (mark-character function calling-options).

Available calling-options: :single (Default) Each value is passed separately to the supplied function. :all all values selected with this mark are passed to the function in a list.

Example: ’((#d ’delete-window) (#m ’move-multiple-windows :all))

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

13.2.1 Single Selection Menus

Single selection menus can be searched; start typing when the menu is active, and the results are immediately filtered. Use <RET> to selected the highlighted option.


Select the highlighted option.

Variable: *single-menu-map*

The keymap used by single selection menus in addition to *menu-map*

Function: select-from-menu screen table &optional (prompt Search:) (initial-selection 0) extra-keymap (filter-pred (function menu-item-matches-regexp))

Prompt the user to select from a menu on SCREEN. TABLE can be a list of values or an alist. If it’s an alist, the CAR of each element is displayed in the menu. What is displayed as menu items must be strings.

EXTRA-KEYMAP can be a keymap whose bindings will take precedence over the default bindings.

FILTER-PRED should be a a function returning T when a certain menu item should be visible to the user. It should accept arguments

ITEM-STRING (the string shown to the user), ITEM-OBJECT (the object corresponding to the menu item), and USER-INPUT (the current user input). The default is MENU-ITEM-MATCHES-REGEXP. Returns the selected element in TABLE or nil if aborted.

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

13.2.2 Batch Menus

Batch menus provide a menu that allows the user to mark items. Items are marked by highlighting an item, then pressing a corresponding key. The key pressed depends on the menu being shown, and the desired action. For example, in a menu allowing users to manage windows, windows to be closed/removed could be marked by <d>, and windows to be raised could be marked by <r>. All available actions and their keybindings are shown below. These can be customized with *batch-menu-map*.


Highlight the next item.


Highlight the previous item.


Unmark the selected item, then move the cursor down.


Unmark the selected item, then move the cursor up if it is not at the top of the menu.


Exit the menu and perform the actions associated with each mark.

Variable: *batch-menu-map*

The keymap used by batch-menu menus in addition to *menu-map*

Function: select-from-batch-menu screen table &key (prompt Select:) allowed-markers (initial-selection 0) extra-keymap

Prompt the user with a menu that allows them to mark each item with a character. They can exit the menu by pressing enter, or whatever key is mapped to ’menu-finish’ in *menu-map*. Value returned is an alist, where the cdr of each entry is a list of items that were marked with that character. Note that the lisp printer cannot distinguish between ’(a . (b c d)) and ’(a b c d).

Example when "foo" and "bar" are marked with ’#d’, and "baz" is not marked: ((#d "foo" "bar") (NIL "baz")) ALLOWED-MARKERS is a list of characters. If this parameter is specified, no other markers are allowed. EXTRA-KEYMAP can be a keymap whose bindings will take precedence over the default bindings.

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

13.3 StumpWM’s Data Directory

If you want to store StumpWM data between sessions, the recommended method is to store them in ‘~/.stumpwm.d/’. StumpWM supplies some functions to make doing this easier.

Variable: *data-dir*

The directory used by stumpwm to store data between sessions.

Function: data-dir-file name &optional type

Return a pathname inside stumpwm’s data dir with the specified name and type

Macro: with-data-file (s file &rest keys &key (if-exists) &allow-other-keys) &body body

Open a file in StumpWM’s data directory. keyword arguments are sent directly to OPEN. Note that IF-EXISTS defaults to :supersede, instead of :error.

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

13.4 Debugging StumpWM

Variable: *debug-level*

Set this variable to a number > 0 to turn on debugging. The greater the number the more debugging output.

Variable: *debug-stream*

This is the stream debugging output is sent to. It defaults to *error-output*. It may be more convenient for you to pipe debugging output directly to a file.

Variable: *debug-expose-events*

Set this variable for a visual indication of expose events on internal StumpWM windows.

Function: redirect-all-output file

Elect to redirect all output to the specified file. For instance, if you want everything to go to ~/.stumpwm.d/debug-output.txt you would do:

(redirect-all-output (data-dir-file "debug-output" "txt"))

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

13.5 Sending a Bug Report

While StumpWM’s code-base is quite mature, it still contains some bugs. If you encounter one here are some guidelines for making sure the developers can fix it:

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

13.6 Timers

StumpWM has a timer system similar to that of Emacs.

Function: idle-time screen

Returns the time in seconds since idle according to the root window of the ‘screen’.

Function: run-with-timer secs repeat function &rest args

Perform an action after a delay of SECS seconds. Repeat the action every REPEAT seconds, if repeat is non-nil. SECS and REPEAT may be reals. The action is to call FUNCTION with arguments ARGS.

Function: cancel-timer timer

Remove TIMER from the list of active timers.

Function: timer-p timer

Return T if TIMER is a timer structure.

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

13.7 Getting Help

Command: describe-key keys

Either interactively type the key sequence or supply it as text. This command prints the command bound to the specified key sequence.

Command: describe-variable var

Print the online help associated with the specified variable.

Command: describe-function fn

Print the online help associated with the specified function.

Command: describe-command com

Print the online help associated with the specified command.

Command: where-is cmd

Print the key sequences bound to the specified command.

Command: modifiers

List the modifiers stumpwm recognizes and what MOD-X it thinks they’re on.

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

This document was generated by Raimon Grau on May 28, 2019 using texi2html 1.82.