Revision as of 23:00, 12 January 2011

This document assumes you're running >= XMonad-0.8.

It describes general tips for configuring xmonad.hs, for example "How to make window X float by default" and others. If you can't find what you're searching for, you may want to look at the Config archive or ask for help on #xmonad@irc.freenode.net.

Also useful, for an overview of how to configure bindings and hooks, and (somewhat out of date) summary of xmonad-contrib extensions, see XMonad.Doc.Extending.

Please add what you found useful, and of course improving existing tips or adding alternatives is highly appreciated!

1 Managing Windows aka Manage Hooks

ManageHooks define special actions to be performed on newly created windows matching specific properties.

1.1 Making window float by default, or send it to specific workspace

1.1.1 ManageHook examples

This example shifts Rythmbox to workspace "=" and XDvi to "7:dvi", floats Xmessage, and uses manageDocks to make docks visible on all workspaces. All this is combined with the default xmonad manageHook. This step-by-step tutorial covers initially setting up a manageHook, too.

This example sends Firefox to workspace "web" when it starts. Gajim gets sent to workspace "jabber". Finally, it floats Firefox dialog windows, Gajim and Xmessage windows, and windows with Google or Pidgin as any part of the class name, likewise any window with "VLC" anywhere in its title.

1.1.5 More info about ManageHooks

1.2 Gimp

The most popular gimp setups with xmonad are the default of floating all gimp windows, or using two nested Layout.IM modifiers to put the toolbox and dock panels to either side of some other layout like tabbed or (MyFavoriteTilingLayout ||| Full), plus usually floating tool dialogs with manageHooks. Some people combine the toolbox and dock into a single panel. See sample configs below.

1.2.1 Gimp windows as seen by xmonad

To choose how to work with the gimp in xmonad it's helpful to understand
the different types of windows as xmonad sees them. If you just want
some example setups, skip to the next section.

All gimp windows, i.e. those with WM_CLASS class of "Gimp". These windows float if you have

manageHook defaultConfig

anywhere in your manageHook. You probably don't want this if you plan to tile even the gimp tool setting dialogs. Otherwise keep the

manageHook defaultConfig

, and only unfloat the gimp-toolbox, gimp-image-window, and possibly gimp-dock.

Transient or fixed size windows, like file open, ok/cancel, fixed size tool dialogs, etc. XMonad floats these by default for all applications, even without using

manageHook defaultConfig

. If you really want to you can unfloat specific transients or fixed size windows -- see unfloat above.

Gimp toolbox or dock(s), matched with WM_WINDOW_ROLE(STRING) to use layoutHooks or manageHooks to place and manage them. Also, with drag and drop you can combine or separate their tabs and panes into one or more windows depending on how you want to use them.

On startup, a default gimp install creates (1) an empty image window, (2) the toolbox window (brushes, eraser, etc. and their options), and (3) a single dock (layers, paths, etc.) Customize them by dragging tabs to and from existing panels or onto the "create panel separator" on either type of window, (it will highlight when a dragged tab is over it). (It's just below the fg/bg color swatches on the toolbox window.)

Gimp tool windows, matched by suffix "tool" with WM_WINDOW_ROLE(STRING). (Or with darcs xmonad (0.9) use isDialog from ManageHelpers). These are the many tool settings popups like Levels, Threshold, Curves that normally don't have toolbox tabs. Most people probably want these floated, below is an example of how to do it if you're not starting from all gimp windows being floated.

1.2.2 Tiling most windows in gimp

A good way to work with the gimp in xmonad is to tile most windows with
resizableTall, Full, tabbed (or several layout choices separated by ||| )
in the center of the screen, and....

Use withIM, nested withIM's, or XMonad.Layout.LayoutCombinators
to tile your toolbox, combined toolbox and dock, or separate toolbox and dock(s)
at the screen edges. As needed, float or unfloat windows by role, or by using Hooks.ManageHelpers.isDialog from darcs xmonad-contrib.

If you use a Tabbed or Full layout as your main layout and get unwanted
focus shifts using withIM, instead try LayoutCombinators or ComboP, or one
of the other layout combiners in xmonad-0.9. Also make sure you're using
shiftMaster instead of swapMaster in your key and mouse bindings (swapMaster
was old default before xmonad-0.9 and some people may still have it in
xmonad.hs.)

Also, instead of picking the Full/Tabbed window with mod-tab, you can add
the following to your mouse bindings, to be able to roll the mouse wheel
over the gimp toolbox till the correct window is focused, which seems to
prevent the shifting around:

In >xmonad-0.8, the XMonad.Layout.Monitor offers some useful functions for managing such windows as well.

1.5 Matching specific windows by setting the resource name or class

Most X11 programs allow you to specify the resource name and/or class of individual windows. (Some terminal emulators will also set the resource name by default if you start a program in them with -e, but this is not common.) Note that Java-based programs do not support any useful way to set either resource name or window class. (I can't find the related bug filed against Java; insert it here)

1.5.1 Gnome and KDE

All Gnome and KDE programs support --name= and --class= options to specify the resource name and class for windows opened by those programs. Use the --help-all option to see these and other low-level options not normally visible.

1.5.1.1 Terminal emulator factories

gnome-terminal by default starts a single back-end "factory" and spawns terminal windows from it; all of these windows will share the same resource name and class. Use the --disable-factory option with --name= or --class= to insure that the created window is not shared with unrelated terminals.

Other terminal emulators for Gnome and KDE are likely to behave similarly. (konsole does not at present, but akonadiconsole may.) Look for options to disable shared sessions or factories.

1.5.2 Xlib and Xaw applications

Programs such as xterm and the rxvt family of terminal emulators use the standard X11 toolkit, and accept standard toolkit options ("man X"; see the OPTIONS section). Specifically of interest here is the -name option. You cannot set the window class; this is fixed by the toolkit to a constant string supplied by the application developer.

1.5.2.1 urxvtc and urxvtd

This combination uses a single backend (urxvtd) which is asked to open terminal windows by urxvtc. These windows will share the same resource name. Do not use -name with urxvtc; instead, use urxvt directly. (See #Terminal emulator factories above.)

1.5.2.2 Caveat

Programs using the standard X11 toolkit use the resource name and class to read configuration information from the app-defaults database and ~/.Xresources. Be careful when changing the resource name to insure that it is not being used to select specific configuration information, or copy that configuration information to the new resource name you are using.

1.5.3 Gtk+ and Qt

Gtk+ and Qt programs are encouraged but not required to support --name and --class as specified above under Gnome and KDE. Unfortunately, if a given program doesn't support the standard options, it probably doesn't provide any way to control its resource name or class.

For a list of the identifiers used for various keys, see
Graphics.X11.Types and ExtraTypes.

Also, the Util.EZConfig extension allows adding keybindings with simpler syntax, and even creates submaps for sequences like, e.g. "mod-x f" to launch firefox. You can use normal xmonad keybinding lists with its additionalKeys function, or with additionalKeysP, the bindings look like this:

2.3 Displaying keybindings with dzen2

Sometimes, trying different xmonad.hs files, or while dialing in custom key bindings it can be nice to have a reminder of what does what. Of course, just editing or grepping the xmonad.hs is one solution, but for a nice colourized output, try adapting a script like this to your needs:

. While there's plenty of room for improvement in the parsing, this is fine for a quick and dirty display of normal or additionalKeys style bindings. It obviously would need to be changed to parse additionalKeysP style. To have comments displayed, note that it looks for indented comments containing 'eys' so use "Keys" or "keys" in " --" style comments to create keybinding subsections.

Note that in older versions of dzen ^togglecollapse() and ^scrollhome() may not yet be supported. Use something like the following in dzen command line to get similar result:

2.4 Binding to the numeric keypad

Bind to the non-numeric versions of these keys. They work
regardless of NumLock status. To avoid conflicts with other apps
you probably want to use them with modifiers. Here is an example
of using them to navigate workspaces in the usual mod-N mod-shift-N
way, but on the key pad:

3 Navigating and Displaying Workspaces

3.1 Using Next Previous Recent Workspaces rather than mod-n

The Actions.Plane, Actions.CycleWS, and Actions.CycleRecentWS
extensions allow many ways to navigate workspaces, or shift
windows to other workspaces.

Plane is easier to set up, especially if you use Gnome. CycleWS
allows binding to nearly any behavior you'd ever want.
Actions.CycleRecentWS allows swapping with previous or next most
recently viewed workspace similar to how many window managers
cycle windows with alt tab.

In darcs xmonad-contrib (will release as 0.9): Layout.IndependentScreens
simulates dwm style workspaces per screen. For spatial navigation more
general than Plane, i.e. four 3x3 grids of workspaces, see
Actions.WorkspaceCursors.

3.2 Skipping the Scratchpad workspace while using CycleWS

The Util.Scratchpad module provides a configurable floating terminal that is easily shifted to the current workspace or banished to its own "SP" workspace. Most people want the "SP" tag ignored during workspace navigation. (Note that in xmonad newer than 0.8.*
the scratchpad workspace has been renamed to "NSP".)

Here's one way to do that with Actions.CycleWS, ready to be customized, for example to use HiddenEmptyWSs instead of HiddenNonEmptyWSs, etc.

Note that

notSP

is defined in the where clause of this example. It is
just another name for

4.2 Docks, Monitors, Sticky Windows

5 Misc

5.1 Using local state in the config file

As the xmonad config file is really just the entry point to the entire
program, you can do arbitrary IO effects before running xmonad.
Including initialising mutable "global" state. That state could even be
made persistent , independent of xmonad's built-in persistence (by
writing it to a file on mod-q).

Here's an example where we store the layouts "IncMaster" value in a
local mutable variable, so that we can provide a key binding that
takes that value to compute an offset.