diff options
Diffstat (limited to 'readme.org')
| -rw-r--r-- | readme.org | 1612 |
1 files changed, 0 insertions, 1612 deletions
@@ -180,7 +180,6 @@ Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2: screen. * Configuration - ** Quick Start See [[http://github.com/jaor/xmobar/raw/master/examples/xmobar.config][examples/xmobar.config]] for an example. @@ -526,1617 +525,6 @@ much more: we list all available plugins below. Other commands can be created as plugins with the Plugin infrastructure. See below. -* 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. - -** =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 - -* 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. - -* Other Plugins - -** =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 - -** =Date Format Alias RefreshRate= - -- Format is a time format string, as accepted by the standard ISO C - =strftime= function (or Haskell's =formatCalendarTime=). - -- 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= - -- Format is a time format string, as accepted by the standard ISO C - =strftime= function (or Haskell's =formatCalendarTime=). - -- If Locale is "" the default locale of the system is used, otherwise - the given locale. If there are more instances of DateZone, using "" as - input for Locale is not recommended. - -- Zone is the name of the TimeZone. It is assumed that the tz database - is stored in =/usr/share/zoneinfo/=. If "" 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 - -** =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 - -** =XMonadLog= - -- Aliases to XMonadLog - -- Displays information from xmonad's =_XMONAD_LOG=. You can set this - property by using =xmonadPropLog= as your log hook in xmonad's - configuration, as in the following example (more info [[https://hackage.haskell.org/package/xmonad-contrib-0.16/docs/XMonad-Hooks-DynamicLog.html][here]]): - - #+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. - -** =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 - -** =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 - -* 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]]. - * Authors and credits Andrea Rossato originally designed and implemented xmobar up to version |