XMonad Overview

The window manager XMonad, as the name suggests, manages windows. That is, when an app needs to be shown, XMonad reserves a rectangle area on the screen, called a window, in which the app is shown. However, XMonad decides at which position and at what size this window is placed.

Because the screen space of a single or even two monitors is very limited, XMonad uses the concept of “virtual screens”, called workspaces, to increase the available screen space to as much as you need. XMonad allows you to decide how many workspaces you need, to decide which windows to put on which workspaces in what window arrangement, called layouts. It also allows you to decide which workspace is shown on which physical screen and to quickly switch between workspaces and layouts using keyboard shortcuts.

These so-called modifier keys, Mod1, …, Mod5 are names for for special keyboard keys.

You can run the xmodmap terminal app to find out to which keyboard key is assigned to which mod-key in your linux distribution. The output should look like:

In XMonad there is a so-called standard mod-key, called Mod on this website. It is used in many of the built-in keyboard shortcuts, which have the form Mod+…. This mod-key is normally set to the left Alt key, but you can change it.
[How to change the standard mod-key.]

Define the keyboard key that you want to use as your so-called standard modifier key Mod, or mod-key for short.
[What are mod-keys.]
The name Mask may be confusing and can be considered a leaky abstraction, because you as a user don’t care that this functionality is implemented with a bitmask. So simply read the word Mask as Key.

By default Mod is set to the left Alt key, but you can change it to the Win key like many XMonad users do as follows:

--- Inline definition
myConfig = def
  { modMask = mod4Mask -- win key
  }

However, it is wiser to introduce a readable name for the mod-keys as follows:

--- External definition
windowsKey = mod4Mask
leftAltKey = mod1Mask

myConfig = def
  { modMask = windowsKey
  }

The reason is that you may forget what mod4Mask stands for after some time and that you may forget to update the comment when you try different mod-keys.
[How to set up and modify keyboard shortcuts.]
[How to find out which mod-key is which keyboard key.]

Since the modMask setting is represented by a KeyMask value, you can only choose one of the values found in the docs:

Define the terminal app that you want to have opened in a new window whenever you press the built-in keymap Mod+Enter.

Since the terminal setting is a String, you have to provide the app’s name in double qoutes. For example, the default terminal app in Ubuntu is named gnome-terminal and you would set it up as follows:

--- Inline definition
myConfig = def
  { terminal = "gnome-terminal"
  }

Thus, whenever you press Mod+Enter, a new gnome-terminal window is opened. You can set the mod-key to a key of your choice with the XMonad’s modMask setting.

Other nice terminal apps are:

• terminator
• urvxt

Define keyboard shortcuts, called “keymaps” for short. With keymaps you can for example rearrange your windows, start an app or run a script.
[The built-in keymaps cheatsheet.]

Technically, a keymap is pair of a key combination to trigger an action and the action itself. Since the keys setting is a

XConfig Layout -> M.Map (ButtonMask, KeySym) (X ())

you will need to write a Haskell function.
[How to write a Haskell function.]
Briefly, the arrow symbol tells you that this must be a function that expects a XConfig Layout value and returns a M.Map (ButtonMask, KeySym) (X ()) value.

• XConfig Layout: An existing XConfig value whose other properties like workspaces you can access for your keymaps.
• M.Map (ButtonMask, KeySym) (X ()):
  • M.Map: A Haskell mappings representation which contains your keymaps. It’s a collection of mappings from key combination to an action.
  • (ButtonMask, KeySym): The triggering key combination as a pair of one special key and one normal key that should trigger an “XMonad action” when pressed to together.
    • ButtonMask: A special key like Ctrl, Shift and Windows. It’s a synonym for KeyMask that you know from setting up the modMask setting, so it allows the same key values.
    • KeySym: A normal key like a letter or digit.
  • X (): An XMonad action like starting an app or changing the layout of your windows.

For example, you could define keymaps yourself as follows:

import qualified Data.Map as M

-- External definition
myKeysFunc baseConfig@(XConfig {modMask = modKey}) = M.fromList $
 [ ((modKey, xK_Return), spawn (terminal baseConfig) )
 , ((modKey, xK_q),      restart "xmonad" True)
 ]

myConfig = def
  { keys = myKeysFun -- override previous keymaps
  }

The keymaps in this example are built-in, so wouldn’t want to define them yourself.
[How to write your own keymaps in detail.]
Briefly, myKeysFunc is our chosen function name that we set as the keys setting. baseConfig is our name for the XConfig value that will be passed to our myKeysFunc function, which we extract the modMask property from. With the @ symbol we use Haskell’s as-pattern notation to give a name to the full XConfig value and with XConfig {modMask = modKey} we use pattern matching to extract the modMask value from the given baseConfig value. We use modMask value locally under the name modKey.
[How to access and change a Haskell value.]
With M.fromList we create a Data.Map value. This function expects a list of

( <key-combination>, <action>)

pairs, where key-combination itself is a

( <special-key>, <regular-key>)

pair. With the bracket [item, item, ...] notation we create that list.
[How to write lists in Haskell.]
The fromList function is available though the import line at the top. [How to import functions from other modules.]
The xK_Return value and the xK_q value are XMonad’s representations for the Enter and q keys. The spawn function runs a given String value. Here, we start an the terminal app that is set in the terminal property of the given baseConfig value. We access this property with terminal baseConfig, because terminal is also an accessor function.
[How to access properties with accessor functions.]

This example deletes and overrides all built-in keymaps in def and introduces the two keymaps Mod+Enter to open a terminal in a new window and Mod+q to restart XMonad. If you don’t want to delete all existing keymaps, take a look at short example.

Define the names/identifiers of workspaces. The default ones are named:

 defaultWorkspaces = ["1","2","3","4","5","6","7","8","9"]

If you choose to use a [statusbar like xmobar][xmobarPage], which you definitely should, these workspace names will appear in your statusbar to indicate which workspaces contain windows and which one you are looking at.

If you don’t need that many workspaces or want more meaningful names you can change them as follows:

-- External definition
myWorkspaces = ["1:work", "2:browser", "3:chat"]

myConfig = def
  { workspaces = myWorkspaces
  }

However, when you change workspace names/identifiers, you will also need to update your keymaps in your keys settings, because the default keymaps for switching to a certain workspace or moving windows from one workspace to another look for the default workspace names "1", "2" etc.
[How to setup your own keymaps.]

Define actions to be executed right before the start of XMonad.

import XMonad.Util.SpawnOnce (spawnOnce)
import XMonad.Hooks.SetWMName (setWMName)

myStartupHook baseConfig = do
  return () -- workaround for checkKeymap!
  checkKeymap baseConfig myKeys -- check keymaps from EZ notation
	-- workaround to integrate Java Swing/GUI apps into XMonad layouts;
	-- otherwise they just float around.
	setWMName "LG3D"
	-- workaround to keep xmobar/dock visible after xmonad restart; otherwise
	-- the dock can be lost/hidden behind wallpaper.
  spawn "xdotool windowraise `xdotool search --all --name xmobar`"
  spawnOnce "dropbox start"
  spawnOnce "nm-applet"
	spawnOnce "~/.xmonad/xmonad-starthook.sh"
  -- ...

myConfig = def
  { startupHook = myStartupHook
  }

Here, you should check your user-defined keymaps if you used the EZ keymap notation, place your workarounds if necessary, and start apps you would like to have available from the beginning. For example, you can start the Dropbox daemon, or Ubuntu’s network-manager nm-applet (You can also start these apps through a shell script, which you run here with the spawn function). The difference between the two spawn functions is that spawn in myStartupHook will run anytime you restart XMonad, whereas spawnOnce will only the run the first time you start XMonad but at a later restart. This is what you usually want for background daemons.

Define what should happen when a new window is opened. This allows you to treat an app different from others, for example, place it on a special workspace or let it float (above all other windows).

import XMonad.Hooks.ManageHelpers (isDialog, doFullFloat, doCenterFloat, transience')

myWorkspaces = ["1", "2", "3:social"]

myManageHook = composeAll
  [ className =? "stalonetray"         --> doIgnore
  , isDialog                           --> doCenterFloat
  , className =? "Gimp"                --> doFullFloat
  , className =? "Thunderbird"         --> doShift "2"
  , fmap ("Firefox" `isInfixOf`) title --> doShift "2"
  -- move transient windows like dialogs/alerts on top of their parents
  , transience'
  ]

myConfig = def
  { manageHook = myManageHook
  }

The composeAll function allows us to write our desired hooks as a list. A hook consists of a trigger (left side of --->) that inspect a new window see if some “xproperty” of that window matches (with =?) some given String, and an action (right side of -->). Note that the matchings are done in the order of your list. You can run the terminal app xprop and then click on a window like Firefox to find out the xproperties of that window. The long output looks like:

...
WM_CLASS(STRING) = "Navigator", "Firefox"
WM_ICON_NAME(STRING) = "xmonad | the tiling window manager that rocks - Mozilla Firefox"
_NET_WM_ICON_NAME(UTF8_STRING) = "xmonad | the tiling window manager that rocks - Mozilla Firefox"
WM_NAME(STRING) = "xmonad | the tiling window manager that rocks - Mozilla Firefox"
_NET_WM_NAME(UTF8_STRING) = "xmonad | the tiling window manager that rocks - Mozilla Firefox"

For example, you can combine this app with the terminal app grep as in

xprop | grep WM_NAME

to only show the output lines you care about.

In the following we list some useful matching helper functions, as well as window actions:

You can read about all matching helper functions and actions in the documentation.

Define the layouts, that is, the windows arrangement styles that you want XMonad to have available for you to cycle through with Mod+Space, the default keymap to select the next layout.
[How to build your layoutHook.]

Define the color of the border around a window.

Since each color is a String you write a color code surrounded with double quotes. There are two styles to write a color code. First, you can use the universal RGB hex notation.

"#<red><green><blue>"

For example you can set:

-- Inline definition
myConfig = def
  { normalBorderColor = "#010D21"
  , focusedBorderColor = "#0080FF"
  }

In XMonad each color uses two hex digits. However, this is hard to read after some time, so it is wiser to write it like this:

-- External definition
myBlack = "#010D21"
myBlue = "#7F0303"

myConfig = def
  { normalBorderColor = myBlack
  , focusedBorderColor = myBlue
  }

The windows borders then looks as follows:

To find the specific hex values for the color of your choice you can use any color picker such as Google’s.

The second style to write a color code is to write the plaintext name from the list of X11 color names. Of course not every color has such a name, but if you are happy with these standard colors, use them, because they are a lot more readable. For example, you can write

myConfig = def
  { normalBorderColor = "Black"
  , focusedBorderColor = "Dark Cyan"
  }

Define the width of the normal and focused window border in number of pixels. Since the width is represented by a Dimension in XMonad which is just another name for a non-negative integer number, you can set it like this:

--- Inline definition
myConfig = def
  { borderWidth = 2
  }

Try some pixelsizes to see what is as small as possible but still visible at your screen size.