diff options
Diffstat (limited to 'readme.md')
| -rw-r--r-- | readme.md | 428 |
1 files changed, 302 insertions, 126 deletions
@@ -1,7 +1,6 @@ -% xmobar - A Minimalistic Text Based Status Bar +% xmobar - a minimalistic status bar -About -===== +# About xmobar is a minimalistic, mostly text based, status bar. It was originally designed and implemented by Andrea Rossato to work with @@ -11,7 +10,7 @@ xmobar was inspired by the [Ion3] status bar, and supports similar features, like dynamic color management, icons, output templates, and extensibility through plugins. -This page documents xmobar 0.18 (see [release notes]). +This page documents xmobar 0.23 (see [release notes]). [This screenshot] shows xmobar running under [sawfish], with antialiased fonts. And [this one] is my desktop with [xmonad] and two @@ -23,16 +22,17 @@ instances of xmobar. [This screenshot]: http://projects.haskell.org/xmobar/xmobar-sawfish.png [this one]: http://projects.haskell.org/xmobar/xmobar-xmonad.png -Bug Reports -=========== +# Bug Reports -To submit bug reports you can use the [bug tracker over at Google -code] or send mail to our [Mailing list]. +To submit bug reports you can use the [bug tracker over at Github] or +send mail to our [Mailing list]. -[bug tracker over at Google code]: http://code.google.com/p/xmobar/issues +Note: the old bug tracker at Google code is deprecated. Please use +Github's for new bugs. -Installation -============ +[bug tracker over at Github]: https://github.com/jaor/xmobar/issues + +# Installation ## Using cabal-install @@ -121,6 +121,10 @@ Otherwise, you'll need to install them yourself. font = "xft:Times New Roman-10:italic" + Or to have fallback fonts, just separate them by commas: + + font = "xft:Open Sans:size=9,WenQuanYi Zen Hei:size=9" + `with_mpd` : Enables support for the [MPD] daemon. Requires the [libmpd] package. @@ -129,7 +133,7 @@ Otherwise, you'll need to install them yourself. Requires the [dbus] and [text] packages. `with_inotify` -: Support for inotify in modern linux kernels. This option is needed +: Support for inotify in modern Linux kernels. This option is needed for the MBox and Mail plugins to work. Requires the [hinotify] package. @@ -149,11 +153,14 @@ Otherwise, you'll need to install them yourself. : Support for other timezones. Enables the DateZone plugin. Requires [timezone-olson] and [timezone-series] package. +`with_xpm` +: Support for xpm image file format. This will allow loading .xpm files in `<icon>`. + Requires the [libXpm] C library. + `all_extensions` : Enables all the extensions above. -Running xmobar -============== +# Running xmobar You can now run xmobar with: @@ -167,7 +174,7 @@ if you have the default configuration file saved as `$XDG\_CONFIG\_HOME/xmobar/xmobarrc` (defaulting to `~/.config/xmobar/xmobarrc`), or `~/.xmobarrc`. -### Signal Handling +## Signal Handling Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2: @@ -175,8 +182,7 @@ Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2: - After receiving SIGUSR2 xmobar repositions it self on the current screen. -Configuration -============= +# Configuration ## Quick Start @@ -192,9 +198,29 @@ For the output template: - `<fc=#FF0000>string</fc>` will print `string` with `#FF0000` color (red). -- `<icon=/path/to/icon.xbm/>` will insert the given bitmap. +- `<icon=/path/to/icon.xbm/>` will insert the given bitmap. XPM image + format is also supported when compiled with `--flags="with_xpm"`. + +- ```<action=`command` button=12345>``` will execute given command when + clicked with specified buttons. If not specified, button is equal to 1 + (left mouse button). Using old syntax (without backticks surrounding `command`) + will result in `button` attribute being ignored. + +- `<raw=len:str/>` allows the encapsulation of arbitrary text `str` (which + must be `len` `Char`s long, where `len` is encoded as a decimal sequence). + Careful use of this and `UnsafeStdinReader`, for example, permits window + managers to feed xmobar strings with `<action>` tags mixed with un-trusted + content (e.g. window titles). For example, if xmobar is invoked as -- `<action=command>` will execute given command. + ```xmobar -c "[Run UnsafeStdinReader]" -t "%UnsafeStdinReader%"``` + + and receives on standard input the line + + ```<action=`echo test` button=1><raw=41:<action=`echo mooo` +button=1>foo</action>/></action>``` + + then it will display the text ```<action=`echo mooo` button=1>foo</action>```, + which, when clicked, will cause `test` to be echoed. Other configuration options: @@ -246,6 +272,15 @@ Other configuration options: : position = Top +`textOffset` +: The vertical offset, in pixels, for the text baseline. If + negative or not given, xmobar will try to center text + vertically. + +`iconOffset` +: The vertical offset, in pixels, for icons bottom line. If negative + or not given, xmobar will try to center icons vertically. + `lowerOnStart` : When True the window is sent the bottom of the window stack initially. @@ -256,7 +291,7 @@ Other configuration options: `allDesktops` : When set to True (the default), xmobar will tell the window manager - explicitily to be shown in all desktops, by setting + explicitly to be shown in all desktops, by setting `_NET_WM_DESKTOP` to 0xffffffff. `overrideRedirect` @@ -264,6 +299,12 @@ Other configuration options: to set this option to `False` so that it behaves as a docked application. Defaults to `True`. +`pickBroadest` +: When multiple displays are available, xmobar will choose by default + the first one to place itself. With this flag set to `True` + (the default is `False`) it will choose the broadest one + instead. + `persistent` : When True the window status is fixed i.e. hiding or revealing is not possible. This option can be toggled at runtime. Defaults to False. @@ -282,6 +323,15 @@ Other configuration options: `borderColor` : Border color. +`borderWidth` +: Border width in pixels. + +`iconRoot` +: Root folder where icons are stored. For <icon=path/> + if path start with `"/"`, `"./"` or `"../"` it is interpreted as + it is. Otherwise it will have `iconRoot ++ "/"` prepended to + it. Default is `"."`. + `commands` : For setting the options of the programs to run (optional). @@ -336,6 +386,7 @@ xmobar --help): -s char --sepchar=char The character used to separate commands in the output template. Default '%' -t template --template=template The output template + -i path --iconroot=path Default directory for icon pattern files -c commands --commands=commands The list of commands to be executed -C command --add-command=command Add to the list of commands to be executed -x screen --screen=screen On which X screen number to start @@ -348,7 +399,7 @@ When compiled with the optional `with_dbus` flag, xmobar can be controlled over dbus. All signals defined in [src/Signal.hs] as `data SignalType` can now be sent over dbus to xmobar. Due to current limitations of the implementation only one process of xmobar can -aquire the dbus. This is handled on a first-come-first-seved basis, +acquire the dbus. This is handled on a first-come-first-served basis, meaning that the first process will get the dbus interface. Other processes will run without further problems, yet have no dbus interface. @@ -458,13 +509,16 @@ form: <icon=/path/to/bitmap.xbm/> -which will produce the expected result. +which will produce the expected result. Accepted image formats are XBM +and XPM (when `with_xpm` flag is enabled). If path does not start with +`"/"`, `"./"`, `"../"` it will have `iconRoot ++ "/"` prepended to it. It's also possible to use action directives of the form: - <action=command> + <action=`command` button=12345> -which will be executed when clicked on. +which will be executed when clicked on with specified mouse buttons. This tag +can be nested, allowing different commands to be run depending on button clicked. ## The `commands` Configuration Option @@ -489,7 +543,7 @@ an example of a template for the commands above using an icon: This example will run "xclock" command when date is clicked: - template="<action=xclock>%date%</action> + template="<action=`xclock`>%date%</action> The only internal available command is `Com` (see below Executing External Commands). All other commands are provided by plugins. xmobar @@ -511,11 +565,28 @@ Monitors have default aliases. The sections below describe every monitor in turn, but before we provide a list of the configuration options (or *monitor arguments*) they all share. +### Icon patterns + +Some monitors allow usage of strings that depend on some integer value +from 0 to 8 by replacing all occurences of `"%%"` with it +(i.e. `"<icon=/path/to/icon_%%.xpm/>"` will be interpreted +as `"<icon=/path/to/icon_3.xpm/>"` when the value is `3`, also `"%"` is interpreted +as `"%"`, `"%%"` as `"3"`, `"%%%"` as `"3%"`, `"%%%%"` as `"33"` and so on). Essentially +it allows to replace vertical bars with custom icons. For example, + + Run Brightness + [ "-t", "<ipat>" + , "--" + , "--brightness-icon-pattern", "<icon=bright_%%.xpm/>" + ] 30 + +Will display `bright_0.xpm` to `bright_8.xpm` depending on current brightness +value. ### Default Monitor Arguments Monitors accept a common set of arguments, described in the first -subsection below. In additon, some monitors accept additional options +subsection below. In addition, some monitors accept additional options that are specific to them. When specifying the list of arguments in your configuration, the common options come first, followed by "--", followed by any monitor-specific options. @@ -617,6 +688,10 @@ These are the options available for all monitors below: - Total number of characters used to draw bars. - Long option: `--bwidth` - Default value: 10 +- `-x` _string_ N/A string + - String to be used when the monitor is not available + - Long option: `--nastring` + - Default value: "N/A" Commands' arguments must be set as a list. E.g.: @@ -643,47 +718,53 @@ something like: ### `Weather StationID Args RefreshRate` -- Aliases to the Station ID: so `Weather "LIPB" []` can be used in template as `%LIPB%` +- Aliases to the Station ID: so `Weather "LIPB" []` can be used in + template as `%LIPB%` - Args: default monitor arguments - Variables that can be used with the `-t`/`--template` argument: `station`, `stationState`, `year`, `month`, `day`, `hour`, - `wind`, `visibility`, `skyCondition`, `tempC`, `tempF`, - `dewPoint`, `rh`, `pressure` + `windCardinal`, `windAzimuth`, `windMph`, `windKnots`, + `visibility`, `skyCondition`, `tempC`, `tempF`, + `dewPointC`, `dewPointF`, `rh`, `pressure` - Default template: `<station>: <tempC>C, rh <rh>% (<hour>)` -- Requires `curl` in the `$PATH` to retrieve weather information from - `http://weather.noaa.gov` +- Retrieves weather information from http://weather.noaa.gov. ### `Network Interface Args RefreshRate` - Aliases to the interface name: so `Network "eth0" []` can be used as `%eth0%` -- Args: default monitor arguments +- Args: default monitor arguments, plus: + - `--rx-icon-pattern`: dynamic string for reception rate in `rxipat`. + - `--tx-icon-pattern`: dynamic string for transmission rate in `txipat`. - Variables that can be used with the `-t`/`--template` argument: - `dev`, `rx`, `tx`, `rxbar`, `txbar`. Reception and transmission - rates (`rx` and `tx`) are displayed in Kbytes per second, and you - can set the `-S` to "True" to make them displayed with units (the - string "Kb/s"). + `dev`, `rx`, `tx`, `rxbar`, `rxvbar`, `rxipat`, `txbar`, `txvbar`, + `txipat`. Reception and transmission rates (`rx` and `tx`) are displayed + by default as Kb/s, without any suffixes, but you can set the `-S` to + "True" to make them displayed with adaptive units (Kb/s, Mb/s, etc.). - Default template: `<dev>: <rx>KB|<tx>KB` ### `DynNetwork Args RefreshRate` - Active interface is detected automatically - Aliases to "dynnetwork" -- Args: default monitor arguments +- Args: default monitor arguments, plus: + - `--rx-icon-pattern`: dynamic string for reception rate in `rxipat`. + - `--tx-icon-pattern`: dynamic string for transmission rate in `txipat`. - Variables that can be used with the `-t`/`--template` argument: - `dev`, `rx`, `tx`, `rxbar`, `txbar`. Reception and transmission - rates (`rx` and `tx`) are displayed in Kbytes per second, and you - can set the `-S` to "True" to make them displayed with units (the - string "Kb/s"). + `dev`, `rx`, `tx`, `rxbar`, `rxvbar`, `rxipat`, `txbar`, `txvbar`, + `txipat`. Reception and transmission rates (`rx` and `tx`) are displayed + in Kbytes per second, and you can set the `-S` to "True" to make them + displayed with units (the string "Kb/s"). - Default template: `<dev>: <rx>KB|<tx>KB` ### `Wireless Interface Args RefreshRate` -- Aliases to the interface name with the suffix "wi": thus, `Wirelss +- Aliases to the interface name with the suffix "wi": thus, `Wireless "wlan0" []` can be used as `%wlan0wi%` -- Args: default monitor arguments +- Args: default monitor arguments, plus: + - `--quality-icon-pattern`: dynamic string for connection quality in `qualityipat`. - Variables that can be used with the `-t`/`--template` argument: - `essid`, `quality`, `qualitybar` + `essid`, `quality`, `qualitybar`, `qualityvbar`, `qualityipat` - Default template: `<essid> <quality>` - Requires the C library [iwlib] (part of the wireless tools suite) installed in your system. In addition, to activate this plugin you @@ -692,10 +773,15 @@ something like: ### `Memory Args RefreshRate` - Aliases to `memory` -- Args: default monitor arguments +- Args: default monitor arguments, plus: + - `--used-icon-pattern`: dynamic string for used memory ratio in `usedipat`. + - `--free-icon-pattern`: dynamic string for free memory ratio in `freeipat`. + - `--available-icon-pattern`: dynamic string for available memory ratio in `availableipat`. - Variables that can be used with the `-t`/`--template` argument: - `total`, `free`, `buffer`, `cache`, `rest`, `used`, - `usedratio`, `usedbar`, `freeratio`, `freebar` + `total`, `free`, `buffer`, `cache`, `available`, `used`, + `usedratio`, `usedbar`, `usedvbar`, `usedipat`, + `freeratio`, `freebar`, `freevbar`, `freeipat`, + `availableratio`, `availablebar`, `availablevbar`, `availableipat` - Default template: `Mem: <usedratio>% (<cache>M)` ### `Swap Args RefreshRate` @@ -709,19 +795,24 @@ something like: ### `Cpu Args RefreshRate` - Aliases to `cpu` -- Args: default monitor arguments +- Args: default monitor arguments, plus: + - `--load-icon-pattern`: dynamic string for cpu load in `ipat`. - Variables that can be used with the `-t`/`--template` argument: - `total`, `bar`, `user`, `nice`, `system`, `idle`, `iowait` + `total`, `bar`, `vbar`, `ipat`, `user`, `nice`, `system`, `idle`, `iowait` - Default template: `Cpu: <total>%` ### `MultiCpu Args RefreshRate` - Aliases to `multicpu` -- Args: default monitor arguments +- Args: default monitor arguments, plus: + - `--load-icon-pattern`: dynamic string for overall cpu load in `ipat`. + - `--load-icon-patterns`: dynamic string for each cpu load in `autoipat`, `ipat{i}`. + This option can be specified several times. nth option + corresponds to nth cpu. - Variables that can be used with the `-t`/`--template` argument: - `autototal`, `autobar`, `autouser`, `autonice`, - `autosystem`, `autoidle`, `total`, `bar`, `user`, `nice`, - `system`, `idle`, `total0`, `bar0`, `user0`, `nice0`, + `autototal`, `autobar`, `autovbar`, `autoipat`, `autouser`, `autonice`, + `autosystem`, `autoidle`, `total`, `bar`, `vbar`, `ipat`, `user`, `nice`, + `system`, `idle`, `total0`, `bar0`, `vbar0`, `ipat0`, `user0`, `nice0`, `system0`, `idle0`, ... The auto* variables automatically detect the number of CPUs on the system and display one entry for each. @@ -748,13 +839,19 @@ something like: - `-H`: high power threshold (default: -10) - `-l`: color to display power lower than the `-L` threshold - `-m`: color to display power lower than the `-H` threshold - - `-h`: color to display power highter than the `-H` threshold + - `-h`: color to display power higher than the `-H` threshold - `-p`: color to display positive power (battery charging) - `-f`: file in `/sys/class/power_supply` with AC info (default: "AC/online") + - `--on-icon-pattern`: dynamic string for current battery charge + when AC is "on" in `leftipat`. + - `--off-icon-pattern`: dynamic string for current battery charge + when AC is "off" in `leftipat`. + - `--idle-icon-pattern`: dynamic string for current battery charge + when AC is "idle" in `leftipat`. - Variables that can be used with the `-t`/`--template` argument: - `left`, `leftbar`, `timeleft`, `watts`, `acstatus` + `left`, `leftbar`, `leftvbar`, `leftipat`, `timeleft`, `watts`, `acstatus` - Default template: `Batt: <watts>, <left>% / <timeleft>` - Example (note that you need "--" to separate regular monitor options from Battery's specific ones): @@ -827,14 +924,17 @@ more than one battery. - Aliases to `disku` - Disks: list of pairs of the form (device or mount point, template), where the template can contain `<size>`, `<free>`, `<used>`, `<freep>` or - `<usedp>`, `<freebar>` or `<usedbar>` for total, free, used, free - percentage and used percentage of the given file system capacity. -- Args: default monitor arguments. `-t`/`--template` is ignored. + `<usedp>`, `<freebar>`, `<freevbar>`, `<freeipat>`, `<usedbar>`, + `<usedvbar>` or `<usedipat>` for total, free, used, free percentage and + used percentage of the given file system capacity. +- Args: default monitor arguments. `-t`/`--template` is ignored. Plus + - `--free-icon-pattern`: dynamic string for free disk space in `freeipat`. + - `--used-icon-pattern`: dynamic string for used disk space in `usedipat`. - Default template: none (you must specify a template for each file system). - Example: DiskU [("/", "<used>/<size>"), ("sdb1", "<usedbar>")] - ["-L", "20", "-H", "50", "-m", "1", "-p", "3",] + ["-L", "20", "-H", "50", "-m", "1", "-p", "3"] 20 ### `DiskIO Disks Args RefreshRate` @@ -842,8 +942,14 @@ more than one battery. - Aliases to `diskio` - Disks: list of pairs of the form (device or mount point, template), where the template can contain `<total>`, `<read>`, `<write>` for total, - read and write speed, respectively. -- Args: default monitor arguments. `-t`/`--template` is ignored. + read and write speed, respectively. There are also bar versions of each: + `<totalbar>`, `<totalvbar>`, `<totalipat>`, + `<readbar>`, `<readvbar>`, `<readipat>`, + `<writebar>`, `<writevbar>`, and `<writeipat>`. +- Args: default monitor arguments. `-t`/`--template` is ignored. Plus + - `--total-icon-pattern`: dynamic string for total disk I/O in `<totalipat>`. + - `--write-icon-pattern`: dynamic string for write disk I/O in `<writeipat>`. + - `--read-icon-pattern`: dynamic string for read disk I/O in `<readipat>`. - Default template: none (you must specify a template for each file system). - Example: @@ -857,7 +963,7 @@ more than one battery. - Variables that can be used with the `-t`/`--template` argument: `temp` - Default template: `<temp>C` -- This plugin works only on sytems with devices having thermal zone. +- This plugin works only on systems with devices having thermal zone. Check directories in `/sys/class/thermal` for possible values of the zone number (e.g., 0 corresponds to `thermal_zone0` in that directory). @@ -875,7 +981,7 @@ more than one battery. - Variables that can be used with the `-t`/`--template` argument: `temp` - Default template: `Thm: <temp>C` -- This plugin works only on sytems with devices having thermal zone. +- This plugin works only on systems with devices having thermal zone. Check directories in /proc/acpi/thermal_zone for possible values. - Example: @@ -931,8 +1037,9 @@ more than one battery. - Long option: `--offc` - `--highd` _number_ High threshold for dB. Defaults to -5.0. - `--lowd` _number_ Low threshold for dB. Defaults to -30.0. + - `--volume-icon-pattern` _string_ dynamic string for current volume in `volumeipat`. - Variables that can be used with the `-t`/`--template` argument: - `volume`, `volumebar`, `dB`, `status` + `volume`, `volumebar`, `volumevbar`, `volumeipat`, `dB`, `status` - Note that `dB` might only return 0 on your system. This is known to happen on systems with a pulseaudio backend. - Default template: `Vol: <volume>% <status>` @@ -949,19 +1056,21 @@ more than one battery. `-P`, `-S` and `-Z`, with an string argument, to represent the playing, stopped and paused states in the `statei` template field. The environment variables `MPD_HOST` and `MPD_PORT` are used to configure the - mpd server to communicate with. + mpd server to communicate with. Also available: + - `lapsed-icon-pattern`: dynamic string for current track position in `ipat`. - Variables that can be used with the `-t`/`--template` argument: - `bar`, `state`, `statei`, `volume`, `length` + `bar`, `vbar`, `ipat`, `state`, `statei`, `volume`, `length`, `lapsed`, `remaining`, - `plength` (playlist length), `ppos` (playlist position) - `name`, `artist`, `composer`, `performer` + `plength` (playlist length), `ppos` (playlist position), + `flags` (ncmpcpp-style playback mode), + `name`, `artist`, `composer`, `performer`, `album`, `title`, `track`, `file`, `genre` - Default template: `MPD: <state>` - Example (note that you need "--" to separate regular monitor options from MPD's specific ones): Run MPD ["-t", - "<composer> <title> (<album>) <track>/<plength> <statei> ", + "<composer> <title> (<album>) <track>/<plength> <statei> [<flags>]", "--", "-P", ">>", "-Z", "|", "-S", "><"] 10 ### `Mpris1 PlayerName Args RefreshRate` @@ -980,7 +1089,7 @@ more than one battery. ### `Mpris2 PlayerName Args RefreshRate` -- Aliases to `mpris1` +- Aliases to `mpris2` - Requires [dbus] and [text] packages. To activate, pass `--flags="with_mpris"` during compilation. - PlayerName: player supporting MPRIS v2 protocol, in lowercase. @@ -991,14 +1100,14 @@ more than one battery. - Default template: `<artist> - <title>` - Example: - Run Mpris2 "clementine" ["-t", "<artist> - [<composer>] <title>"] 10 + Run Mpris2 "spotify" ["-t", "<artist> - [<composer>] <title>"] 10 ### `Mail Args Alias` - Args: list of maildirs in form `[("name1","path1"),...]`. Paths may start with a '~' to expand to the user's home directory. -- This plugin requires inotify support in your linux kernel and the +- This plugin requires inotify support in your Linux kernel and the [hinotify] package. To activate, pass `--flags="with_inotify"` during compilation. - Example: @@ -1018,11 +1127,11 @@ more than one battery. -d dir --dir dir a string giving the base directory where mbox files with a relative path live. -p prefix --prefix prefix a string giving a prefix for the list - of displayed mail coints + of displayed mail counts -s suffix --suffix suffix a string giving a suffix for the list - of displayed mail coints + of displayed mail counts - Paths may start with a '~' to expand to the user's home directory. -- This plugin requires inotify support in your linux kernel and the +- This plugin requires inotify support in your Linux kernel and the [hinotify] package. To activate, pass `--flags="with_inotify"` during compilation. - Example. The following command look for mails in `/var/mail/inbox` @@ -1043,9 +1152,23 @@ more than one battery. [samples/xmonadpropwrite.hs script]: https://github.com/jaor/xmobar/raw/master/samples/xmonadpropwrite.hs +### `UnsafeXPropertyLog PropName` + +- Aliases to `PropName` +- Same as `XPropertyLog`, but the input is not filtered to avoid + injection of actions (cf. `UnsafeXMonadLog`). The program writing + the value of the read property is responsible of performing any + needed cleanups. + ### `NamedXPropertyLog PropName Alias` -- Same as XPropertyLog, but a custom alias can be specified. +- Aliases to `Alias` +- Same as `XPropertyLog`, but a custom alias can be specified. + +### `NamedXPropertyLog PropName Alias` + +- Aliases to `Alias` +- Same as `UnsafeXPropertyLog`, but a custom alias can be specified. ### `Brightness Args RefreshRate` @@ -1056,9 +1179,10 @@ more than one battery. - `-C`: file with the current brightness (default: actual_brightness) - `-M`: file with the maximum brightness (default: - max_brigtness) + max_brightness) + - `--brightness-icon-pattern`: dynamic string for current brightness in `ipat`. - Variables that can be used with the `-t`/`--template` argument: - `hbar`, `percent`, `bar` + `vbar`, `percent`, `bar`, `ipat` - Default template: `<percent>` - Example: @@ -1067,9 +1191,9 @@ more than one battery. ### `Kbd Opts` - Registers to XKB/X11-Events and output the currently active keyboard layout. - Supports replacement of layoutnames. + Supports replacement of layout names. - Aliases to `kbd` -- Opts is a list of tuple: +- Opts is a list of tuples: - first element of the tuple is the search string - second element of the tuple is the corresponding replacement - Example: @@ -1084,6 +1208,16 @@ more than one battery. Run Locks +### `CatInt n fn` + +- Reads and displays an integer from the file whose path is `fn` + (especially useful with files in `/sys`). +- Aliases as `catn` (e.g. `Cat 0` as `cat0`, etc.) so you can + have several. +- Example: + + Run CatInt 0 "/sys/devices/platform/thinkpad_hwmon/fan1_input" [] 50 + ## Executing External Commands In order to execute an external command you can either write the @@ -1114,18 +1248,35 @@ can be used in the output template as `%mydate%` ## Other Plugins -`StdinReader` +<font size="+1">**`StdinReader`**</font> - Aliases to StdinReader - Displays any text received by xmobar on its standard input. +- Strips actions from the text received. This means you can't pass dynamic + actions via stdin. This is safer than `UnsafeStdinReader` because there is + no need to escape the content before passing it to xmobar's standard input. -`Date Format Alias RefreshRate` +<font size="+1">**`UnsafeStdinReader`**</font> + +- Aliases to UnsafeStdinReader +- Displays any text received by xmobar on its standard input. +- Will not do anything to the text received. This means you can pass dynamic + actions via stdin. Be careful to remove tags from dynamic text that you + pipe-thru to xmobar's standard input, e.g. window's title. There is no way + to escape the tags, i.e. you can't print a literal `<action>` tag as a text + on xmobar. +- Sample usage: send to xmobar's stdin the list of your workspaces enclosed by + actions tags that switches the workspaces to be able to switch workspaces by + clicking on xmobar: + ```<action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action>``` + +<font size="+1">**`Date Format Alias RefreshRate`**</font> - Format is a time format string, as accepted by the standard ISO C `strftime` function (or Haskell's `formatCalendarTime`). - Sample usage: `Run Date "%a %b %_d %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10` -`DateZone Format Locale Zone Alias RefreshRate` +<font size="+1">**`DateZone Format Locale Zone Alias RefreshRate`**</font> - Format is a time format string, as accepted by the standard ISO C `strftime` function (or Haskell's `formatCalendarTime`). @@ -1138,45 +1289,57 @@ can be used in the output template as `%mydate%` - Sample usage: `Run DateZone "%a %H:%M:%S" "de_DE.UTF-8" "Europe/Vienna" "viennaTime" 10` -`CommandReader "/path/to/program" Alias` +<font size="+1">**`CommandReader "/path/to/program" Alias`**</font> - Runs the given program, and displays its standard output. -`PipeReader "default text:/path/to/pipe" Alias` +<font size="+1">**`PipeReader "default text:/path/to/pipe" Alias`**</font> - Reads its displayed output from the given pipe. - Prefix an optional default text separated by a colon -`BufferedPipeReader Alias [ (Timeout, Bool, "/path/to/pipe1") - , (Timeout, Bool, "/path/to/pipe2") - , .. - ]` +<font size="+1">**`MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias`**</font> + +- Generally equivalent to PipeReader +- Text is displayed as marquee with the specified length, rate in 10th + seconds and separator when it wraps around + + Run MarqueePipeReader "/tmp/testpipe" (10, 7, "+") "mpipe" + +<font size="+1"> +**`BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]`** +</font> - Display data from multiple pipes. -- Timeout (in tenth of seconds) is the value after which the previous content is - restored i.e. if there was already something from a previous pipe it will be - put on display again, overwriting the current status. -- A pipe with Timout of 0 will be displayed permanently, just like `PipeReader` -- The boolean option indicates whether new data for this pipe should make xmobar - appear (unhide, reveal). In this case, the Timeout additionally specifies when - the window should be hidden again. The output is restored in any case. -- Use it for OSD like status bars e.g. for setting the volume or brightness: +- Timeout (in tenth of seconds) is the value after which the previous + content is restored i.e. if there was already something from a + previous pipe it will be put on display again, overwriting the + current status. +- A pipe with Timeout of 0 will be displayed permanently, just like + `PipeReader` +- The boolean option indicates whether new data for this pipe should + make xmobar appear (unhide, reveal). In this case, the Timeout + additionally specifies when the window should be hidden again. The + output is restored in any case. +- Use it for OSD-like status bars e.g. for setting the volume or + brightness: Run BufferedPipeReader "bpr" [ ( 0, False, "/tmp/xmobar_window" ) , ( 15, True, "/tmp/xmobar_status" ) ] - Have your window manager send window titles to `"/tmp/xmobar_window"`. They will - always be shown and not reveal your xmobar. - Sending some status information to `"/tmp/xmobar_status"` will reveal xmonad - for 1.5 seconds and temporarily overwrite the window titles. + Have your window manager send window titles to + `"/tmp/xmobar_window"`. They will always be shown and not reveal + your xmobar. Sending some status information to + `"/tmp/xmobar_status"` will reveal xmonad for 1.5 seconds and + temporarily overwrite the window titles. - Take a look at [samples/status.sh] [samples/status.sh]: http://github.com/jaor/xmobar/raw/master/samples/status.sh -`XMonadLog` +<font size="+1">**`XMonadLog`**</font> - Aliases to XMonadLog - Displays information from xmonad's `_XMONAD_LOG`. You can set this @@ -1194,8 +1357,20 @@ can be used in the output template as `%mydate%` [here]: http://xmonad.org/xmonad-docs/xmonad-contrib/XMonad-Hooks-DynamicLog.html -Plugins -======= +<font size="+1">**`UnsafeXMonadLog`**</font> + +- Aliases to UnsafeXMonadLog +- Similar to StdinReader versus UnsafeStdinReader, this does not strip `<action + ...>` tags from XMonad's `_XMONAD_LOG`. +- It is advised that you still use `xmobarStrip` for the ppTitle in your + logHook: + + myPP = defaultPP { ppTitle = xmobarStrip } + main = xmonad $ defaultConfig { + logHook = dynamicLogString myPP >>= xmonadPropLog + } + +# Plugins ## Writing a Plugin @@ -1311,24 +1486,26 @@ To remove the system monitor plugin: 3. rebuild xmobar. -Authors and credits -=================== +# Authors and credits Andrea Rossato originally designed and implemented xmobar up to -version 0.11.1. Since then, it is maintained and developed by [Jose -Antonio Ortega Ruiz](http://hacks-galore.org/jao/), with the help of -the greater Haskell community. - -In particular, xmobar [incorporates patches] by Ben Boeckel, Roman -Cheplyaka, Patrick Chilton, John Goerzen, Reto Hablützel, Juraj -Hercek, Tomas Janousek, Spencer Janssen, Jochen Keil, Lennart -Kolmodin, Krzysztof Kosciuszkiewicz, Dmitry Kurochkin, Todd Lunter, -Dmitry Malikov, Edward O'Callaghan, Svein Ove, Martin Perner, Jens -Petersen, Alexander Polakov, Petr Rockai, Peter Simons, Andrew -Sackville-West, Alexander Solovyov, John Soros, Artem Tarasov, Sergei -Trofimovich, Thomas Tuegel, Jan Vornberger, Daniel Wagner and Norbert -Zeh. - +version 0.11.1. Since then, it is maintained and developed by [jao], +with the help of the greater xmobar and Haskell communities. + +In particular, xmobar [incorporates patches] by Axel Angel, Ben +Boeckel, Duncan Burke, Roman Cheplyaka, Patrick Chilton, Nathaniel +Wesley Filardo, John Goerzen, Reto Hablützel, Juraj Hercek, Tomas +Janousek, Spencer Janssen, Jochen Keil, Lennart Kolmodin, Krzysztof +Kosciuszkiewicz, Dmitry Kurochkin, Todd Lunter, Robert J. Macomber, +Dmitry Malikov, David McLean, Marcin Mikołajczyk, Tony Morris, Eric +Mrak, Thiago Negri, Edward O'Callaghan, Svein Ove, Martin Perner, Jens +Petersen, Alexander Polakov, Petr Rockai, Andrew Sackville-West, +Alexander Shabalin, Peter Simons, Alexander Solovyov, John Soros, +Travis Staton, Artem Tarasov, Samuli Thomasson, Sergei Trofimovich, +Thomas Tuegel, Jan Vornberger, Anton Vorontsov, Daniel Wagner, Phil +Xiaojun Hu and Norbert Zeh. + +[jao]: http://jao.io [incorporates patches]: http://www.ohloh.net/p/xmobar/contributors ## Thanks @@ -1347,8 +1524,7 @@ __jao__: Thanks to Andrea for creating xmobar in the first place, and for giving me the chance to contribute. -Useful links -============ +# Useful links - [Github page]. - [Mailing list]. @@ -1364,15 +1540,14 @@ Useful links [this tutorial]: http://www.haskell.org/haskellwiki/X_window_programming_in_Haskell [sawflibs]: http://github.com/jaor/sawflibs -License -======= +# License This software is released under a BSD-style license. See [LICENSE] for more details. -Copyright © 2007-2010 Andrea Rossato +Copyright © 2010-2013 Jose Antonio Ortega Ruiz -Copyright © 2010-2012 Jose Antonio Ortega Ruiz +Copyright © 2007-2010 Andrea Rossato [Github]: http://github.com/jaor/xmobar/ [Github page]: http://github.com/jaor/xmobar @@ -1395,3 +1570,4 @@ Copyright © 2010-2012 Jose Antonio Ortega Ruiz [alsa-mixer]: http://hackage.haskell.org/package/alsa-mixer [timezone-olson]: http://hackage.haskell.org/package/timezone-olson [timezone-series]: http://hackage.haskell.org/package/timezone-series +[libXpm]: http://cgit.freedesktop.org/xorg/lib/libXpm |