1. Introduction

StumpWM is a manual, tiling X11 window manager written entirely in Common Lisp. Unlike traditional window managers, StumpWM places windows in order to maximize the amount of the screen used. The window layouts managed by StumpWM are defined by the user in much the same way that windows are managed by GNU screen, or emacs.

Before StumpWM, there was ratpoison, another tiling window manager written entirely in C. StumpWM grew out of the authors’ frustration with writing ratpoison in C. Very quickly we realized we were building into ratpoison lispy-emacs style paradigms. StumpWM’s goals are similar to ratpoison’s but with an emphasis on customizability, completeness, and cushiness.

1.1 Starting StumpWM

There are a number of ways to start StumpWM but the most straight forward method is as follows. This assumes you have a copy of the StumpWM source code and are using the ‘SBCL’ Common Lisp environment.

1. Install the prerequisites and build StumpWM as described in ‘README’. This should give you a ‘stumpwm’ executable.
2. In your ‘~/.xinitrc’ file include the line /path/to/stumpwm. Remember to replace ‘/path/to/’ with the actual path.
3. Finally, start X windows with startx. Cross your fingers. You should see a ‘Welcome To the Stump Window Manager’ message pop up in the upper, right corner. At this point, you have successfully started StumpWM.

1.2 Basic Usage

Once you have StumpWM up and running, the first thing you might want to do is start emacs. Type C-t e, or in other words Control + t followed by e. Now perhaps you want an xterm. Type C-t c. Now you have some programs running.

To see a list of windows StumpWM is managing, type C-t w. The highlighted window is the one you’re looking at right now. It’s the focused window.

All of StumpWM’s keys are bound to named commands, which can be executed not only by keys but also from the input bar. Type C-t ; to open a command prompt. Now type time and press return. Note, time can also be called by typing C-t a. Throughout this manual you’ll find definitions for commands, functions, and variables. Any command you see in this manual can be executed from the input bar or bound to a key.

At this point you probably want to switch back from your new xterm to emacs. Type C-t C-t. This runs the other command. Type it again and you’re back to xterm.

Perhaps you’d like to see emacs and xterm side-by-side. Type C-t s. You have now split the screen into 2 frames. For more information see Frames. To switch to the empty frame type C-t TAB. Now let’s pull the xterm window into this empty frame. Type C-t w for a window listing. Find the xterm window. See the number beside it? Type C-t followed by xterm’s window number.

Another common activity is browsing the internet. Type C-t !. The input bar pops up again. You can now run a shell command. Let’s start a web browser: type firefox into the input bar and press return.

Unfortunately, firefox probably isn’t wide enough because it’s in one of the frames. Type C-t Q to remove all frames but the current one and resize it to fit the screen.

For a full list of key bindings, see List of Default Keybindings.

1.3 Basic Concepts

An introduction to some of the basic concepts used by StumpWM.

1.3.1 Screens and Heads

A screen is an Xlib concept representing a section of video memory onto which physical monitors, called “heads”, are mapped. A screen can be thought of as an abstract rectangle containing all the heads arranged in a particular layout.

With most modern systems, you’ll only have a single screen no matter how many heads are connected to your computer. Each head will have its own frame, and you can move between heads using the normal frame movement commands.

The layout of the heads within the screen can be specified in one of two ways: either at startup using your system’s Xorg configuration files, or on the fly using tools like XRandR. If the computer is booted with multiple monitors attached, but without specifying a layout for them, they will all show identical output.

StumpWM will attempt to detect the layout of the heads once at startup, or any time a RandR command is issued.

In rarer setups you may have multiple screens, with one head per screen. That means that you’ll move between heads using screen movement commands (‘snext’, ‘sprev’, and ‘sother’) rather than frame movement commands.

1.3.2 Group Basics

A group is usually referred to as a “desktop” or “workspace” in other window managers. StumpWM starts with a single group, called “Default”. Each group has its own configuration of frames and windows that is separate from and independent of other groups. You can’t have different groups display in different monitors: when you switch groups, all monitors switch to that group.

Each group contains an ordered list of frames.

1.3.3 Floating Group Basics

Within a floating group, windows behave more like they do in traditional window managers: rather than being arranged into frames, they each have their own box, which can be freely resized and repositioned, and allowed to overlap. Each window has a thicker border at the top. Left click in this border and drag to move the window, or right click and drag to resize it.

Most of the window-switching commands listed below do not function in a floating group. You’re restricted to ‘other’, the ‘select-window-*’ commands, and ‘windowlist’.

1.3.4 Frame Basics

Frames are the boxes within which windows are displayed. StumpWM starts with a single frame per head, meaning that each monitor shows a single window, full screen. If you want to see windows side-by-side, you can “split” this frame in two, either vertically or horizontally. These frames can be further split, creating nested boxes.

Technically speaking, frames live within a “frame tree”. When you split a frame, the command actually creates two new frames side-by-side within the original parent frame. This makes no practical difference, unless you use the ‘sibling’ command, which will move to the other child frame within the parent frame.

Within this frame tree model, all frames either contain other frames, or windows. The command ‘fclear’ will hide all a frame’s windows and show the background.

1.3.5 Window Basics

Windows are created by programs to display their output. They take the shape of the frame in which they are created. The windows within a frame are ordered by how recently that window was focused. Only the top window in the stack is visible.

1.3.6 System Trays and the Mode Line

Many users choose to sacrifice a little screen real-estate to display some generally useful information: the current time and date, wireless network connections, the names of open windows, etc. StumpWM allows you to display this information in a bar across either the top or the bottom of the screen. There are two ways to do this: using external programs called system trays, or using StumpWM’s own mode line.

System trays are a special kind of X window. They advertise to running programs that they are available for embedding icons or notifications from those programs. They often also display clickable icons for each open window. Common tray programs include the GNOME panel or KDE’s kicker, or simpler programs such as stalonetray. Simply starting one of these programs is usually enough for StumpWM to detect it, place it correctly, and allow it to function normally.

The mode line, a concept borrowed from Emacs, is a built-in part of StumpWM. It is essentially a string of text that can include a variety of information about your current session, including the names of current groups and windows. Several modules provide for different types of information. See section Mode Line, (and the modules directory) for more.

1.4 Manipulating Frames and Windows

Frames and windows are concepts borrowed from Emacs and the GNU Screen program, and should be familiar to users of those programs. Others may find the terms a little confusing. In other window managers, a “window” usually refers to a bounded box on the screen, showing output from a single program. StumpWM splits this into two concepts: the “frame” is the bounded box, the “window” is the visible output of a program.

One frame can contain many windows. As new windows are created, they appear at the top of the window-stack of the current frame. This is also a little different from other tiling window managers, many of which automatically create new frames for new windows.

Both frames and windows are ordered by when they were last focused. In the following commands and documentation, the terms “next” and “previous” refer to this order. “Other” refers to the most-recently focused object. Calling “other” commands multiple times will bounce back and forth between the two most recent objects.

By default, StumpWM starts with a single group, called “Default”, which contains one full-screen frame per head. You can split individual frames horizontally or vertically using the ‘hsplit’ and ‘vsplit’ commands, bound to “C-t S” and “C-t s” by default. When a frame is split, the next-most-recently-focused window is pulled into the new frame. See section Frames, and Windows, for a complete listing of commands.

1.4.1 Moving Between Frames

Once you have multiple frames, you can move between them in various ways:

• fnext (C-t o or C-t TAB) jumps to the next frame in the current group’s frame list.
• fother (C-t M-TAB) jumps to the last frame that had focus.
• fselect (C-t f) displays numbers on each visible frame: hit a number key to move to that frame.
• move-focus (C-t <arrow key>) focus the frame in the direction of the arrow key pressed.
• sibling (unbound by default) focus the frame from which the current frame was split.

1.4.2 Manipulating Windows

Some commands change which window is currently focused, some move windows between frames, and some may do both at once.

There are two general ways to move focus between windows: either between windows belonging to the current frame, or between all windows within the current group. Within a single frame:

• next-in-frame (C-t C-M-n) focus the next window in the current frame’s list of windows.
• prev-in-frame (C-t C-M-p) focus the previous window in the current frame’s list of windows.
• other-in-frame (C-t M-t) focus the most recently focused window in the current frame’s list of windows.
• frame-windowlist (unbound by default) display a menu of windows in the currently-focused frame, and allow the user to choose one. Alternately, the command frame-windows will simply display the list of window names, with no menu choice available.

Within the current group, the following commands will go straight to the specified window. They will never move a window from its original frame, and so may result in focus switching frames.

• next (C-t M-n) focus the next window in the current group.
• prev (C-t M-p) focus the previous window in the current group.
• other or other-window (unbound by default) focus the most recently focused window in the current group.
• next-urgent (C-t C-u) focus the next window that has marked itself “urgent”.
• select or select-window (C-t ') prompt for the title of a window and focus it. Works with partial completion of the title.
• select-window-by-name (unbound by default) prompt for the title of a window and focus it. Requires the window title to be entered exactly.
• select-window-by-number (C-t <number>) choose a window by number.
• windowlist (“C-t "") display a menu of windows in the currently-focused group, and allow the user to choose one.

The following commands always keep the current frame focused. If the selected window is not in the current frame, it will be pulled there from wherever it is (hence the “pull” naming scheme).

• pull or pull-window-by-number (C-t C-<number>) pull the numbered window into the current frame.
• pull-hidden-next (C-t n or C-t SPC) pull the next currently undisplayed window in the window list into the current frame.
• pull-hidden-previous (C-t p) pull the previous currently undisplayed window in the window list into the current frame.
• pull-hidden-other (C-t C-t) pull the most recently focused, currently undisplayed window into the current frame.

The following commands move the current window from one frame to another, bringing focus with them.

• move-window (C-t M-<arrow>) move the currently focused window in the direction indicated by the arrow key.
• exchange-direction (unbound by default) prompt for a direction, then swap the currently focused window with the top window of the frame in that direction.

1.5 Interacting with the Lisp process

Since StumpWM is a Lisp program, there is a way for you to evaluate Lisp code directly, on the same Lisp process that StumpWM is running on. Type C-t : and an input box will appear. Then type some Lisp expression.

When you call eval this way, you will be in the STUMPWM-USER package, which imports all the exported symbols from the main STUMPWM package.

*mode-line-border-width*

Reads the value of *mode-line-border-width*.

(setf *mode-line-border-width* 3)

Sets the variable *mode-line-border-width* to 3.

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

Calls the set-prefix-key function (and sets a new keyboard prefix)

1.6 Init File

Like other window managers, StumpWM’s configuration and startup state can be controlled by an initialization file. Unlike other window managers, StumpWM’s init is not limited to changing settings and keybindings. The init file is itself a Common Lisp program running in a Common Lisp environment, so you can write your own hacks and make them a part of your StumpWM experience.

On launch, StumpWM searches for an init file of different names and locations on your system, and will use the first one found in this order:

• ‘~/.stumpwmrc’ is the classic UNIX-style configuration name;
• ‘~/.stumpwm.d/init.lisp’ is an Emacs-style location and name;
• ‘~/.config/stumpwm/config’ is the XDG standard;
• ‘/etc/stumpwmrc’ is a system-wide file giving all users a standardized environment.

StumpWM includes a basic ‘sample-stumpwm.lisp’ in its source directory. You can use this as a template when you’re starting out: copy it to the above name and location you prefer and edit it to suit your preferences.

It is possible to split your initialization among multiple files, if you call the additional files from within an init file matching the names and locations listed above.

1.7 Contact the StumpWM developers

The StumpWM home page is http://stumpwm.nongnu.org/.

The StumpWM mailing list is stumpwm-devel@nongnu.org which you can subscribe to at https://lists.nongnu.org/mailman/listinfo/stumpwm-devel. It is the preferred way of contacting developers for questions. If you have a bug report or patch, please open an issue or pull request at https://github.com/stumpwm/stumpwm/issues.

The StumpWM IRC channel can be found on Freenode at #stumpwm.

This document was generated by David Bjergaard on January 12, 2017 using texi2html 1.82.