Goomwwm: Tutorial

First Steps

Below, we will refer to the Mod key. By default, this means Mod4 which is usually the left Windows key. When we say Mod-key, it means first press and hold down Mod, then press key, then release both.

The Default Screen

After starting goomwwm, you should see a blank screen! A small greeting message will appear in the bottom right corner to let you know goomwwm is alive.


There are no built-in panels, icons, or desktop menus. The screen background is not set by goomwwm either; it will be the default X cross hatch pattern or whatever desktop graphic was placed there by your login manager.

In the screenshots here, the X background was made plain black and the mouse pointer nicer by running:

xsetroot -solid black
xsetroot -cursor_name left_ptr

This sort of thing is often done in .xinitrc beforehand.

Launching an Application

Pres Mod-x. A dmenu window will appear at the top of the screen and list every application in your $PATH.


Start typing the name of an application you wish to start, for example xterm. As you type, dmenu will reduce the list of options to show only those containing the characters you have input. Once the list is small enough, use the arrow keys to select the correct application. Finally, press the return (or enter) key to start the selected application.


Start another xterm window. Notice that the active window with keyboard focus has a blue border while inactive windows have a gray border. This is all the decoration windows ever get, except for a some small coloured squares you might spot flashing briefly in window corners; these are just a visual feedback aid.

To close the active window, use Mod-Escape.

Switching Windows

Popup Switcher

Obviously you can use the mouse to click on any window to activate and raise it, just like most popular stacking window managers. For keyboard based window switching many environments use Alt-Tab to switch via some sort of visual most-recently-used list. goomwwm uses Mod-Tab to give you a window list which can be used in a similar way to dmenu: you can type to filter the list, use the arrow keys to navigate, and press return to select a window.


Fast Switching

Other Switching

You're also free to use your favourite EWMH-friendly panel, dock, or taskbar. These should work normally with goomwwm.

For yet more window switching options, see the man page, specifially, the -1 through -9 command line options.

Moving Windows

As with any stacking window manager, the mouse can be used to move windows. But, since goomwwm has no title bars to grab, we must use the Mod key with the mouse buttons. Press Mod-Button1 on the xterm window and drag it around.

Basic 3x3 Grid

Great, so the mouse works! But, goomwwm's strength lies with the keyboard. Play with Mod-Left and Mod-Right (the arrow keys). The xterm should move horizontally across the screen. Notice that the three positions are aligned-left, centered, and aligned-right.

screenshot screenshot screenshot

As you may have guessed, Mod-Up and Mod-Down do the same vertically.

screenshot screenshot screenshot

If you have a multi-head setup, the same Mod-Left/Right/Up/Down will move windows between monitors.

Snap to Edges

Open two or more xterm windows and play with Mod-Shift-Left/Right/Up/Down. The active window should move around snapping to the edges of other windows and the screen. Notice that both leading and trailing edges of the active window will snap in turn.

screenshot screenshot screenshot

Window layout changes can be undone with Mod-u, up to ten steps back. If you make a mistake, just undo it.

Resizing Windows

Growing and Shrinking

Using the mouse again: Mod-Button3 will resize a window however you like.

Using the keyboard, center the xterm and try Mod-PageUp and Mod-PageDown. The xterm should grow through four basic sizes:

screenshot screenshot screenshot

You can imagine full screen, right? :-)

Combine these sizes with moving around the 3x3 grid. You might notice some window tiling starting to happen, but we'll get to that below...

If you need even finer incremental resizing, try out Mod-Shift-PageUp and Mod-Shift-PageDown.

Horizontal and Vertical Maximizing

Resize the xterm to 1/4th screen size and center it. Now press Mod-End several times. The xterm should toggle between its current width and maximum width.

screenshot screenshot

Of course, Mod-Home does the same for maximum height:

screenshot screenshot

Now try growing and shrinking the xterm while H-max or V-max is active. Notice how the maximized states are respected, allowing new combinations of width and height.

You might notice more coloured squares flashing in window corners when toggling settings. Green means on. Red means off.

Horizontal and Vertical Tiling

Bouncing windows around the 3x3 grid and using the fixed size increments allows a simple form of window tiling. But, sometimes more complex layouts are needed. Start two xterm windows of the same size and place them in the same position on screen. Now press Mod-h. The windows horizontally tile within the same space:

screenshot screenshot

The same may be done for vertical tiling with Mod-v. Reverse tiling -- untiling? -- can be done with Mod-Shift-h/v.

Tiling is not just limited to two windows: any number of windows with the same tag, position, and size will tile.

Expanding and Contracting

The secret weapon for more complex tiling is window expansion and contraction. Start two xterm windows and place them in different, non-overlapping positions. Focus one, and press Mod-Return (enter key). The xterm should expand to fill the surrounding empty space.

screenshot screenshot

This works for any number of windows with just one rule: windows that are fully visible will not be obscured. Windows that are partially obscured are considered empty space, and may be covered by the expanded window.

Contracting a window with Mod-BackSpace is a litter trickier. The window will shrink until it finds a contiguous empty space within its original area. If it completely obscures the empty space initially, you may have to roughly center it over the gap.

screenshot screenshot

Windows can also be duplicated. Place the active window over another and press Mod-d; it will resize to match.

Swapping Positions

Pure-tiling window managers generally have some way of quickly swapping windows between tiles. This makes it easy to have a large master area and a smaller stacking area, and to swap windows in and out of the master area.

Goomwwm can do this too, but without requiring strict tiling layouts. Open two windows, make them different sizes, and tile them edge to edge. Now experiment with Mod-Shift-i/j/k/l treating i/j/k/l like arrow keys. The two windows will swap their positions and sizes.

screenshot screenshot

This also works like a toggle in most cases; ie, swapping back should choose the same two windows.

Splitting the Screen

Besides fanatical neatness, there are two common reasons to tile windows:

  1. Comparing two windows side by side (documents, web pages, images, etc). Usually a 50/50 screen split is needed because both windows are equally important.
  2. Working on a main task while monitoring one or more secondary tasks. In this case a 66/34 screen split is nicer allowing more space for the main task.

It also seems likely that most people split their screen horizontally because of our modern wide-screen monitors.

Try out Mod-[ (left square bracket) and Mod-]. These keys make the active window large (66% screen width), vertically maximized, and place it on the left and right respectively. Because V-max is turned on, Mod-PageUp and PageDown can then be used to quickly change the width. An easy way to start off your tiling layout!

Putting it all together!

The following layouts were created entirely using the keyboard. Once you get used to the controls, the process is at least as fast as most manual tiling window managers, and probably much faster than anything you can do with the mouse.

screenshot screenshot screenshot screenshot

Who ever thought a stacking window manager couldn't tile? :-)

Window Tagging

Tagging windows in goomwwm is quite similar to the way dwm does it. It's a method of grouping windows so they can be raised en masse, and particularly effective because windows can be in more than one tag. EWMH pagers see tags as desktops, which is actually a perfectly fine way to think about and use them at first, but you will soon notice differences, and possibilities!

There are nine numeric tags selected by Mod-F1 through Mod-F9. There is always a current tag which is simply the last one you selected. New windows get automatically assigned to the current tag. Mod-t toggles a window's membership of the current tag.

Raising tags, unlike desktops, simply raises all windows in the tag group without hiding everything else. Use Mod-o to show only windows in the current tag.

Config File

All goomwwm options can be specified on the command line, so a config file can be as simple as a bash script. But, for convenience, goomwwm will also look for and load ~/.goomwwmrc at startup.

Config file format is as follows:

For example, consider the following command line:

goomwwm -border 3 -modkey "control,mod1" -1 firefox -2 konsole

The equivalent config file would be:

border 3
modkey control,mod1
1 firefox
2 konsole

For all possible options and arguments, see the man page.

Window Rules

Rules allow windows to be automatically configured when they first start, such as:

Rules match windows based on WM_CLASS, application name, or window title.


firefox always in tag 9:

goomwwm -rule "firefox tag9"

xterm covering the right half of the screen:

goomwwm -rule "xterm right,medium,maximize_vert"

pidgin never stealing focus and stacking on the bottom right:

goomwwm -rule "pidgin block,bottom,right,small"

xfce4-notifyd alerts never managed nor stealing focus:

goomwwm -rule "xfce4-notifyd ignore"

See the man page for a list of all available rules.

Sloppy Focus

By default, goomwwm uses click-to-focus. To use sloppy focus mode, start goomwwm with:

goomwwm -focusmode sloppy

This changes behavior in three ways:

  1. Focus changes when the mouse pointer enters a window.
  2. Windows do not automatically raise on focus. You have to Mod-Click to raise a window.
  3. When using keyboard driven focus changes, the mouse pointer will warp to the active window.

There is also a variant to limit focus change to the current tag:

goomwwm -focusmode sloppytag

To customize this behavior further, see the man page.