xmonad-contrib-0.18.1: Community-maintained extensions for xmonad
Copyright(c) David Roundy <droundy@darcs.net>
LicenseBSD
Maintainernone
Stabilityunstable
Portabilityportable
Safe HaskellSafe-Inferred
LanguageHaskell2010

XMonad.Layout.LayoutModifier

Description

A module for writing easy layout modifiers, which do not define a layout in and of themselves, but modify the behavior of or add new functionality to other layouts. If you ever find yourself writing a layout which takes another layout as a parameter, chances are you should be writing a LayoutModifier instead!

In case it is not clear, this module is not intended to help you configure xmonad, it is to help you write other extension modules. So get hacking!

Synopsis

Usage

The LayoutModifier class is provided to help extension developers write easy layout modifiers. End users won't find much of interest here. =)

To write a layout modifier using the LayoutModifier class, define a data type to represent the layout modification (storing any necessary state), define an instance of LayoutModifier, and export an appropriate function for applying the modifier. For example:

data MyModifier a = MyModifier MyState
  deriving (Show, Read)

instance LayoutModifier MyModifier a where
  -- override whatever methods from LayoutModifier you like

modify :: l a -> ModifiedLayout MyModifier l a
modify = ModifiedLayout (MyModifier initialState)

When defining an instance of LayoutModifier, you are free to override as many or as few of the methods as you see fit. See the documentation below for specific information about the effect of overriding each method. Every method has a default implementation; an instance of LayoutModifier which did not provide a non-default implementation of any of the methods would simply act as the identity on any layouts to which it is applied.

For more specific usage examples, see

and several others. You probably want to start by looking at some of the above examples; the documentation below is detailed but possibly confusing, and in many cases the creation of a LayoutModifier is actually quite simple.

Important note: because of the way the LayoutModifier class is intended to be used, by overriding any of its methods and keeping default implementations for all the others, LayoutModifier methods should never be called explicitly. It is likely that such explicit calls will not have the intended effect. Rather, the LayoutModifier methods should only be called indirectly through the LayoutClass instance for ModifiedLayout, since it is this instance that defines the semantics of overriding the various LayoutModifier methods.

The LayoutModifier class

class (Show (m a), Read (m a)) => LayoutModifier m a where Source #

Minimal complete definition

Nothing

Methods

modifyLayout Source #

Arguments

:: LayoutClass l a 
=> m a

the layout modifier

-> Workspace WorkspaceId (l a) a

current workspace

-> Rectangle

screen rectangle

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

modifyLayout allows you to intercept a call to runLayout before it is called on the underlying layout, in order to perform some effect in the X monad, and/or modify some of the parameters before passing them on to the runLayout method of the underlying layout.

The default implementation of modifyLayout simply calls runLayout on the underlying layout.

modifyLayoutWithUpdate :: LayoutClass l a => m a -> Workspace WorkspaceId (l a) a -> Rectangle -> X (([(a, Rectangle)], Maybe (l a)), Maybe (m a)) Source #

Similar to modifyLayout, but this function also allows you update the state of your layout modifier(the second value in the outer tuple).

If both modifyLayoutWithUpdate and redoLayout return a modified state of the layout modifier, redoLayout takes precedence. If this function returns a modified state, this state will internally be used in the subsequent call to redoLayout as well.

handleMess :: m a -> SomeMessage -> X (Maybe (m a)) Source #

handleMess allows you to spy on messages to the underlying layout, in order to have an effect in the X monad, or alter the layout modifier state in some way (by returning Just nm, where nm is a new modifier). In all cases, the underlying layout will also receive the message as usual, after the message has been processed by handleMess.

If you wish to possibly modify a message before it reaches the underlying layout, you should use handleMessOrMaybeModifyIt instead. If you do not need to modify messages or have access to the X monad, you should use pureMess instead.

The default implementation of handleMess calls unhook when receiving a Hide or ReleaseResources method (after which it returns Nothing), and otherwise passes the message on to pureMess.

handleMessOrMaybeModifyIt :: m a -> SomeMessage -> X (Maybe (Either (m a) SomeMessage)) Source #

handleMessOrMaybeModifyIt allows you to intercept messages sent to the underlying layout, in order to have an effect in the X monad, alter the layout modifier state, or produce a modified message to be passed on to the underlying layout.

The default implementation of handleMessOrMaybeModifyIt simply passes on the message to handleMess.

pureMess :: m a -> SomeMessage -> Maybe (m a) Source #

pureMess allows you to spy on messages sent to the underlying layout, in order to possibly change the layout modifier state.

The default implementation of pureMess ignores messages sent to it, and returns Nothing (causing the layout modifier to remain unchanged).

redoLayout Source #

Arguments

:: m a

the layout modifier

-> Rectangle

screen rectangle

-> Maybe (Stack a)

current window stack

-> [(a, Rectangle)]

(window,rectangle) pairs returned by the underlying layout

-> X ([(a, Rectangle)], Maybe (m a)) 

redoLayout allows you to intercept a call to runLayout on workspaces with at least one window, after it is called on the underlying layout, in order to perform some effect in the X monad, possibly return a new layout modifier, and/or modify the results of runLayout before returning them.

If you don't need access to the X monad, use pureModifier instead. Also, if the behavior you need can be cleanly separated into an effect in the X monad, followed by a pure transformation of the results of runLayout, you should consider implementing hook and pureModifier instead of redoLayout.

On empty workspaces, the Stack is Nothing.

The default implementation of redoLayout calls hook and then pureModifier.

pureModifier Source #

Arguments

:: m a

the layout modifier

-> Rectangle

screen rectangle

-> Maybe (Stack a)

current window stack

-> [(a, Rectangle)]

(window, rectangle) pairs returned by the underlying layout

-> ([(a, Rectangle)], Maybe (m a)) 

pureModifier allows you to intercept a call to runLayout after it is called on the underlying layout, in order to modify the list of window/rectangle pairings it has returned, and/or return a new layout modifier.

The default implementation of pureModifier returns the window rectangles unmodified.

hook :: m a -> X () Source #

hook is called by the default implementation of redoLayout, and as such represents an X action which is to be run each time runLayout is called on the underlying layout, after runLayout has completed. Of course, if you override redoLayout, then hook will not be called unless you explicitly call it.

The default implementation of hook is return () (i.e., it has no effect).

unhook :: m a -> X () Source #

unhook is called by the default implementation of handleMess upon receiving a Hide or a ReleaseResources message.

The default implementation, of course, does nothing.

modifierDescription :: m a -> String Source #

modifierDescription is used to give a String description to this layout modifier. It is the empty string by default; you should only override this if it is important that the presence of the layout modifier be displayed in text representations of the layout (for example, in the status bar of a XMonad.Hooks.StatusBar user).

modifyDescription :: LayoutClass l a => m a -> l a -> String Source #

modifyDescription gives a String description for the entire layout (modifier + underlying layout). By default, it is derived from the concatenation of the modifierDescription with the description of the underlying layout, with a "smart space" in between (the space is not included if the modifierDescription is empty).

Instances

Instances details
LayoutModifier MouseResize Window Source # 
Instance details

Defined in XMonad.Actions.MouseResize

LayoutModifier WorkspaceCursors a Source # 
Instance details

Defined in XMonad.Actions.WorkspaceCursors

LayoutModifier AvoidStruts a Source # 
Instance details

Defined in XMonad.Hooks.ManageDocks

LayoutModifier RefocusLastLayoutHook a Source # 
Instance details

Defined in XMonad.Hooks.RefocusLast

Eq w => LayoutModifier AutoMaster w Source # 
Instance details

Defined in XMonad.Layout.AutoMaster

LayoutModifier BorderResize Window Source # 
Instance details

Defined in XMonad.Layout.BorderResize

LayoutModifier BoringWindows Window Source # 
Instance details

Defined in XMonad.Layout.BoringWindows

LayoutModifier CenteredIfSingle Window Source # 
Instance details

Defined in XMonad.Layout.CenteredIfSingle

LayoutModifier CenteredMaster Window Source # 
Instance details

Defined in XMonad.Layout.CenteredMaster

LayoutModifier TopRightMaster Window Source # 
Instance details

Defined in XMonad.Layout.CenteredMaster

LayoutModifier DraggingVisualizer Window Source # 
Instance details

Defined in XMonad.Layout.DraggingVisualizer

LayoutModifier FixedAspectRatio Window Source # 
Instance details

Defined in XMonad.Layout.FixedAspectRatio

LayoutModifier FocusTracking Window Source # 
Instance details

Defined in XMonad.Layout.FocusTracking

LayoutModifier FullscreenFloat Window Source # 
Instance details

Defined in XMonad.Layout.Fullscreen

LayoutModifier FullscreenFocus Window Source # 
Instance details

Defined in XMonad.Layout.Fullscreen

LayoutModifier FullscreenFull Window Source # 
Instance details

Defined in XMonad.Layout.Fullscreen

LayoutModifier Gaps a Source # 
Instance details

Defined in XMonad.Layout.Gaps

LayoutModifier HiddenWindows Window Source # 
Instance details

Defined in XMonad.Layout.Hidden

LayoutModifier AddRoster Window Source # 
Instance details

Defined in XMonad.Layout.IM

LayoutModifier LayoutHints Window Source # 
Instance details

Defined in XMonad.Layout.LayoutHints

LayoutModifier LayoutHintsToCenter Window Source # 
Instance details

Defined in XMonad.Layout.LayoutHints

LayoutModifier LimitWindows a Source # 
Instance details

Defined in XMonad.Layout.LimitWindows

LayoutModifier Selection a Source # 
Instance details

Defined in XMonad.Layout.LimitWindows

LayoutModifier MagicFocus Window Source # 
Instance details

Defined in XMonad.Layout.MagicFocus

LayoutModifier Magnifier Window Source # 
Instance details

Defined in XMonad.Layout.Magnifier

LayoutModifier AddMaster Window Source # 
Instance details

Defined in XMonad.Layout.Master

LayoutModifier Maximize Window Source # 
Instance details

Defined in XMonad.Layout.Maximize

LayoutModifier UnEscape a Source # 
Instance details

Defined in XMonad.Layout.MessageControl

LayoutModifier Minimize Window Source # 
Instance details

Defined in XMonad.Layout.Minimize

LayoutModifier Monitor Window Source # 
Instance details

Defined in XMonad.Layout.Monitor

LayoutModifier WithBorder Window Source # 
Instance details

Defined in XMonad.Layout.NoBorders

LayoutModifier Reflect a Source # 
Instance details

Defined in XMonad.Layout.Reflect

LayoutModifier Rename a Source # 
Instance details

Defined in XMonad.Layout.Renamed

LayoutModifier ResizeScreen a Source # 
Instance details

Defined in XMonad.Layout.ResizeScreen

LayoutModifier ShowWName a Source # 
Instance details

Defined in XMonad.Layout.ShowWName

Eq a => LayoutModifier Spacing a Source # 
Instance details

Defined in XMonad.Layout.Spacing

LayoutModifier Stoppable Window Source # 
Instance details

Defined in XMonad.Layout.Stoppable

LayoutModifier UseTransientFor Window Source # 
Instance details

Defined in XMonad.Layout.TrackFloating

(Show a, Read a, Eq a) => LayoutModifier WindowArranger a Source # 
Instance details

Defined in XMonad.Layout.WindowArranger

LayoutModifier WindowNavigation Window Source # 
Instance details

Defined in XMonad.Layout.WindowNavigation

LayoutModifier WorkspaceDir Window Source # 
Instance details

Defined in XMonad.Layout.WorkspaceDir

(LayoutClass l Window, Read (l Window)) => LayoutModifier (Drawer l) Window Source # 
Instance details

Defined in XMonad.Layout.Drawer

(Read p, Show p, SetsAmbiguous p) => LayoutModifier (ConfigurableBorder p) Window Source # 
Instance details

Defined in XMonad.Layout.NoBorders

(Read (l Window), Show (l Window), LayoutClass l Window) => LayoutModifier (Sublayout l) Window Source # 
Instance details

Defined in XMonad.Layout.SubLayouts

(DecorationStyle ds Window, Shrinker s) => LayoutModifier (Decoration ds s) Window Source #

The long LayoutModifier instance for the Decoration type.

In redoLayout we check the state: if there is no state we initialize it.

The state is diffed against the list of windows produced by the underlying layout: removed windows get deleted and new ones decorated by createDecos, which will call decorate to decide if a window must be given a Rectangle, in which case a decoration window will be created.

After that we resync the updated state with the windows' list and then we process the resynced stated (as we do with a new state).

First we map the decoration windows, we update each decoration to reflect any decorated window's change, and we insert, in the list of windows and rectangles returned by the underlying layout, the decoration for each window. This way xmonad will restack the decorations and their windows accordingly. At the end we remove invisible/stacked windows.

Message handling is quite simple: when needed we release the state component of the Decoration LayoutModifier. Otherwise we call handleEvent, which will call the appropriate DecorationStyle methods to perform its tasks.

Instance details

Defined in XMonad.Layout.Decoration

(DecorationEngine engine widget Window, DecorationGeometry geom Window, Shrinker shrinker) => LayoutModifier (DecorationEx engine widget geom shrinker) Window Source #

The long LayoutModifier instance for the DecorationEx type.

In redoLayout we check the state: if there is no state we initialize it.

The state is diffed against the list of windows produced by the underlying layout: removed windows get deleted and new ones decorated by createDecos, which will call decorate to decide if a window must be given a Rectangle, in which case a decoration window will be created.

After that we resync the updated state with the windows' list and then we process the resynced stated (as we do with a new state).

First we map the decoration windows, we update each decoration to reflect any decorated window's change, and we insert, in the list of windows and rectangles returned by the underlying layout, the decoration for each window. This way xmonad will restack the decorations and their windows accordingly. At the end we remove invisible/stacked windows.

Message handling is quite simple: when needed we release the state component of the DecorationEx LayoutModifier. Otherwise we call handleEvent, which will call the appropriate DecorationEngine methods to perform its tasks.

Instance details

Defined in XMonad.Layout.DecorationEx.LayoutModifier

Methods

modifyLayout :: LayoutClass l Window => DecorationEx engine widget geom shrinker Window -> Workspace WorkspaceId (l Window) Window -> Rectangle -> X ([(Window, Rectangle)], Maybe (l Window)) Source #

modifyLayoutWithUpdate :: LayoutClass l Window => DecorationEx engine widget geom shrinker Window -> Workspace WorkspaceId (l Window) Window -> Rectangle -> X (([(Window, Rectangle)], Maybe (l Window)), Maybe (DecorationEx engine widget geom shrinker Window)) Source #

handleMess :: DecorationEx engine widget geom shrinker Window -> SomeMessage -> X (Maybe (DecorationEx engine widget geom shrinker Window)) Source #

handleMessOrMaybeModifyIt :: DecorationEx engine widget geom shrinker Window -> SomeMessage -> X (Maybe (Either (DecorationEx engine widget geom shrinker Window) SomeMessage)) Source #

pureMess :: DecorationEx engine widget geom shrinker Window -> SomeMessage -> Maybe (DecorationEx engine widget geom shrinker Window) Source #

redoLayout :: DecorationEx engine widget geom shrinker Window -> Rectangle -> Maybe (Stack Window) -> [(Window, Rectangle)] -> X ([(Window, Rectangle)], Maybe (DecorationEx engine widget geom shrinker Window)) Source #

pureModifier :: DecorationEx engine widget geom shrinker Window -> Rectangle -> Maybe (Stack Window) -> [(Window, Rectangle)] -> ([(Window, Rectangle)], Maybe (DecorationEx engine widget geom shrinker Window)) Source #

hook :: DecorationEx engine widget geom shrinker Window -> X () Source #

unhook :: DecorationEx engine widget geom shrinker Window -> X () Source #

modifierDescription :: DecorationEx engine widget geom shrinker Window -> String Source #

modifyDescription :: LayoutClass l Window => DecorationEx engine widget geom shrinker Window -> l Window -> String Source #

data ModifiedLayout m l a Source #

A ModifiedLayout is simply a container for a layout modifier combined with an underlying layout. It is, of course, itself a layout (i.e. an instance of LayoutClass).

Constructors

ModifiedLayout (m a) (l a) 

Instances

Instances details
(LayoutModifier m a, LayoutClass l a, Typeable m) => LayoutClass (ModifiedLayout m l) a Source #

The LayoutClass instance for a ModifiedLayout defines the semantics of a LayoutModifier applied to an underlying layout.

Instance details

Defined in XMonad.Layout.LayoutModifier

(Read (m a), Read (l a)) => Read (ModifiedLayout m l a) Source # 
Instance details

Defined in XMonad.Layout.LayoutModifier

(Show (m a), Show (l a)) => Show (ModifiedLayout m l a) Source # 
Instance details

Defined in XMonad.Layout.LayoutModifier

Methods

showsPrec :: Int -> ModifiedLayout m l a -> ShowS #

show :: ModifiedLayout m l a -> String #

showList :: [ModifiedLayout m l a] -> ShowS #