xmonad-contrib-0.14: Third party extensions for xmonad

Copyright(c) Don Stewart <dons@cse.unsw.edu.au>
LicenseBSD3-style (see LICENSE)
MaintainerDon Stewart <dons@cse.unsw.edu.au>
Stabilityunstable
Portabilityunportable
Safe HaskellNone
LanguageHaskell98

XMonad.Hooks.DynamicLog

Contents

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

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 xmobar or dzen functions:

main = xmonad =<< xmobar myConfig

myConfig = def { ... }

There is also statusBar if you'd like to use another status bar, or would like to use different formatting options. The xmobar, dzen, and statusBar functions are preferred over the other options listed below, as they take care of all the necessary plumbing -- no shell scripting required!

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

main = xmonad $ def {
   ...
   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 $ def {
      ...
      logHook = dynamicLogWithPP $ def { 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 :: LayoutClass l Window => XConfig l -> IO (XConfig (ModifiedLayout AvoidStruts l)) Source #

Run xmonad with a dzen status bar set to some nice defaults.

main = xmonad =<< dzen myConfig

myConfig = def { ... }

The intent is that the above config file should provide a nice status bar with minimal effort.

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

dzenWithFlags :: LayoutClass l Window => String -> XConfig l -> IO (XConfig (ModifiedLayout AvoidStruts l)) Source #

Run xmonad with a dzen status bar with specified dzen command line arguments.

main = xmonad =<< dzenWithFlags flags myConfig

myConfig = def { ... }

flags = "-e onstart lower -w 800 -h 24 -ta l -fg #a8a3f7 -bg #3f3c6d"

This function can be used to customize the arguments passed to dzen2. e.g changing the default width and height of dzen2.

If you wish to customize the status bar format at all, you'll have to use the statusBar function 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.

You should use this function only when the default dzen function does not serve your purpose.

xmobar :: LayoutClass l Window => XConfig l -> IO (XConfig (ModifiedLayout AvoidStruts l)) Source #

Run xmonad with a xmobar status bar set to some nice defaults.

main = xmonad =<< xmobar myConfig

myConfig = def { ... }

This works pretty much the same as dzen function above.

statusBar Source #

Arguments

:: LayoutClass l Window 
=> String

the command line to launch the status bar

-> PP

the pretty printing options

-> (XConfig Layout -> (KeyMask, KeySym))

the desired key binding to toggle bar visibility

-> XConfig l

the base config

-> IO (XConfig (ModifiedLayout AvoidStruts l)) 

Modifies the given base configuration to launch the given status bar, send status information to that bar, and allocate space on the screen edges for the bar.

dynamicLog :: X () Source #

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.

dynamicLogXinerama :: X () Source #

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.

At the present time, the current layout and window title are not shown. The xinerama workspace format shown above can be (mostly) replicated using dynamicLogWithPP by setting ppSort to getSortByXineramaRule from XMonad.Util.WorkspaceCompare. For example,

def { ppCurrent = dzenColor "red" "#efebe7"
    , ppVisible = wrap "[" "]"
    , ppSort    = getSortByXineramaRule
    }

xmonadPropLog' :: String -> String -> X () Source #

Write a string to a property on the root window. This property is of type UTF8_STRING. The string must have been processed by encodeString (dynamicLogString does this).

xmonadPropLog :: String -> X () Source #

Write a string to the _XMONAD_LOG property on the root window.

Build your own formatter

dynamicLogWithPP :: PP -> X () Source #

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

dynamicLogString :: PP -> X String Source #

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 Source #

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

Constructors

PP 

Fields

Instances
Default PP Source # 
Instance details

Defined in XMonad.Hooks.DynamicLog

Methods

def :: PP #

defaultPP :: PP Source #

Deprecated: Use def (from Data.Default, and re-exported by XMonad.Hooks.DynamicLog) instead.

The default pretty printing options, as seen in dynamicLog.

def :: Default a => a #

The default value for this type.

Example formatters

dzenPP :: PP Source #

Settings to emulate dwm's statusbar, dzen only.

xmobarPP :: PP Source #

Some nice xmobar defaults.

sjanssenPP :: PP Source #

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 Source #

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

Formatting utilities

wrap Source #

Arguments

:: String

left delimiter

-> String

right delimiter

-> String

output string

-> String 

Wrap a string in delimiters, unless it is empty.

pad :: String -> String Source #

Pad a string with a leading and trailing space.

trim :: String -> String Source #

Trim leading and trailing whitespace from a string.

shorten :: Int -> String -> String Source #

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

xmobarColor Source #

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.

xmobarAction Source #

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.

xmobarRaw :: String -> String Source #

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 Source #

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

xmobarStripTags Source #

Arguments

:: [String]

tags

-> String 
-> String

with all tag.../tag removed

dzenColor Source #

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 Source #

Escape any dzen metacharacters.

dzenStrip :: String -> String Source #

Strip dzen formatting or commands.

Internal formatting functions

pprWindowSet :: WorkspaceSort -> [Window] -> PP -> WindowSet -> String Source #

Format the workspace information, given a workspace sorting function, a list of urgent windows, a pretty-printer format, and the current WindowSet.

To Do

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