<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<!-- Generated by HsColour, http://code.haskell.org/~malcolm/hscolour/ -->
<title>XMonad/Doc/Developing.hs</title>
<link type='text/css' rel='stylesheet' href='hscolour.css' />
</head>
<body>
<pre><a name="line-1"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span>
<a name="line-2"></a><span class='hs-comment'>-- |</span>
<a name="line-3"></a><span class='hs-comment'>-- Module : XMonad.Doc.Developing</span>
<a name="line-4"></a><span class='hs-comment'>-- Copyright : (C) 2007 Andrea Rossato</span>
<a name="line-5"></a><span class='hs-comment'>-- License : BSD3</span>
<a name="line-6"></a><span class='hs-comment'>--</span>
<a name="line-7"></a><span class='hs-comment'>-- Maintainer : andrea.rossato@unibz.it</span>
<a name="line-8"></a><span class='hs-comment'>-- Stability : unstable</span>
<a name="line-9"></a><span class='hs-comment'>-- Portability : portable</span>
<a name="line-10"></a><span class='hs-comment'>--</span>
<a name="line-11"></a><span class='hs-comment'>-- This module gives a brief overview of the xmonad internals. It is</span>
<a name="line-12"></a><span class='hs-comment'>-- intended for advanced users who are curious about the xmonad source</span>
<a name="line-13"></a><span class='hs-comment'>-- code and want an brief overview. This document may also be helpful</span>
<a name="line-14"></a><span class='hs-comment'>-- for the beginner\/intermediate Haskell programmer who is motivated</span>
<a name="line-15"></a><span class='hs-comment'>-- to write an xmonad extension as a way to deepen her understanding</span>
<a name="line-16"></a><span class='hs-comment'>-- of this powerful functional language; however, there is not space</span>
<a name="line-17"></a><span class='hs-comment'>-- here to go into much detail. For a more comprehensive document</span>
<a name="line-18"></a><span class='hs-comment'>-- covering some of the same material in more depth, see the guided</span>
<a name="line-19"></a><span class='hs-comment'>-- tour of the xmonad source on the xmonad wiki:</span>
<a name="line-20"></a><span class='hs-comment'>-- <<a href="http://haskell.org/haskellwiki/Xmonad/Guided_tour_of_the_xmonad_source">http://haskell.org/haskellwiki/Xmonad/Guided_tour_of_the_xmonad_source</a>>.</span>
<a name="line-21"></a><span class='hs-comment'>--</span>
<a name="line-22"></a><span class='hs-comment'>-- If you write an extension module and think it may be useful for</span>
<a name="line-23"></a><span class='hs-comment'>-- others, consider releasing it. Coding guidelines and licensing</span>
<a name="line-24"></a><span class='hs-comment'>-- policies are covered at the end of this document, and must be</span>
<a name="line-25"></a><span class='hs-comment'>-- followed if you want your code to be included in the official</span>
<a name="line-26"></a><span class='hs-comment'>-- repositories. For a basic tutorial on the nuts and bolts of</span>
<a name="line-27"></a><span class='hs-comment'>-- developing a new extension for xmonad, see the tutorial on the</span>
<a name="line-28"></a><span class='hs-comment'>-- wiki:</span>
<a name="line-29"></a><span class='hs-comment'>-- <<a href="http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial">http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial</a>>.</span>
<a name="line-30"></a><span class='hs-comment'>--</span>
<a name="line-31"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span>
<a name="line-32"></a>
<a name="line-33"></a><span class='hs-keyword'>module</span> <span class='hs-conid'>XMonad</span><span class='hs-varop'>.</span><span class='hs-conid'>Doc</span><span class='hs-varop'>.</span><span class='hs-conid'>Developing</span>
<a name="line-34"></a> <span class='hs-layout'>(</span>
<a name="line-35"></a> <span class='hs-comment'>-- * Writing new extensions</span>
<a name="line-36"></a> <span class='hs-comment'>-- $writing</span>
<a name="line-37"></a>
<a name="line-38"></a> <span class='hs-comment'>-- * Libraries for writing window managers</span>
<a name="line-39"></a> <span class='hs-comment'>-- $xmonad-libs</span>
<a name="line-40"></a>
<a name="line-41"></a> <span class='hs-comment'>-- * xmonad internals</span>
<a name="line-42"></a> <span class='hs-comment'>-- $internals</span>
<a name="line-43"></a>
<a name="line-44"></a> <span class='hs-comment'>-- ** The @main@ entry point</span>
<a name="line-45"></a> <span class='hs-comment'>-- $main</span>
<a name="line-46"></a>
<a name="line-47"></a> <span class='hs-comment'>-- ** The X monad and the internal state</span>
<a name="line-48"></a> <span class='hs-comment'>-- $internalState</span>
<a name="line-49"></a>
<a name="line-50"></a> <span class='hs-comment'>-- ** Event handling and messages</span>
<a name="line-51"></a> <span class='hs-comment'>-- $events</span>
<a name="line-52"></a>
<a name="line-53"></a> <span class='hs-comment'>-- ** The 'LayoutClass'</span>
<a name="line-54"></a> <span class='hs-comment'>-- $layoutClass</span>
<a name="line-55"></a>
<a name="line-56"></a> <span class='hs-comment'>-- * Coding style</span>
<a name="line-57"></a> <span class='hs-comment'>-- $style</span>
<a name="line-58"></a>
<a name="line-59"></a> <span class='hs-comment'>-- * Licensing policy</span>
<a name="line-60"></a> <span class='hs-comment'>-- $license</span>
<a name="line-61"></a> <span class='hs-layout'>)</span> <span class='hs-keyword'>where</span>
<a name="line-62"></a>
<a name="line-63"></a><span class='hs-comment'>--------------------------------------------------------------------------------</span>
<a name="line-64"></a><span class='hs-comment'>--</span>
<a name="line-65"></a><span class='hs-comment'>-- Writing Extensions</span>
<a name="line-66"></a><span class='hs-comment'>--</span>
<a name="line-67"></a><span class='hs-comment'>--------------------------------------------------------------------------------</span>
<a name="line-68"></a>
<a name="line-69"></a><span class='hs-comment'>{- $writing
<a name="line-70"></a>-}</span>
<a name="line-71"></a>
<a name="line-72"></a><span class='hs-comment'>{- $xmonad-libs
<a name="line-73"></a>
<a name="line-74"></a>Starting with version 0.5, xmonad and xmonad-contrib are packaged and
<a name="line-75"></a>distributed as libraries, instead of components which must be compiled
<a name="line-76"></a>by the user into a binary (as they were prior to version 0.5). This
<a name="line-77"></a>way of distributing xmonad has many advantages, since it allows
<a name="line-78"></a>packaging by GNU\/Linux distributions while still allowing the user to
<a name="line-79"></a>customize the window manager to fit her needs.
<a name="line-80"></a>
<a name="line-81"></a>Basically, xmonad and the xmonad-contrib libraries let users write
<a name="line-82"></a>their own window manager in just a few lines of code. While
<a name="line-83"></a>@~\/.xmonad\/xmonad.hs@ at first seems to be simply a configuration
<a name="line-84"></a>file, it is actually a complete Haskell program which uses the xmonad
<a name="line-85"></a>and xmonad-contrib libraries to create a custom window manager.
<a name="line-86"></a>
<a name="line-87"></a>This makes it possible not only to edit the default xmonad
<a name="line-88"></a>configuration, as we have seen in the "XMonad.Doc.Extending" document,
<a name="line-89"></a>but to use the Haskell programming language to extend the window
<a name="line-90"></a>manager you are writing in any way you see fit.
<a name="line-91"></a>
<a name="line-92"></a>-}</span>
<a name="line-93"></a>
<a name="line-94"></a><span class='hs-comment'>{- $internals
<a name="line-95"></a>-}</span>
<a name="line-96"></a>
<a name="line-97"></a><span class='hs-comment'>{- $main
<a name="line-98"></a>#The_main_entry_point#
<a name="line-99"></a>
<a name="line-100"></a>xmonad installs a binary, @xmonad@, which must be executed by the
<a name="line-101"></a>Xsession starting script. This binary, whose code can be read in
<a name="line-102"></a>@Main.hs@ of the xmonad source tree, will use 'XMonad.Core.recompile'
<a name="line-103"></a>to run @ghc@ in order to build a binary from @~\/.xmonad\/xmonad.hs@.
<a name="line-104"></a>If this compilation process fails, for any reason, a default @main@
<a name="line-105"></a>entry point will be used, which calls the 'XMonad.Main.xmonad'
<a name="line-106"></a>function with a default configuration.
<a name="line-107"></a>
<a name="line-108"></a>Thus, the real @main@ entry point, the one that even the users' custom
<a name="line-109"></a>window manager application in @~\/.xmonad\/xmonad.hs@ must call, is
<a name="line-110"></a>the 'XMonad.Main.xmonad' function. This function takes a configuration
<a name="line-111"></a>as its only argument, whose type ('XMonad.Core.XConfig')
<a name="line-112"></a>is defined in "XMonad.Core".
<a name="line-113"></a>
<a name="line-114"></a>'XMonad.Main.xmonad' takes care of opening the connection with the X
<a name="line-115"></a>server, initializing the state (or deserializing it when restarted)
<a name="line-116"></a>and the configuration, and calling the event handler
<a name="line-117"></a>('XMonad.Main.handle') that goes into an infinite loop (using
<a name="line-118"></a>'Prelude.forever') waiting for events and acting accordingly.
<a name="line-119"></a>
<a name="line-120"></a>-}</span>
<a name="line-121"></a>
<a name="line-122"></a><span class='hs-comment'>{- $internalState
<a name="line-123"></a>
<a name="line-124"></a>The event loop which calls 'XMonad.Main.handle' to react to events is
<a name="line-125"></a>run within the 'XMonad.Core.X' monad, which is a
<a name="line-126"></a>'Control.Monad.State.StateT' transformer over 'IO', encapsulated
<a name="line-127"></a>within a 'Control.Monad.Reader.ReaderT' transformer. The
<a name="line-128"></a>'Control.Monad.State.StateT' transformer encapsulates the
<a name="line-129"></a>(read\/writable) state of the window manager (of type
<a name="line-130"></a>'XMonad.Core.XState'), whereas the 'Control.Monad.Reader.ReaderT'
<a name="line-131"></a>transformer encapsulates the (read-only) configuration (of type
<a name="line-132"></a>'XMonad.Core.XConf').
<a name="line-133"></a>
<a name="line-134"></a>Thanks to GHC's newtype deriving feature, the instance of the
<a name="line-135"></a>'Control.Monad.State.MonadState' class parametrized over
<a name="line-136"></a>'XMonad.Core.XState' and the instance of the
<a name="line-137"></a>'Control.Monad.Reader.MonadReader' class parametrized over
<a name="line-138"></a>'XMonad.Core.XConf' are automatically derived for the 'XMonad.Core.X'
<a name="line-139"></a>monad. This way we can use 'Control.Monad.State.get',
<a name="line-140"></a>'Control.Monad.State.gets' and 'Control.Monad.State.modify' for the
<a name="line-141"></a>'XMonad.Core.XState', and 'Control.Monad.Reader.ask' and
<a name="line-142"></a>'Control.Monad.Reader.asks' for reading the 'XMonad.Core.XConf'.
<a name="line-143"></a>
<a name="line-144"></a>'XMonad.Core.XState' is where all the sensitive information about
<a name="line-145"></a>window management is stored. The most important field of the
<a name="line-146"></a>'XMonad.Core.XState' is the 'XMonad.Core.windowset', whose type
<a name="line-147"></a>('XMonad.Core.WindowSet') is a synonym for a
<a name="line-148"></a>'XMonad.StackSet.StackSet' parametrized over a
<a name="line-149"></a>'XMonad.Core.WorkspaceID' (a 'String'), a layout type wrapped inside
<a name="line-150"></a>the 'XMonad.Layout.Layout' existential data type, the
<a name="line-151"></a>'Graphics.X11.Types.Window' type, the 'XMonad.Core.ScreenID' and the
<a name="line-152"></a>'XMonad.Core.ScreenDetail's.
<a name="line-153"></a>
<a name="line-154"></a>What a 'XMonad.StackSet.StackSet' is and how it can be manipulated
<a name="line-155"></a>with pure functions is described in the Haddock documentation of the
<a name="line-156"></a>"XMonad.StackSet" module.
<a name="line-157"></a>
<a name="line-158"></a>The 'XMonad.StackSet.StackSet' ('XMonad.Core.WindowSet') has four
<a name="line-159"></a>fields:
<a name="line-160"></a>
<a name="line-161"></a>* 'XMonad.StackSet.current', for the current, focused workspace. This
<a name="line-162"></a> is a 'XMonad.StackSet.Screen', which is composed of a
<a name="line-163"></a> 'XMonad.StackSet.Workspace' together with the screen information (for
<a name="line-164"></a> Xinerama support).
<a name="line-165"></a>
<a name="line-166"></a>* 'XMonad.StackSet.visible', a list of 'XMonad.StackSet.Screen's for
<a name="line-167"></a> the other visible (with Xinerama) workspaces. For non-Xinerama
<a name="line-168"></a> setups, this list is always empty.
<a name="line-169"></a>
<a name="line-170"></a>* 'XMonad.StackSet.hidden', the list of non-visible
<a name="line-171"></a> 'XMonad.StackSet.Workspace's.
<a name="line-172"></a>
<a name="line-173"></a>* 'XMonad.StackSet.floating', a map from floating
<a name="line-174"></a> 'Graphics.X11.Types.Window's to 'XMonad.StackSet.RationalRect's
<a name="line-175"></a> specifying their geometry.
<a name="line-176"></a>
<a name="line-177"></a>The 'XMonad.StackSet.Workspace' type is made of a
<a name="line-178"></a>'XMonad.StackSet.tag', a 'XMonad.StackSet.layout' and
<a name="line-179"></a>a (possibly empty) 'XMonad.StackSet.stack' of windows.
<a name="line-180"></a>
<a name="line-181"></a>"XMonad.StackSet" (which should usually be imported qualified, to
<a name="line-182"></a>avoid name clashes with Prelude functions such as 'Prelude.delete' and
<a name="line-183"></a>'Prelude.filter') provides many pure functions to manipulate the
<a name="line-184"></a>'XMonad.StackSet.StackSet'. These functions are most commonly used as
<a name="line-185"></a>an argument to 'XMonad.Operations.windows', which takes a pure
<a name="line-186"></a>function to manipulate the 'XMonad.Core.WindowSet' and does all the
<a name="line-187"></a>needed operations to refresh the screen and save the modified
<a name="line-188"></a>'XMonad.Core.XState'.
<a name="line-189"></a>
<a name="line-190"></a>During each 'XMonad.Operations.windows' call, the
<a name="line-191"></a>'XMonad.StackSet.layout' field of the 'XMonad.StackSet.current' and
<a name="line-192"></a>'XMonad.StackSet.visible' 'XMonad.StackSet.Workspace's are used to
<a name="line-193"></a>physically arrange the 'XMonad.StackSet.stack' of windows on each
<a name="line-194"></a>workspace.
<a name="line-195"></a>
<a name="line-196"></a>The possibility of manipulating the 'XMonad.StackSet.StackSet'
<a name="line-197"></a>('XMonad.Core.WindowSet') with pure functions makes it possible to
<a name="line-198"></a>test all the properties of those functions with QuickCheck, providing
<a name="line-199"></a>greater reliability of the core code. Every change to the
<a name="line-200"></a>"XMonad.StackSet" module must be accompanied by appropriate QuickCheck
<a name="line-201"></a>properties before being applied.
<a name="line-202"></a>
<a name="line-203"></a>-}</span>
<a name="line-204"></a>
<a name="line-205"></a><span class='hs-comment'>{- $events
<a name="line-206"></a>
<a name="line-207"></a>Event handling is the core activity of xmonad. Events generated by
<a name="line-208"></a>the X server are most important, but there may also be events
<a name="line-209"></a>generated by layouts or the user.
<a name="line-210"></a>
<a name="line-211"></a>"XMonad.Core" defines a class that generalizes the concept of events,
<a name="line-212"></a>'XMonad.Core.Message', constrained to types with a
<a name="line-213"></a>'Data.Typeable.Typeable' instance definition (which can be
<a name="line-214"></a>automatically derived by GHC). 'XMonad.Core.Message's are wrapped
<a name="line-215"></a>within an existential type 'XMonad.Core.SomeMessage'. The
<a name="line-216"></a>'Data.Typeable.Typeable' constraint allows for the definition of a
<a name="line-217"></a>'XMonad.Core.fromMessage' function that can unwrap the message with
<a name="line-218"></a>'Data.Typeable.cast'. X Events are instances of this class, along
<a name="line-219"></a>with any messages used by xmonad itself or by extension modules.
<a name="line-220"></a>
<a name="line-221"></a>Using the 'Data.Typeable.Typeable' class for any kind of
<a name="line-222"></a>'XMonad.Core.Message's and events allows us to define polymorphic functions
<a name="line-223"></a>for processing messages or unhandled events.
<a name="line-224"></a>
<a name="line-225"></a>This is precisely what happens with X events: xmonad passes them to
<a name="line-226"></a>'XMonad.Main.handle'. If the main event handling function doesn't have
<a name="line-227"></a>anything to do with the event, the event is sent to all visible
<a name="line-228"></a>layouts by 'XMonad.Operations.broadcastMessage'.
<a name="line-229"></a>
<a name="line-230"></a>This messaging system allows the user to create new message types,
<a name="line-231"></a>simply declare an instance of the 'Data.Typeable.Typeable' and use
<a name="line-232"></a>'XMonad.Operations.sendMessage' to send commands to layouts.
<a name="line-233"></a>
<a name="line-234"></a>And, finally, layouts may handle X events and other messages within the
<a name="line-235"></a>same function... miracles of polymorphism.
<a name="line-236"></a>
<a name="line-237"></a>-}</span>
<a name="line-238"></a>
<a name="line-239"></a><span class='hs-comment'>{- $layoutClass
<a name="line-240"></a>#The_LayoutClass#
<a name="line-241"></a>to do
<a name="line-242"></a>-}</span>
<a name="line-243"></a>
<a name="line-244"></a><span class='hs-comment'>{- $style
<a name="line-245"></a>
<a name="line-246"></a>These are the coding guidelines for contributing to xmonad and the
<a name="line-247"></a>xmonad contributed extensions.
<a name="line-248"></a>
<a name="line-249"></a>* Comment every top level function (particularly exported funtions), and
<a name="line-250"></a> provide a type signature.
<a name="line-251"></a>
<a name="line-252"></a>* Use Haddock syntax in the comments (see below).
<a name="line-253"></a>
<a name="line-254"></a>* Follow the coding style of the other modules.
<a name="line-255"></a>
<a name="line-256"></a>* Code should be compilable with "ghc-options: -Wall -Werror" set in the
<a name="line-257"></a>xmonad-contrib.cabal file. There should be no warnings.
<a name="line-258"></a>
<a name="line-259"></a>* Code should be free of any warnings or errors from the Hlint tool; use your
<a name="line-260"></a> best judgement on some warnings like eta-reduction or bracket removal, though.
<a name="line-261"></a>
<a name="line-262"></a>* Partial functions should be avoided: the window manager should not
<a name="line-263"></a> crash, so never call 'error' or 'undefined'.
<a name="line-264"></a>
<a name="line-265"></a>* Tabs are /illegal/. Use 4 spaces for indenting.
<a name="line-266"></a>
<a name="line-267"></a>* Any pure function added to the core must have QuickCheck properties
<a name="line-268"></a> precisely defining its behaviour. Tests for everything else are encouraged.
<a name="line-269"></a>
<a name="line-270"></a>For examples of Haddock documentation syntax, have a look at other
<a name="line-271"></a>extensions. Important points are:
<a name="line-272"></a>
<a name="line-273"></a>* Every exported function (or even better, every function) should have
<a name="line-274"></a> a Haddock comment explaining what it does, and providing examples.
<a name="line-275"></a>
<a name="line-276"></a>* Literal chunks of code can be written in comments using
<a name="line-277"></a> \"birdtrack\" notation (a greater-than symbol at the beginning of
<a name="line-278"></a> each line). Be sure to leave a blank line before and after each
<a name="line-279"></a> birdtrack-quoted section.
<a name="line-280"></a>
<a name="line-281"></a>* Link to functions by surrounding the names in single quotes, modules
<a name="line-282"></a> in double quotes.
<a name="line-283"></a>
<a name="line-284"></a>* Literal quote marks and slashes should be escaped with a backslash.
<a name="line-285"></a>
<a name="line-286"></a>To generate and view the Haddock documentation for your extension, run
<a name="line-287"></a>
<a name="line-288"></a>> runhaskell Setup haddock
<a name="line-289"></a>
<a name="line-290"></a>and then point your browser to @\/path\/to\/XMonadContrib\/dist\/doc\/html\/xmonad-contrib\/index.html@.
<a name="line-291"></a>
<a name="line-292"></a>For more information, see the Haddock documentation:
<a name="line-293"></a><<a href="http://www.haskell.org/haddock/doc/html/index.html">http://www.haskell.org/haddock/doc/html/index.html</a>>.
<a name="line-294"></a>
<a name="line-295"></a>For more information on the nuts and bolts of how to develop your own
<a name="line-296"></a>extension, see the tutorial on the wiki:
<a name="line-297"></a><<a href="http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial">http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial</a>>.
<a name="line-298"></a>
<a name="line-299"></a>-}</span>
<a name="line-300"></a>
<a name="line-301"></a><span class='hs-comment'>{- $license
<a name="line-302"></a>
<a name="line-303"></a>New modules should identify the author, and be submitted under the
<a name="line-304"></a>same license as xmonad (BSD3 license or freer).
<a name="line-305"></a>
<a name="line-306"></a>-}</span>
</pre></body>
</html>
