diff options
Diffstat (limited to 'readme.md')
| -rw-r--r-- | readme.md | 176 |
1 files changed, 128 insertions, 48 deletions
@@ -11,7 +11,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.21 (see [release notes]). +This page documents xmobar 0.22.1 (see [release notes]). [This screenshot] shows xmobar running under [sawfish], with antialiased fonts. And [this one] is my desktop with [xmonad] and two @@ -124,6 +124,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. @@ -152,6 +156,10 @@ 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. @@ -195,7 +203,8 @@ 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 @@ -307,6 +316,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). @@ -360,6 +378,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 @@ -482,7 +501,9 @@ 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: @@ -536,6 +557,23 @@ 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 @@ -677,8 +715,9 @@ something like: - 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>)` - Retrieves weather information from http://weather.noaa.gov. @@ -686,33 +725,38 @@ something like: - 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`, `rxvbar`, `txbar`, `txvbar`. 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`, `rxvbar`, `txbar`, `txvbar`. 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, `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`, `qualityvbar` + `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 @@ -721,10 +765,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`, `usedvbar`, `freeratio`, `freebar`, `freevbar` + `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` @@ -738,19 +787,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`, `vbar`, `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`, `autovbar`, `autouser`, `autonice`, - `autosystem`, `autoidle`, `total`, `bar`, `vbar`, `user`, `nice`, - `system`, `idle`, `total0`, `bar0`, `vbar0`, `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. @@ -781,9 +835,15 @@ something like: - `-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`, `leftvbar`, `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): @@ -856,10 +916,12 @@ 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>`, `<freevbar>`, `<usedbar>` or `<usedvbar>` 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: @@ -873,9 +935,13 @@ more than one battery. - 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. There are also bar versions of each: - `<totalbar>`, `<totalvbar>`, `<readbar>`, `<readvbar>`, `<writebar>`, and - `<writevbar>`. -- Args: default monitor arguments. `-t`/`--template` is ignored. + `<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: @@ -963,8 +1029,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`, `volumevbar`, `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>` @@ -981,9 +1048,10 @@ 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`, `vbar`, `state`, `statei`, `volume`, `length`, + `bar`, `vbar`, `ipat`, `state`, `statei`, `volume`, `length`, `lapsed`, `remaining`, `plength` (playlist length), `ppos` (playlist position), `name`, `artist`, `composer`, `performer`, @@ -1103,8 +1171,9 @@ more than one battery. actual_brightness) - `-M`: file with the maximum brightness (default: max_brightness) + - `--brightness-icon-pattern`: dynamic string for current brightness in `ipat`. - Variables that can be used with the `-t`/`--template` argument: - `vbar`, `percent`, `bar` + `vbar`, `percent`, `bar`, `ipat` - Default template: `<percent>` - Example: @@ -1220,6 +1289,14 @@ can be used in the output template as `%mydate%` - Reads its displayed output from the given pipe. - Prefix an optional default text separated by a colon +<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> @@ -1408,16 +1485,18 @@ Andrea Rossato originally designed and implemented xmobar up to 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 Ben Boeckel, 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, Dmitry Malikov, David McLean, Marcin Mikołajczyk, Eric -Mrak, Thiago Negri, 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. +In particular, xmobar [incorporates patches] by Axel Angel, Ben +Boeckel, 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 @@ -1486,3 +1565,4 @@ Copyright © 2007-2010 Andrea Rossato [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 |