2. Key Bindings

StumpWM is controlled entirely by keystrokes and Lisp commands. It mimics GNU Screen’s keyboard handling. StumpWM’s default prefix key is C-t.

2.1 List of Default Keybindings

The following is a list of keybindings.

C-t d

Select the window with the corresponding digit d

C-t C-d

Pull the window with the corresponding digit d into the current frame

C-t n

C-t C-n

C-t Space

Go to the next window in the window list

C-t p

C-t C-p

Go to the previous window in the window list

C-t '

Go to a window by name

C-t "

Select a window from a list and focus the window.

C-t C-g

Abort the current command. This is useful if you accidentally hit C-t

C-t w

List all the windows

C-t i

Display information about the current window.

C-t f

Select a frame by number

C-t s

Split current frame vertically

C-t S

Split current frame horizontally

C-t k

C-t C-k

Sends a kill message to the current frame and the running program.

C-t K

Kills the current frame and running program; like a kill -9.

C-t c

C-t C-c

Run an X terminal; by default xterm

C-t e

C-t C-e

Run Emacs or raise it if it is already running.

C-t t

Sends a C-t to the frame; this is useful for applications like Firefox which make heavy use of C-t (in Firefox’s case, for opening a new tab). This is similar to how GNU screen uses C-a a.

C-t w

C-t C-w

Prints out a list of the windows, their number, and their name.

C-t b

C-t C-b

Banish the mouse point to the lower right corner of the screen.

C-t a

C-t C-a

Display the current time and date, much like the Unix command date.

C-t C-t

Switch to the last window to have focus in the current frame.

C-t !

Prompt for a shell command to run via ‘/bin/sh’. All output is discarded.

C-t R

If the screen is split into multiple frames, one split will be undone. If there is only one split, the effect will be the same as C-t Q.

C-t o

C-t TAB

If the screen is split into multiple frames, focus shifts to the next frame, where it cycles to the right and then down; analogous to C-x o in Emacs.

C-t F

Display “Current Frame” in the frame which has focus.

C-t ;

Opens the input box. StumpWM commands can be run from here, and the input history moved through.

C-t :

Opens the input box, but all things typed in here will be sent to the Common Lisp interpreter where they will be ran as Lisp programs; thus, input should be valid Common Lisp.

C-t C-h

C-t ?

The help.

C-t -

Hide all frames and show the root window.

C-t Q

Removes all splits and maximizes the frame with focus.

C-t Up

C-t Down

C-t Left

C-t Right

Shift focus to an adjacent frame in the specified direction. C-t Up will shift focus up, if possible, C-t Down will shift downwards, etc.

C-t v

Prints out the version of the running StumpWM.

C-t #

Toggle the mark on the current window

C-t m

C-t C-m

Display the last message. Hitting this keybinding again displays the message before that, and so on.

C-t l

C-t C-l

redisplay the current window and force it to take up the entire frame.

C-t G

Display all groups and windows in each group. For more information see Groups.

C-t Fn

Jump to the corresponding group n. C-t F1 jumps to group 1 and so on.

C-t g g

Show the list of groups.

C-t g c

Create a new group.

C-t g n

C-t g C-n

C-t g SPC

C-t g C-SPC

Go to the next group in the list.

C-t g N

Go to the next group in the list and bring the current window along.

C-t g p

C-t g C-p

Go to the previous group in the list.

C-t g P

Go to the previous group in the list and bring the current window along.

C-t g '

Select a group by name or by number.

C-t g "

Select a group from a list and switch to it.

C-t g m

Move the current window to the specified group.

C-t g k

Kill the current group. All windows are merged into the next group.

C-t g A

C-t g r

Change the current group’s name.

C-t g d

Go to the group with digit d. C-t g 1 jumps to group 1 and so on.

C-t +

Make frames the same height or width in the current frame’s subtree.

C-t h k

Describe the specified key binding.

C-t h f

Describe the specified function.

C-t h v

Describe the specified variable.

C-t h w

List all key sequences that are bound to the specified command

C-t h c

Describe the specified command.

2.2 Binding Keys

Function: define-key map key command

Add a keybinding mapping for the key, key, to the command, command, in the specified keymap. If command is nil, remove an exising binding. For example,

(stumpwm:define-key stumpwm:*root-map* (stumpwm:kbd "C-z") "echo Zzzzz...")

Now when you type C-t C-z, you’ll see the text “Zzzzz...” pop up.

Function: undefine-key map key

Clear the key binding in the specified keybinding.

Function: kbd keys

This compiles a key string into a key structure used by ‘define-key’, ‘undefine-key’, ‘set-prefix-key’ and others.

Command: set-prefix-key key

Change the stumpwm prefix key to KEY.

(stumpwm:set-prefix-key (stumpwm:kbd "C-M-H-s-z"))

This will change the prefix key to <Control> + <Meta> + <Hyper> + <Super> + the <z> key. By most standards, a terrible prefix key but it makes a great example.

Function: make-sparse-keymap

Create an empty keymap. If you want to create a new list of bindings in the key binding tree, this is where you start. To hang frame related bindings off C-t C-f one might use the following code:

(defvar *my-frame-bindings* (let ((m (stumpwm:make-sparse-keymap))) (stumpwm:define-key m (stumpwm:kbd "f") "curframe") (stumpwm:define-key m (stumpwm:kbd "M-b") "move-focus left") m ; NOTE: this is important )) (stumpwm:define-key stumpwm:*root-map* (stumpwm:kbd "C-f") '*my-frame-bindings*)

Variable: *root-map*

This is the keymap by default bound to C-t. It is known as the prefix map.

Variable: *top-map*

The top level key map. This is where you’ll find the binding for the prefix map.

Variable: *groups-map*

The keymap that group related key bindings sit on. It is bound to C-t g by default.

Command: bind key command

Hang a key binding off the escape key.

2.3 Modifiers

Many users have had some difficulty with setting up modifiers for StumpWM keybindings. This is caused by a combination of how StumpWM handles modifiers and the default modifiers list for many users’ X servers.

• My “Super” key doesn’t work!

  This is most likely caused by having the Hyper and Super keys listed as the same modifier in the modifier list.

  $ xmodmap xmodmap: up to 3 keys per modifier, (keycodes in parentheses): shift Shift_L (0x32), Shift_R (0x3e) lock Caps_Lock (0x42) control Control_L (0x25), Control_R (0x6d) mod1 Alt_L (0x40), Alt_R (0x71), Meta_L (0x9c) mod2 Num_Lock (0x4d) mod3 mod4 Super_L (0x7f), Hyper_L (0x80) mod5 Mode_switch (0x5d), ISO_Level3_Shift (0x7c)

  The problem is in the line beginning with “mod4”. The way to set up the modifier list correctly is to have just the Super key as the mod4 modifier. The following xmodmap commands will do just that.

  # clear out the mod4 modifier $ xmodmap -e 'clear mod4' $ xmodmap xmodmap: up to 3 keys per modifier, (keycodes in parentheses): shift Shift_L (0x32), Shift_R (0x3e) lock Caps_Lock (0x42) control Control_L (0x25), Control_R (0x6d) mod1 Alt_L (0x40), Alt_R (0x71), Meta_L (0x9c) mod2 Num_Lock (0x4d) mod3 mod4 mod5 Mode_switch (0x5d), ISO_Level3_Shift (0x7c) # add Super as a mod4 modifier $ xmodmap -e 'add mod4 = Super_L' $ xmodmap xmodmap: up to 3 keys per modifier, (keycodes in parentheses): shift Shift_L (0x32), Shift_R (0x3e) lock Caps_Lock (0x42) control Control_L (0x25), Control_R (0x6d) mod1 Alt_L (0x40), Alt_R (0x71), Meta_L (0x9c) mod2 Num_Lock (0x4d) mod3 mod4 Super_L (0x73), Super_L (0x7f) mod5 Mode_switch (0x5d), ISO_Level3_Shift (0x7c)

  You can automate this by storing the commands in a file and calling xmodmap when you start your X session.

  $ cat ~/.Xmodmap clear mod4 add mod4 = Super_L

  If you use startx, modify your ‘~/.xsession’ or ‘~/.xinitrc’ file.

  $ cat ~/.xsession #!/bin/sh xmodmap ~/.Xmodmap exec /usr/bin/stumpwm

  If you use a graphical login manager (GDM, KDM, etc.), your ‘~/.Xmodmap’ file should be fed to xmodmap when you log in. FIXME: verify this.

• Handling Meta and Alt: when do I use M- and A-?

  If you have no Meta keys defined (see the output of the xmodmap command), then StumpWM will treat the M- prefix in keybindings to mean Alt. However, if there are Meta keys defined, then the M- prefix refers to them, and the A- prefix refers to Alt.

  Most users will simply use M- to refer to their Alt keys. However, users that define separate Meta and Alt keys will use M- to refer to the former, and A- to refer to the latter.

• How can I set up a Hyper key and use it with StumpWM?

  To set up a Hyper key, you need to do two things: bind a physical key to be a Hyper key, and add that key to the modifiers list.

  The following example shows how to bind the control key at the bottom-left of most keyboards to be Hyper. This is useful if you’ve made Caps Lock into a control key, and have no use for the bottom-left key.

  $ xmodmap -e 'keycode 37 = Hyper_L' $ xmodmap -e 'clear mod5' $ xmodmap -e 'add mod5 = Hyper_L'

  To use a different key for Hyper, replace the keycode “37” above. Use the xev program to see the keycode that any physical key has. Refer to the section above on setting up the Super key to see how to automate setting the Hyper key when you start X.

  Now you can use H- as a prefix in StumpWM bindings.

  (define-key *top-map* (kbd "H-RET") "fullscreen") (define-key *top-map* (kbd "H-Left") "gprev") (define-key *top-map* (kbd "H-Right") "gnext") (define-key *top-map* (kbd "H-TAB") "other")

  Since essentially no programs have Hyper bindings, you can safely bind commands to the *top-map*.

This document was generated by David Bjergaard on November 1, 2014 using texi2html 1.82.