diff options
Diffstat (limited to 'doc/plugins.org')
| -rw-r--r-- | doc/plugins.org | 1621 |
1 files changed, 1621 insertions, 0 deletions
diff --git a/doc/plugins.org b/doc/plugins.org new file mode 100644 index 0000000..f4d0754 --- /dev/null +++ b/doc/plugins.org @@ -0,0 +1,1621 @@ +#+OPTIONS: toc:t + +* 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 +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 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, + +#+begin_src haskell + Run Brightness + [ "-t", "<ipat>" + , "--" + , "--brightness-icon-pattern", "<icon=bright_%%.xpm/>" + ] 30 +#+end_src + +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 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. + +These are the options available for all monitors below: + +- =-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.: + +#+begin_src haskell + Run Weather "EGPF" ["-t", "<station>: <tempC>C"] 36000 +#+end_src + +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: + +#+begin_src shell + Glasgow Airport: 16.0C +#+end_src + +** =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= + +** =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 [[https://tgftp.nws.noaa.gov/data/observations/metar/decoded/CYLD.TXT][example]], also showcasing the kind of information that may be + extracted. + +** =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: + +#+begin_src haskell + 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 +#+end_src + +As mentioned, the replacement string can also be an icon specification, +such as =("clear", "<icon=weather-clear.xbm/>")=. + +** =Network Interface Args RefreshRate= + +- Aliases to the interface name: so =Network "eth0" []= can be used as + =%eth0%= +- Thresholds refer to velocities expressed in Kb/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 Kb/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. + +** =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=. + +- 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)= + +** =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>%= + +** =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>%= + +** =Battery Args RefreshRate= + +- Same as + + #+begin_src haskell + BatteryP ["BAT", "BAT0", "BAT1", "BAT2"] Args RefreshRate + #+end_src + +** =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): + + #+begin_src haskell + 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 + #+end_src + + 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: + + #+begin_src haskell + Run BatteryP ["BAT0"] + ["-t", "<acstatus>" + , "-L", "10", "-H", "80" + , "-l", "red", "-h", "green" + , "--", "-O", "Charging", "-o", "Battery: <left>%" + ] 10 + #+end_src + +- 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. + +** =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. + +** =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: + + #+begin_src haskell + Run Date "%a %b %_d %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10 + #+end_src + +** =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: + + #+begin_src haskell + Run DateZone "%a %H:%M:%S" "de_DE.UTF-8" "Europe/Vienna" "viennaTime" 10 + #+end_src + +** =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: + + #+begin_src haskell + DiskU [("/", "<used>/<size>"), ("sdb1", "<usedbar>")] + ["-L", "20", "-H", "50", "-m", "1", "-p", "3"] + 20 + #+end_src + +** =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: + + #+begin_src haskell + DiskIO [("/", "<read> <write>"), ("sdb1", "<total>")] [] 10 + #+end_src + +** =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: + + #+begin_src haskell + Run ThermalZone 0 ["-t","<id>: <temp>C"] 30 + #+end_src + +** =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: + + #+begin_src haskell + Run Thermal "THRM" ["-t","iwl4965-temp: <temp>C"] 50 + #+end_src + +** =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= + +- Default template: =Freq: <cpu0>GHz= + +- This monitor requires acpi_cpufreq module to be loaded in kernel + +- Example: + + #+begin_src haskell + Run CpuFreq ["-t", "Freq:<cpu0>|<cpu1>GHz", "-L", "0", "-H", "2", + "-l", "lightblue", "-n","white", "-h", "red"] 50 + #+end_src + +** =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: + + #+begin_src haskell + Run CoreTemp ["-t", "Temp:<core0>|<core1>C", + "-L", "40", "-H", "60", + "-l", "lightblue", "-n", "gray90", "-h", "red"] 50 + #+end_src + +** =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. + - =--hwmonitor-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: + + #+begin_src haskell + Run MultiCoreTemp ["-t", "Temp: <avg>°C | <avgpc>%", + "-L", "60", "-H", "80", + "-l", "green", "-n", "yellow", "-h", "red", + "--", "--mintemp", "20", "--maxtemp", "100"] 50 + #+end_src + +** =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 [[http://hackage.haskell.org/package/alsa-core][alsa-core]] and [[http://hackage.haskell.org/package/alsa-mixer][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 Mixer Element Args RefreshRate=][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=. + +** =MPD Args RefreshRate= + +- This monitor will only be compiled if you ask for it using the + =with_mpd= flag. It needs [[http://hackage.haskell.org/package/libmpd/][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): + + #+begin_src haskell + Run MPD ["-t", + "<composer> <title> (<album>) <track>/<plength> <statei> [<flags>]", + "--", "-P", ">>", "-Z", "|", "-S", "><"] 10 + #+end_src + +** =MPDX Args RefreshRate Alias= + +Like =MPD= but uses as alias its last argument instead of "mpd". + +** =Mpris1 PlayerName Args RefreshRate= + +- Aliases to =mpris1= + +- Requires [[http://hackage.haskell.org/package/dbus][dbus]] and [[http://hackage.haskell.org/package/text][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: + + #+begin_src haskell + Run Mpris1 "clementine" ["-t", "<artist> - [<tracknumber>] <title>"] 10 + #+end_src + +** =Mpris2 PlayerName Args RefreshRate= + +- Aliases to =mpris2= + +- Requires [[http://hackage.haskell.org/package/dbus][dbus]] and [[http://hackage.haskell.org/package/text][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: + + #+begin_src haskell + Run Mpris2 "spotify" ["-t", "<artist> - [<composer>] <title>"] 10 + #+end_src + +** =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 + [[http://hackage.haskell.org/package/hinotify/][hinotify]] package. To activate, pass the =with_inotify= flag during + compilation. + +- Example: + + #+begin_src haskell + Run Mail [("inbox", "~/var/mail/inbox"), + ("lists", "~/var/mail/lists")] + "mail" + #+end_src + +** =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 + [[http://hackage.haskell.org/package/hinotify/][hinotify]] package. To activate, pass the =with_inotify= flag during + compilation. + +- Example: + + #+begin_src haskell + Run MailX [("I", "inbox", "green"), + ("L", "lists", "orange")] + ["-d", "~/var/mail", "-p", " ", "-s", " "] + "mail" + #+end_src + +** =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 + [[http://hackage.haskell.org/package/hinotify/][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=: + + #+begin_src haskell + Run MBox [("I ", "inbox", "red"), ("O ", "~/foo/mbox", "")] + ["-d", "/var/mail/", "-p", " "] "mbox" + #+end_src + +** =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 + + #+begin_src haskell + [ MailItem "name" "address" "query" + ... + ] + #+end_src + + or, using explicit record syntax: + + #+begin_src haskell + [ MailItem + { name = "name" + , address = "address" + , query = "query" + } + ... + ] + #+end_src + + 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: + + #+begin_src haskell + MailItem "mbs:" "soliditsallgood@mailbox.org" "" + #+end_src + + - A single =MailItem= that displays all unread threads with + "[My-Subject]" somewhere in the title: + + #+begin_src haskell + MailItem "S:" "" "subject:[My-Subject]" + #+end_src + + - A full example of a =NotmuchMail= configuration: + + #+begin_src haskell + 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:" + "soliditsallgood@mailbox.org" + "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 + #+end_src + +** =XPropertyLog PropName= + +- Aliases to =PropName= +- Reads the X property named by =PropName= (a string) and displays its + value. The [[https://github.com/jaor/xmobar/raw/master/examples/xmonadpropwrite.hs][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. + +** =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: + + #+begin_src haskell + Run Brightness ["-t", "<bar>"] 60 + #+end_src + +** =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: + + #+begin_src haskell + Run Kbd [("us(dvorak)", "DV"), ("us", "US")] + #+end_src + +** =Locks= + +- Displays the status of Caps Lock, Num Lock and Scroll Lock. + +- Aliases to =locks= + +- Example: + + #+begin_src haskell + Run Locks + #+end_src + +** =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: + + #+begin_src haskell + Run CatInt 0 "/sys/devices/platform/thinkpad_hwmon/fan1_input" [] 50 + #+end_src + +** =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: + + #+begin_src haskell + Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900 + #+end_src + +* Interfacing with Window Managers + +Listed below are ways to interface xmobar with your window manager of +choice. + +** =XMonadLog= + +- Aliases to XMonadLog + +- Displays information from xmonad's =_XMONAD_LOG=. You can use this by + using functions from the [[https://hackage.haskell.org/package/xmonad-contrib-0.16/docs/XMonad-Hooks-DynamicLog.html][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. + + #+begin_src haskell + main = do + spawn "xmobar" + xmonad $ def + { logHook = dynamicLogString defaultPP >>= xmonadPropLog + } + #+end_src + + This plugin can be used as a sometimes more convenient alternative to + =StdinReader=. For instance, it allows you to (re)start xmobar outside + xmonad. + +** =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. +- Will not do anything to the text received. This means you can pass + dynamic actions via stdin. Be careful to escape (using =<raw=…>=) or + remove tags from dynamic text that you pipe-thru to xmobar's standard + input, e.g. window's title. +- 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: + + #+begin_src shell + <action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action> + #+end_src + +** =UnsafeXMonadLog= + +- 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: + + #+begin_src haskell + myPP = defaultPP { ppTitle = xmobarStrip } + main = xmonad $ def + { logHook = dynamicLogString myPP >>= xmonadPropLog + } + #+end_src + +** =CommandReader "/path/to/program" Alias= + +- Runs the given program, and displays its standard output. + +** =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 + + #+begin_src haskell + Run MarqueePipeReader "/tmp/testpipe" (10, 7, "+") "mpipe" + #+end_src + +- 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: + + #+begin_src haskell + Run BufferedPipeReader "bpr" + [ ( 0, False, "/tmp/xmobar_window" ) + , ( 15, True, "/tmp/xmobar_status" ) + ] + #+end_src + + 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 [[http://github.com/jaor/xmobar/raw/master/examples/status.sh][examples/status.sh]] + +- Expands environment variables for the pipe path + +** =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: + + #+begin_src haskell + (readHandle, writeHandle) <- createPipe + xmobarProcess <- forkProcess $ xmobar myConfig + { commands = + Run (HandleReader readHandle "handle") : commands myConfig + } + hPutStr writeHandle "Hello World" + #+end_src + +* 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.: + +#+begin_src haskell + Run Com "uname" ["-s","-r"] "" 0 +#+end_src + +can be used in the output template as =%uname%= (and xmobar will call +/uname/ only once), while + +#+begin_src haskell + Run Com "date" ["+\"%a %b %_d %H:%M\""] "mydate" 600 +#+end_src + +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: + +#+begin_src haskell + Run ComX "date" ["+\"%a %b %_d %H:%M\""] "N/A" "mydate" 600 +#+end_src + +will display "N/A" if for some reason the =date= invocation fails. + +* The DBus Interface + +When compiled with the optional =with_dbus= flag, xmobar can be +controlled over dbus. All signals defined in [[https://github.com/jaor/xmobar/blob/master/src/Xmobar/System/Signal.hs][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 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. + +- Bus Name: =org.Xmobar.Control= +- Object Path: =/org/Xmobar/Control= +- Member Name: Any of SignalType, e.g. =string:Reveal= +- Interface Name: =org.Xmobar.Control= + +An example using the =dbus-send= command line utility: + +#+begin_src shell + dbus-send \ + --session \ + --dest=org.Xmobar.Control \ + --type=method_call \ + --print-reply \ + '/org/Xmobar/Control' \ + org.Xmobar.Control.SendSignal \ + "string:Toggle 0" +#+end_src + +It is also possible to send multiple signals at once: + +#+begin_src shell + # send to another screen, reveal and toggle the persistent flag + dbus-send [..] \ + "string:ChangeScreen 0" "string:Reveal 0" "string:TogglePersistent" +#+end_src + +The =Toggle=, =Reveal=, and =Hide= signals take an additional integer +argument that denotes an initial delay, in tenths of a second, before +the command takes effect. + +** Example for using the DBus IPC interface with XMonad + +Bind the key which should {,un}map xmobar to a dummy value. This is +necessary for {,un}grabKey in xmonad. + +#+begin_src haskell + ((0, xK_Alt_L), pure ()) +#+end_src + +Also, install =avoidStruts= layout modifier from +=XMonad.Hooks.ManageDocks= + +Finally, install these two event hooks (=handleEventHook= in =XConfig=) +=myDocksEventHook= is a replacement for =docksEventHook= which reacts on +unmap events as well (which =docksEventHook= doesn't). + +#+begin_src haskell + import qualified XMonad.Util.ExtensibleState as XS + + data DockToggleTime = DTT { lastTime :: Time } deriving (Eq, Show, Typeable) + + instance ExtensionClass DockToggleTime where + initialValue = DTT 0 + + toggleDocksHook :: Int -> KeySym -> Event -> X All + toggleDocksHook to ks ( KeyEvent { ev_event_display = d + , ev_event_type = et + , ev_keycode = ekc + , ev_time = etime + } ) = + io (keysymToKeycode d ks) >>= toggleDocks >> return (All True) + where + toggleDocks kc + | ekc == kc && et == keyPress = do + safeSendSignal ["Reveal 0", "TogglePersistent"] + XS.put ( DTT etime ) + | ekc == kc && et == keyRelease = do + gap <- XS.gets ( (-) etime . lastTime ) + safeSendSignal [ "TogglePersistent" + , "Hide " ++ show (if gap < 400 then to else 0) + ] + | otherwise = return () + + safeSendSignal s = catchX (io $ sendSignal s) (return ()) + sendSignal = withSession . callSignal + withSession mc = connectSession >>= \c -> callNoReply c mc >> disconnect c + callSignal :: [String] -> MethodCall + callSignal s = ( methodCall + ( objectPath_ "/org/Xmobar/Control" ) + ( interfaceName_ "org.Xmobar.Control" ) + ( memberName_ "SendSignal" ) + ) { methodCallDestination = Just $ busName_ "org.Xmobar.Control" + , methodCallBody = map toVariant s + } + + toggleDocksHook _ _ _ = return (All True) + + myDocksEventHook :: Event -> X All + myDocksEventHook e = do + when (et == mapNotify || et == unmapNotify) $ + whenX ((not `fmap` (isClient w)) <&&> runQuery checkDock w) refresh + return (All True) + where w = ev_window e + et = ev_event_type e +#+end_src + +* User plugins +** Writing a Plugin + +Writing a plugin for xmobar should be very simple. You need to create a +data type with at least one constructor. + +Next you must declare this data type an instance of the =Exec= class, by +defining the 1 needed method (alternatively =start= or =run=) and 3 +optional ones (=alias=, =rate=, and =trigger=): + +#+begin_src haskell + start :: e -> (String -> IO ()) -> IO () + run :: e -> IO String + rate :: e -> Int + alias :: e -> String + trigger :: e -> (Maybe SignalType -> IO ()) -> IO () +#+end_src + +=start= must receive a callback to be used to display the =String= +produced by the plugin. This method can be used for plugins that need to +perform asynchronous actions. See =src/Xmobar/Plugins/PipeReader.hs= for +an example. + +=run= can be used for simpler plugins. If you define only =run= the +plugin will be run every second. To overwrite this default you just need +to implement =rate=, which must return the number of tenth of seconds +between every successive runs. See [[https://github.com/jaor/xmobar/blob/master/examples/xmobar.hs][examples/xmobar.hs]] for an example of +a plugin that runs just once, and [[https://github.com/jaor/xmobar/blob/master/src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one +that implements =rate=. + +Notice that Date could be implemented as: + +#+begin_src haskell + instance Exec Date where + alias (Date _ a _) = a + start (Date f _ r) = date f r + + date :: String -> Int -> (String -> IO ()) -> IO () + date format r callback = do go + where go = do + t <- toCalendarTime =<< getClockTime + callback $ formatCalendarTime defaultTimeLocale format t + tenthSeconds r >> go +#+end_src + +This implementation is equivalent to the one you can read in +=Plugins/Date.hs=. + +=alias= is the name to be used in the output template. Default alias +will be the data type constructor. + +After that your type constructor can be used as an argument for the +Runnable type constructor =Run= in the =commands= list of the +configuration options. + +** Using a Plugin + +To use your new plugin, you need to use a pure Haskell configuration for +xmobar, and load your definitions there. You can see an example in +[[./examples/xmobar.hs][examples/xmobar.hs]] showing you how to write a Haskell configuration that +uses a new plugin, all in one file. + +When xmobar runs with the full path to that Haskell file as its argument +(or if you put it in =~/.config/xmobar/xmobar.hs=), and with the xmobar +library installed (e.g., with =cabal install --lib xmobar=), the Haskell +code will be compiled as needed, and the new executable spawned for you. + +That's it! + +** Configurations written in pure Haskell + +xmobar can be used as a pure Haskell program, that is compiled with your +specific configuration, expressed as Haskell source code. For an +example, see [[https://gitlab.com/jaor/xmobar-config/][the author's configuration]]. |