Skip to content

Latest commit

 

History

History
1597 lines (1181 loc) · 57.7 KB

plugins.org

File metadata and controls

1597 lines (1181 loc) · 57.7 KB
Raw

Plugins and monitors

System monitor plugins

This is the description of the system monitor plugins available in xmobar. Some of them are only installed when an optional build option is set: we mention that fact, when needed, in their description.

Each monitor has an alias to be used in the output template. Monitors may have default aliases, see the documentation of the monitor in question.

There are two types of arguments: ones that all monitors share (the so called default monitor arguments) and arguments that are specific to a certain monitor.

All Monitors accept a common set of arguments, described below in Default Monitor Arguments. Some monitors also 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. For example, the following Battery configuration first sets the global template and Low arguments and then specifies the battery-specific off option.

Run Battery
  [ "--template", "<acstatus>"
  , "--Low"     , "15"
  -- battery specific options start here.
  , "--"
  , "--off"     , "<left> (<timeleft>)"
  ]
  100

See also Interfacing with window managers below for a collection of plugins that let you interact and control xmobar from window managers.

Icon Patterns

Some monitors allow usage of strings that depend on some integer value from 0 to 8 by replacing all occurrences 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

These are the options available for all monitors:

  • -t string Output template
    • Template for the monitor output. Field names must be enclosed between pointy brackets (<foo>) and will be substituted by the computed values. You can also specify the foreground (and optionally, background) color for a region by bracketing it between <fc=fgcolor> (or <fc=fgcolor,bgcolor>) and </fc>. The rest of the template is output verbatim.
    • Long option: --template
    • Default value: per monitor (see above).
  • -H number The high threshold.
    • Numerical values higher than number will be displayed with the color specified by -h (see below).
    • Long option: --High
    • Default value: 66
  • -L number The low threshold.
    • Numerical values higher than number and lower than the high threshold will be displayed with the color specified by -n (see below). Values lower than number will use the -l color.
    • Long option: --Low
    • Default value: 33
  • -h color High threshold color.
    • Color for displaying values above the high threshold. color can be either a name (e.g. “blue”) or an hexadecimal RGB (e.g. “#FF0000”).
    • Long option: --high
    • Default: none (use the default foreground).
  • -n color Color for ‘normal’ values
    • Color used for values greater than the low threshold but lower than the high one.
    • Long option: --normal
    • Default: none (use the default foreground).
  • -l color The low threshold color
    • Color for displaying values below the low threshold.
    • Long option: --low
    • Default: none (use the default foreground).
  • -S boolean Display optional suffixes
    • When set to a true designator (“True”, “Yes” or “On”), optional value suffixes such as the ‘%’ symbol or optional units will be displayed.
    • Long option: --suffix
    • Default: False.
  • -p number Percentages padding
    • Width, in number of digits, for quantities representing percentages. For instance -p 3 means that all percentages in the monitor will be represented using 3 digits.
    • Long option: --ppad
    • Default value: 0 (don’t pad)
  • -d number Decimal digits
    • Number of digits after the decimal period to use in float values.
    • Long option: --ddigits
    • Default value: 0 (display only integer part)
  • -m number Minimum field width
    • Minimum width, in number of characters, of the fields in the monitor template. Values whose printed representation is shorter than this value will be padded using the padding characters given by the -c option with the alignment specified by -a (see below).
    • Long option: --minwidth
    • Default: 0
  • -M number Maximum field width
    • Maximum width, in number of characters, of the fields in the monitor template. Values whose printed representation is longer than this value will be truncated.
    • Long option: --maxwidth
    • Default: 0 (no maximum width)
  • -e string Maximum width ellipsis
    • Ellipsis to be added to the field when it has reached its max width.
    • Long option: --maxwidthellipsis
    • Default: “” (no ellipsis)
  • -w number Fixed field width
    • All fields will be set to this width, padding or truncating as needed.
    • Long option: --width
    • Default: 0 (variable width)
  • -T number Maximum total width
    • Maximum total width of the text.
    • Long option: --maxtwidth
    • Default: 0 (no limit)
  • -E string Maximum total width ellipsis
    • Ellipsis to be added to the total text when it has reached its max width.
    • Long option: --maxtwidthellipsis
    • Default: “” (no ellipsis)
  • -c string
    • Characters used for padding. The characters of string are used cyclically. E.g., with -P +- -w 6, a field with value “foo” will be represented as “+-+foo”.
    • Long option: --padchars
    • Default value: ” ”
  • -a r|l Field alignment
    • Whether to use right (r) or left (l) alignment of field values when padding.
    • Long option: --align
    • Default value: r (padding to the left)
  • -b string Bar background
    • Characters used, cyclically, to draw the background of bars. For instance, if you set this option to “·.”, an empty bar will look like this: ·.·.·.·.·.
    • Long option: --bback
    • Default value: “:”
  • -f string Bar foreground
    • Characters used, cyclically, to draw the foreground of bars.
    • Long option: --bfore
    • Default value: “#”
  • -W number Bar width
    • Total number of characters used to draw bars.
    • Long option: --bwidth
    • Default value: 10
    • Special value: 0. When this parameter is 0, the percentage to display is interpreted as a position in the bar foreground string (given by -f), and the character at that position is displayed.
  • -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.:

    Run Weather "EGPF" ["-t", "<station>: <tempC>C"] 36000

    In this case xmobar will run the weather monitor, getting information for the weather station ID EGPF (Glasgow Airport, as a homage to GHC) every hour (36000 tenth of seconds), with a template that will output something like:

    Glasgow Airport: 16.0C

Battery monitors

Battery Args RefreshRate

Same as

BatteryP ["BAT", "BAT0", "BAT1", "BAT2"] Args RefreshRate

BatteryP Dirs Args RefreshRate

  • Aliases to battery
  • Dirs: list of directories in /sys/class/power_supply/ where to look for the ACPI files of each battery. Example: ["BAT0","BAT1","BAT2"]. Only up to 3 existing directories will be searched.
  • Args: default monitor arguments, plus the following specific ones (these options, being specific to the monitor, are to be specified after a -- in the argument list):
    • -O: string for AC “on” status (default: “On”)
    • -i: string for AC “idle” status (default: “On”)
    • -o: string for AC “off” status (default: “Off”)
    • -L: low power (watts) threshold (default: 10)
    • -H: high power threshold (default: 12)
    • -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 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”)
    • -A: a number between 0 and 100, threshold below which the action given by -a, if any, is performed (default: 5)
    • -a: a string with a system command that is run when the percentage left in the battery is less or equal than the threshold given by the -A option. If not present, no action is undertaken.
    • -P: to include a percentage symbol in left.
    • --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.
    • --lows: string for AC “off” status and power lower than the -L threshold (default: “”)
    • --mediums: string for AC “off” status and power lower than the -H threshold (default: “”)
    • --highs: string for AC “off” status and power higher than the -H threshold (default: “”)
  • Variables that can be used with the -t/--template argument: 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): 
    Run BatteryP ["BAT0"]
             ["-t", "<acstatus><watts> (<left>%)",
              "-L", "10", "-H", "80", "-p", "3",
              "--", "-O", "<fc=green>On</fc> - ", "-i", "",
              "-L", "-15", "-H", "-5",
              "-l", "red", "-m", "blue", "-h", "green",
              "-a", "notify-send -u critical 'Battery running out!!'",
              "-A", "3"]
             600

    In the above example, the thresholds before the -- separator affect only the <left> and <leftbar> fields, while those after the separator affect how <watts> is displayed. For this monitor, neither the generic nor the specific options have any effect on <timeleft>. We are also telling the monitor to execute the unix command notify-send when the percentage left in the battery reaches 6%.

    It is also possible to specify template variables in the -O and -o switches, as in the following example:

    Run BatteryP ["BAT0"]
             ["-t", "<acstatus>"
             , "-L", "10", "-H", "80"
             , "-l", "red", "-h", "green"
             , "--", "-O", "Charging", "-o", "Battery: <left>%"
             ] 10
  • The “idle” AC state is selected whenever the AC power entering the battery is zero.

BatteryN Dirs Args RefreshRate Alias

Works like BatteryP, but lets you specify an alias for the monitor other than “battery”. Useful in case you one separate monitors for more than one battery.

Cpu and Memory monitors

Cpu Args RefreshRate

  • Aliases to cpu
  • Args: default monitor arguments, plus:
    • --load-icon-pattern: dynamic string for cpu load in ipat
  • Thresholds refer to percentage of CPU load
  • Variables that can be used with the -t/--template argument: total, bar, vbar, ipat, user, nice, system, idle, iowait
  • Default template: Cpu: <total>%

MultiCpu Args RefreshRate

  • Aliases to multicpu
  • 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.
    • --fallback-icon-pattern: dynamic string used by autoipat and ipat{i} when no --load-icon-patterns has been provided for cpu{i}
    • --contiguous-icons: flag (no value needs to be provided) that causes the load icons to be drawn without padding.
  • Thresholds refer to percentage of CPU load
  • Variables that can be used with the -t/--template argument: 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.
  • Default template: Cpu: <total>%

CpuFreq Args RefreshRate

  • Aliases to cpufreq
  • Args: default monitor arguments
  • Thresholds refer to frequency in GHz
  • Variables that can be used with the -t/--template argument: cpu0, cpu1, .., cpuN, give the current frequency of the respective CPU core, and max, min and avg the maximum, minimum and average frequency over all available cores.
  • Default template: Freq: <cpu0>GHz
  • This monitor requires acpi_cpufreq module to be loaded in kernel
  • Example: 
    Run CpuFreq ["-t", "Freq:<cpu0>|<cpu1>GHz", "-L", "0", "-H", "2",
             "-l", "lightblue", "-n","white", "-h", "red"] 50

Run CpuFreq ["-t", "Freq:<avg> GHz", "-L", "0", "-H", "2",
             "-l", "lightblue", "-n","white", "-h", "red"] 50

CoreTemp Args RefreshRate

  • Aliases to coretemp
  • Args: default monitor arguments
  • Thresholds refer to temperature in degrees
  • Variables that can be used with the -t/--template argument: core0, core1, .., coreN
  • Default template: Temp: <core0>C
  • This monitor requires coretemp module to be loaded in kernel
  • Example: 
    Run CoreTemp ["-t", "Temp:<core0>|<core1>C",
              "-L", "40", "-H", "60",
              "-l", "lightblue", "-n", "gray90", "-h", "red"] 50

MultiCoreTemp Args RefreshRate

  • Aliases to multicoretemp
  • Args: default monitor arguments, plus:
    • --max-icon-pattern: dynamic string for overall cpu load in maxipat.
    • --avg-icon-pattern: dynamic string for overall cpu load in avgipat.
    • --mintemp: temperature in degree Celsius, that sets the lower limit for percentage calculation.
    • --maxtemp: temperature in degree Celsius, that sets the upper limit for percentage calculation.
    • --hwmon-path: this monitor tries to find coretemp devices by looking for them in directories following the pattern /sys/bus/platform/devices/coretemp.*/hwmon/hwmon*, but some processors (notably Ryzen) might expose those files in a different tree (e.g., Ryzen) puts them somewhere in “/sys/class/hwmon/hwmon*”, and the lookup is most costly. With this option, it is possible to explicitly specify the full path to the directory where the tempN_label and tempN_input files are located.
  • Thresholds refer to temperature in degree Celsius
  • Variables that can be used with the -t/--template argument: max, maxpc, maxbar, maxvbar, maxipat, avg, avgpc, avgbar, avgvbar, avgipat, core0, core1, …, coreN

    The /pc, /bar, /vbar and /ipat variables are showing percentages on the scale defined by --mintemp and --maxtemp. The max* and avg* variables to the highest and the average core temperature.

  • Default template: Temp: <max>°C - <maxpc>%
  • This monitor requires coretemp module to be loaded in kernel
  • Example: 
    Run MultiCoreTemp ["-t", "Temp: <avg>°C | <avgpc>%",
                   "-L", "60", "-H", "80",
                   "-l", "green", "-n", "yellow", "-h", "red",
                   "--", "--mintemp", "20", "--maxtemp", "100"] 50

K10Temp Slot Args RefreshRate

  • Aliases to k10temp
  • Slot: The PCI slot address of the k10temp device as a string. You can find it as a subdirectory in /sys/bus/pci/drivers/k10temp/.
  • Args: default monitor arguments
  • Thresholds refer to temperature in degrees
  • Variables that can be used with the -t/--template argument: Tctl, Tdie, Tccd1, .., Tccd8
  • Default template: Temp: <Tdie>C
  • This monitor requires k10temp module to be loaded in kernel
  • It is important to note that not all measurements are available on on all models of processor. Of particular importance - Tdie (used in the default template) may not be present on processors prior to Zen (17h). Tctl, however, may be offset from the real temperature and so is not used by default.
  • Example: 
    Run K10Temp "0000:00:18.3"
            ["-t", "Temp: <Tdie>C|<Tccd1>C",
             "-L", "40", "-H", "60",
             "-l", "lightblue", "-n", "gray90", "-h", "red"]
            50

Memory Args RefreshRate

  • Aliases to memory
  • 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.
    • --scale: sizes (total, free, etc.) are reported in units of Mb/scale, with scale defaulting to 1.0. So, for instance, to get sizes reported in Gb, set this parameter to 1024.
  • Thresholds refer to percentage of used memory
  • Variables that can be used with the -t/--template argument: total, free, buffer, cache, available, used, usedratio, usedbar, usedvbar, usedipat, freeratio, freebar, freevbar, freeipat, availableratio, availablebar, availablevbar, availableipat
  • Default template: Mem: <usedratio>% (<cache>M)
  • Examples: 
    -- A monitor reporting memory used in Gb
Memory [ "-t", "<used> Gb", "--", "--scale", "1024"] 20
-- As above, but using one decimal digit to print numbers
Memory [ "-t", "<used> Gb", "-d", "1", "--", "--scale", "1024"] 20

Swap Args RefreshRate

  • Aliases to swap
  • Args: default monitor arguments
  • Thresholds refer to percentage of used swap
  • Variables that can be used with the -t/--template argument: total, used, free, usedratio
  • Default template: Swap: <usedratio>%

Date monitors

Date Format Alias RefreshRate

  • Format is a time format string, as accepted by the standard ISO C strftime function (or Haskell’s formatCalendarTime). Basically, if date +"my-string" works with your command then Date will handle it correctly.
  • Timezone changes are picked up automatically every minute.
  • Sample usage: 
    Run Date "%a %b %_d %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10

DateZone Format Locale Zone Alias RefreshRate

A variant of the Date monitor where one is able to explicitly set the time-zone, as well as the locale.

  • The format of DateZone is exactly the same as Date.
  • If Locale is "" (the empty string) the default locale of the system is used, otherwise use the given locale. If there are more instances of DateZone, using the empty string as input for Locale is not recommended.
  • Zone is the name of the TimeZone. It is assumed that the time-zone database is stored in /usr/share/zoneinfo/. If the empty string is given as Zone, the default system time is used.
  • Sample usage: 
    Run DateZone "%a %H:%M:%S" "de_DE.UTF-8" "Europe/Vienna" "viennaTime" 10

Disk monitors

DiskU Disks Args RefreshRate

  • 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>, <freeipat>, <usedbar>, <usedvbar> or <usedipat> for total, free, used, free percentage and used percentage of the given file system capacity.
  • Thresholds refer to usage percentage.
  • 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"]
      20

DiskIO Disks Args RefreshRate

  • 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, as well as <totalb>, <readb>, <writeb>, which report number of bytes during the last refresh period rather than speed. There are also bar versions of each: <totalbar>, <totalvbar>, <totalipat>, <readbar>, <readvbar>, <readipat>, <writebar>, <writevbar>, and <writeipat>; and their “bytes” counterparts: <totalbbar>, <totalbvbar>, <totalbipat>, <readbbar>, <readbvbar>, <readbipat>, <writebbar>, <writebvbar>, and <writebipat>.
  • Thresholds refer to speed in b/s
  • 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: 
    DiskIO [("/", "<read> <write>"), ("sdb1", "<total>")] [] 10

Keyboard and screen monitors

Kbd Opts

  • Registers to XKB/X11-Events and output the currently active keyboard layout. Supports replacement of layout names.
  • Aliases to kbd
  • 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: 
    Run Kbd [("us(dvorak)", "DV"), ("us", "US")]

Brightness Args RefreshRate

  • Aliases to bright
  • Args: default monitor arguments, plus the following specif ones:
    • -D: directory in /sys/class/backlight/ with files in it (default: “acpi_video0”)
    • -C: file with the current brightness (default: 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, ipat
  • Default template: <percent>
  • Example: 
    Run Brightness ["-t", "<bar>"] 60

Locks

  • Displays the status of Caps Lock, Num Lock and Scroll Lock.
  • Aliases to locks
  • Example: 
    Run Locks

Load and Process monitors

Load Args RefreshRate

  • Aliases to load
  • Args: default monitor arguments. The low and high thresholds (-L and -H) refer to load average values.
  • Variables that can be used with the -t/--template argument: load1, load5, load15.
  • Default template: Load: <load1>.
  • Displays load averages for the last 1, 5 or 15 minutes as reported by, e.g., uptime(1). The displayed values are float, so that the "-d" option will control how many decimal digits are shown (zero by default).
  • Example: to have 2 decimal digits displayed, with a low threshold at 1.0 and a high one at 3, you’d write something like: 
    Run Load ["-t" , "<load1> <load5> <load15>"
         , "-L", "1", "-H", "3", "-d", "2"]) 300

TopProc Args RefreshRate

  • Aliases to top
  • Args: default monitor arguments. The low and high thresholds (-L and -H) denote, for memory entries, the percent of the process memory over the total amount of memory currently in use and, for cpu entries, the activity percentage (i.e., the value of cpuN, which takes values between 0 and 100).
  • Variables that can be used with the -t/--template argument: no, name1, cpu1, both1, mname1, mem1, mboth1, name2, cpu2, both2, mname2, mem2, mboth2, …
  • Default template: <both1>
  • Displays the name and cpu/mem usage of running processes (bothn and mboth display both, and is useful to specify an overall maximum and/or minimum width, using the -m/-M arguments. no gives the total number of processes.

TopMem Args RefreshRate

  • Aliases to topmem
  • Args: default monitor arguments. The low and high thresholds (-L and -H) denote the percent of the process memory over the total amount of memory currently in use.
  • Variables that can be used with the -t/--template argument: name1, mem1, both1, name2, mem2, both2, …
  • Default template: <both1>
  • Displays the name and RSS (resident memory size) of running processes (bothn displays both, and is useful to specify an overall maximum and/or minimum width, using the -m/-M arguments.

Thermal monitors

ThermalZone Number Args RefreshRate

  • Aliases to “thermaln”: so ThermalZone 0 [] can be used in template as %thermal0%
  • Thresholds refer to temperature in degrees
  • Args: default monitor arguments
  • Variables that can be used with the -t/--template argument: temp
  • Default template: <temp>C
  • 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).
  • Example: 
    Run ThermalZone 0 ["-t","<id>: <temp>C"] 30

Thermal Zone Args RefreshRate

  • This plugin is deprecated. Use =ThermalZone= instead.
  • Aliases to the Zone: so Thermal "THRM" [] can be used in template as %THRM%
  • Args: default monitor arguments
  • Thresholds refer to temperature in degrees
  • Variables that can be used with the -t/--template argument: temp
  • Default template: Thm: <temp>C
  • This plugin works only on systems with devices having thermal zone. Check directories in /proc/acpi/thermal_zone for possible values.
  • Example: 
    Run Thermal "THRM" ["-t","iwl4965-temp: <temp>C"] 50

Volume monitors

Volume Mixer Element Args RefreshRate

  • Aliases to the mixer name and element name separated by a colon. Thus, Volume "default" "Master" [] 10 can be used as %default:Master%.
  • Args: default monitor arguments. Also accepts:
    • -O string On string
      • The string used in place of <status> when the mixer element is on. Defaults to “[on]”.
      • Long option: --on
    • -o string Off string
      • The string used in place of <status> when the mixer element is off. Defaults to “[off]”.
      • Long option: --off
    • -C color On color
      • The color to be used for <status> when the mixer element is on. Defaults to “green”.
      • Long option: --onc
    • -c color Off color
      • The color to be used for <status> when the mixer element is off. Defaults to “red”.
      • 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.
    • -H number High threshold for volume (in %). Defaults to 60.0.
      • Long option: --highv
    • -L number Low threshold for volume (in %). Defaults to 20.0.
      • Long option: --lowv
    • -h: string High string
      • The string added in front of <status> when the mixer element is on and the volume percentage is higher than the -H threshold. Defaults to “”.
      • Long option: --highs
    • -m: string Medium string
      • The string added in front of <status> when the mixer element is on and the volume percentage is lower than the -H threshold. Defaults to “”.
      • Long option: --mediums
    • -l: string Low string
      • The string added in front of <status> when the mixer element is on and the volume percentage is lower than the -L threshold. Defaults to “”.
      • Long option: --lows
  • Variables that can be used with the -t/--template argument: volume, volumebar, volumevbar, volumeipat, dB, status, volumestatus
  • 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>
  • Requires the package alsa-core and alsa-mixer installed in your system. In addition, to activate this plugin you must pass the with_alsa flag during compilation.

Alsa Mixer Element Args

Like Volume but with the following differences:

  • Uses event-based refreshing via alsactl monitor instead of polling, so it will refresh instantly when there’s a volume change, and won’t use CPU until a change happens.
  • Aliases to alsa: followed by the mixer name and element name separated by a colon. Thus, Alsa "default" "Master" [] can be used as %alsa:default:Master%.
  • Additional options (after the --):
    • --alsactl=/path/to/alsactl: If this option is not specified, alsactl will be sought in your PATH first, and failing that, at /usr/sbin/alsactl (this is its location on Debian systems. alsactl monitor works as a non-root user despite living in /usr/sbin.).
    • stdbuf (from coreutils) must be (and most probably already is) in your PATH.

Mail monitors

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 hinotify package. To activate, pass the with_inotify flag during compilation.
  • Example: 
    Run Mail [("inbox", "~/var/mail/inbox"),
          ("lists", "~/var/mail/lists")]
         "mail"

MailX Args Opts Alias

  • Args: list of maildirs in form [("name1","path1","color1"),...]. Paths may start with a ‘~’ to expand to the user’s home directory. When mails are present, counts are displayed with the given name and color.
  • Opts is a possibly empty list of options, as flags. Possible values: -d dir –dir dir a string giving the base directory where maildir files with a relative path live. -p prefix –prefix prefix a string giving a prefix for the list of displayed mail counts -s suffix –suffix suffix a string giving a suffix for the list of displayed mail counts
  • This plugin requires inotify support in your Linux kernel and the hinotify package. To activate, pass the with_inotify flag during compilation.
  • Example: 
    Run MailX [("I", "inbox", "green"),
           ("L", "lists", "orange")]
          ["-d", "~/var/mail", "-p", " ", "-s", " "]
          "mail"

MBox Mboxes Opts Alias

  • Mboxes a list of mbox files of the form [("name", "path", "color")], where name is the displayed name, path the absolute or relative (to BaseDir) path of the mbox file, and color the color to use to display the mail count (use an empty string for the default).
  • Opts is a possibly empty list of options, as flags. Possible values: -a –all (no arg) Show all mailboxes, even if empty. -u (no arg) Show only the mailboxes’ names, sans counts. -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 counts -s suffix –suffix suffix a string giving a suffix for the list 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 hinotify package. To activate, pass the with_inotify flag during compilation.
  • Example. The following command look for mails in /var/mail/inbox and ~/foo/mbox, and will put a space in front of the printed string (when it’s not empty); it can be used in the template with the alias mbox: 
    Run MBox [("I ", "inbox", "red"), ("O ", "~/foo/mbox", "")]
         ["-d", "/var/mail/", "-p", " "] "mbox"

NotmuchMail Alias Args Rate

This plugin checks for new mail, provided that this mail is indexed by notmuch. In the notmuch spirit, this plugin checks for new threads and not new individual messages.

  • Alias: What name the plugin should have in your template string.
  • Args: A list of MailItem s of the form 
    [ MailItem "name" "address" "query"
...
]

    where

    • name is what gets printed in the status bar before the number of new threads.
    • address is the e-mail address of the recipient, i.e. we only query mail that was send to this particular address (in more concrete terms, we pass the address to the to: constructor when performing the search). If address is empty, we search through all unread mail, regardless of whom it was sent to.
    • query is funneled to notmuch search verbatim. For the general query syntax, consult notmuch search --help, as well as notmuch-search-terms(7). Note that the unread tag is always added in front of the query and composed with it via an and.
  • Rate: Rate with which to update the plugin (in deciseconds).
  • Example:
    • A single MailItem that displays all unread threads from the given address: 
      MailItem "mbs:" "[email protected]" ""
    • A single MailItem that displays all unread threads with “[My-Subject]” somewhere in the title: 
      MailItem "S:" "" "subject:[My-Subject]"
    • A full example of a NotmuchMail configuration: 
      Run NotmuchMail "mail"  -- name for the template string
  [ -- All unread mail to the below address, but nothing that's tagged
    -- with @lists@ or @haskell@.
    MailItem "mbs:"
             "[email protected]"
             "not tag:lists and not tag:haskell"

    -- All unread mail that has @[Haskell-Cafe]@ in the subject line.
  , MailItem "C:" "" "subject:[Haskell-Cafe]"

    -- All unread mail that's tagged as @lists@, but not @haskell@.
  , MailItem "H:" "" "tag:lists and not tag:haskell"
  ]
  600                   -- update every 60 seconds

Music monitors

MPD Args RefreshRate

  • This monitor will only be compiled if you ask for it using the with_mpd flag. It needs libmpd 5.0 or later (available on Hackage).
  • Aliases to mpd
  • Args: default monitor arguments. In addition you can provide -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, unless given in the additional arguments -p (--port) and -h (--host). 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, ipat, state, statei, volume, length, lapsed, remaining, plength (playlist length), ppos (playlist position), flags (ncmpcpp-style playback mode), name, artist, composer, performer, album, title, track, file, genre, date
  • 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> [<flags>]",
         "--", "-P", ">>", "-Z", "|", "-S", "><"] 10

MPDX Args RefreshRate Alias

Like MPD but uses as alias its last argument instead of “mpd”.

Mpris1 PlayerName Args RefreshRate

  • Aliases to mpris1
  • Requires dbus and text packages. To activate, pass the with_mpris flag during compilation.
  • PlayerName: player supporting MPRIS v1 protocol. Some players need this to be an all lowercase name (e.g. “spotify”), but some others don’t.
  • Args: default monitor arguments.
  • Variables that can be used with the -t/--template argument: album, artist, arturl, length, title, tracknumber
  • Default template: <artist> - <title>
  • Example: 
    Run Mpris1 "clementine" ["-t", "<artist> - [<tracknumber>] <title>"] 10

Mpris2 PlayerName Args RefreshRate

  • Aliases to mpris2
  • Requires dbus and text packages. To activate, pass the with_mpris flag during compilation.
  • PlayerName: player supporting MPRIS v2 protocol. Some players need this to be an all lowercase name (e.g. “spotify”), but some others don’t.
  • Args: default monitor arguments.
  • Variables that can be used with the -t/--template argument: album, artist, arturl, length, title, tracknumber, composer, genre
  • Default template: <artist> - <title>
  • Example: 
    Run Mpris2 "spotify" ["-t", "<artist> - [<composer>] <title>"] 10

Network monitors

Network Interface Args RefreshRate

  • Aliases to the interface name: so Network "eth0" [] can be used as %eth0%
  • Thresholds refer to velocities expressed in B/s
  • 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.
    • --up: string used for the up variable value when the interface is up.
  • Variables that can be used with the -t=/–template= argument: dev, rx, tx, rxbar, rxvbar, rxipat, txbar, txvbar, txipat, up. 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”
  • Thresholds are expressed in B/s
  • 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
  • --devices: comma-separated list of devices to show.
  • Variables that can be used with the -t=/–template= argument: 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
    • Example of usage of --devices option:

      ["--", "--devices", "wlp2s0,enp0s20f41"]

Wireless Interface Args RefreshRate

  • If set to “”, first suitable wireless interface is used.
  • Aliases to the interface name with the suffix “wi”: thus, Wireless "wlan0" [] can be used as %wlan0wi%, and Wireless "" [] as %wi%.
  • 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: ssid, signal, quality, qualitybar, qualityvbar, qualityipat
  • Thresholds refer to link quality on a [0, 100] scale. Note that quality is calculated from signal (in dBm) by a possibly lossy conversion. It is also not taking into account many factors such as noise level, air busy time, transcievers’ capabilities and the others which can have drastic impact on the link performance.
  • Default template: <ssid> <quality>
  • To activate this plugin you must pass the with_nl80211 or the with_iwlib flag during compilation.

Weather monitors

Weather StationID Args RefreshRate

  • Aliases to the Station ID: so Weather "LIPB" [] can be used in template as %LIPB%
  • Thresholds refer to temperature in the selected units
  • Args: default monitor arguments, plus:
    • --weathers string : display a default string when the weather variable is not reported.
      • short option: -w
      • Default: “”
    • --useManager bool : Whether to use one single manager per monitor for managing network connections or create a new one every time a connection is made.
      • Short option: -m
      • Default: True
  • Variables that can be used with the -t/--template argument: station, stationState, year, month, day, hour, windCardinal, windAzimuth, windMph, windKnots, windMs, windKmh visibility, skyCondition, weather, tempC, tempF, dewPointC, dewPointF, rh, pressure
  • Default template: <station>: <tempC>C, rh <rh>% (<hour>)
  • Retrieves weather information from http://tgftp.nws.noaa.gov. Here is an example, also showcasing the kind of information that may be extracted. Here is a sample list of station IDs.

WeatherX StationID SkyConditions Args RefreshRate

  • Works in the same way as Weather, but takes an additional argument, a list of pairs from sky conditions to their replacement (typically a unicode string or an icon specification).
  • Use the variable skyConditionS to display the replacement of the corresponding sky condition. All other Weather template variables are available as well.

    For example:

    WeatherX "LEBL"
         [ ("clear", "🌣")
         , ("sunny", "🌣")
         , ("mostly clear", "🌤")
         , ("mostly sunny", "🌤")
         , ("partly sunny", "⛅")
         , ("fair", "🌑")
         , ("cloudy","☁")
         , ("overcast","☁")
         , ("partly cloudy", "⛅")
         , ("mostly cloudy", "🌧")
         , ("considerable cloudiness", "⛈")]
         ["-t", "<fn=2><skyConditionS></fn> <tempC>° <rh>%  <windKmh> (<hour>)"
         , "-L","10", "-H", "25", "--normal", "black"
         , "--high", "lightgoldenrod4", "--low", "darkseagreen4"]
         18000

    As mentioned, the replacement string can also be an icon specification, such as ("clear", "<icon=weather-clear.xbm/>").

UVMeter

  • Aliases to “uv” + station id. For example: %uv Brisbane% or %uv Alice Springs%
  • Args: default monitor arguments, plus:
    • --useManager bool : Whether to use one single manager per monitor for managing network connections or create a new one every time a connection is made.
      • Short option: -m
      • Default: True
  • Reminder: Keep the refresh rate high, to avoid making unnecessary requests every time the plug-in is run.
  • Station IDs can be found here: http://www.arpansa.gov.au/uvindex/realtime/xml/uvvalues.xml
  • Example: 
    Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900

Other monitors

CatInt n filename

  • Reads and displays an integer from the file whose path is filename (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

CommandReader "/path/to/program" Alias

  • Runs the given program, and displays its standard output.

Uptime Args RefreshRate

  • Aliases to uptime
  • Args: default monitor arguments. The low and high thresholds refer to the number of days.
  • Variables that can be used with the -t/--template argument: days, hours, minutes, seconds. The total uptime is the sum of all those fields. You can set the -S argument to True to add units to the display of those numeric fields.
  • Default template: Up: <days>d <hours>h <minutes>m

Interfacing with window managers

Property-based logging

XMonadLog

  • Aliases to XMonadLog
  • Displays information from xmonad’s _XMONAD_LOG. You can use this by using functions from the XMonad.Hooks.DynamicLog module. By using the xmonadPropLog function in your logHook, you can write the the above property. The following shows a minimal xmonad configuration that spawns xmobar and then writes to the _XMONAD_LOG property. 
    main = do
  spawn "xmobar"
  xmonad $ def
    { logHook = dynamicLogString defaultPP >>= xmonadPropLog
    }

    This plugin can be used as a sometimes more convenient alternative to StdinReader. For instance, it allows you to (re)start xmobar outside xmonad.

UnsafeXMonadLog

  • Aliases to UnsafeXMonadLog
  • Displays any text received by xmobar on the _XMONAD_LOG atom.
  • Will not do anything to the text received. This means you can pass xmobar dynamic actions. Be careful to escape (using <raw=…>) or remove tags from dynamic text that you pipe through to xmobar in this way.
  • Sample usage: Send the list of your workspaces, enclosed by actions tags, to xmobar. This enables you to switch to a workspace when you click on it in xmobar! 
    <action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action>
  • If you use xmonad, It is advised that you still use xmobarStrip for the ppTitle in your logHook: 
    myPP = defaultPP { ppTitle = xmobarStrip }
main = xmonad $ def
  { logHook = dynamicLogString myPP >>= xmonadPropLog
  }

XPropertyLog PropName

  • Aliases to PropName
  • Reads the X property named by PropName (a string) and displays its value. The examples/xmonadpropwrite.hs script in xmobar’s distribution can be used to set the given property from the output of any other program or script.

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

  • Aliases to Alias
  • Same as XPropertyLog but a custom alias can be specified.

UnsafeNamedXPropertyLog PropName Alias

  • Aliases to Alias
  • Same as UnsafeXPropertyLog, but a custom alias can be specified.

Logging via Stdin

StdinReader

  • 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.

UnsafeStdinReader

  • Aliases to UnsafeStdinReader
  • Displays any text received by xmobar on its standard input.
  • Similar to UnsafeXMonadLog, in the sense that it does not strip any actions from the received text, only using stdin and not a property atom of the root window. Please be equally carefully when using this as when using UnsafeXMonadLog!

Pipe-based logging

PipeReader "default text:/path/to/pipe" Alias

  • Reads its displayed output from the given pipe.
  • Prefix an optional default text separated by a colon
  • Expands environment variables in the first argument of syntax ${VAR} or $VAR

MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias

  • 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"
  • Expands environment variables in the first argument

BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]

  • 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 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.

  • Take a look at examples/status.sh
  • Expands environment variables for the pipe path

Handle-based logging

HandleReader Handle Alias

  • Display data from a Haskell Handle
  • This plugin is only useful if you are running xmobar from another Haskell program like XMonad.
  • You can use System.Process.createPipe to create a pair of read & write Handles. Pass the read Handle to HandleReader and write your output to the write Handle: 
    (readHandle, writeHandle) <- createPipe
xmobarProcess <- forkProcess $ xmobar myConfig
        { commands =
            Run (HandleReader readHandle "handle") : commands myConfig
        }
hPutStr writeHandle "Hello World"

Software Transactional Memory

When invoking xmobar from other Haskell code it can be easier and more performant to use shared memory. The following plugins leverage Control.Concurrent.STM to realize these gains for xmobar.

QueueReader (TQueue a) (a -> String) String

  • Display data from a Haskell TQueue a.
  • This plugin is only useful if you are running xmobar from another haskell program like xmonad.
  • You should make an IO safe TQueue a with Control.Concurrent.STM.newTQueueIO. Write to it from the user code with writeTQueue, and read with readTQueue. A common use is to overwite ppOutput from XMonad.Hooks.DynamicLog as shown below. 
    main :: IO ()
main = do
  initThreads
  q <- STM.newTQueueIO @String
  bar <- forkOS $ xmobar myConf
    { commands = Run (QueueReader q id "XMonadLog") : commands myConf }
  xmonad $ def { logHook = logWorkspacesToQueue q }

logWorkspacesToQueue :: STM.TQueue String -> X ()
logWorkspacesToQueue q =
  dynamicLogWithPP def { ppOutput = STM.atomically . STM.writeTQueue q }

    Note that xmonad uses blocking Xlib calls in its event loop and isn’t normally compiled with the threaded RTS so an xmobar thread running inside xmonad will suffer from delayed updates. It is thus necessary to enable -threaded when compiling xmonad configuration (xmonad.hs), e.g. by using a custom ~/.xmonad/build script.

Executing external commands

In order to execute an external command you can either write the command name in the template, in this case it will be executed without arguments, or you can configure it in the “commands” configuration option list with the Com template command:

Com ProgramName Args Alias RefreshRate

  • ProgramName: the name of the program
  • Args: the arguments to be passed to the program at execution time
  • RefreshRate: number of tenths of second between re-runs of the command. A zero or negative rate means that the command will be executed only once.
  • Alias: a name to be used in the template. If the alias is en empty string the program name can be used in the template.

E.g.:

Run Com "uname" ["-s","-r"] "" 0

can be used in the output template as %uname% (and xmobar will call uname only once), while

Run Com "date" ["+\"%a %b %_d %H:%M\""] "mydate" 600

can be used in the output template as %mydate%.

Sometimes, you don’t mind if the command executed exits with an error, or you might want to display a custom message in that case. To that end, you can use the ComX variant:

ComX ProgramName Args ExitMessage Alias RefreshRate

Works like Com, but displaying ExitMessage (a string) if the execution fails. For instance:

Run ComX "date" ["+\"%a %b %_d %H:%M\""] "N/A" "mydate" 600

will display “N/A” if for some reason the date invocation fails.