aboutsummaryrefslogtreecommitdiffstats
path: root/XMonad/Layout
diff options
context:
space:
mode:
authorBrent Yorgey <byorgey@gmail.com>2008-03-25 21:50:06 +0100
committerBrent Yorgey <byorgey@gmail.com>2008-03-25 21:50:06 +0100
commit4d23441b1277c116900437184c3e62db1cf9fae0 (patch)
treed3774078b042c9cedc842d17eed8ea4b55d008fc /XMonad/Layout
parent4d1a934346d612ae0ce15b2bea38f794917aaabc (diff)
downloadXMonadContrib-4d23441b1277c116900437184c3e62db1cf9fae0.tar.gz
XMonadContrib-4d23441b1277c116900437184c3e62db1cf9fae0.tar.xz
XMonadContrib-4d23441b1277c116900437184c3e62db1cf9fae0.zip
XMonad.Layout.LayoutModifier: add a metric crapload of documentation
darcs-hash:20080325205006-bd4d7-4f991be5593d55564ac0952d9019e43e8e68ba31.gz
Diffstat (limited to 'XMonad/Layout')
-rw-r--r--XMonad/Layout/LayoutModifier.hs215
1 files changed, 205 insertions, 10 deletions
diff --git a/XMonad/Layout/LayoutModifier.hs b/XMonad/Layout/LayoutModifier.hs
index d1f8b04..56f1590 100644
--- a/XMonad/Layout/LayoutModifier.hs
+++ b/XMonad/Layout/LayoutModifier.hs
@@ -11,12 +11,22 @@
-- Stability : unstable
-- Portability : portable
--
--- A module for writing easy Llayouts and layout modifiers
+-- 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!
-----------------------------------------------------------------------------
module XMonad.Layout.LayoutModifier (
-- * Usage
-- $usage
+
+ -- * The 'LayoutModifier' class
LayoutModifier(..), ModifiedLayout(..)
) where
@@ -24,48 +34,225 @@ import XMonad
import XMonad.StackSet ( Stack, Workspace (..) )
-- $usage
--- Use LayoutModifier to help write easy Layouts.
--
--- LayouModifier defines a class 'LayoutModifier'. Each method as a
--- default implementation.
+-- 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
+--
+-- * "XMonad.Layout.WorkspaceDir"
+--
+-- * "XMonad.Layout.Magnifier"
+--
+-- * "XMonad.Layout.NoBorders"
+--
+-- * "XMonad.Layout.Reflect"
+--
+-- * "XMonad.Layout.Named"
+--
+-- * "XMonad.Layout.WindowNavigation"
+--
+-- 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.
--
--- For usage examples you can see "XMonad.Layout.WorkspaceDir",
--- "XMonad.Layout.Magnifier", "XMonad.Layout.NoBorder",
+-- /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.
class (Show (m a), Read (m a)) => LayoutModifier m a where
- modifyLayout :: (LayoutClass l a) => m a -> Workspace WorkspaceId (l a) a
- -> 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.
+ modifyLayout :: (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 _ w r = runLayout w r
+
+ -- | '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'.
handleMess :: m a -> SomeMessage -> X (Maybe (m a))
handleMess m mess | Just Hide <- fromMessage mess = doUnhook
| Just ReleaseResources <- fromMessage mess = doUnhook
| otherwise = return $ pureMess m mess
where doUnhook = do unhook m; return Nothing
+
+ -- | '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'.
handleMessOrMaybeModifyIt :: m a -> SomeMessage -> X (Maybe (Either (m a) SomeMessage))
handleMessOrMaybeModifyIt m mess = do mm' <- handleMess m mess
return (Left `fmap` mm')
+
+ -- | '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).
pureMess :: m a -> SomeMessage -> Maybe (m a)
pureMess _ _ = Nothing
- redoLayout :: m a -> Rectangle -> Stack a -> [(a, Rectangle)]
+
+ -- | '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'.
+ --
+ -- If you also need to perform some action when 'runLayout' is
+ -- called on an empty workspace, see 'emptyLayoutMod'.
+ --
+ -- The default implementation of 'redoLayout' calls 'hook' and
+ -- then 'pureModifier'.
+ redoLayout :: m a -- ^ the layout modifier
+ -> Rectangle -- ^ screen rectangle
+ -> Stack a -- ^ current window stack
+ -> [(a, Rectangle)] -- ^ (window,rectangle) pairs returned
+ -- by the underlying layout
-> X ([(a, Rectangle)], Maybe (m a))
redoLayout m r s wrs = do hook m; return $ pureModifier m r s wrs
- pureModifier :: m a -> Rectangle -> Stack a -> [(a, Rectangle)]
+
+ -- | '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.
+ pureModifier :: m a -- ^ the layout modifier
+ -> Rectangle -- ^ screen rectangle
+ -> Stack a -- ^ current window stack
+ -> [(a, Rectangle)] -- ^ (window, rectangle) pairs returned
+ -- by the underlying layout
-> ([(a, Rectangle)], Maybe (m a))
pureModifier _ _ _ wrs = (wrs, Nothing)
+
+ -- | 'emptyLayoutMod' allows you to intercept a call to
+ -- 'runLayout' on an empty workspace, /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, then tough luck.
+ -- There isn't a pure version of 'emptyLayoutMod'.
+ --
+ -- The default implementation of 'emptyLayoutMod' ignores its
+ -- arguments and returns an empty list of window\/rectangle
+ -- pairings.
+ --
+ -- /NOTE/: 'emptyLayoutMod' will likely be combined with
+ -- 'redoLayout' soon!
emptyLayoutMod :: m a -> Rectangle -> [(a, Rectangle)]
-> X ([(a, Rectangle)], Maybe (m a))
emptyLayoutMod _ _ _ = return ([], Nothing)
+
+ -- | '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).
hook :: m a -> X ()
hook _ = return ()
+
+ -- | 'unhook' is called by the default implementation of
+ -- 'handleMess' upon receiving a 'Hide' or a 'ReleaseResources'
+ -- message.
+ --
+ -- The default implementation, of course, does nothing.
unhook :: m a -> X ()
unhook _ = return ()
+
+ -- | '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.DynamicLog" user).
modifierDescription :: m a -> String
modifierDescription = const ""
+
+ -- | '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).
modifyDescription :: (LayoutClass l a) => m a -> l a -> String
modifyDescription m l = modifierDescription m <> description l
where "" <> x = x
x <> y = x ++ " " ++ y
+-- | The 'LayoutClass' instance for a 'ModifiedLayout' defines the
+-- semantics of a 'LayoutModifier' applied to an underlying layout.
instance (LayoutModifier m a, LayoutClass l a) => LayoutClass (ModifiedLayout m l) a where
runLayout (Workspace i (ModifiedLayout m l) ms) r =
do (ws, ml') <- modifyLayout m (Workspace i l ms) r
@@ -87,4 +274,12 @@ instance (LayoutModifier m a, LayoutClass l a) => LayoutClass (ModifiedLayout m
_ -> (ModifiedLayout m) `fmap` ml'
description (ModifiedLayout m l) = modifyDescription m l
+-- | 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').
data ModifiedLayout m l a = ModifiedLayout (m a) (l a) deriving ( Read, Show )
+
+-- N.B. I think there is a Haddock bug here; the Haddock output for
+-- the above does not parenthesize (m a) and (l a), which is obviously
+-- incorrect.
+