XMonad.Core

The X monad, a state monad transformer over IO, for the window manager state, and support routines.

Documentation

data X a

The X monad, ReaderT and StateT transformers over IO encapsulating the window manager configuration and state, respectively.

Dynamic components may be retrieved with get, static components with ask. With newtype deriving we get readers and state monads instantiated on XConf and XState automatically.

Instances

Monad X

Methods

(>>=) :: X a -> (a -> X b) -> X b

(>>) :: X a -> X b -> X b

return :: a -> X a

fail :: String -> X a

Functor X

Methods

fmap :: (a -> b) -> X a -> X b

(<$) :: a -> X b -> X a

Applicative X

Methods

pure :: a -> X a

(<*>) :: X (a -> b) -> X a -> X b

(*>) :: X a -> X b -> X b

(<*) :: X a -> X b -> X a

MonadIO X

Methods

liftIO :: IO a -> X a

MonadReader XConf X

Methods

ask :: X XConf

local :: (XConf -> XConf) -> X a -> X a

reader :: (XConf -> a) -> X a

MonadState XState X

Methods

get :: X XState

put :: XState -> X ()

state :: (XState -> (a, XState)) -> X a

Monoid a => Monoid (X a)

Methods

mempty :: X a

mappend :: X a -> X a -> X a

mconcat :: [X a] -> X a

Default a => Default (X a)

Methods

def :: X a

type WindowSet = StackSet WorkspaceId (Layout Window) Window ScreenId ScreenDetail

type WindowSpace = Workspace WorkspaceId (Layout Window) Window

type WorkspaceId = String

Virtual workspace indices

newtype ScreenId

Physical screen indices

Constructors

S Int

Instances

Enum ScreenId

Methods

succ :: ScreenId -> ScreenId

pred :: ScreenId -> ScreenId

toEnum :: Int -> ScreenId

fromEnum :: ScreenId -> Int

enumFrom :: ScreenId -> [ScreenId]

enumFromThen :: ScreenId -> ScreenId -> [ScreenId]

enumFromTo :: ScreenId -> ScreenId -> [ScreenId]

enumFromThenTo :: ScreenId -> ScreenId -> ScreenId -> [ScreenId]

Eq ScreenId

Methods

(==) :: ScreenId -> ScreenId -> Bool

(/=) :: ScreenId -> ScreenId -> Bool

Integral ScreenId

Methods

quot :: ScreenId -> ScreenId -> ScreenId

rem :: ScreenId -> ScreenId -> ScreenId

div :: ScreenId -> ScreenId -> ScreenId

mod :: ScreenId -> ScreenId -> ScreenId

quotRem :: ScreenId -> ScreenId -> (ScreenId, ScreenId)

divMod :: ScreenId -> ScreenId -> (ScreenId, ScreenId)

toInteger :: ScreenId -> Integer

Num ScreenId

Methods

(+) :: ScreenId -> ScreenId -> ScreenId

(-) :: ScreenId -> ScreenId -> ScreenId

(*) :: ScreenId -> ScreenId -> ScreenId

negate :: ScreenId -> ScreenId

abs :: ScreenId -> ScreenId

signum :: ScreenId -> ScreenId

fromInteger :: Integer -> ScreenId

Ord ScreenId

Methods

compare :: ScreenId -> ScreenId -> Ordering

(<) :: ScreenId -> ScreenId -> Bool

(<=) :: ScreenId -> ScreenId -> Bool

(>) :: ScreenId -> ScreenId -> Bool

(>=) :: ScreenId -> ScreenId -> Bool

max :: ScreenId -> ScreenId -> ScreenId

min :: ScreenId -> ScreenId -> ScreenId

Read ScreenId

Methods

readsPrec :: Int -> ReadS ScreenId

readList :: ReadS [ScreenId]

readPrec :: ReadPrec ScreenId

readListPrec :: ReadPrec [ScreenId]

Real ScreenId

Methods

toRational :: ScreenId -> Rational

Show ScreenId

Methods

showsPrec :: Int -> ScreenId -> ShowS

show :: ScreenId -> String

showList :: [ScreenId] -> ShowS

data ScreenDetail

The Rectangle with screen dimensions

Constructors

SD

Fields

• screenRect :: !Rectangle

Instances

Eq ScreenDetail

Methods

(==) :: ScreenDetail -> ScreenDetail -> Bool

(/=) :: ScreenDetail -> ScreenDetail -> Bool

Read ScreenDetail

Methods

readsPrec :: Int -> ReadS ScreenDetail

readList :: ReadS [ScreenDetail]

readPrec :: ReadPrec ScreenDetail

readListPrec :: ReadPrec [ScreenDetail]

Show ScreenDetail

Methods

showsPrec :: Int -> ScreenDetail -> ShowS

show :: ScreenDetail -> String

showList :: [ScreenDetail] -> ShowS

data XState

XState, the (mutable) window manager state.

Constructors

XState

Fields

• windowset :: !WindowSet

  workspace list

• mapped :: !(Set Window)

  the Set of mapped windows

• waitingUnmap :: !(Map Window Int)

  the number of expected UnmapEvents

• dragging :: !(Maybe (Position -> Position -> X (), X ()))
• numberlockMask :: !KeyMask

  The numlock modifier

• extensibleState :: !(Map String (Either String StateExtension))

  stores custom state information.

  The module XMonad.Utils.ExtensibleState in xmonad-contrib provides additional information and a simple interface for using this.

Instances

MonadState XState X

Methods

get :: X XState

put :: XState -> X ()

state :: (XState -> (a, XState)) -> X a

data XConf

XConf, the (read-only) window manager configuration.

Constructors

XConf

Fields

• display :: Display

  the X11 display

• config :: !(XConfig Layout)

  initial user configuration

• theRoot :: !Window

  the root window

• normalBorder :: !Pixel

  border color of unfocused windows

• focusedBorder :: !Pixel

  border color of the focused window

• keyActions :: !(Map (KeyMask, KeySym) (X ()))

  a mapping of key presses to actions

• buttonActions :: !(Map (KeyMask, Button) (Window -> X ()))

  a mapping of button presses to actions

• mouseFocused :: !Bool

  was refocus caused by mouse action?

• mousePosition :: !(Maybe (Position, Position))

  position of the mouse according to the event currently being processed

• currentEvent :: !(Maybe Event)

  event currently being processed

Instances

MonadReader XConf X

Methods

ask :: X XConf

local :: (XConf -> XConf) -> X a -> X a

reader :: (XConf -> a) -> X a

data XConfig l

Constructors

XConfig

Fields

• normalBorderColor :: !String

  Non focused windows border color. Default: "#dddddd"

• focusedBorderColor :: !String

  Focused windows border color. Default: "#ff0000"

• terminal :: !String

  The preferred terminal application. Default: "xterm"

• layoutHook :: !(l Window)

  The available layouts

• manageHook :: !ManageHook

  The action to run when a new window is opened

• handleEventHook :: !(Event -> X All)

  Handle an X event, returns (All True) if the default handler should also be run afterwards. mappend should be used for combining event hooks in most cases.

• workspaces :: ![String]

  The list of workspaces' names

• modMask :: !KeyMask

  the mod modifier

• keys :: !(XConfig Layout -> Map (ButtonMask, KeySym) (X ()))

  The key binding: a map from key presses and actions

• mouseBindings :: !(XConfig Layout -> Map (ButtonMask, Button) (Window -> X ()))

  The mouse bindings

• borderWidth :: !Dimension

  The border width

• logHook :: !(X ())

  The action to perform when the windows set is changed

• startupHook :: !(X ())

  The action to perform on startup

• focusFollowsMouse :: !Bool

  Whether window entry events can change focus

• clickJustFocuses :: !Bool

  False to make a click which changes focus to be additionally passed to the window

• clientMask :: !EventMask

  The client events that xmonad is interested in

• rootMask :: !EventMask

  The root events that xmonad is interested in

• handleExtraArgs :: !([String] -> XConfig Layout -> IO (XConfig Layout))

  Modify the configuration, complain about extra arguments etc. with arguments that are not handled by default

class Show (layout a) => LayoutClass layout a where

Every layout must be an instance of LayoutClass, which defines the basic layout operations along with a sensible default for each.

Minimal complete definition:

• runLayout || ((doLayout || pureLayout) && emptyLayout), and
• handleMessage || pureMessage

You should also strongly consider implementing description, although it is not required.

Note that any code which uses LayoutClass methods should only ever call runLayout, handleMessage, and description! In other words, the only calls to doLayout, pureMessage, and other such methods should be from the default implementations of runLayout, handleMessage, and so on. This ensures that the proper methods will be used, regardless of the particular methods that any LayoutClass instance chooses to define.

Methods

runLayout :: Workspace WorkspaceId (layout a) a -> Rectangle -> X ([(a, Rectangle)], Maybe (layout a))

By default, runLayout calls doLayout if there are any windows to be laid out, and emptyLayout otherwise. Most instances of LayoutClass probably do not need to implement runLayout; it is only useful for layouts which wish to make use of more of the Workspace information (for example, XMonad.Layout.PerWorkspace).

doLayout :: layout a -> Rectangle -> Stack a -> X ([(a, Rectangle)], Maybe (layout a))

Given a Rectangle in which to place the windows, and a Stack of windows, return a list of windows and their corresponding Rectangles. If an element is not given a Rectangle by doLayout, then it is not shown on screen. The order of windows in this list should be the desired stacking order.

Also possibly return a modified layout (by returning Just newLayout), if this layout needs to be modified (e.g. if it keeps track of some sort of state). Return Nothing if the layout does not need to be modified.

Layouts which do not need access to the X monad (IO, window manager state, or configuration) and do not keep track of their own state should implement pureLayout instead of doLayout.

pureLayout :: layout a -> Rectangle -> Stack a -> [(a, Rectangle)]

This is a pure version of doLayout, for cases where we don't need access to the X monad to determine how to lay out the windows, and we don't need to modify the layout itself.

emptyLayout :: layout a -> Rectangle -> X ([(a, Rectangle)], Maybe (layout a))

emptyLayout is called when there are no windows.

handleMessage :: layout a -> SomeMessage -> X (Maybe (layout a))

handleMessage performs message handling. If handleMessage returns Nothing, then the layout did not respond to the message and the screen is not refreshed. Otherwise, handleMessage returns an updated layout and the screen is refreshed.

Layouts which do not need access to the X monad to decide how to handle messages should implement pureMessage instead of handleMessage (this restricts the risk of error, and makes testing much easier).

pureMessage :: layout a -> SomeMessage -> Maybe (layout a)

Respond to a message by (possibly) changing our layout, but taking no other action. If the layout changes, the screen will be refreshed.

description :: layout a -> String

This should be a human-readable string that is used when selecting layouts by name. The default implementation is show, which is in some cases a poor default.

Instances

LayoutClass Layout Window

Methods

runLayout :: Workspace WorkspaceId (Layout Window) Window -> Rectangle -> X ([(Window, Rectangle)], Maybe (Layout Window))

doLayout :: Layout Window -> Rectangle -> Stack Window -> X ([(Window, Rectangle)], Maybe (Layout Window))

pureLayout :: Layout Window -> Rectangle -> Stack Window -> [(Window, Rectangle)]

emptyLayout :: Layout Window -> Rectangle -> X ([(Window, Rectangle)], Maybe (Layout Window))

handleMessage :: Layout Window -> SomeMessage -> X (Maybe (Layout Window))

pureMessage :: Layout Window -> SomeMessage -> Maybe (Layout Window)

description :: Layout Window -> String

LayoutClass Tall a

Methods

runLayout :: Workspace WorkspaceId (Tall a) a -> Rectangle -> X ([(a, Rectangle)], Maybe (Tall a))

doLayout :: Tall a -> Rectangle -> Stack a -> X ([(a, Rectangle)], Maybe (Tall a))

pureLayout :: Tall a -> Rectangle -> Stack a -> [(a, Rectangle)]

emptyLayout :: Tall a -> Rectangle -> X ([(a, Rectangle)], Maybe (Tall a))

handleMessage :: Tall a -> SomeMessage -> X (Maybe (Tall a))

pureMessage :: Tall a -> SomeMessage -> Maybe (Tall a)

description :: Tall a -> String

LayoutClass Full a

Methods

runLayout :: Workspace WorkspaceId (Full a) a -> Rectangle -> X ([(a, Rectangle)], Maybe (Full a))

doLayout :: Full a -> Rectangle -> Stack a -> X ([(a, Rectangle)], Maybe (Full a))

pureLayout :: Full a -> Rectangle -> Stack a -> [(a, Rectangle)]

emptyLayout :: Full a -> Rectangle -> X ([(a, Rectangle)], Maybe (Full a))

handleMessage :: Full a -> SomeMessage -> X (Maybe (Full a))

pureMessage :: Full a -> SomeMessage -> Maybe (Full a)

description :: Full a -> String

LayoutClass l a => LayoutClass (Mirror l) a

Methods

runLayout :: Workspace WorkspaceId (Mirror l a) a -> Rectangle -> X ([(a, Rectangle)], Maybe (Mirror l a))

doLayout :: Mirror l a -> Rectangle -> Stack a -> X ([(a, Rectangle)], Maybe (Mirror l a))

pureLayout :: Mirror l a -> Rectangle -> Stack a -> [(a, Rectangle)]

emptyLayout :: Mirror l a -> Rectangle -> X ([(a, Rectangle)], Maybe (Mirror l a))

handleMessage :: Mirror l a -> SomeMessage -> X (Maybe (Mirror l a))

pureMessage :: Mirror l a -> SomeMessage -> Maybe (Mirror l a)

description :: Mirror l a -> String

(LayoutClass l a, LayoutClass r a) => LayoutClass (Choose l r) a

Methods

runLayout :: Workspace WorkspaceId (Choose l r a) a -> Rectangle -> X ([(a, Rectangle)], Maybe (Choose l r a))

doLayout :: Choose l r a -> Rectangle -> Stack a -> X ([(a, Rectangle)], Maybe (Choose l r a))

pureLayout :: Choose l r a -> Rectangle -> Stack a -> [(a, Rectangle)]

emptyLayout :: Choose l r a -> Rectangle -> X ([(a, Rectangle)], Maybe (Choose l r a))

handleMessage :: Choose l r a -> SomeMessage -> X (Maybe (Choose l r a))

pureMessage :: Choose l r a -> SomeMessage -> Maybe (Choose l r a)

description :: Choose l r a -> String

data Layout a

An existential type that can hold any object that is in Read and LayoutClass.

Constructors

(LayoutClass l a, Read (l a)) => Layout (l a)

Instances

LayoutClass Layout Window

Methods

runLayout :: Workspace WorkspaceId (Layout Window) Window -> Rectangle -> X ([(Window, Rectangle)], Maybe (Layout Window))

doLayout :: Layout Window -> Rectangle -> Stack Window -> X ([(Window, Rectangle)], Maybe (Layout Window))

pureLayout :: Layout Window -> Rectangle -> Stack Window -> [(Window, Rectangle)]

emptyLayout :: Layout Window -> Rectangle -> X ([(Window, Rectangle)], Maybe (Layout Window))

handleMessage :: Layout Window -> SomeMessage -> X (Maybe (Layout Window))

pureMessage :: Layout Window -> SomeMessage -> Maybe (Layout Window)

description :: Layout Window -> String

Show (Layout a)

Methods

showsPrec :: Int -> Layout a -> ShowS

show :: Layout a -> String

showList :: [Layout a] -> ShowS

readsLayout :: Layout a -> String -> [(Layout a, String)]

Using the Layout as a witness, parse existentially wrapped windows from a String.

class Typeable k a

The class Typeable allows a concrete representation of a type to be calculated.

Minimal complete definition

typeRep#

class Typeable a => Message a

Based on ideas in /An Extensible Dynamically-Typed Hierarchy of Exceptions/, Simon Marlow, 2006. Use extensible messages to the handleMessage handler.

User-extensible messages must be a member of this class.

Instances

Message Event

Message LayoutMessages

Message ChangeLayout

Message IncMasterN

Message Resize

data SomeMessage

A wrapped value of some type in the Message class.

Constructors

Message a => SomeMessage a

fromMessage :: Message m => SomeMessage -> Maybe m

And now, unwrap a given, unknown Message type, performing a (dynamic) type check on the result.

data LayoutMessages

LayoutMessages are core messages that all layouts (especially stateful layouts) should consider handling.

Constructors

Hide

sent when a layout becomes non-visible

ReleaseResources

sent when xmonad is exiting or restarting

Instances

Eq LayoutMessages

Methods

(==) :: LayoutMessages -> LayoutMessages -> Bool

(/=) :: LayoutMessages -> LayoutMessages -> Bool

Message LayoutMessages

data StateExtension

Existential type to store a state extension.

Constructors

ExtensionClass a => StateExtension a

Non-persistent state extension

(Read a, Show a, ExtensionClass a) => PersistentExtension a

Persistent extension

class Typeable a => ExtensionClass a where

Every module must make the data it wants to store an instance of this class.

Minimal complete definition: initialValue

Minimal complete definition

initialValue

Methods

initialValue :: a

Defines an initial value for the state extension

extensionType :: a -> StateExtension

Specifies whether the state extension should be persistent. Setting this method to PersistentExtension will make the stored data survive restarts, but requires a to be an instance of Read and Show.

It defaults to StateExtension, i.e. no persistence.

runX :: XConf -> XState -> X a -> IO (a, XState)

Run the X monad, given a chunk of X monad code, and an initial state Return the result, and final state

catchX :: X a -> X a -> X a

Run in the X monad, and in case of exception, and catch it and log it to stderr, and run the error case.

userCode :: X a -> X (Maybe a)

Execute the argument, catching all exceptions. Either this function or catchX should be used at all callsites of user customized code.

userCodeDef :: a -> X a -> X a

Same as userCode but with a default argument to return instead of using Maybe, provided for convenience.

io :: MonadIO m => IO a -> m a

General utilities

Lift an IO action into the X monad

catchIO :: MonadIO m => IO () -> m ()

Lift an IO action into the X monad. If the action results in an IO exception, log the exception to stderr and continue normal execution.

installSignalHandlers :: MonadIO m => m ()

Ignore SIGPIPE to avoid termination when a pipe is full, and SIGCHLD to avoid zombie processes, and clean up any extant zombie processes.

uninstallSignalHandlers :: MonadIO m => m ()

withDisplay :: (Display -> X a) -> X a

Run a monad action with the current display settings

withWindowSet :: (WindowSet -> X a) -> X a

Run a monadic action with the current stack set

isRoot :: Window -> X Bool

True if the given window is the root window

runOnWorkspaces :: (WindowSpace -> X WindowSpace) -> X ()

This is basically a map function, running a function in the X monad on each workspace with the output of that function being the modified workspace.

getAtom :: String -> X Atom

Wrapper for the common case of atom internment

spawn :: MonadIO m => String -> m ()

spawn. Launch an external application. Specifically, it double-forks and runs the String you pass as a command to /bin/sh.

Note this function assumes your locale uses utf8.

spawnPID :: MonadIO m => String -> m ProcessID

Like spawn, but returns the ProcessID of the launched application

xfork :: MonadIO m => IO () -> m ProcessID

A replacement for forkProcess which resets default signal handlers.

recompile :: MonadIO m => Bool -> m Bool

'recompile force', recompile the xmonad configuration file when any of the following apply:

• force is True
• the xmonad executable does not exist
• the xmonad executable is older than xmonad.hs or any file in the lib directory (under the configuration directory).

The -i flag is used to restrict recompilation to the xmonad.hs file only, and any files in the aforementioned lib directory.

Compilation errors (if any) are logged to the xmonad.errors file in the xmonad data directory. If GHC indicates failure with a non-zero exit code, an xmessage displaying that file is spawned.

False is returned if there are compilation errors.

trace :: MonadIO m => String -> m ()

A trace for the X monad. Logs a string to stderr. The result may be found in your .xsession-errors file

whenJust :: Monad m => Maybe a -> (a -> m ()) -> m ()

Conditionally run an action, using a Maybe a to decide.

whenX :: X Bool -> X () -> X ()

Conditionally run an action, using a X event to decide

getXMonadDir :: MonadIO m => m String

Return the path to the xmonad configuration directory. This directory is where user configuration files are stored (e.g, the xmonad.hs file). You may also create a lib subdirectory in the configuration directory and the default recompile command will add it to the GHC include path.

Several directories are considered. In order of preference:

1. The directory specified in the XMONAD_CONFIG_DIR environment variable.
2. The ~/.xmonad directory.
3. The XDG_CONFIG_HOME/xmonad directory.

The first directory that exists will be used. If none of the directories exist then (1) will be used if it is set, otherwise (2) will be used. Either way, a directory will be created if necessary.

getXMonadCacheDir :: MonadIO m => m String

Return the path to the xmonad cache directory. This directory is used to store temporary files that can easily be recreated. For example, the XPrompt history file.

Several directories are considered. In order of preference:

1. The directory specified in the XMONAD_CACHE_DIR environment variable.
2. The ~/.xmonad directory.
3. The XDG_CACHE_HOME/xmonad directory.

The first directory that exists will be used. If none of the directories exist then (1) will be used if it is set, otherwise (2) will be used. Either way, a directory will be created if necessary.

getXMonadDataDir :: MonadIO m => m String

Return the path to the xmonad data directory. This directory is used by XMonad to store data files such as the run-time state file and the configuration binary generated by GHC.

Several directories are considered. In order of preference:

1. The directory specified in the XMONAD_DATA_DIR environment variable.
2. The ~/.xmonad directory.
3. The XDG_DATA_HOME/xmonad directory.

The first directory that exists will be used. If none of the directories exist then (1) will be used if it is set, otherwise (2) will be used. Either way, a directory will be created if necessary.

stateFileName :: (Functor m, MonadIO m) => m FilePath

Get the name of the file used to store the xmonad window state.

atom_WM_STATE :: X Atom

Common non-predefined atoms

atom_WM_PROTOCOLS :: X Atom

Common non-predefined atoms

atom_WM_DELETE_WINDOW :: X Atom

Common non-predefined atoms

atom_WM_TAKE_FOCUS :: X Atom

Common non-predefined atoms

withWindowAttributes :: Display -> Window -> (WindowAttributes -> X ()) -> X ()

Safely access window attributes.

type ManageHook = Query (Endo WindowSet)

newtype Query a

Constructors

Query (ReaderT Window X a)

Instances

Monad Query

Methods

(>>=) :: Query a -> (a -> Query b) -> Query b

(>>) :: Query a -> Query b -> Query b

return :: a -> Query a

fail :: String -> Query a

Functor Query

Methods

fmap :: (a -> b) -> Query a -> Query b

(<$) :: a -> Query b -> Query a

Applicative Query

Methods

pure :: a -> Query a

(<*>) :: Query (a -> b) -> Query a -> Query b

(*>) :: Query a -> Query b -> Query b

(<*) :: Query a -> Query b -> Query a

MonadIO Query

Methods

liftIO :: IO a -> Query a

MonadReader Window Query

Methods

ask :: Query Window

local :: (Window -> Window) -> Query a -> Query a

reader :: (Window -> a) -> Query a

Monoid a => Monoid (Query a)

Methods

mempty :: Query a

mappend :: Query a -> Query a -> Query a

mconcat :: [Query a] -> Query a

Default a => Default (Query a)

Methods

def :: Query a

runQuery :: Query a -> Window -> X a