From e26731b1fc292a16230f6517aa292dd3973929ae Mon Sep 17 00:00:00 2001 From: Alexander Shabalin Date: Tue, 9 Sep 2014 00:18:13 +0400 Subject: Add documentation for DynamicStrings. --- readme.md | 109 ++++++++++++++++++++++++++++++++++++++++++++------------------ 1 file 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. `""` will be interpreted +as `""` 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", "" + , "--" + , "--brightness-dynamic-string", "" + ] 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: `: KB|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: `: KB|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: ` ` - 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: % (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: %` ### `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: , % / ` - 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 ``, ``, ``, `` or - ``, ``, ``, `` or `` for total, - free, used, free percentage and used percentage of the given file system - capacity. -- Args: default monitor arguments. `-t`/`--template` is ignored. + ``, ``, ``, ``, ``, + `` or `` 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 ``, ``, `` for total, read and write speed, respectively. There are also bar versions of each: - ``, ``, ``, ``, ``, and - ``. -- Args: default monitor arguments. `-t`/`--template` is ignored. + ``, ``, ``, + ``, ``, ``, + ``, ``, and ``. +- Args: default monitor arguments. `-t`/`--template` is ignored. Plus + - `--total-dynamic-string`: dynamic string for total disk I/O in ``. + - `--write-dynamic-string`: dynamic string for write disk I/O in ``. + - `--read-dynamic-string`: dynamic string for read disk I/O in ``. - 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: % ` @@ -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: `` - Example: -- cgit v1.2.3