XMonad.Core

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

Functor X

Applicative X

MonadIO X

MonadState XState X

MonadReader XConf X

Monoid a => Monoid (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

Eq ScreenId

Integral ScreenId

Num ScreenId

Ord ScreenId

Read ScreenId

Real ScreenId

Show ScreenId

data ScreenDetail

The Rectangle with screen dimensions

Constructors

screenRect :: !Rectangle

Instances

Eq ScreenDetail

Read ScreenDetail

Show ScreenDetail

data XState

XState, the (mutable) window manager state.

Constructors

XState

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 ())

Instances

MonadState XState X

data XConf

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

Constructors

XConf

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?

Instances

MonadReader XConf X

data XConfig l

Constructors

XConfig

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
workspaces :: ![String]	The list of workspaces' names
numlockMask :: !KeyMask	The numlock modifier
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

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

LayoutClass Full a

LayoutClass Tall a

LayoutClass l a => LayoutClass (Mirror l) a

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

data Layout a

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

Constructors

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

Instances

LayoutClass Layout Window

Show (Layout a)

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

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

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 LayoutMessages

Message Resize

Message IncMasterN

Message ChangeLayout

data SomeMessage

A wrapped value of some type in the Message class.

Constructors

forall a . 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

Typeable LayoutMessages

Message LayoutMessages

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 () -> X ()

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

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.

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

Double fork and execute an IO action (usually one of the exec family of functions)

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

getXMonadDir :: MonadIO m => m String

Return the path to ~/.xmonad.

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

'recompile force', recompile ~/.xmonad/xmonad.hs when any of the following apply:

force is True
the xmonad executable does not exist
the xmonad executable is older than xmonad.hs

The -i flag is used to restrict recompilation to the xmonad.hs file only.

Compilation errors (if any) are logged to ~/.xmonad/xmonad.errors. 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

atom_WM_STATE :: X Atom

atom_WM_PROTOCOLS :: X Atom

atom_WM_DELETE_WINDOW :: X Atom

Common non-predefined atoms

type ManageHook = Query (Endo WindowSet)

newtype Query a

Constructors

Query (ReaderT Window X a)

Instances

Monad Query

Functor Query

MonadIO Query

MonadReader Window Query

Monoid a => Monoid (Query a)

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

Produced by Haddock version 2.1.0