| xmonad-contrib-0.8.1: Third party extensions for xmonad | Contents | Index

XMonad.Hooks.DynamicLog

Portability | unportable
Stability | unstable
Maintainer | Don Stewart <dons@cse.unsw.edu.au>

Contents

Usage
Drop-in loggers
Build your own formatter
Formatting utilities
Internal formatting functions
To Do

Description
xmonad calls the logHook with every internal state update, which is useful for (among other things) outputting status information to an external status bar program such as xmobar or dzen. DynamicLog provides several drop-in logHooks for this purpose, as well as flexible tools for specifying your own formatting.
Synopsis

dzen :: (XConfig (ModifiedLayout AvoidStruts (Choose Tall (Choose (Mirror Tall) Full))) -> IO t) -> IO t
xmobar :: (XConfig (ModifiedLayout AvoidStruts (Choose Tall (Choose (Mirror Tall) Full))) -> IO t) -> IO t
dynamicLog :: X ()
dynamicLogDzen :: X ()
dynamicLogXmobar :: X ()
dynamicLogXinerama :: X ()
dynamicLogWithPP :: PP -> X ()
dynamicLogString :: PP -> X String

data PP = PP {

ppCurrent :: WorkspaceId -> String
ppVisible :: WorkspaceId -> String
ppHidden :: WorkspaceId -> String
ppHiddenNoWindows :: WorkspaceId -> String
ppUrgent :: WorkspaceId -> String
ppSep :: String
ppWsSep :: String
ppTitle :: String -> String
ppLayout :: String -> String
ppOrder :: [String] -> [String]
ppSort :: X ([WindowSpace] -> [WindowSpace])
ppExtras :: [X (Maybe String)]
ppOutput :: String -> IO ()

}

defaultPP :: PP
dzenPP :: PP
xmobarPP :: PP
sjanssenPP :: PP
byorgeyPP :: PP
wrap :: String -> String -> String -> String
pad :: String -> String
shorten :: Int -> String -> String
xmobarColor :: String -> String -> String -> String
dzenColor :: String -> String -> String -> String
dzenEscape :: String -> String
pprWindowSet :: WorkspaceSort -> [Window] -> PP -> WindowSet -> String
pprWindowSetXinerama :: WindowSet -> String

Usage

You can use this module with the following in your `~/.xmonad/xmonad.hs`:

        import XMonad
        import XMonad.Hooks.DynamicLog

If you just want a quick-and-dirty status bar with zero effort, try the `dzen` function, which sets up a dzen status bar with a default format:

     main = dzen xmonad

or, to use this with your own custom xmonad configuration,

     main = dzen $ \conf -> xmonad $ conf { <your customizations> }

Also you can use `xmobar` function instead of `dzen` in the examples above, if you have xmobar installed.

Alternatively, you can choose among several default status bar formats (`dynamicLog`, `dynamicLogDzen`, `dynamicLogXmobar`, or `dynamicLogXinerama`) by simply setting your logHook to the appropriate function, for instance:

     main = xmonad $ defaultConfig {
        ...
        logHook = dynamicLog
        ...
      }

For more flexibility, you can also use `dynamicLogWithPP` and supply your own pretty-printing format (by either defining one from scratch, or customizing one of the provided examples). For example:

        -- use sjanssen's pretty-printer format, but with the sections
        -- in reverse
        logHook = dynamicLogWithPP $ sjanssenPP { ppOrder = reverse }

Note that setting the `logHook` only sets up xmonad's output; you are responsible for starting your own status bar program (e.g. dzen or xmobar) and making sure xmonad's output is piped into it appropriately, either by putting it in your `.xsession` or similar file, or by using `spawnPipe` in your `main` function, for example:

     import XMonad.Util.Run   -- for spawnPipe and hPutStrLn

     main = do
         h <- spawnPipe "xmobar -options -foo -bar"
         xmonad $ defaultConfig {
           ...
           logHook = dynamicLogWithPP $ defaultPP { ppOutput = hPutStrLn h }

If you use `spawnPipe`, be sure to redefine the `ppOutput` field of your pretty-printer as in the example above; by default the status will be printed to stdout rather than the pipe you create.

Even if you don't use a statusbar, you can still use `dynamicLogString` to show on-screen notifications in response to some events. For example, to show the current layout when it changes, you could make a keybinding to cycle the layout and display the current status:

        , ((mod1Mask, xK_a     ), sendMessage NextLayout >> (dynamicLogString myPP >>= \d->spawn $"xmessage "++d))

Drop-in loggers
dzen :: (XConfig (ModifiedLayout AvoidStruts (Choose Tall (Choose (Mirror Tall) Full))) -> IO t) -> IO t

Run xmonad with a dzen status bar set to some nice defaults. Output is taken from the dynamicLogWithPP hook.

     main = dzen xmonad

The intent is that the above config file should provide a nice status bar with minimal effort. If you want to customize your xmonad configuration while using this, you'll have to do something like

     main = dzen $ \conf -> xmonad $ conf { <your customized settings...> }

If you wish to customize the status bar format at all, you'll have to use something like `dynamicLogWithPP` instead.

The binding uses the XMonad.Hooks.ManageDocks module to automatically handle screen placement for dzen, and enables 'mod-b' for toggling the menu bar.

xmobar :: (XConfig (ModifiedLayout AvoidStruts (Choose Tall (Choose (Mirror Tall) Full))) -> IO t) -> IO t

Run xmonad with a xmobar status bar set to some nice defaults. Output is taken from the dynamicLogWithPP hook.

     main = xmobar xmonad

This works pretty much the same as `dzen` function above

dynamicLog :: X ()

An example log hook, which prints status information to stdout in the default format:

     1 2 [3] 4 7 : full : title

That is, the currently populated workspaces, the current workspace layout, and the title of the focused window.

To customize the output format, see `dynamicLogWithPP`.

dynamicLogDzen :: X ()
An example log hook that emulates dwm's status bar, using colour codes printed to dzen. Requires dzen. Workspaces, xinerama, layouts and the window title are handled.
dynamicLogXmobar :: X ()
These are good defaults to be used with the xmobar status bar.
dynamicLogXinerama :: X ()

Workspace logger with a format designed for Xinerama:

     [1 9 3] 2 7

where 1, 9, and 3 are the workspaces on screens 1, 2 and 3, respectively, and 2 and 7 are non-visible, non-empty workspaces.

Unfortunately, at the present time, the current layout and window title are not shown, and there is no way to incorporate the xinerama workspace format shown above with `dynamicLogWithPP`. Hopefully this will change soon.

Build your own formatter
dynamicLogWithPP :: PP -> X ()
Format the current status using the supplied pretty-printing format, and write it to stdout.
dynamicLogString :: PP -> X String
The same as `dynamicLogWithPP`, except it simply returns the status as a formatted string without actually printing it to stdout, to allow for further processing, or use in some application other than a status bar.
data PP

The `PP` type allows the user to customize the formatting of status information.
Constructors

PP |

ppCurrent :: WorkspaceId -> String | how to print the tag of the currently focused workspace
ppVisible :: WorkspaceId -> String | how to print tags of visible but not focused workspaces (xinerama only)
ppHidden :: WorkspaceId -> String | how to print tags of hidden workspaces which contain windows
ppHiddenNoWindows :: WorkspaceId -> String | how to print tags of empty hidden workspaces
ppUrgent :: WorkspaceId -> String | format to be applied to tags of urgent workspaces. NOTE that `ppUrgent` is applied in addition to `ppHidden`!
ppSep :: String | separator to use between different log sections (window name, layout, workspaces)
ppWsSep :: String | separator to use between workspace tags
ppTitle :: String -> String | window title format
ppLayout :: String -> String | layout name format

ppOrder :: [String] -> [String]

how to order the different log sections. By default, this function receives a list with three formatted strings, representing the workspaces, the layout, and the current window title, respectively. If you have specified any extra loggers in `ppExtras`, their output will also be appended to the list. To get them in the reverse order, you can just use `ppOrder = reverse`. If you don't want to display the current layout, you could use something like `ppOrder = \(ws:_:t:_) -> [ws,t]`, and so on.

ppSort :: X ([WindowSpace] -> [WindowSpace]) | how to sort the workspaces. See XMonad.Util.WorkspaceCompare for some useful sorts.
ppExtras :: [X (Maybe String)] | loggers for generating extra information such as time and date, system load, battery status, and so on. See XMonad.Util.Loggers for examples, or create your own!
ppOutput :: String -> IO () | applied to the entire formatted string in order to output it. Can be used to specify an alternative output method (e.g. write to a pipe instead of stdout), and/or to perform some last-minute formatting.

defaultPP :: PP
The default pretty printing options, as seen in `dynamicLog`.
dzenPP :: PP
Settings to emulate dwm's statusbar, dzen only.
xmobarPP :: PP
Some nice xmobar defaults.
sjanssenPP :: PP
The options that sjanssen likes to use with xmobar, as an example. Note the use of `xmobarColor` and the record update on `defaultPP`.
byorgeyPP :: PP
The options that byorgey likes to use with dzen, as another example.
Formatting utilities
wrap

:: String | left delimiter
-> String | right delimiter
-> String | output string
-> String |
Wrap a string in delimiters, unless it is empty.

pad :: String -> String
Pad a string with a leading and trailing space.
shorten :: Int -> String -> String
Limit a string to a certain length, adding ... if truncated.
xmobarColor

:: String | foreground color: a color name, or #rrggbb format
-> String | background color
-> String | output string
-> String |
Use xmobar escape codes to output a string with given foreground and background colors.

dzenColor

:: String | foreground color: a color name, or #rrggbb format
-> String | background color
-> String | output string
-> String |
Use dzen escape codes to output a string with given foreground and background colors.

dzenEscape :: String -> String
Escape any dzen metacharacters.
Internal formatting functions
pprWindowSet :: WorkspaceSort -> [Window] -> PP -> WindowSet -> String
Format the workspace information, given a workspace sorting function, a list of urgent windows, a pretty-printer format, and the current WindowSet.
pprWindowSetXinerama :: WindowSet -> String
To Do

- incorporate dynamicLogXinerama into the PP framework somehow
- add an xmobarEscape function

Produced by Haddock version 2.1.0