mirror of
https://github.com/xmonad/xmonad-contrib.git
synced 2025-07-31 20:21:51 -07:00
392 lines
10 KiB
Haskell
392 lines
10 KiB
Haskell
-----------------------------------------------------------------------------
|
|
-- |
|
|
-- 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
|
|
|
|
-} |