summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorAlexander Shabalin <shabalyn.a@gmail.com>2014-09-09 00:18:13 +0400
committerAlexander Shabalin <shabalyn.a@gmail.com>2014-09-14 12:34:30 +0400
commite26731b1fc292a16230f6517aa292dd3973929ae (patch)
tree7e9012fdb465074a051ef1e89cc86d197db6a5d4
parente590f14593728b8afc2b77e8be356e5c06428107 (diff)
downloadxmobar-e26731b1fc292a16230f6517aa292dd3973929ae.tar.gz
xmobar-e26731b1fc292a16230f6517aa292dd3973929ae.tar.bz2
Add documentation for DynamicStrings.
-rw-r--r--readme.md109
1 files changed, 77 insertions, 32 deletions
diff --git a/readme.md b/readme.md
index 2ddfb41..cb3b9cc 100644
--- a/readme.md
+++ b/readme.md
@@ -542,6 +542,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.
+### Dynamic Strings
+
+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", "<dstr>"
+ , "--"
+ , "--brightness-dynamic-string", "<icon=bright_%%.xpm/>"
+ ] 30
+
+Will display `bright_0.xpm` to `bright_8.xpm` depending on current brightness
+value.
### Default Monitor Arguments
@@ -693,33 +710,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-dynamic-string`: dynamic string for reception rate in `rxdstr`.
+ - `--tx-dynamic-string`: dynamic string for transmission rate in `txdstr`.
- 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 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.).
+ `dev`, `rx`, `tx`, `rxbar`, `rxvbar`, `rxdstr`, `txbar`, `txvbar`,
+ `txdstr`. 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-dynamic-string`: dynamic string for reception rate in `rxdstr`.
+ - `--tx-dynamic-string`: dynamic string for transmission rate in `txdstr`.
- 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`, `rxdstr`, `txbar`, `txvbar`,
+ `txdstr`. 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-dynamic-string`: dynamic string for connection quality in `qualitydstr`.
- Variables that can be used with the `-t`/`--template` argument:
- `essid`, `quality`, `qualitybar`, `qualityvbar`
+ `essid`, `quality`, `qualitybar`, `qualityvbar`, `qualitydstr`
- 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
@@ -728,10 +750,13 @@ something like:
### `Memory Args RefreshRate`
- Aliases to `memory`
-- Args: default monitor arguments
+- Args: default monitor arguments, plus:
+ - `--used-dynamic-string`: dynamic string for used memory ratio in `useddstr`.
+ - `--free-dynamic-string`: dynamic string for free memory ratio in `freedstr`.
- Variables that can be used with the `-t`/`--template` argument:
`total`, `free`, `buffer`, `cache`, `rest`, `used`,
- `usedratio`, `usedbar`, `usedvbar`, `freeratio`, `freebar`, `freevbar`
+ `usedratio`, `usedbar`, `usedvbar`, `useddstr`,
+ `freeratio`, `freebar`, `freevbar`, `freedstr`
- Default template: `Mem: <usedratio>% (<cache>M)`
### `Swap Args RefreshRate`
@@ -745,19 +770,24 @@ something like:
### `Cpu Args RefreshRate`
- Aliases to `cpu`
-- Args: default monitor arguments
+- Args: default monitor arguments, plus:
+ - `--load-dynamic-string`: dynamic string for cpu load in `dstr`.
- Variables that can be used with the `-t`/`--template` argument:
- `total`, `bar`, `vbar`, `user`, `nice`, `system`, `idle`, `iowait`
+ `total`, `bar`, `vbar`, `dstr`, `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-dynamic-string`: dynamic string for overall cpu load in `dstr`.
+ - `--load-dynamic-strings`: dynamic string for each cpu load in `autodstr`, `dstr{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`, `autodstr`, `autouser`, `autonice`,
+ `autosystem`, `autoidle`, `total`, `bar`, `vbar`, `dstr`, `user`, `nice`,
+ `system`, `idle`, `total0`, `bar0`, `vbar0`, `dstr0`, `user0`, `nice0`,
`system0`, `idle0`, ...
The auto* variables automatically detect the number of CPUs on the system
and display one entry for each.
@@ -788,9 +818,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-dynamic-string`: dynamic string for current battery charge
+ when AC is "on" in `leftdstr`.
+ - `--off-dynamic-string`: dynamic string for current battery charge
+ when AC is "off" in `leftdstr`.
+ - `--idle-dynamic-string`: dynamic string for current battery charge
+ when AC is "idle" in `leftdstr`.
- Variables that can be used with the `-t`/`--template` argument:
- `left`, `leftbar`, `leftvbar`, `timeleft`, `watts`, `acstatus`
+ `left`, `leftbar`, `leftvbar`, `leftdstr`, `timeleft`, `watts`, `acstatus`
- Default template: `Batt: <watts>, <left>% / <timeleft>`
- Example (note that you need "--" to separate regular monitor options from
Battery's specific ones):
@@ -863,10 +899,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>`, `<freedstr>`, `<usedbar>`,
+ `<usedvbar>` or `<useddstr>` 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-dynamic-string`: dynamic string for free disk space in `freedstr`.
+ - `--used-dynamic-string`: dynamic string for used disk space in `useddstr`.
- Default template: none (you must specify a template for each file system).
- Example:
@@ -880,9 +918,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>`, `<totaldstr>`,
+ `<readbar>`, `<readvbar>`, `<readdstr>`,
+ `<writebar>`, `<writevbar>`, and `<writedstr>`.
+- Args: default monitor arguments. `-t`/`--template` is ignored. Plus
+ - `--total-dynamic-string`: dynamic string for total disk I/O in `<totaldstr>`.
+ - `--write-dynamic-string`: dynamic string for write disk I/O in `<writedstr>`.
+ - `--read-dynamic-string`: dynamic string for read disk I/O in `<readdstr>`.
- Default template: none (you must specify a template for each file system).
- Example:
@@ -970,8 +1012,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-dynamic-string` _string_ dynamic string for current volume in `volumedstr`.
- Variables that can be used with the `-t`/`--template` argument:
- `volume`, `volumebar`, `volumevbar`, `dB`, `status`
+ `volume`, `volumebar`, `volumevbar`, `volumedstr`, `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>`
@@ -988,9 +1031,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-dynamic-string`: dynamic string for current track position in `dstr`.
- Variables that can be used with the `-t`/`--template` argument:
- `bar`, `vbar`, `state`, `statei`, `volume`, `length`,
+ `bar`, `vbar`, `dstr`, `state`, `statei`, `volume`, `length`,
`lapsed`, `remaining`,
`plength` (playlist length), `ppos` (playlist position),
`name`, `artist`, `composer`, `performer`,
@@ -1110,8 +1154,9 @@ more than one battery.
actual_brightness)
- `-M`: file with the maximum brightness (default:
max_brightness)
+ - `--brightness-dynamic-string`: dynamic string for current brightness in `dstr`.
- Variables that can be used with the `-t`/`--template` argument:
- `vbar`, `percent`, `bar`
+ `vbar`, `percent`, `bar`, `dstr`
- Default template: `<percent>`
- Example: