path: root/Documentation.hs

-----------------------------------------------------------------------------
-- |
-- Module      :  Documentation
-- Copyright   :  (C) 2007 Andrea Rossato
-- License     :  BSD3
--
-- Maintainer  :  andrea.rossato@unibz.it
-- Stability   :  unstable
-- Portability :  unportable
--
-- This is a module for documenting the xmonad-contrib library
--
-----------------------------------------------------------------------------

module Documentation
    ( 
    -- * Configuring XMonad
    -- $configure
      
    -- ** A simple example
    -- $example
    
    -- ** Checking your xmonad.hs is correct
    -- $check
    
    -- ** Loading your configuration
    -- $load
    
    -- ** Where are the defaults?
    -- $where
    
    -- * The XmonadContrib Library
    -- $library
    
    -- * Extending XMonad
    -- $extending
    
    -- ** Editing Key Bindings
    -- $keys

    -- *** Adding Key Bindings
    -- $keyAdding

    -- *** Removing Key Bindings
    -- $keyDel

    -- *** Adding and Removing Key Bindings
    -- $keyAddDel

    -- ** Adding\/Removing Layouts
    -- $layout

    -- ** Hooks Management
    -- $hooks

    -- * Writing Other Extensions
    -- $writing
    ) where

--------------------------------------------------------------------------------
--
--  Configuring Xmonad
--
--------------------------------------------------------------------------------

{- $configure

xmonad is configured by creating and editing the Haskell file:

>    ~/.xmonad/xmonad.hs

xmonad then uses default settings from this file as arguments to the
window manager.

-}

{- $example

Here is a basic example, which takes defaults from xmonad, and
overrides the border width, default terminal, and some colours:

>    --
>    -- An example, simple ~/.xmonad/xmonad.hs file.
>    -- It overrides a few basic settings, reusing all the other defaults,
>    -- 
>
>    import XMonad
>
>    main = xmonad $ defaultConfig
>        { borderWidth        = 2
>        , terminal           = "urxvt"
>        , normalBorderColor  = "#cccccc"
>        , focusedBorderColor = "#cd8b00" }

This will run \'xmonad\', the window manager, with your settings
passed as arguments.

Overriding default settings like this (using \"record update
syntax\"), will yield the shortest config file, as you only have to
describe values that differ from the defaults.

An alternative is to inline the entire default config file from
xmonad, and edit values you wish to change. This is requires more
work, but some users may find this easier. You can find the defaults
in the file:

>    XMonad/Config.hs

-}

{- $check

Place this text in @~\/.xmonad\/xmonad.hs@, and then check that it is
syntactically and type correct, by loading it in the Haskell
interpreter:

>    $ ghci ~/.xmonad/xmonad.hs  
>    GHCi, version 6.8.1: http://www.haskell.org/ghc/  :? for help
>    Loading package base ... linking ... done.
>    Ok, modules loaded: Main.
>
>    Prelude Main> :t main
>    main :: IO ()

Ok, looks good.  

-}

{- $load

To have xmonad start using your settings, try @mod-q@. xmonad will
attempt to compile this file, and run it. If it is unable to, the
defaults are used. This requires GHC and xmonad are in your @$PATH@
settings. If GHC isn't in your path, you can still compile the
@xmonad.hs@ file yourself:

>    $ cd ~/.xmonad
>    $ ghc --make xmonad.hs
>    $ ls
>    xmonad    xmonad.hi xmonad.hs xmonad.o

When you hit @mod-q@, this newly compiled xmonad will be used.

-}

{- $where

The default configuration values are defined in the source file:

>   XMonad/Config.hs 

the 'XMonad.Core.XConfig' data structure itself is defined in:

>    XMonad/Core.hs

See "XMonad.Core".

-}

--------------------------------------------------------------------------------
--
--  The XmonadContrib Library
--
--------------------------------------------------------------------------------

{- $library

The xmonad-contrib (xmc) library is a set of modules contributed by
xmonad hackers and users. Examples include an ion3-like tabbed layout,
a prompt\/program launcher, and various other useful modules.

Some of these modules provide libraries and other useful functions to
write other modules and extensions.

Here is a short overview of the xmc content:
 
   [@Actions@] The content of Action

   [@Config@] The content of Config

   [@Hooks@] The content of Hooks

   [@Layout@] The content of Layout

   [@Prompt@] The content of Prompt

   [@Util@] The content of Util

-}

--------------------------------------------------------------------------------
--
--  Extending Xmonad
--
--------------------------------------------------------------------------------

{- $extending

Since the @xmonad.hs@ file is just another Haskell module, you may
import and use any Haskell code or libraries you wish, such as
extensions from the xmonad-contrib library, or other code you write
yourself.

-}

{- $keys

Editing key bindings means changing the 'XMonad.Core.XConfig.keys'
record of the 'XMonad.Core.XConfig' data type, like:

>    main = xmonad defaultConfig { keys = myKeys }

and providing a proper definition of @myKeys@ such as:

> myKeys x =
>          [ ((modMask x, xK_F12), xmonadPrompt defaultXPConfig)
>          , ((modMask x, xK_F3 ), shellPrompt  defaultXPConfig)
>          ]

Remember that this definition requires importing "Graphics.X11.Xlib",
"XMonad.Prompt", "XMonad.Prompt.Shell", and "XMonad.Prompt.XMonad"

-}

{- $keyAdding

Adding key bindings can be done in different ways. The type signature
of "XMonad.Core.XConfig.keys" is:

> keys :: XConfig Layout -> M.Map (ButtonMask,KeySym) (X ())

which means thatm in order to add new bindings you need to create a
'Data.Map.Map' from the list of your new key bindings, you can do that
with 'Data.Map.fromList', and then join this newly created map with
the one of the existing bindings. This can be done with
'Data.Map.union'.

For instance, if you have defined some additional key bindings like
these:

> myKeys x =
>          [ ((modMask x, xK_F12), xmonadPrompt defaultXPConfig)
>          , ((modMask x, xK_F3 ), shellPrompt  defaultXPConfig)
>          ]

then you create a new key bindings map by joining the default one with
yours:

> newKeys x  = M.union (keys defaultConfig x) (M.fromList (myKeys x))

Finally you need to update accordingly the default configuration
'XMonad.Core.XConfig.keys' record:

> main = xmonad defaultConfig { keys = newKeys }


And that's it.

At the end your @~\/.xmonad\/xmonad.hs@ would look like this:


> module Main (main) where
> 
> import XMonad
> 
> import qualified Data.Map as M
> import Graphics.X11.Xlib
> import XMonad.Prompt
> import XMonad.Prompt.Shell
> import XMonad.Prompt.XMonad
>
> main :: IO ()
> main = xmonad defaultConfig { keys = newKeys }
>
> newKeys x = M.union (keys defaultConfig x) (M.fromList (myKeys x))
>
> myKeys x =
>          [ ((modMask x, xK_F12), xmonadPrompt defaultXPConfig)
>          , ((modMask x, xK_F3 ), shellPrompt  defaultXPConfig)
>          ]


Obviously there are other ways of defining @newKeys@. For instance,
you could define it like this:

> newKeys x = foldr (uncurry M.insert) (keys defaultConfig x) (myKeys x)

An even simpler way to add new key bindings is the use of some of the
utilities provided by the xmonad-contrib library. For instance,
"XMonad.Util.EZConfig" and "XMonad.Util.CustomKeys" both provide
useful functions for editing your key bindings. Look, for instance, at
'XMonad.Util.EZConfig.additionalKeys'.

 -}

{- $keyDel

Removing key bindings requires modifying the binding 'Data.Map.Map'.
This can be done with 'Data.Map.difference' or with 'Data.Map.delete'.

Suppose you wan to get rid of @mod-q@ and @mod-shift-q@. To do this
you just need to define a @newKeys@ as a 'Data.Map.difference' between
the default map and the map of the key bindings you want to remove.

> newKeys x = M.difference (keys defaultConfig x) (M.fromList $ keysToRemove x)
> 
> keysToRemove :: XConfig Layout -> [((KeyMask, KeySym),X ())]
> keysToRemove x =
>          [ ((modMask x              , xK_q ), return ())
>          , ((modMask x .|. shiftMask, xK_q ), return ())
>          ]                                              

As you may see we do not need to define an action for the key bindings
we want to get rid of. We just build a map of keys to remove.

It is also possible to define a list of key bindings and then use
'Data.Map.delete' to remove them from the default key bindings, in
which case we should write something like:

> newKeys x = foldr M.delete (keys defaultConfig x) (keysToRemove x)
> 
> keysToRemove :: XConfig Layout -> [(KeyMask, KeySym)]
> keysToRemove x =
>          [ (modMask x              , xK_q )
>          , (modMask x .|. shiftMask, xK_q )
>          ]                                              

Another even simpler possibility is the use of some of the utilities
provided by the xmonad-contrib library. Look, for instance, at
'XMonad.Util.EZConfig.removeKeys'.

-}

{- $keyAddDel

Adding and removing key bindings requires to compose the action of
removing and, after that, the action of adding.

This is an example you may find in "XMonad.Config.Arossato":


>      defKeys    = keys defaultConfig
>      delKeys x  = foldr M.delete           (defKeys x) (toRemove x)
>      newKeys x  = foldr (uncurry M.insert) (delKeys x) (toAdd    x)
>      -- remove some of the default key bindings
>      toRemove x = 
>          [ (modMask x              , xK_j     )
>          , (modMask x              , xK_k     )
>          , (modMask x              , xK_p     )
>          , (modMask x .|. shiftMask, xK_p     )
>          , (modMask x .|. shiftMask, xK_q     )
>          , (modMask x              , xK_q     )
>          ] ++
>          -- I want modMask .|. shiftMask 1-9 to be free!
>          [(shiftMask .|. modMask x, k) | k <- [xK_1 .. xK_9]]
>      -- These are my personal key bindings
>      toAdd x   = 
>          [ ((modMask x              , xK_F12   ), xmonadPrompt defaultXPConfig )
>          , ((modMask x              , xK_F3    ), shellPrompt  defaultXPConfig )
>          ] ++
>          -- Use modMask .|. shiftMask .|. controlMask 1-9 instead
>          [( (m .|. modMask x, k), windows $ f i)
>           | (i, k) <- zip (workspaces x) [xK_1 .. xK_9]
>          ,  (f, m) <- [(W.greedyView, 0), (W.shift, shiftMask .|. controlMask)]
>          ]

You can achieve the same result by using "XMonad.Util.CustomKeys" and,
specifically, 'XMonad.Util.CustomKeys.customKeys'.

-}

{- $layout

Layouts
-}

{- $hooks

Hooks
-}

--------------------------------------------------------------------------------
--
--  Writing Extensions
--
--------------------------------------------------------------------------------

{- $writing

Writing Other Extensions

-}