View source for Xmonad/Notable changes since 0.9

This page is for keeping a record of significant changes in darcs xmonad and xmonad-contrib since the 0.9 releases. See <tt>darcs changes</tt> in the source repositories for the patches and more details covering documentation and bug fixes not noted here. Xmonad 0.9 was released on 26 October 2009, and Xmonad 0.10 on 18 November 2011.

(0.9.1 was a maintenance release, with no changes to user functionality. 0.9.1 builds against haskell X11-1.5.0.0 while 0.9 requires 1.4.6.1. Otherwise the only changes were a few documentation updates, automatic detection of numlockMask, and a minor bug fix for forked processes.) 

The idea is to put here a list of things which a user upgrading from 0.9 to 0.10 might like to know.

__TOC__

== Updates that require changes in xmonad.hs ==

=== numlockMask is now set automatically ===
Users explicitly setting numlockMask in their configs should remove those references. XConfig no longer has a numlockMask field.

If for some reason this detection isn't correct, you could still set it in the startupHook (or elsewhere), using this function:

<haskell>
setNumLockMask :: KeyMask -> X ()
setNumLockMask m = modify (\x -> x { numberlockMask = m })
</haskell>

=== Simplified interface for X.A.SpawnOn and X.H.DynamicHooks ===
Since contrib modules can now store custom state in XState, the additional IORef parameters are no longer required: Users have to remove the first parameter to the respective functions. The functions <code>mkSpawner</code> and <code>initDynamicHooks</code> are also no longer necessary and have been removed. The same applies to XMonad.Hooks.DynamicHooks. See [[#XState change details|below]] for examples.

=== MultiToggle ===
All instances of <code>Transformer</code> need to add another argument to <code>k</code> to provide a way to undo the modifier:

==== Old ====
<haskell>
instance Transformer StdTransformers Window where
    transform NBFULL       x k = k (noBorders Full)
    transform MIRROR       x k = k (Mirror x      )
</haskell>

==== New ====
<haskell>
instance Transformer StdTransformers Window where
    transform NBFULL       x k = k (noBorders Full) (\_ -> x)
    transform MIRROR       x k = k (Mirror x      ) (\(Mirror x') -> x')
</haskell>

=== X.A.GridSelect changes ===
gs_navigate changed incompatibly. There is no straightforward translation: just start over with your customization with reference to documentation in the module.

=== X.A.OnScreen changes ===
The type of <code>onScreen</code> has been changed to allow more general onScreen functions. The new <code>onScreen</code> takes any function that modifies the stack and runs it on the given screen. An onScreen' to run in X is also provided. Since XMonad can not guess what you'd like to do with the focus after running this function, <code>onScreen</code> also accepts a <code>Focus</code> data which tells XMonad how to act.  See [[#OnScreen change details|below]] for detailed examples. The more common "end user" functions like <code>viewOnScreen</code> and <code>greedyViewOnScreen</code> didn't change in their interface though.

=== Optional or obscure changes ===
Changes unlikely to affect most xmonad users.

* '''X.Hooks.DynamicLog urgency''' Urgency formatting now takes precedence over all other formatting, so xmobarStrip and dzenStrip are no longer needed. Multi-head users that distinguish urgent current from urgent visibles will need custom pretty printers but default behaviour is unchanged.

* '''The X.Util.XUtils''' <hask>paintAndWrite</hask> utility's parameter types have changed to allow printing multiple strings. Configs using it will need to be updated to use [Align] and [String].

== Changes to the xmonad core ==
* XState now supports state extensions in xmonad-contrib. See darcs [http://code.haskell.org/XMonadContrib/XMonad/Util/ExtensibleState.hs source] or documentation.

* xmonad --verbose-version flag added to provide more detailed information about the xmonad build useful for troubleshooting.

* xmonad --replace flag added to attempt to replace compliant window managers.

* <hask><+></hask> is `mappend` and composeAll mconcat for any Monoid now, not just ManageHook. Thus it can be used with keybindings, handleEventHook, X (a -> a), and more. Also (-->) works withing any Monad rather than being restricted to Query, and doF any Query(Endo a) rather than only Endo WindowSet.

* The GenerateManpage script now uses the GPL'd pandoc to generate html and man versions of the manpage.

* spawn works for non-ascii commands by assuming the user locale is utf8. Previously users would have had to use (spawn . Codec.Binary.UTF8.String.encodeString)

== Changes to xmonad-contrib ==
Throughout xmonad-contrib many monadic computations have been generalized to work in any MonadIO, i.e. in X or directly in main in IO.

=== Updated modules ===
====Actions====

* '''CycleWS''' now allows cycling within <hask>WSTagGroups</hask>, e.g. from "tag2:baz" with `workspaces = ["tag1:foo","tag1:bar","tag2:foo","tag2:baz","tag2:yow" ]' only tag2's foo, baz, and yow workspaces would cycle. Toggle actions now allow filtering out some workspaces, for example "NSP".

* '''DynamicWorkspaces''' includes several bug fixes and improvements.

* '''GridSelect''' has a new interface and exports numerous new helpers. Changes to xmonad.hs will be needed, see [[#Updates that require changes in xmonad.hs|changes in xmonad.hs]] for details.

* '''OnScreen''' has improved several functions and offers greater flexibility; some interfaces have changed. See [[#Updates that require changes in xmonad.hs|changes in xmonad.hs]] for details.

* '''PhysicalScreens''' added the exports <hask>onPrevNeighbour</hask> and <hask>onNextNeighbour</hask>.

* '''Search''' has added new predefined searches.

* '''SpawnOn''' uses extensible state rather than IORefs. See [[#Updates that require changes in xmonad.hs|changes in xmonad.hs]] for details.

* '''TopicSpace''' added defaultTopicConfig for easier setup, manages its history via extensible state rather than U.StringProp, and also added reverseLastFocusedTopics.

* '''WindowBringer''' can use a custom menu command in place of dmenu. (The old dmenu actions haven't changed.)

* '''WindowMenu''' added the ability to use custom colors in its GridSelect menu.

====Hooks====
* '''DynamicHooks''' uses extensible state rather than IORefs. See [[#Updates that require changes in xmonad.hs|changes in xmonad.hs]] for details.

* '''DynamicLog''' includes xmonadPropLog to output data via root window properties rather than via pipes. See also <code>scripts/xmonadpropread.hs</code> included with XMonadContrib source. For configs using X.H.UrgencyHook, enabling urgency on current or visible will override ppCurrent or ppVisible formatting and use the urgency formatting instead whenever a workspace contains urgent windows, similarly it ignores ppHidden formatting, eliminating the need for the dzen and xmobar format strippers.

* '''EwmhDesktops''' added fullscreenEventHook to full float windows requesting fullscreen via _NET_WM_STATE. See X.Layout.Fullscreen for a more flexible Layout Modifier approach to fullscreen requests.

* '''ManageDocks''' avoidStruts has been extended to behave more sensibly with over under multi-head configurations, i.e. allowing the use of xmobar at the bottom of a screen positioned over another xinerama screen. Note that current wm specifications do not support per screen struts, although it is under discussion, so many applications won't set struts at an interior screen edge.

* '''ManageHelpers''' has new currentWS query enabling per workspace differences in manageHooks.

====Layout====
* '''BorderResize''' modifies layouts supporting the SetGeometry message to allow resizing windows by dragging their corners (without needing to press a modifier key). It is best used with X.L.PositionStoreFloat or the complete X.C.Bluetile, however it can also be used with X.L.WindowArranger.

* '''Decoration''' has internal changes to support bluetile additions, including new windowTitleAddons and windowTitleIcons fields in Theme.

* '''GridVariants''' has added messages to further adjust layout behaviour.

* '''IndependentScreens''' now exports additional helpers to convert to and from its representation of workspaces assigned to each physical screen. It has also added <hask>marshallPP</hask> to make a pretty-printer aware of IndependentScreens.

* '''LayoutHints''' now exports <hask>hintsEventHook</hask> to refresh the screen immediately when a window's hints change, rather than waiting for a focus change.

* '''LayoutScreens''' now exports <hask>layoutSplitScreen</hask> to split the current screen into multiple workspaces based on some pure layout (versus <hask>layoutScreens</hask> which affects all screens.)

* '''Mastered''' can now add more than one window tiled vertically in the column it adds to some layout.

* '''MouseResizableTile''' now allows setting default window sizes similar to ResizableTile, while still resizing when dragging window splits.

* '''NoBorders''' is configurable, allowing the user to customize the presence of window borders in several different contexts.

* '''WindowSwitcherDecoration''' can use image buttons created with X.Layout.ImageButtonDecoration or the original bluetile buttons.

====Prompt====

* '''X.Prompt''' exports setInput and getInput for use in custom keymaps. copyString has been removed. The default quit bindings are Esc, C-[, and C-q. C-g is no longer bound.

====Util====
* '''Dzen''' has an improved interface including many new helper functions useful for creating custom notifications or message popups.

* '''XSelection''' putSelection has been removed. See [http://code.google.com/p/xmonad/issues/detail?id=317 Issue 317].

* '''XUtils''' paintAndWrite now prints multiple strings, taking [Align] and [String] parameters in place of Align and String.

=== New contrib modules ===
====Actions====
* '''BluetileCommands''' are the X.H.ServerMode commands used by the bluetile gtk2hs dock. Most of them can also be used with other interfaces to ServerMode if you have enabled the appropriate layout extensions from X.C.Bluetile.

* '''DynamicWorkspaceGroups''' implements switching groups of workspaces all at once on all monitors. It uses a prompt interface to select, add, and delete groups. It also exports helpers to work with these actions directly.

* '''DynamicWorkspaceOrder''' creates a custom ordering of workspaces for use with X.Actions.CycleWS.

* '''GroupNavigation''' provides methods for cycling through groups of windows across workspaces, ignoring windows that do not belong to this group. A  group consists windows matching a user-provided boolean query.  It also enables jumping back to the last used window in a group, (an action of special interest to mod-Tab recent window users.)

* '''KeyRemap''' allows remapping keymaps to, for example, switch between typing in Dvorak or US while keeping your xmonad keybindings in US layout

* '''WorkspaceNames''' without changing the config workspace list, WorkspaceNames allows dynamic workspace renaming, translation from workspaceID to name for use in dynamic log, and swapping workspaces by name. It persists across restarts. See also X.Layout.WorkspaceDir.

====Config====
* '''Bluetile''' enables the bluetile extensions minus the greeter and dock. See the [http://www.bluetile.org bluetile project page] for more details.

====Hooks====
* '''CurrentWorkspaceOnTop''' is a logHook used to restack floating layouts, ensuring dragged windows stay on top. It is used by bluetile config.

* '''DebugKeyEvents''' debugging module to track and print key events.

* '''FadeWindows''' is a more flexible and general interface for working with compositors than FadeInactive.

* '''FloatNext''' exports helpers for working with manage hooks that float spawned windows. See the X.Hooks.ToggleHook module for more flexible tools doing this and more.

* '''ICCCMFocus''' is a partial implentation of ICCCM focus support, mainly designed to improve java application user experience during focus changes. See also tracker [http://code.google.com/p/xmonad/issues/detail?id=177 Issue 177].

* '''ManageDocks''' no longer requires a focus change to trigger avoiding docks.

* '''Minimize''' implements an event hook handling minimize and restore hints. It's used with X.Layout.Minimize.

* '''PositionStoreHooks''' provides a manageHook and an eventHook to store and maintain position and size data, used by bluetile config.  It added an argument to <hask>positionStoreManageHook</hask> to take window decorations (such as tabs) into account.

* '''ScreenCorners''' runs actions when you touch a screen corner with your mouse.

* '''ToggleHook''' toggles manageHooks on and off, or between two manageHooks, for example between doFloat and doRectFloat. It also provides helpers to show hook toggle state via dynamicLog. It's more general than X.Hooks.FloatNext.

====Layout====
* '''ButtonDecoration''' provides window decoration with clickable menu, minimize, maximize, close buttons. Requires use of X.L.Minimize, X.L.Maximize and X.L.DecorationAddons.

* '''DecorationAddons''' exports extra utilities to make decorations more useful.

* '''DraggingVisualizer''' is a helper for X.L.WindowSwitcherDecoration to make dragged windows follow the mouse cursor.

* '''Drawer''' is a layout modifier putting some windows into a "drawer" that expands or contracts depending on whether one of its windows has focus.

* '''Fullscreen''' provides hooks and helpers to send fullscreen messages to layouts, along with layout modifier examples that respond to these messages.

* '''Groups''' is a two-level layout that nests layout groups within a user provided layout that manages the nested groups.

* '''Groups.Examples''' shows two examples of Groups layouts.

* '''Groups.Helpers''' exports focus, swap, move and split helpers for use with Groups layouts.

* '''Groups.Wmii''' is another example Groups layout inspired by wmii's window management.

* '''ImageButtonDecoration''' lets you define your own xbm-like buttons to display on window decorations, and define actions to run when a button is clicked.

* '''LayoutBuilderP''' is a layout combiner similar to LayoutBuilder, but sends windows to rectangles by predicate rather than sending n windows to one rectangle and the rest to another.

* '''MultiColumns''' allows you to use as many columns as you'd like with as many windows in each column as you'd like.

* '''PositionStoreFloat''' is the main bluetile floating layout designed for dual-head, should be used along with X.L.NoFrillsDecoration and X.L.BorderResize. (Currently requires use of mouse to move and resize floating windows.)

* '''Renamed''' replaces the deprecated X.Layout.Named module. It provides much richer interface for transforming layout descriptions.

* '''TrackFloating''' is a layout modifier that prevents undesired focus shifts, for example in tiled layouts where the focus determines what's visible.

* '''WindowSwitcherDecoration''' allows dragging windows on top of each other to swap positions, (in certain layouts.) It can be used either with or without the ButtonDecoration action buttons.

* '''ZoomRow''' is a layout that places all windows in a row (or with Mirror, in a column). Windows can be resized, plus each window can be set to zoom to all available space when focused. The "zoom full" behaviour can be toggled per window.

====Util====
* '''Dmenu''' can now pass arguments to dmenu calls.

* '''ExtensibleState''' allows storing custom mutable state in xmonad.  Can optionally be made persistent over restarts.

* '''Image''' manipulates xbm like images defined with matrices of Bool. Used by X.Layout.ImageButtonDecoration.

* '''PositionStore''' stores window position and size info in XState for better float management. Used by X.C.Bluetile.

* '''SpawnOnce''' spawns a command once and only once. Useful for session settings unique to xmonad to be run from startupHook only on login rather than on each xmonad restart.

* '''Stack''' is a collection of utilities for working with <hask>Maybe X.StackSet.Stack</hask>s. X.Layout.Groups and the Groups example modules make extensive use of X.Util.Stack.

* '''WorkspaceCompare''' has added physical screen compatible xinerama compare and sort (see X.Actions.PhysicalScreens.)

====Misc====

* The scripts directory in the xmonad-contrib source now includes <code>window-properties.sh</code> which uses <code>xprop</code> to display window properties formatted  for pasting into manage hooks.

=== Deleted and deprecated modules ===

* '''X.Layout.Named''' (deprecated) Use X.Layout.Renamed instead.

==Related Projects==

[http://code.haskell.org/xmonad-extras xmonad-extras] includes some modules with additional dependencies, like a Volume control, an MPD prompt and <code>xmonad-eval</code> which uses the [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hint hint interpreter] to manipulate xmonad state during runtime via arbitrary haskell expressions ala emacs eval.

[http://www.bluetile.org 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. It provides both keyboard and mouse access for its features. It is designed to be usable "out of the box" without being configurable, however all its core features excluding its dock are provided by xmonad-contrib extensions. People wanting a customized bluetile-like window manager can use XMonad.Config.Bluetile as a base or cherry pick modules providing the features they need.

[http://braincrater.wordpress.com/2008/08/28/announcing-xmonad-light/ xmonad-light] allows using a limited version of xmonad-0.8 without having to have ghc installed. It provides a special syntax to customize a few common options using xmonad.conf instead of xmonad.hs.

[http://dmwit.com/yeganesh yeganesh] is a wrapper for dmenu that offers more commonly used choices first in the menu. Here is [[//Xmonad/Config_archive/dmwit%27s_xmonad.hs|an example]] of using yeganesh and dmenu with xmonad.

[http://mad.unserver.de/2010/xmonad/xmenud xmenud] is a hierarchical pop-up gtk menu written in python, useful to spawn from a key binding. (Available in archlinux's AUR or via git from the website.

[http://hackage.haskell.org/package/dzen-utils dzen-utils] provides combinators for creating and processing [http://dzen.geekmode.org dzen2] input strings.

[http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlint hlint] parses haskell source and offers suggestions on how to improve it. (Requires >=ghc-6.10)

[http://jaspervdj.be/posts/2011-02-26-gnome-socket-applet.html gnome socket applet] allows displaying xmonad logHook output in gnome-panel via a localhost port.

[http://github.com/alexkay/xmonad-log-applet  xmonad log applet] allows displaying xmonad logHook output in xfce or gnome panels via dbus.

[http://gitorious.org/xmonad-log-plasmoid/xmonad-log-plasmoid.git xmonad log plasmoid] enables logHook output to kde plasmoids, also via dbus. (See also charon's version at 
git://git.thomasrast.ch/xmonad-log-plasmoid.git .)

[http://github.com/travitch/taffybar taffybar] is a gtk2hs based desktop information bar including an integrated system tray. It also communicates via dbus. It is similar to xmobar, but gives up some simplicity for flexibility plus a reasonable helping of eye candy.

== Detailed examples regarding changes to xmonad.hs ==
=== XState change details ===
Since contrib modules can now store custom state in XState, the SpawnOn and DynamicHooks IORef parameters are no longer required: Users have to remove the first parameter to the respective functions. The functions <code>mkSpawner</code> and <code>initDynamicHooks</code> are also no longer necessary and have been removed.

Example:<br />
<haskell>
-- Old code:
 sp <- mkSpawner
 ..
  [((mod1Mask,xK_k), shellPromptHere sp defaultXPConfig
   ..]
</haskell>
The above has to be changed to:
<haskell>
  -- no mkSpawner line
  ..
  [((mod1Mask,xK_k), shellPromptHere defaultXPConfig)
   ..]
</haskell>
The same applies to XMonad.Hooks.DynamicHooks.

=== OnScreen change details ===
The type of <code>onScreen</code> has been changed to allow more general onScreen functions. The old <code>onScreen</code> was very limited. Basicly the only working function derived from onScreen was <code>viewOnScreen</code>, since the <code>greedyViewOnScreen</code> never worked as supposed to, and any other function wouldn't work either.

The new <code>onScreen</code> takes any function that modifies the stack and runs it on the given screen. Since XMonad can not guess what you'd like to do with the focus after running this function, <code>onScreen</code> also accepts a <code>Focus</code> data which tells XMonad how to act.

Comparison:

<haskell>
---- Old version ----

-- Old type of onScreen:
onScreen :: (WorkspaceId -> WindowSet -> WindowSet) -- ^ default action
         -> ScreenId                                -- ^ screen id
         -> WorkspaceId                             -- ^ index of the workspace
         -> WindowSet                               -- ^ current stack
         -> WindowSet

-- The old implementation of viewOnScreen was:
viewOnScreen :: ScreenId -> WorkspaceId -> WindowSet -> WindowSet
viewOnScreen sc i = onScreen view sc i


---- New version ----

-- The new Focus data:
data Focus = FocusNew                       -- ^ always focus the new screen
           | FocusCurrent                   -- ^ always keep the focus on the current screen
           | FocusTag WorkspaceId           -- ^ always focus tag i on the new stack
           | FocusTagVisible WorkspaceId    -- ^ focus tag i only if workspace with tag i is visible on the old stack

-- New type of onScreen:
onScreen :: (WindowSet -> WindowSet) -- ^ function to run
         -> Focus                    -- ^ what to do with the focus
         -> ScreenId                 -- ^ screen id
         -> WindowSet                -- ^ current stack
         -> WindowSet

-- A few example implementations (don't worry - they're already built in):
viewOnScreen           :: ScreenId -> WorkspaceId -> WindowSet -> WindowSet
viewOnScreen sc i       = onScreen (view i) (FocusTag i) sc
greedyViewOnScreen     :: ScreenId -> WorkspaceId -> WindowSet -> WindowSet
greedyViewOnScreen sc i = onScreen (greedyView i) FocusCurrent sc
</haskell>

[[Category:XMonad]]