xmonad-bluetilebranch-0.8.1: A tiling window managerSource codeContentsIndex
XMonad.Core
Portabilitynot portable, uses cunning newtype deriving
Stabilityunstable
Maintainerspencerjanssen@gmail.com
Description
The X monad, a state monad transformer over IO, for the window manager state, and support routines.
Synopsis
data X a
type WindowSet = StackSet WorkspaceId (Layout Window) Window ScreenId ScreenDetail
type WindowSpace = Workspace WorkspaceId (Layout Window) Window
type WorkspaceId = String
newtype ScreenId = S Int
data ScreenDetail = SD {
screenRect :: !Rectangle
}
data XState = XState {
windowset :: !WindowSet
positionStore :: !(PositionStore Window)
mapped :: !(Set Window)
waitingUnmap :: !(Map Window Int)
dragging :: !(Maybe (Position -> Position -> X (), X ()))
}
data XConf = XConf {
display :: Display
config :: !(XConfig Layout)
theRoot :: !Window
normalBorder :: !Pixel
focusedBorder :: !Pixel
keyActions :: !(Map (KeyMask, KeySym) (X ()))
buttonActions :: !(Map (KeyMask, Button) (Window -> X ()))
mouseFocused :: !Bool
mousePosition :: !(Maybe (Position, Position))
}
data XConfig l = XConfig {
normalBorderColor :: !String
focusedBorderColor :: !String
terminal :: !String
layoutHook :: !(l Window)
manageHook :: !ManageHook
handleEventHook :: !(Event -> X All)
workspaces :: ![String]
numlockMask :: !KeyMask
modMask :: !KeyMask
keys :: !(XConfig Layout -> Map (ButtonMask, KeySym) (X ()))
mouseBindings :: !(XConfig Layout -> Map (ButtonMask, Button) (Window -> X ()))
borderWidth :: !Dimension
logHook :: !(X ())
startupHook :: !(X ())
focusFollowsMouse :: !Bool
}
class Show (layout a) => LayoutClass layout a where
runLayout :: Workspace WorkspaceId (layout a) a -> Rectangle -> X ([(a, Rectangle)], Maybe (layout a))
doLayout :: layout a -> Rectangle -> Stack a -> X ([(a, Rectangle)], Maybe (layout a))
pureLayout :: layout a -> Rectangle -> Stack a -> [(a, Rectangle)]
emptyLayout :: layout a -> Rectangle -> X ([(a, Rectangle)], Maybe (layout a))
handleMessage :: layout a -> SomeMessage -> X (Maybe (layout a))
pureMessage :: layout a -> SomeMessage -> Maybe (layout a)
description :: layout a -> String
data Layout a = forall l . (LayoutClass l a, Read (l a)) => Layout (l a)
readsLayout :: Layout a -> String -> [(Layout a, String)]
Typeable (typeOf)
class Typeable a => Message a
data SomeMessage = forall a . Message a => SomeMessage a
fromMessage :: Message m => SomeMessage -> Maybe m
data LayoutMessages
= Hide
| ReleaseResources
runX :: XConf -> XState -> X a -> IO (a, XState)
catchX :: X a -> X a -> X a
userCode :: X a -> X (Maybe a)
userCodeDef :: a -> X a -> X a
io :: MonadIO m => IO a -> m a
catchIO :: MonadIO m => IO () -> m ()
installSignalHandlers :: MonadIO m => m ()
uninstallSignalHandlers :: MonadIO m => m ()
withDisplay :: (Display -> X a) -> X a
withWindowSet :: (WindowSet -> X a) -> X a
modifyPosStore :: (PositionStore Window -> PositionStore Window) -> X ()
isRoot :: Window -> X Bool
runOnWorkspaces :: (WindowSpace -> X WindowSpace) -> X ()
getAtom :: String -> X Atom
spawn :: MonadIO m => String -> m ()
spawnPID :: MonadIO m => String -> m ProcessID
getXMonadDir :: MonadIO m => m String
recompile :: MonadIO m => Bool -> m Bool
trace :: MonadIO m => String -> m ()
whenJust :: Monad m => Maybe a -> (a -> m ()) -> m ()
whenX :: X Bool -> X () -> X ()
atom_WM_STATE :: X Atom
atom_WM_PROTOCOLS :: X Atom
atom_WM_DELETE_WINDOW :: X Atom
type ManageHook = Query (Endo WindowSet)
newtype Query a = Query (ReaderT Window X a)
runQuery :: Query a -> Window -> X a
Documentation
data X a Source

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.

show/hide Instances
type WindowSet = StackSet WorkspaceId (Layout Window) Window ScreenId ScreenDetailSource
type WindowSpace = Workspace WorkspaceId (Layout Window) WindowSource
type WorkspaceId = StringSource
Virtual workspace indices
newtype ScreenId Source
Physical screen indices
Constructors
S Int
show/hide Instances
data ScreenDetail Source
The Rectangle with screen dimensions
Constructors
SD
screenRect :: !Rectangle
show/hide Instances
data XState Source
XState, the (mutable) window manager state.
Constructors
XState
windowset :: !WindowSetworkspace list
positionStore :: !(PositionStore Window)preferred rectangles for windows
mapped :: !(Set Window)the Set of mapped windows
waitingUnmap :: !(Map Window Int)the number of expected UnmapEvents
dragging :: !(Maybe (Position -> Position -> X (), X ()))
show/hide Instances
data XConf Source
XConf, the (read-only) window manager configuration.
Constructors
XConf
display :: Displaythe X11 display
config :: !(XConfig Layout)initial user configuration
theRoot :: !Windowthe root window
normalBorder :: !Pixelborder color of unfocused windows
focusedBorder :: !Pixelborder 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 :: !Boolwas refocus caused by mouse action?
mousePosition :: !(Maybe (Position, Position))position of the mouse according to the event currently being processed
show/hide Instances
data XConfig l Source
Constructors
XConfig
normalBorderColor :: !StringNon focused windows border color. Default: "#dddddd"
focusedBorderColor :: !StringFocused windows border color. Default: "#ff0000"
terminal :: !StringThe preferred terminal application. Default: "xterm"
layoutHook :: !(l Window)The available layouts
manageHook :: !ManageHookThe 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
numlockMask :: !KeyMaskThe numlock modifier
modMask :: !KeyMaskthe 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 :: !DimensionThe border width
logHook :: !(X ())The action to perform when the windows set is changed
startupHook :: !(X ())The action to perform on startup
focusFollowsMouse :: !BoolWhether window entry events can change focus
class Show (layout a) => LayoutClass layout a whereSource

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

Minimal complete definition:

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

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)]Source
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))Source
emptyLayout is called when there are no windows.
handleMessage :: layout a -> SomeMessage -> X (Maybe (layout a))Source

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)Source
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 -> StringSource
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.
show/hide Instances
data Layout a Source
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)
show/hide Instances
readsLayout :: Layout a -> String -> [(Layout a, String)]Source
Using the Layout as a witness, parse existentially wrapped windows from a String.
Typeable (typeOf)
class Typeable a => Message a Source

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.

show/hide Instances
data SomeMessage Source
A wrapped value of some type in the Message class.
Constructors
forall a . Message a => SomeMessage a
fromMessage :: Message m => SomeMessage -> Maybe mSource
And now, unwrap a given, unknown Message type, performing a (dynamic) type check on the result.
data LayoutMessages Source
LayoutMessages are core messages that all layouts (especially stateful layouts) should consider handling.
Constructors
Hidesent when a layout becomes non-visible
ReleaseResourcessent when xmonad is exiting or restarting
show/hide Instances
runX :: XConf -> XState -> X a -> IO (a, XState)Source
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 aSource
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)Source
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 aSource
Same as userCode but with a default argument to return instead of using Maybe, provided for convenience.
io :: MonadIO m => IO a -> m aSource

General utilities

Lift an IO action into the X monad

catchIO :: MonadIO m => IO () -> m ()Source
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 ()Source
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 ()Source
withDisplay :: (Display -> X a) -> X aSource
Run a monad action with the current display settings
withWindowSet :: (WindowSet -> X a) -> X aSource
Run a monadic action with the current stack set
modifyPosStore :: (PositionStore Window -> PositionStore Window) -> X ()Source
isRoot :: Window -> X BoolSource
True if the given window is the root window
runOnWorkspaces :: (WindowSpace -> X WindowSpace) -> X ()Source
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 AtomSource
Wrapper for the common case of atom internment
spawn :: MonadIO m => String -> m ()Source
spawn. Launch an external application. Specifically, it double-forks and runs the String you pass as a command to binsh.
spawnPID :: MonadIO m => String -> m ProcessIDSource
Like spawn, but returns the ProcessID of the launched application
getXMonadDir :: MonadIO m => m StringSource
Return the path to ~/.xmonad.
recompile :: MonadIO m => Bool -> m BoolSource

'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 ()Source
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 ()Source
Conditionally run an action, using a Maybe a to decide.
whenX :: X Bool -> X () -> X ()Source
Conditionally run an action, using a X event to decide
atom_WM_STATE :: X AtomSource
atom_WM_PROTOCOLS :: X AtomSource
atom_WM_DELETE_WINDOW :: X AtomSource
Common non-predefined atoms
type ManageHook = Query (Endo WindowSet)Source
newtype Query a Source
Constructors
Query (ReaderT Window X a)
show/hide Instances
runQuery :: Query a -> Window -> X aSource
Produced by Haddock version 2.4.2