xmonad-contrib-0.17.1: Community-maintained extensions for xmonad

Copyright | (c) Don Stewart <dons@cse.unsw.edu.au>
License | BSD3-style (see LICENSE)
Maintainer | Don Stewart <dons@cse.unsw.edu.au>
Stability | unstable
Portability | unportable
Safe Haskell | Safe-Inferred
Language | Haskell2010

XMonad.Hooks.StatusBar.PP

Contents

- Usage
- Build your own formatter
- Predicates and formatters
- Example formatters
- Formatting utilities
- Internal formatting functions

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.

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.

Synopsis

- data PP = PP {
  - ppCurrent :: WorkspaceId -> String
  - ppVisible :: WorkspaceId -> String
  - ppHidden :: WorkspaceId -> String
  - ppHiddenNoWindows :: WorkspaceId -> String
  - ppVisibleNoWindows :: Maybe (WorkspaceId -> String)
  - ppUrgent :: WorkspaceId -> String
  - ppRename :: String -> WindowSpace -> String
  - ppSep :: String
  - ppWsSep :: String
  - ppTitle :: String -> String
  - ppTitleSanitize :: String -> String
  - ppLayout :: String -> String
  - ppOrder :: [String] -> [String]
  - ppSort :: X ([WindowSpace] -> [WindowSpace])
  - ppExtras :: [X (Maybe String)]
  - ppOutput :: String -> IO ()
  - ppPrinters :: WSPP
  }
- def :: Default a => a
- dynamicLogString :: PP -> X String
- dynamicLogWithPP :: PP -> X ()
- data WS = WS {
  - wsUrgents :: [Window]
  - wsWindowSet :: WindowSet
  - wsWS :: WindowSpace
  - wsPP :: PP
  }
- type WSPP = WSPP' (WorkspaceId -> String)
- type WSPP' = ReaderT WS Maybe
- fallbackPrinters :: WSPP
- isUrgent :: WS -> Bool
- isCurrent :: WS -> Bool
- isVisible :: WS -> Bool
- isVisibleNoWindows :: WS -> Bool
- isHidden :: WS -> Bool
- dzenPP :: PP
- xmobarPP :: PP
- sjanssenPP :: PP
- byorgeyPP :: PP
- wrap :: String -> String -> String -> String
- pad :: String -> String
- trim :: String -> String
- shorten :: Int -> String -> String
- shorten' :: String -> Int -> String -> String
- shortenLeft :: Int -> String -> String
- shortenLeft' :: String -> Int -> String -> String
- xmobarColor :: String -> String -> String -> String
- xmobarFont :: Int -> String -> String
- xmobarAction :: String -> String -> String -> String
- xmobarBorder :: String -> String -> Int -> String -> String
- xmobarRaw :: String -> String
- xmobarStrip :: String -> String
- xmobarStripTags :: [String] -> String -> String
- dzenColor :: String -> String -> String -> String
- dzenEscape :: String -> String
- dzenStrip :: String -> String
- filterOutWsPP :: [WorkspaceId] -> PP -> PP
- pprWindowSet :: WorkspaceSort -> [Window] -> PP -> WindowSet -> String
- pprWindowSetXinerama :: WindowSet -> String

# 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

Instances details

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.

Instance details 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.

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 #