# Xmonad/Guided tour of the xmonad source/Core.hs

### From HaskellWiki

(break up guided tour into subpages) |
m (→The X monad) |
||

(One intermediate revision by one user not shown) | |||

Line 1: | Line 1: | ||

− | |||

The next source file to examine is Core.hs. It defines several core data types and some of the core functionality of xmonad. If StackSet.hs is the heart of xmonad, Core.hs is its guts. | The next source file to examine is Core.hs. It defines several core data types and some of the core functionality of xmonad. If StackSet.hs is the heart of xmonad, Core.hs is its guts. | ||

Line 56: | Line 55: | ||

The X monad represents a common pattern for building custom monad instances: using ''monad transformers'', one can simply 'layer' the capabilities and effects of several monads into one, and then use GHC's newtype deriving capabilities to automatically derive instances of the relevant type classes. In this case, the base monad out of which the X monad is built is IO; this is necessary since communicating with the X server involves IO operations. On top of that is <hask>StateT XState</hask>, which automatically threads a mutable <hask>XState</hask> record through computations in the X monad; finally there is a <hask>ReaderT XConf</hask> which also threads a read-only <hask>XConf</hask> record through. As noted in the comments in the source, the <hask>XState</hask> record can be accessed with any functions in the [http://haskell.org/ghc/docs/latest/html/libraries/mtl/Control-Monad-State-Class.html#t%3AMonadState <hask>MonadState</hask>] type class, such as <hask>get</hask>, <hask>put</hask>, <hask>gets</hask>, and <hask>modify</hask>; the <hask>XConf</hask> record can be accessed with [http://haskell.org/ghc/docs/latest/html/libraries/mtl/Control-Monad-Reader-Class.html#t%3AMonadReader <hask>MonadReader</hask>] functions, such as <hask>ask</hask>. | The X monad represents a common pattern for building custom monad instances: using ''monad transformers'', one can simply 'layer' the capabilities and effects of several monads into one, and then use GHC's newtype deriving capabilities to automatically derive instances of the relevant type classes. In this case, the base monad out of which the X monad is built is IO; this is necessary since communicating with the X server involves IO operations. On top of that is <hask>StateT XState</hask>, which automatically threads a mutable <hask>XState</hask> record through computations in the X monad; finally there is a <hask>ReaderT XConf</hask> which also threads a read-only <hask>XConf</hask> record through. As noted in the comments in the source, the <hask>XState</hask> record can be accessed with any functions in the [http://haskell.org/ghc/docs/latest/html/libraries/mtl/Control-Monad-State-Class.html#t%3AMonadState <hask>MonadState</hask>] type class, such as <hask>get</hask>, <hask>put</hask>, <hask>gets</hask>, and <hask>modify</hask>; the <hask>XConf</hask> record can be accessed with [http://haskell.org/ghc/docs/latest/html/libraries/mtl/Control-Monad-Reader-Class.html#t%3AMonadReader <hask>MonadReader</hask>] functions, such as <hask>ask</hask>. | ||

− | For more information on monad transformers in general, I recommend reading Martin Grabmüller's excellent tutorial paper, [http:// | + | For more information on monad transformers in general, I recommend reading Martin Grabmüller's excellent tutorial paper, [http://www.grabmueller.de/martin/www/pub/Transformers.en.html Monad Transformers Step-by-Step]; for more information on this particular style of composing monad transformers and using automatic newtype deriving, read Cale Gibbard's tutorial, [http://cale.yi.org/index.php/How_To_Use_Monad_Transformers How To Use Monad Transformers]. |

Along with the X monad, several utility functions are provided, such as <hask>runX</hask>, which turns an action in the X monad into an IO action, and <hask>catchX</hask>, which provides error handling for X actions. There are also several higher-order functions provided for convenience, including <hask>withDisplay</hask> (apply a function producing an X action to the current display) and <hask>withWindowSet</hask> (apply a function to the current window set). | Along with the X monad, several utility functions are provided, such as <hask>runX</hask>, which turns an action in the X monad into an IO action, and <hask>catchX</hask>, which provides error handling for X actions. There are also several higher-order functions provided for convenience, including <hask>withDisplay</hask> (apply a function producing an X action to the current display) and <hask>withWindowSet</hask> (apply a function to the current window set). | ||

Line 137: | Line 136: | ||

=== Utility functions === | === Utility functions === | ||

+ | |||

+ | The end of <pre>Core.hs</pre> includes a number of utility functions which are used throughout the rest of the xmonad codebase; you should take some time to familiarize yourself with the functions here. Notable examples include <hask>spawn</hask> and <hask>doubleFork</hask>, which allow for creation of new threads; <hask>io</hask>, a short synonym for <hask>liftIO</hask> (which can be used to turn <hask>IO ()</hask> actions into <hask>X ()</hask> actions); and <hask>runOnWorkspaces</hask>, which maps <hask>(WindowSpace -> X WindowSpace)</hask> functions over all workspaces. | ||

=== On-the-fly recompilation === | === On-the-fly recompilation === |

## Latest revision as of 10:58, 2 May 2012

The next source file to examine is Core.hs. It defines several core data types and some of the core functionality of xmonad. If StackSet.hs is the heart of xmonad, Core.hs is its guts.

## Contents |

### [edit] 1 XState, XConf, and XConfig

These three record types make up the core of xmonad's state and configuration:

- A value of type stores xmonad's mutable runtime state, consisting of the list of workspaces, a set of mapped windows, something to do with keeping track of pending UnmapEvents, and something to do with dragging.XState

data XState = XState { windowset :: !WindowSet -- ^ workspace list , mapped :: !(S.Set Window) -- ^ the Set of mapped windows , waitingUnmap :: !(M.Map Window Int) -- ^ the number of expected UnmapEvents , dragging :: !(Maybe (Position -> Position -> X (), X ())) }

type WindowSet = StackSet WorkspaceId (Layout Window) Window ScreenId ScreenDetail type WindowSpace = Workspace WorkspaceId (Layout Window) Window -- | Virtual workspace indicies type WorkspaceId = String -- | Physical screen indicies newtype ScreenId = S Int deriving (Eq,Ord,Show,Read,Enum,Num,Integral,Real) -- | The 'Rectangle' with screen dimensions and the list of gaps data ScreenDetail = SD { screenRect :: !Rectangle , statusGap :: !(Int,Int,Int,Int) -- ^ width of status bar on the screen } deriving (Eq,Show, Read)

newtype ScreenId = S Int deriving (...)

*just as if*

- An record stores xmonad's (immutable) configuration data, such as window border colors, the keymap, information about the X11 display and root window, and other user-specified configuration information. The reason this record is separated fromXConfis that, as we'll see later, xmonad's code provides a static guarantee that the data stored in this record is truly read-only, and cannot be changed while xmonad is running.XState

- provides a way for the user to customize xmonad's configuration, by defining anXConfigrecord in theirXConfigfile. You're probably already familiar with this record type.xmonad.hs

### [edit] 2 The X monad

And now, what you've all been waiting for: the X monad!

newtype X a = X (ReaderT XConf (StateT XState IO) a) deriving (Functor, Monad, MonadIO, MonadState XState, MonadReader XConf)

*monad transformers*, one can simply 'layer' the capabilities and effects of several monads into one, and then use GHC's newtype deriving capabilities to automatically derive instances of the relevant type classes. In this case, the base monad out of which the X monad is built is IO; this is necessary since communicating with the X server involves IO operations. On top of that is

For more information on monad transformers in general, I recommend reading Martin Grabmüller's excellent tutorial paper, Monad Transformers Step-by-Step; for more information on this particular style of composing monad transformers and using automatic newtype deriving, read Cale Gibbard's tutorial, How To Use Monad Transformers.

Along with the X monad, several utility functions are provided, such as### [edit] 3 ManageHook

This is a bit more advanced, and not really a central part of the system, so I'm skipping it for now, hopefully coming back to add more later.

### [edit] 4 LayoutClass

Next, let's take a look at the - Note that all the functions provide default implementations, so thatLayoutClassinstances do not have to provide implementations of those functions where the default behavior is desired. For example, by default,LayoutClasssimply callsdoLayout, so a layout that does not require access to the X monad need only implement thepureLayoutfunction. (For example, the Accordion, Square, and Grid layouts from the contrib library all use this approach.)pureLayout

- Layouts can have their own private state, by storing this state in the instance and returning a modified structue (viaLayoutClass) when the state changes.doLayout

- Both anddoLayouthave corresponding "pure" versions, which do not give results in the X monad. These functions are never called directly by the xmonad core, which only callshandleMessageanddoLayout, but a layout may choose to implement one (or both) of these "pure" functions, which will be called by the default implementation of the "impure" versions. Layouts which implementhandleMessageorpureLayoutare guaranteed to only make decisions about layout or messages (respectively) based on the internal layout state, and not on the state of the system or the window manager in general.pureMessage

*existential type*which hides the particular layout type and only exposes the fact that it is an instance of

-- | An existential type that can hold any object that is in Read and LayoutClass. data Layout a = forall l. (LayoutClass l a, Read (l a)) => Layout (l a)

### [edit] 5 Messages

The xmonad core uses *messages* to communicate with layouts. The obvious, simple way to define messages would be by defining a new data type, something like

-- WARNING: not real xmonad code! data Message = Hide | ReleaseResources | ShowMonkey

thus defining three messages types, which tell a layout to hide itself, release any resources, and display a monkey, respectively.

The problem with such an approach should be obvious: it is completely inflexible and inextensible; adding new message types later would be a pain, and it would be practically impossible for extension layouts to define their own message types without modifying the core. So, xmonad uses a more sophisticated system (at the cost of making things slightly harder to read and understand).

Instead of defining a*type class*:

class Typeable a => Message a data SomeMessage = forall a. Message a => SomeMessage a

-- | And now, unwrap a given, unknown Message type, performing a (dynamic) -- type check on the result. -- fromMessage :: Message m => SomeMessage -> Maybe m fromMessage (SomeMessage m) = cast m

Complicated? A bit, perhaps, but the good news is that you probably don't have to worry too much about it. =)

Finally, raw X events (like key presses, mouse movements, and so on) count as-- | X Events are valid Messages instance Message Event -- | LayoutMessages are core messages that all layouts (especially stateful -- layouts) should consider handling. data LayoutMessages = Hide -- ^ sent when a layout becomes non-visible | ReleaseResources -- ^ sent when xmonad is exiting or restarting deriving (Typeable, Eq) instance Message LayoutMessages

### [edit] 6 Utility functions

The end ofCore.hsincludes a number of utility functions which are used throughout the rest of the xmonad codebase; you should take some time to familiarize yourself with the functions here. Notable examples include