Xmonad/Notable changes since 0.8

From HaskellWiki
Jump to navigation Jump to search

This page is for keeping a record of significant changes in darcs xmonad and xmonad-contrib since the 0.8.* releases. See 'darcs changes' for more details about miscellaneous feature enhancements, and documentation and bug fixes not noted here.

(0.8.1 was a maintenance release, with no changes to user functionality. It simply included ghc-6.10.1 related updates and a ghc optimization bug workaround for 64-bit users building xmonad-contrib on ghc-6.10.1.)

The idea is to put here a list of things which a user upgrading from 0.8 to 0.9 might like to know, so that they are sure to be included in the 0.9 release notes.

Updates that require changes in xmonad.hs

Modules formerly using Hooks.EventHook now use Event from core.


Note: EwmhDesktops users must change configuration by removing the obsolete ewmhDesktopsLayout from layoutHook, (it no longer exists), and updating to the current ewmh support which includes a startupHook and handleEventHook. (No need to change config if using ewmh via Config.Desktop, Config.Gnome, etc. Your config will automatically be updated to use current ewmh support so long as your config does not completely replace startupHook, logHook, or handleEventHook. See the change configuration link and Config.Desktop documentation for help merging your customizations with one of the desktop configs.)

See below for details of how to update an EwmhDesktops config.


Most DynamicLog users can continue with configs unchanged, but users of the quickbar functions xmobar or dzen will need to change xmonad.hs: their types have changed to allow easier composition with other XConfig modifiers. The dynamicLogDzen and dynamicLogXmobar functions have been removed. For details, see the 0.9 DynamicLog docs.

WindowGo and safeSpawn

WindowGo or safeSpawn users may need to change command lines due to safeSpawn changes. For details, see Util.Run, and Actions.WindowGo docs.

Optional changes

People who explicitly use swapMaster in key or mouse bindings should change it to shiftMaster. It's the current default used where swapMaster had been used previously. It works better than swapMaster when using floating and tiled windows together on the same workspace.

People explicitly referencing the "SP" scratchpad workspace in xmonad.hs should change it to the currently used id "NSP" which is also used by the new Util.NamedScratchpad

Changes to the xmonad core

  • Supports using local modules in xmonad.hs For example: to use definitions from ~/.xmonad/lib/XMonad/Stack/MyAdditions.hs
    • import XMonad.Stack.MyAdditions
  • Spawned processes are now handled by xmonad. Using 'exec xmonad' in startup files now "does the right thing."
  • New --restart command line flag to restart a running xmonad process.
  • Focus changes across screens with mouse movement, no longer requiring a click, even for empty workspaces. (For non-ewmh configs that use focus-follows-mouse. Ewmh users still need to click if the workspace is empty, use keybindings, or use pagers/taskbars/etc.)
  • XMonad now exports (.|.), no need to import Data.Bits.
  • StackSet exports focusUp', focusDown' for Stack in addition to focusUp/Down StackSet versions.
  • XConfig has new handleEventHook:: Event -> X All field supporting custom event hooks. The function should return (All True) to have the default handler run afterward. (See Graphics.X11.Xlib.Extras Event, Core.hs, Main.hs)
  • X is now typeable. (Enables Language.Haskell.Interpreter, i.e. hint integration, see xmonad-eval project below.)

Changes to xmonad-contrib

Updated modules


  • Actions.CopyWindow has new runOrCopy
  • Actions.CycleWS now includes HiddenWS type.
  • Actions.Plane has a planeKeys function to automatically set up default spatial workspace navigation.
  • Actions.Search has more searches.
  • Actions.Submap now supports a default action, enabling looping to, e.g., set volume, or use an explicit 'exit submap' key.
  • Actions.WindowBringer now works with external programs other than dmenu, such as nafai's gtkmenu
  • Actions.WindowGo
    • has raiseMaster variant of runOrRaiseMaster
    • uses safeSpawn instead of regular spawn


  • All desktop configs now set the root window mouse cursor when xmonad starts up. (Desktop, Gnome, Kde, Xfce)
  • Config.Gnome also registers with dbus for speedier startup on many Gnome setups.
  • Config.Kde has optional KDE 4 specific settings.


  • Hooks.EwmhDesktops ewmhDesktopsLayout must be removed from layoutHook; it no longer exists. Its tasks are now handled by handleEventHook = ewmhDesktopsEventHook and startupHook = ewmhDesktopsStartup.
Your config will be automatically upgraded if you're using EWMH via Config.Desktop, Config.Gnome, etc. but people using defaultConfig with explicit EwmhDesktops hooks and the ewmhDesktopsLayout modifier should update their configs as described below.
  • Hooks.DynamicLog module has a new 'statusBar' function to simplify status bar configuration. Similar dzen and xmobar quick bar functions have changed type for easier composition with other XConfig modifiers. dynamicLogDzen and dynamicLogXmobar have been removed. Format stripping functions for xmobar and dzen have been added to allow independent formatting for ppHidden and ppUrgent.
  • Hooks.FadeInactive The fade parameter can now be a rational between 0 and 1 or an old style 0xffffffff based value. The module interface is more powerful and flexible.
  • Hooks.ManageDocks' Direction type was renamed to Direction2D and is now defined in XMonad.Util.Types. This requires configs that use Direction in type signatures or imports to use Direction2D instead. Has a new SetStruts message in addition to the current toggle.
  • Hooks.ManageHelpers has new 'doFloatDep' and 'doFloatAt' to add more control over floating window geometry.
  • Hooks.RestoreMinimized provides an event hook to restore minimized windows from taskbars. (see Layout.Minimize)
  • Hooks.UrgencyHook now can be configured with reminders at intervals, and urgency can be cleared with a keybinding even without "visiting" the urgent window.
  • Hooks.ServerMode has a better interface for having xmonad execute custom commands specified by user via root window property events.


  • Layout.Grid Grid defaults to 16/9, plus offers new GridRatio with configurable aspect ratio.
  • Layout.LayoutHints layoutHintsToCenter added, to respect size hints but eliminate gaps between windows by placing them at outside edges.
  • Layout.Master is now a layout modifier rather than layout. Also, it no longer applies size hints by default; otherwise it's backward compatible with old Master. Use the LayoutHints modifiers to restore the old behavior.
  • Layout.Maximize maximizes to a slightly larger window size than previously. When maximizing a new window it automatically restores the previously maximized one. It also moves maximized windows to the background when not focused.
  • Layout.ThreeColumns has several new features including placing master at center.


  • Prompt keymaps are now customizable via XPConfigs. Tab completion is more configurable. Prompt configs include a history filter field with accompaning deleteConsecutive and deleteAllDuplicates helpers for easier history usage with Prompt modules.
  • Prompt.Search completions only use search history, rather than old behavior of matching any prompt's entries.


  • Util.EZConfig includes <Print>, and on systems with X11 that supports them, multimedia keys.
  • Util.Loggers has several new loggers and logger formatting utilities.
  • Util.Run's "safeSpawn" has changed types; now it takes a list of strings/arguments, instead of a single string.
  • Util.Scratchpad has general spawn action allowing user to specify how to set resource to "scratchpad", allowing the use of gnome-terminal or any other app capable of setting its resource as scratchpads. Also new NamedScratchpad module now allows multiple summon/banishable applications.
  • Util.Themes has many more themes to try out with tabbed and other decorated layouts
  • Util.WindowProperties has general getProp32* helpers and doc improvements
  • Util.XSelection has new functions to allow transforming the selection before acting on it.


  • UTF-8 handling has been improved throughout core and contrib.

New contrib modules


  • Actions.BorderResize -- Resize windows by dragging their borders with the mouse (for layouts that react to SetGeometry, i.e. mostly floating layouts.)
  • Actions.CycleWindows -- Cycle recent windows, cycle custom window order, focus nth window, change focused or unfocused window order. Esp. useful with layouts that hide some windows. (See also Layout.LimitWindows.)
  • Actions.FloatSnap -- Tools for moving and resizing floating windows with configurable snapping to various window edges. (See also Hooks.Place.)
  • Actions.GridSelect -- Graphically go to, select, do things with windows. Since its first release it's gained additional colourizers, customizable keybindings plus mouse support. It's also been generalized to work with more than just windows. Use it to select workspaces, applications to spawn, prompts, etc. (See also Actions.WindowMenu for a an easy to configure grid select menu of window related actions.)
  • Actions.MessageFeedback -- Provides a version of sendMessage that returns an X Bool reflecting whether or not the Message was handled. Allows specifying alternative Messages to be sent in sequence until one is handled.
  • Actions.OnScreen -- Actions for use with multiple screens to control workspaces on unfocused screens.
  • Actions.PhysicalScreens -- More intuitive use of multiple xinerama screens by physical ordering rather than ScreenID. (I.e. no more rebinding mod-{w,e,r} because xorg chose 0:middle, 1:right, 2:left, etc.)
  • Actions.RandomBackground -- Start terminals with random '-bg' color or generate random hex color strings. The range of colors can be restricted using RGB min/max value or HSV saturation and value.
  • Actions.SpawnOn -- Binding actions, hooks, and prompts to spawn on a specific workspace even if a different workspace is current by the time the app starts.
  • Actions.TopicSpace -- Utilities for task oriented workspaces: set working directory, startup actions when no windows are on the space, display and navigate topic workspaces by history of last focused topics.
  • Actions.UpdateFocus -- When switching workspaces and using focus follows mouse ensure the window under the mouse is focused as soon as the pointer moves a little.
  • Actions.WindowMenu -- Provides a GridSelect menu for selecting window commands such as minimize, shift to workspace, etc.
  • Actions.WorkspaceCursors -- Navigate workspaces in arbitrary number of dimensions. For example, use nine 3 x 3 grids of workspaces, binding keys to navigate in each of those three dimensions.
  • Actions.WithAll -- Apply functions to all windows on a workspace. (Replaces deprecated SinkAll module which is only included for compatibility.)


  • Hooks.FloatNext -- No need to mess with DynamicHooks if you want to float next windows; use this instead!
  • Hooks.Place -- Manage newly created floating window placement in just about any conceivable manner. Very useful module for float users. Also see Actions.FloatSnap.
  • Hooks.InsertPosition -- Ready made options for position and focus of new windows, e.g 'insertPosition Master Newer' to insert at master and focus it, 'insertPosition Above Older', etc.
  • Hooks.WorkspaceByPos -- For multi-head setups, when windows request geometry not on the current screen attempt to honor it as much as possible by moving the window to the requested screen.


  • Layout.AutoMaster -- Modifies a base layout used in slave area by adding a horizontal master area above it (like Mirror Mastered). The master area shrinks to make more room for slaves as more slave windows are created, but it can also be adjusted manually with keybindings.
  • Layout.CenteredMaster -- Sort of a combination of Master's mastered modifier with Magnifier, adding a master frame above tiled windows that is centered or at the top right of the screen.
  • Layout.Cross -- Similar to Circle, but with a resizable center pane. Limits visible windows to five. Cycles the focused window into the main window keeping visible two above and two below in stack order. See also Layout.LimitWindows.
  • Layout.Column -- Arrange windows in a column with heights forming a geometric progression: h1/h2 = h2/h3 = ... = q where q is adjustable via Shrink/Expand.
  • Layout.ComboP -- Combine layouts more usefully than plain L.Combo: use window properties to decide which windows go to which layout, and move or swap windows between layouts.
  • Layout.FixedColumn -- Neat variation on Tall, using window hints to decide master width, e.g. have your terminal automatically be 80 columns wide in the master.
  • Layout.GridVariants -- More customizable Grid, and adjustable SplitGrid, for details see here.
  • Layout.IndependentScreens -- Utilities to simulate dwm's screen model, where each physical screen has its own set of the defined workspaces.
  • Layout.LayoutBuilder -- another method for combining layouts within layouts based on number of windows to place into different sub screen layouts.
  • Layout.LimitWindows -- modify a layout to limit the number of visible windows. Provides several configurations to choose which windows are visible in addition to the focused one such as n below, a slice with some above and some below displayed, or limitSelect which aims to minimize window remapping on focus changes. The number of windows can be raised or lowered dynamically via keybindings.
  • Layout.MessageControl -- tools for piping messages to the correct sub layout in complex combined layouts.
  • Layout.Minimize -- layout modifier to minimize windows (see also Hooks.RestoreMinimized)
  • Layout.Monitor -- many useful functions for gkrellm, clock, widget type windows.
  • Layout.MouseResizableTall -- ResizableTall-like layout where tiles can be resized with the mouse. All window separations can be dragged to modify the layout. Key bindings can also be used.
  • Layout.NoFrillsDecoration -- basic full width decorations (title bars) for windows even simpler than SimpleDecoration.
  • Layout.OneBig -- A little like Mosaic combined with Grid, this layout lets you specify a (top left) master area in terms of fractions of the screen dimensions, (yes, can shrink/expand it), then it splits the rectangles below and to the right of that area into equal portions.
  • Layout.SubLayouts -- often requested tools to nest layouts within other layouts.
  • Layout.Spacing -- puts blank space around each window.
  • Layout.Mosaic -- Versatile, easy to configure, fun layout that can yield a wide range of window arrangements. It sizes panes based on the relative sizes of a list of numbers. Keybindings can be added to resize windows and change the overall aspect ratio. Works well combined with Layout.LimitWindows.


  • Util.Cursor allows setting the root window cursor from xmonad rather than in .xsession, .xinitrc, etc. It is included in the startupHook when using desktop configs instead of defaultConfig for the base config.
  • Util.NamedActions -- tools to make keybindings showable.
  • Util.NamedScratchpad -- configure multiple summonable/banishable application windows. Can be floated or tiled on creation, etc. with manageHooks.
  • Util.Paste -- For pasting strings to windows.
  • Util.Replace -- Configure xmonad to replace compliant window managers started from DE's, (such as metacity), so for example one can work in metacity for a while, then start xmonad.
  • Util.StringProp -- Internal utility functions for storing Strings with the root window. Used for global state like IORefs with string keys that persists over xmonad restarts. However, this persistence comes at the cost of more latency and increased traffic with the X server.
  • Util.Types -- Unifies Direction types used in various modules. Dev utility.

Deleted modules

  • Config.PlainConfig is now a separate project, shepheb's xmonad-light.
  • Hooks.EventHook is superseded by handleEventHook from core.

Related Projects

xmonad-light allows using a limited version of xmonad without having to have ghc installed. It provides a special syntax to customize a few common options using xmonad.conf instead of xmonad.hs.

xmonad-extras includes some modules with additional dependencies, like a Volume control, an MPD prompt and the xmonad-eval package that uses the hint interpreter to manipulate xmonad state during runtime via arbitrary haskell expressions ala emacs eval.

Bluetile is a tiling window manager based on xmonad which focuses on making the tiling paradigm easily accessible to users coming from traditional window managers by drawing on known conventions and providing both mouse and keyboard access for all features. It also tries to maximize usability 'out of the box', and provides minimal customization. (Aside from its dock, bluetile features are now provided by xmonad-contrib (darcs) extensions, so users wanting custom bluetile-like configs can create them using xmonad.)

dzen-utils provides combinators for creating and processing dzen2 input strings.

hlint parses haskell source and offers suggestions on how to improve it. (Requires >=ghc-6.10)

xmonad log applet allows displaying xmonad logHook output in gnome-panel via dbus.

EwmhDesktops 0.9 config updates

Users of defaultConfig that explicitly include EwmhDesktops hooks and the ewmhDesktopsLayout modifier should remove the old layout modifier, then choose one of the following upgrade methods:

darcs xmonad users who already have ewmh log and event hooks will likely choose 2) which will only require them to add ewmhDesktopsStartup to the existing config.

1) To combine your custom non-ewmh hooks with all the current ewmh defaults:

Remove any of the ewmh hooks or modifiers currently in your config*, and instead use the new ewmh function which adds EWMH support to defaultConfig all at once. You should keep avoidStruts and manageDocks if you're using them. If you are using a different WM Name for java, setWMName needs to over-ride part but not all of the ewmh startupHook; use method 2) below.)
* Remove ewmhDesktopsLayout, ewmhDesktopsLogHook, and if you have it, ewmhHandleEventHook, or use method 2 instead.
        import XMonad
        import XMonad.Hooks.EwmhDesktops

        main = xmonad $ ewmh defaultConfig {
                -- non-ewmh customizations

2) To override these hooks, customize them or explicitly define them yourself:

Use something like the following example. It overrides logHook completely to use a custom hook that filters the workspaces, and explicitly adds the EwmhDesktops handleEventHook and startupHook, over-riding the default WM name. For more information about modifying these fields see the Hooks.EwmhDesktops and Config.Desktop documentation.
        import XMonad
        import XMonad.Hooks.EwmhDesktops
        -- imports needed for this example, but normally not needed
        import Data.Monoid (mappend)
        import XMonad.Actions.SetWMName
        import XMonad.Hooks.FadeInactive

        main = xmonad $ defaultConfig {
                  startupHook = ewmhDesktopsStartup >> setWMName "LG3D"

                , logHook = ewmhDesktopsLogHookCustom scratchpadFilterOutWorkspace
                -- This completely replaces the config logHook.
                -- Use '>>'  or 'do' to run an ewmh logHook /plus/ your own
                -- chosen logHook(s). Same as for startupHook. For example:
                -- , logHook = logHook gnomeConfig >> fadeInactiveLogHook

                , handleEventHook = myCustomEventHook `mappend` ewmhDesktopsEventHook 
                -- handleEventHook combines with mappend or mconcat instead of '>>'