<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--Rendered using the Haskell Html Library v0.2-->
<HTML
><HEAD
><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8"
><TITLE
>XMonad.Doc.Developing</TITLE
><LINK HREF="haddock.css" REL="stylesheet" TYPE="text/css"
><SCRIPT SRC="haddock-util.js" TYPE="text/javascript"
></SCRIPT
><SCRIPT TYPE="text/javascript"
>window.onload = function () {setSynopsis("mini_XMonad-Doc-Developing.html")};</SCRIPT
></HEAD
><BODY
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="topbar"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD
><IMG SRC="haskell_icon.gif" WIDTH="16" HEIGHT="16" ALT=" "
></TD
><TD CLASS="title"
>xmonad-contrib-0.9.1: Third party extensions for xmonad</TD
><TD CLASS="topbut"
><A HREF="src/XMonad-Doc-Developing.html"
>Source code</A
></TD
><TD CLASS="topbut"
><A HREF="index.html"
>Contents</A
></TD
><TD CLASS="topbut"
><A HREF="doc-index.html"
>Index</A
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="modulebar"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD
><FONT SIZE="6"
>XMonad.Doc.Developing</FONT
></TD
><TD ALIGN="right"
><TABLE CLASS="narrow" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="infohead"
>Portability</TD
><TD CLASS="infoval"
>portable</TD
></TR
><TR
><TD CLASS="infohead"
>Stability</TD
><TD CLASS="infoval"
>unstable</TD
></TR
><TR
><TD CLASS="infohead"
>Maintainer</TD
><TD CLASS="infoval"
>andrea.rossato@unibz.it</TD
></TR
></TABLE
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="section4"
><B
>Contents</B
></TD
></TR
><TR
><TD
><DL
><DT
><A HREF="#1"
>Writing new extensions
</A
></DT
><DT
><A HREF="#2"
>Libraries for writing window managers
</A
></DT
><DT
><A HREF="#3"
>xmonad internals
</A
></DT
><DD
><DL
><DT
><A HREF="#4"
>The <TT
>main</TT
> entry point
</A
></DT
><DT
><A HREF="#5"
>The X monad and the internal state
</A
></DT
><DT
><A HREF="#6"
>Event handling and messages
</A
></DT
><DT
><A HREF="#7"
>The LayoutClass
</A
></DT
></DL
></DD
><DT
><A HREF="#8"
>Coding style
</A
></DT
><DT
><A HREF="#9"
>Licensing policy
</A
></DT
></DL
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
>Description</TD
></TR
><TR
><TD CLASS="doc"
><P
>This module gives a brief overview of the xmonad internals. It is
intended for advanced users who are curious about the xmonad source
code and want an brief overview. This document may also be helpful
for the beginner/intermediate Haskell programmer who is motivated
to write an xmonad extension as a way to deepen her understanding
of this powerful functional language; however, there is not space
here to go into much detail. For a more comprehensive document
covering some of the same material in more depth, see the guided
tour of the xmonad source on the xmonad wiki:
<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
>.
</P
><P
>If you write an extension module and think it may be useful for
others, consider releasing it. Coding guidelines and licensing
policies are covered at the end of this document, and must be
followed if you want your code to be included in the official
repositories. For a basic tutorial on the nuts and bolts of
developing a new extension for xmonad, see the tutorial on the
wiki:
<A HREF="http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial"
>http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial</A
>.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
>Synopsis</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="body"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
></TABLE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
><A NAME="1"
><A NAME="1"
>Writing new extensions
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
><A NAME="2"
><A NAME="2"
>Libraries for writing window managers
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
><P
>Starting with version 0.5, xmonad and xmonad-contrib are packaged and
distributed as libraries, instead of components which must be compiled
by the user into a binary (as they were prior to version 0.5). This
way of distributing xmonad has many advantages, since it allows
packaging by GNU/Linux distributions while still allowing the user to
customize the window manager to fit her needs.
</P
><P
>Basically, xmonad and the xmonad-contrib libraries let users write
their own window manager in just a few lines of code. While
<TT
>~/.xmonad/xmonad.hs</TT
> at first seems to be simply a configuration
file, it is actually a complete Haskell program which uses the xmonad
and xmonad-contrib libraries to create a custom window manager.
</P
><P
>This makes it possible not only to edit the default xmonad
configuration, as we have seen in the <A HREF="XMonad-Doc-Extending.html"
>XMonad.Doc.Extending</A
> document,
but to use the Haskell programming language to extend the window
manager you are writing in any way you see fit.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
><A NAME="3"
><A NAME="3"
>xmonad internals
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section2"
><A NAME="4"
><A NAME="4"
>The <TT
>main</TT
> entry point
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
><P
><A NAME="The_main_entry_point"
><A NAME="The_main_entry_point"
></A
></A
>
</P
><P
>xmonad installs a binary, <TT
>xmonad</TT
>, which must be executed by the
Xsession starting script. This binary, whose code can be read in
<TT
>Main.hs</TT
> of the xmonad source tree, will use XMonad.Core.recompile
to run <TT
>ghc</TT
> in order to build a binary from <TT
>~/.xmonad/xmonad.hs</TT
>.
If this compilation process fails, for any reason, a default <TT
>main</TT
>
entry point will be used, which calls the XMonad.Main.xmonad
function with a default configuration.
</P
><P
>Thus, the real <TT
>main</TT
> entry point, the one that even the users' custom
window manager application in <TT
>~/.xmonad/xmonad.hs</TT
> must call, is
the XMonad.Main.xmonad function. This function takes a configuration
as its only argument, whose type (XMonad.Core.XConfig)
is defined in <A HREF="XMonad-Core.html"
>XMonad.Core</A
>.
</P
><P
>XMonad.Main.xmonad takes care of opening the connection with the X
server, initializing the state (or deserializing it when restarted)
and the configuration, and calling the event handler
(XMonad.Main.handle) that goes into an infinite loop (using
Prelude.forever) waiting for events and acting accordingly.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section2"
><A NAME="5"
><A NAME="5"
>The X monad and the internal state
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
><P
>The event loop which calls XMonad.Main.handle to react to events is
run within the XMonad.Core.X monad, which is a
Control.Monad.State.StateT transformer over <TT
><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO"
>IO</A
></TT
>, encapsulated
within a Control.Monad.Reader.ReaderT transformer. The
Control.Monad.State.StateT transformer encapsulates the
(read/writable) state of the window manager (of type
XMonad.Core.XState), whereas the Control.Monad.Reader.ReaderT
transformer encapsulates the (read-only) configuration (of type
XMonad.Core.XConf).
</P
><P
>Thanks to GHC's newtype deriving feature, the instance of the
Control.Monad.State.MonadState class parametrized over
XMonad.Core.XState and the instance of the
Control.Monad.Reader.MonadReader class parametrized over
XMonad.Core.XConf are automatically derived for the XMonad.Core.X
monad. This way we can use Control.Monad.State.get,
Control.Monad.State.gets and Control.Monad.State.modify for the
XMonad.Core.XState, and Control.Monad.Reader.ask and
Control.Monad.Reader.asks for reading the XMonad.Core.XConf.
</P
><P
>XMonad.Core.XState is where all the sensitive information about
window management is stored. The most important field of the
XMonad.Core.XState is the XMonad.Core.windowset, whose type
(XMonad.Core.WindowSet) is a synonym for a
XMonad.StackSet.StackSet parametrized over a
XMonad.Core.WorkspaceID (a <TT
><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString"
>String</A
></TT
>), a layout type wrapped inside
the XMonad.Layout.Layout existential data type, the
Graphics.X11.Types.Window type, the XMonad.Core.ScreenID and the
XMonad.Core.ScreenDetails.
</P
><P
>What a XMonad.StackSet.StackSet is and how it can be manipulated
with pure functions is described in the Haddock documentation of the
<A HREF="XMonad-StackSet.html"
>XMonad.StackSet</A
> module.
</P
><P
>The XMonad.StackSet.StackSet (XMonad.Core.WindowSet) has four
fields:
</P
><UL
><LI
> XMonad.StackSet.current, for the current, focused workspace. This
is a XMonad.StackSet.Screen, which is composed of a
XMonad.StackSet.Workspace together with the screen information (for
Xinerama support).
</LI
><LI
> XMonad.StackSet.visible, a list of XMonad.StackSet.Screens for
the other visible (with Xinerama) workspaces. For non-Xinerama
setups, this list is always empty.
</LI
><LI
> XMonad.StackSet.hidden, the list of non-visible
XMonad.StackSet.Workspaces.
</LI
><LI
> XMonad.StackSet.floating, a map from floating
Graphics.X11.Types.Windows to XMonad.StackSet.RationalRects
specifying their geometry.
</LI
></UL
><P
>The XMonad.StackSet.Workspace type is made of a
XMonad.StackSet.tag, a XMonad.StackSet.layout and
a (possibly empty) XMonad.StackSet.stack of windows.
</P
><P
><A HREF="XMonad-StackSet.html"
>XMonad.StackSet</A
> (which should usually be imported qualified, to
avoid name clashes with Prelude functions such as Prelude.delete and
<TT
><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-List.html#v%3Afilter"
>filter</A
></TT
>) provides many pure functions to manipulate the
XMonad.StackSet.StackSet. These functions are most commonly used as
an argument to XMonad.Operations.windows, which takes a pure
function to manipulate the XMonad.Core.WindowSet and does all the
needed operations to refresh the screen and save the modified
XMonad.Core.XState.
</P
><P
>During each XMonad.Operations.windows call, the
XMonad.StackSet.layout field of the XMonad.StackSet.current and
XMonad.StackSet.visible XMonad.StackSet.Workspaces are used to
physically arrange the XMonad.StackSet.stack of windows on each
workspace.
</P
><P
>The possibility of manipulating the XMonad.StackSet.StackSet
(XMonad.Core.WindowSet) with pure functions makes it possible to
test all the properties of those functions with QuickCheck, providing
greater reliability of the core code. Every change to the
<A HREF="XMonad-StackSet.html"
>XMonad.StackSet</A
> module must be accompanied by appropriate QuickCheck
properties before being applied.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section2"
><A NAME="6"
><A NAME="6"
>Event handling and messages
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
><P
>Event handling is the core activity of xmonad. Events generated by
the X server are most important, but there may also be events
generated by layouts or the user.
</P
><P
><A HREF="XMonad-Core.html"
>XMonad.Core</A
> defines a class that generalizes the concept of events,
XMonad.Core.Message, constrained to types with a
Data.Typeable.Typeable instance definition (which can be
automatically derived by GHC). XMonad.Core.Messages are wrapped
within an existential type XMonad.Core.SomeMessage. The
Data.Typeable.Typeable constraint allows for the definition of a
XMonad.Core.fromMessage function that can unwrap the message with
Data.Typeable.cast. X Events are instances of this class, along
with any messages used by xmonad itself or by extension modules.
</P
><P
>Using the Data.Typeable.Typeable class for any kind of
XMonad.Core.Messages and events allows us to define polymorphic functions
for processing messages or unhandled events.
</P
><P
>This is precisely what happens with X events: xmonad passes them to
XMonad.Main.handle. If the main event handling function doesn't have
anything to do with the event, the event is sent to all visible
layouts by XMonad.Operations.broadcastMessage.
</P
><P
>This messaging system allows the user to create new message types,
simply declare an instance of the Data.Typeable.Typeable and use
XMonad.Operations.sendMessage to send commands to layouts.
</P
><P
>And, finally, layouts may handle X events and other messages within the
same function... miracles of polymorphism.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section2"
><A NAME="7"
><A NAME="7"
>The LayoutClass
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
><A NAME="The_LayoutClass"
><A NAME="The_LayoutClass"
></A
></A
>
to do
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
><A NAME="8"
><A NAME="8"
>Coding style
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
><P
>These are the coding guidelines for contributing to xmonad and the
xmonad contributed extensions.
</P
><UL
><LI
> Comment every top level function (particularly exported funtions), and
provide a type signature.
</LI
><LI
> Use Haddock syntax in the comments (see below).
</LI
><LI
> Follow the coding style of the other modules.
</LI
><LI
> Code should be compilable with <A HREF="ghc-options: -Wall -Werror.html"
>ghc-options: -Wall -Werror</A
> set in the
xmonad-contrib.cabal file. There should be no warnings.
</LI
><LI
> Partial functions should be avoided: the window manager should not
crash, so never call <TT
><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Prelude.html#v%3Aerror"
>error</A
></TT
> or <TT
><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Prelude.html#v%3Aundefined"
>undefined</A
></TT
>.
</LI
><LI
> Tabs are <EM
>illegal</EM
>. Use 4 spaces for indenting.
</LI
><LI
> Any pure function added to the core must have QuickCheck properties
precisely defining its behaviour. Tests for everything else are encouraged.
</LI
></UL
><P
>For examples of Haddock documentation syntax, have a look at other
extensions. Important points are:
</P
><UL
><LI
> Every exported function (or even better, every function) should have
a Haddock comment explaining what it does, and providing examples.
</LI
><LI
> Literal chunks of code can be written in comments using
"birdtrack" notation (a greater-than symbol at the beginning of
each line). Be sure to leave a blank line before and after each
birdtrack-quoted section.
</LI
><LI
> Link to functions by surrounding the names in single quotes, modules
in double quotes.
</LI
><LI
> Literal quote marks and slashes should be escaped with a backslash.
</LI
></UL
><P
>To generate and view the Haddock documentation for your extension, run
</P
><PRE
> runhaskell Setup haddock
</PRE
><P
>and then point your browser to <TT
>/path/to/XMonadContrib/dist/doc/html/xmonad-contrib/index.html</TT
>.
</P
><P
>For more information, see the Haddock documentation:
<A HREF="http://www.haskell.org/haddock/doc/html/index.html"
>http://www.haskell.org/haddock/doc/html/index.html</A
>.
</P
><P
>For more information on the nuts and bolts of how to develop your own
extension, see the tutorial on the wiki:
<A HREF="http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial"
>http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial</A
>.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
><A NAME="9"
><A NAME="9"
>Licensing policy
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
>New modules should identify the author, and be submitted under the
same license as xmonad (BSD3 license or freer).
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="botbar"
>Produced by <A HREF="http://www.haskell.org/haddock/"
>Haddock</A
> version 2.6.1</TD
></TR
></TABLE
></BODY
></HTML
>
