XMonad.Hooks.StatusBar.PP

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.

This module provides a pretty-printing abstraction and utilities that can be used to customize what is logged to a status bar. See XMonad.Hooks.StatusBar for an abstraction over starting these status bars. Together these are a modern replacement for XMonad.Hooks.DynamicLog, which is now just a compatibility wrapper.

Usage

An example usage for this module would be:

import XMonad
import XMonad.Hooks.StatusBar
import XMonad.Hooks.StatusBar.PP

myPP = def { ppCurrent = xmobarColor "black" "white" }
mySB = statusBarProp "xmobar" (pure myPP)
main = xmonad . withEasySB mySB defToggleStrutsKey $ myConfig

Check XMonad.Hooks.StatusBar for more examples and an in depth explanation.

Build your own formatter

data PP

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

Constructors

PP

Fields

• 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

• ppVisibleNoWindows :: Maybe (WorkspaceId -> String)

  how to print tags of empty visible workspaces

• ppUrgent :: WorkspaceId -> String

  format to be applied to tags of urgent workspaces.

• ppRename :: String -> WindowSpace -> String

  rename/augment the workspace tag (note that WindowSpace -> … acts as a Reader monad)

• 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 for the focused window. To display the titles of all windows—even unfocused ones—check logTitles.

• ppTitleSanitize :: String -> String

  escape / sanitizes input to ppTitle

• 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 titles, 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. Note that this is only used by dynamicLogWithPP; it won't work with dynamicLogString or XMonad.Hooks.StatusBar.

• ppPrinters :: WSPP

  extend workspace types with custom predicates. Check $predicates for more details.

Instances

Default PP

The default pretty printing options:

1 2 [3] 4 7 : full : title

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

Defined in XMonad.Hooks.StatusBar.PP

Methods

def :: PP

def :: Default a => a

The default value for this type.

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.

dynamicLogString' :: PP -> X String

The guts of dynamicLogString. Forces the result, so it may throw an exception (most commonly because ppOrder is non-total). Use dynamicLogString for a version that catches the exception and produces an error string.

dynamicLogWithPP :: PP -> X ()

Format the current status using the supplied pretty-printing format, and write it to stdout.

Predicates and formatters

Using WSPP with ppPrinters allows extension modules (and users) to extend PP with new workspace types beyond ppCurrent, ppUrgent, and the rest.

data WS

The data available to WSPP'.

Constructors

WS

Fields

• wsUrgents :: [Window]

  Urgent windows

• wsWindowSet :: WindowSet

  The entire WindowSet, for context

• wsWS :: WindowSpace

  The WindowSpace being formatted

• wsPP :: PP

  The actual final PP

type WSPP = WSPP' (WorkspaceId -> String)

The type allowing to build formatters (and predicates). See the source fallbackPrinters for an example.

type WSPP' = ReaderT WS Maybe

fallbackPrinters :: WSPP

For a PP pp, fallbackPrinters pp returns the default WSPP used to format workspaces: the formatter chosen corresponds to the first matching workspace type, respecting the following precedence: ppUrgent, ppCurrent, ppVisible, ppVisibleNoWindows, ppHidden, ppHiddenNoWindows.

This can be useful if one needs to use the default set of formatters and post-process their output. (For pre-processing their input, there's ppRename.)

isUrgent :: WS -> Bool

Predicate for urgent workspaces.

isCurrent :: WS -> Bool

Predicate for the current workspace.

isVisible :: WS -> Bool

Predicate for visible workspaces.

isVisibleNoWindows :: WS -> Bool

Predicate for visible workspaces that have no windows.

isHidden :: WS -> Bool

Predicate for hidden workspaces.

Example formatters

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 def.

byorgeyPP :: PP

The options that byorgey likes to use with dzen, as another example.

Formatting utilities

wrap

Arguments

:: 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.

trim :: String -> String

Trim leading and trailing whitespace from a string.

shorten :: Int -> String -> String

Limit a string to a certain length, adding "..." if truncated.

shorten' :: String -> Int -> String -> String

Limit a string to a certain length, adding end if truncated.

shortenLeft :: Int -> String -> String

Like shorten, but truncate from the left instead of right.

shortenLeft' :: String -> Int -> String -> String

Like shorten', but truncate from the left instead of right.

xmobarColor

Arguments

:: 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.

xmobarFont

Arguments

:: Int

index: index of the font to use (0: standard font)

-> String

output string

-> String

Use xmobar escape codes to output a string with the font at the given index

xmobarAction

Arguments

:: String

Command. Use of backticks (`) will cause a parse error.

-> String

Buttons 1-5, such as "145". Other characters will cause a parse error.

-> String

Displayed/wrapped text.

-> String

Encapsulate text with an action. The text will be displayed, and the action executed when the displayed text is clicked. Illegal input is not filtered, allowing xmobar to display any parse errors. Uses xmobar's new syntax wherein the command is surrounded by backticks.

xmobarBorder

Arguments

:: String

Border type. Possible values: VBoth, HBoth, Full, Top, Bottom, Left or Right

-> String

color: a color name, or #rrggbb format

-> Int

width in pixels

-> String

output string

-> String

Use xmobar box to add a border to an arbitrary string.

xmobarRaw :: String -> String

Encapsulate arbitrary text for display only, i.e. untrusted content if wrapped (perhaps from window titles) will be displayed only, with all tags ignored. Introduced in xmobar 0.21; see their documentation. Be careful not to shorten the result.

xmobarStrip :: String -> String

Strip xmobar markup, specifically the <fc>, <icon> and <action> tags and the matching tags like </fc>.

xmobarStripTags

Arguments

:: [String]

tags

-> String

-> String

with all <tag>...</tag> removed

dzenColor

Arguments

:: 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.

dzenStrip :: String -> String

Strip dzen formatting or commands.

filterOutWsPP :: [WorkspaceId] -> PP -> PP

Transforms a pretty-printer into one not displaying the given workspaces.

For example, filtering out the NSP workspace before giving the PP to dynamicLogWithPP:

logHook = dynamicLogWithPP . filterOutWsPP [scratchpadWorkspaceTag] $ def

Here is another example, when using XMonad.Layout.IndependentScreens. If you have handles hLeft and hRight for bars on the left and right screens, respectively, and pp is a pretty-printer function that takes a handle, you could write

logHook = let log screen handle = dynamicLogWithPP . filterOutWsPP [scratchpadWorkspaceTag] . marshallPP screen . pp $ handle
          in log 0 hLeft >> log 1 hRight

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