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 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 all 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 run 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 (along with *group-root-map* and either *tile-group-root-map* or *float-group-root-map*). 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.

Variable: *exchange-window-map*

The keymap that exchange-window key bindings sit on. It is bound to C-t x by default.

Command: bind key command

Hang a key binding off the escape key.

Command: send-escape

Send the escape key to the current window.

Function: grab-pointer screen

Grab the pointer and set the pointer shape.

Function: ungrab-pointer

Remove the grab on the cursor and restore the cursor shape.

Variable: *banish-pointer-to*

Where to put the pointer when no argument is given to (banish-pointer) or the banish command. May be one of :screen :head :frame or :window

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 settings daemon from one of the major desktop environments (Gnome,KDE, or Unity) you may be able to set keyboard modifiers from their respective configuration GUIs. If not, xmodmap should always work if invoked at the right place.

• 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*.

Variable: *all-modifiers*

A list of all keycodes that are considered modifiers

Variable: *modifiers*

A mapping from modifier type to x11 modifier.

2.4 Remapped Keys

StumpWM may be configured to translate certain familiar top level keybindings to alternative key sequences that are understood by specific applications. For example, Emacs users are very familiar with C-n and C-p as keybindings for scrolling down and up one line at a time. However, most applications use these specific keybindings for other actions. The stumpwm:define-remapped-keys function may be used to define such application specific remapping of keybindings.

Function: define-remapped-keys specs

Define the keys to be remapped and their mappings. The SPECS argument needs to be of the following structure:

(regexp-or-function . (("key-to-remap" . <new-keycodes>) ...))

EXAMPLE: (define-remapped-keys ’(("Firefox" ("C-n" . "Down") ("C-p" . "Up") ("C-k" . ("C-S-End" "C-x")))))

The above form remaps Ctrl-n to Down arrow, and Ctrl-p to Up arrow keys. The Ctrl-k key is remapped to the sequence of keys Ctrl-Shift-End followed by Ctrl-x.

(define-remapped-keys
    '(("(Firefox|Chrome)"
       ("C-n"   . "Down")
       ("C-p"   . "Up")
       ("C-f"   . "Right")
       ("C-b"   . "Left")
       ("C-v"   . "Next")
       ("M-v"   . "Prior")
       ("M-w"   . "C-c")
       ("C-w"   . "C-x")
       ("C-y"   . "C-v")
       ("M-<"   . "Home")
       ("M->"   . "End")
       ("C-M-b" . "M-Left")
       ("C-M-f" . "M-Right")
       ("C-k"   . ("C-S-End" "C-x")))))

The above form adds Emacs like keybindings to windows whose window-class matches “Firefox” or “Chrome”. Additional application specific bindings may be included by using the specific X window-class values.

The window matching pattern can also be specified as a function which returns T if the focused window matches.

;; Match any window with a window-class matching "Firefox"
(define-remapped-keys
    `((,(lambda (win)
          (string-equal "Firefox" (window-class win)))
       ("C-n"   . "Down")
       ("C-p"   . "Up")
       ("C-f"   . "Right")
       ("C-b"   . "Left")
       ("C-v"   . "Next")
       ("M-v"   . "Prior")
       ("M-w"   . "C-c")
       ("C-w"   . "C-x")
       ("C-y"   . "C-v")
       ("M-<"   . "Home")
       ("M->"   . "End")
       ("C-M-b" . "M-Left")
       ("C-M-f" . "M-Right")
       ("C-k"   . ("C-S-End" "C-x")))))

2.4.1 Circumventing Remapped Keys

However, if the original key binding needs to be explictly applied the send-raw-key command may be used. It will prompt for a key which will be passed to the application as-is. For example, if the send-raw-key command were bound to C-t C-q as follows:

(define-key *root-map* (kbd "C-q") "send-raw-key")

Then, pressing C-t C-q, while the Firefox window has focus, would prompt asking for “Press a key to send”. Pressing C-n at the prompt will send the keystroke as-is to Firefox, causing it to open a new window.

Command: send-raw-key

Prompts for a key and forwards it to the CURRENT-WINDOW.

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