xmobar 0.37 → 0.38
raw patch · 12 files changed
+2164/−2110 lines, 12 files
Files
- changelog.md +12/−0
- doc/plugins.org +1569/−0
- doc/quick-start.org +361/−0
- readme.md +0/−2087
- readme.org +170/−0
- src/Xmobar/App/Compile.hs +1/−1
- src/Xmobar/Plugins/Monitors/Cpu.hs +42/−9
- src/Xmobar/X11/Draw.hs +1/−1
- src/Xmobar/X11/MinXft.hsc +1/−7
- src/Xmobar/X11/Text.hs +1/−1
- src/Xmobar/X11/Window.hs +2/−1
- xmobar.cabal +4/−3
changelog.md view
@@ -1,3 +1,15 @@+## Version 0.38 (May, 2021)++_Bug fixes_++ - Fix off-by-one in strut calculation for `Static` position which reserved+ space for the panel than necessary and caused issues in some multi-head+ setups (fixes #530).+ - Revert the double-UTF-8 encoding workarounds of 0.36 (#482), as they're no+ longer necessary with xmonad-contrib master, and aren't needed with any+ released version of xmonad-contrib either.+ - Fix slow reactions to SIGUSR1/2 signals (reposition, change screen).+ ## Version 0.37 (November, 2020) _New features_
+ doc/plugins.org view
@@ -0,0 +1,1569 @@+* System Monitor Plugins++This is the description of the system monitor plugins available in+xmobar. Some of them are only installed when an optional build option is+set: we mention that fact, when needed, in their description.++Each monitor has an =alias= to be used in the output template. Monitors+may have default aliases, see the documentation of the monitor in+question.++There are two types of arguments: ones that all monitors share (the so+called /default monitor arguments/) and arguments that are specific to a+certain monitor.++All Monitors accept a common set of arguments, described below in+[[Default Monitor Arguments]]. Some monitors also accept additional options+that are specific to them. When specifying the list of arguments in your+configuration, the common options come first, followed by =--=, followed+by any monitor-specific options. For example, the following [[=Battery Args RefreshRate=][Battery]]+configuration first sets the global =template= and =Low= arguments and+then specifies the battery-specific =off= option.++#+begin_src haskell+ Run Battery+ [ "--template", "<acstatus>"+ , "--Low" , "15"+ -- battery specific options start here.+ , "--"+ , "--off" , "<left> (<timeleft>)"+ ]+ 100+#+end_src++** 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++These are the options available for all monitors:++- =-t= /string/ Output template++ - Template for the monitor output. Field names must be enclosed+ between pointy brackets (=<foo>=) and will be substituted by the+ computed values. You can also specify the foreground (and+ optionally, background) color for a region by bracketing it between+ =<fc=fgcolor>= (or =<fc=fgcolor,bgcolor>=) and =</fc>=. The rest of+ the template is output verbatim.+ - Long option: =--template=+ - Default value: per monitor (see above).++- =-H= /number/ The high threshold.++ - Numerical values higher than /number/ will be displayed with the+ color specified by =-h= (see below).+ - Long option: =--High=+ - Default value: 66++- =-L= /number/ The low threshold.++ - Numerical values higher than /number/ and lower than the high+ threshold will be displayed with the color specified by =-n= (see+ below). Values lower than /number/ will use the =-l= color.+ - Long option: =--Low=+ - Default value: 33++- =-h= /color/ High threshold color.++ - Color for displaying values above the high threshold. /color/ can be+ either a name (e.g. "blue") or an hexadecimal RGB (e.g. "#FF0000").+ - Long option: =--high=+ - Default: none (use the default foreground).++- =-n= /color/ Color for 'normal' values++ - Color used for values greater than the low threshold but lower than+ the high one.+ - Long option: =--normal=+ - Default: none (use the default foreground).++- =-l= /color/ The low threshold color++ - Color for displaying values below the low threshold.+ - Long option: =--low=+ - Default: none (use the default foreground).++- =-S= /boolean/ Display optional suffixes++ - When set to a true designator ("True", "Yes" or "On"), optional+ value suffixes such as the '%' symbol or optional units will be+ displayed.+ - Long option: =--suffix=+ - Default: False.++- =-p= /number/ Percentages padding++ - Width, in number of digits, for quantities representing percentages.+ For instance =-p 3= means that all percentages in the monitor will+ be represented using 3 digits.+ - Long option: =--ppad=+ - Default value: 0 (don't pad)++- =-d= /number/ Decimal digits++ - Number of digits after the decimal period to use in float values.+ - Long option: =--ddigits=+ - Default value: 0 (display only integer part)++- =-m= /number/ Minimum field width++ - Minimum width, in number of characters, of the fields in the monitor+ template. Values whose printed representation is shorter than this+ value will be padded using the padding characters given by the =-c=+ option with the alignment specified by =-a= (see below).+ - Long option: =--minwidth=+ - Default: 0++- =-M= /number/ Maximum field width++ - Maximum width, in number of characters, of the fields in the monitor+ template. Values whose printed representation is longer than this+ value will be truncated.+ - Long option: =--maxwidth=+ - Default: 0 (no maximum width)++- =-e= /string/ Maximum width ellipsis++ - Ellipsis to be added to the field when it has reached its max width.+ - Long option: =--maxwidthellipsis=+ - Default: "" (no ellipsis)++- =-w= /number/ Fixed field width++ - All fields will be set to this width, padding or truncating as+ needed.+ - Long option: =--width=+ - Default: 0 (variable width)++- =-T= /number/ Maximum total width++ - Maximum total width of the text.+ - Long option: =--maxtwidth=+ - Default: 0 (no limit)++- =-E= /string/ Maximum total width ellipsis++ - Ellipsis to be added to the total text when it has reached its max+ width.+ - Long option: =--maxtwidthellipsis=+ - Default: "" (no ellipsis)++- =-c= /string/++ - Characters used for padding. The characters of /string/ are used+ cyclically. E.g., with =-P +- -w 6=, a field with value "foo" will+ be represented as "+-+foo".+ - Long option: =--padchars=+ - Default value: " "++- =-a= r|l Field alignment++ - Whether to use right (r) or left (l) alignment of field values when+ padding.+ - Long option: =--align=+ - Default value: r (padding to the left)++- =-b= /string/ Bar background++ - Characters used, cyclically, to draw the background of bars. For+ instance, if you set this option to "·.", an empty bar will look+ like this: =·.·.·.·.·.=+ - Long option: =--bback=+ - Default value: ":"++- =-f= /string/ Bar foreground++ - Characters used, cyclically, to draw the foreground of bars.+ - Long option: =--bfore=+ - Default value: "#"++- =-W= /number/ Bar width++ - Total number of characters used to draw bars.+ - Long option: =--bwidth=+ - Default value: 10+ - Special value: 0. When this parameter is 0, the percentage to+ display is interpreted as a position in the bar foreground string+ (given by =-f=), and the character at that position is displayed.++- =-x= /string/ N/A string++ - String to be used when the monitor is not available+ - Long option: =--nastring=+ - Default value: "N/A"++Commands' arguments must be set as a list. E.g.:++#+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++** Battery Monitors+*** =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.+** Cpu and Memory Monitors+*** =Cpu Args RefreshRate=++ - Aliases to =cpu=+ - Args: default monitor arguments, plus:++ - =--load-icon-pattern=: dynamic string for cpu load in =ipat=++ - Thresholds refer to percentage of CPU load+ - Variables that can be used with the =-t/--template= argument:+ =total=, =bar=, =vbar=, =ipat=, =user=, =nice=, =system=, =idle=,+ =iowait=+ - Default template: =Cpu: <total>%=++*** =MultiCpu Args RefreshRate=++ - Aliases to =multicpu=+ - Args: default monitor arguments, plus:++ - =--load-icon-pattern=: dynamic string for overall cpu load in+ =ipat=.+ - =--load-icon-patterns=: dynamic string for each cpu load in+ =autoipat=, =ipat{i}=. This option can be specified several times.+ nth option corresponds to nth cpu.+ - =--fallback-icon-pattern=: dynamic string used by =autoipat= and+ =ipat{i}= when no =--load-icon-patterns= has been provided for+ =cpu{i}=+ - =--contiguous-icons=: flag (no value needs to be provided) that+ causes the load icons to be drawn without padding.++ - Thresholds refer to percentage of CPU load+ - Variables that can be used with the =-t/--template= argument:+ =autototal=, =autobar=, =autovbar=, =autoipat=, =autouser=,+ =autonice=, =autosystem=, =autoidle=, =total=, =bar=, =vbar=, =ipat=,+ =user=, =nice=, =system=, =idle=, =total0=, =bar0=, =vbar0=, =ipat0=,+ =user0=, =nice0=, =system0=, =idle0=, ... The auto* variables+ automatically detect the number of CPUs on the system and display one+ entry for each.+ - Default template: =Cpu: <total>%=++*** =CpuFreq Args RefreshRate=++ - Aliases to =cpufreq=++ - Args: default monitor arguments++ - Thresholds refer to frequency in GHz++ - Variables that can be used with the =-t/--template= argument:+ =cpu0=, =cpu1=, .., =cpuN=++ - 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+*** =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>%=+** Date Monitors+*** =Date Format Alias RefreshRate=++ - Format is a time format string, as accepted by the standard ISO C+ =strftime= function (or Haskell's =formatCalendarTime=). Basically,+ if =date +"my-string"= works with your command then =Date= will handle+ it correctly.++ - Timezone changes are picked up automatically every minute.++ - Sample usage:++ #+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+** Disk Monitors+*** =DiskU Disks Args RefreshRate=++ - Aliases to =disku=++ - Disks: list of pairs of the form (device or mount point, template),+ where the template can contain =<size>=, =<free>=, =<used>=, =<freep>=+ or =<usedp>=, =<freebar>=, =<freevbar>=, =<freeipat>=, =<usedbar>=,+ =<usedvbar>= or =<usedipat>= for total, free, used, free percentage+ and used percentage of the given file system capacity.++ - Thresholds refer to usage percentage.++ - Args: default monitor arguments. =-t/--template= is ignored. Plus++ - =--free-icon-pattern=: dynamic string for free disk space in+ =freeipat=.+ - =--used-icon-pattern=: dynamic string for used disk space in+ =usedipat=.++ - Default template: none (you must specify a template for each file+ system).++ - Example:++ #+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++** Keyboard Monitors+*** =Kbd Opts=++ - Registers to XKB/X11-Events and output the currently active keyboard+ layout. Supports replacement of layout names.++ - Aliases to =kbd=++ - Opts is a list of tuples:++ - first element of the tuple is the search string+ - second element of the tuple is the corresponding replacement++ - Example:++ #+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+** Process Monitors+*** =TopProc Args RefreshRate=++ - Aliases to =top=+ - Args: default monitor arguments. The low and high thresholds (=-L= and+ =-H=) denote, for memory entries, the percent of the process memory+ over the total amount of memory currently in use and, for cpu entries,+ the activity percentage (i.e., the value of =cpuN=, which takes values+ between 0 and 100).+ - Variables that can be used with the =-t/--template= argument: =no=,+ =name1=, =cpu1=, =both1=, =mname1=, =mem1=, =mboth1=, =name2=, =cpu2=,+ =both2=, =mname2=, =mem2=, =mboth2=, ...+ - Default template: =<both1>=+ - Displays the name and cpu/mem usage of running processes (=bothn= and+ =mboth= display both, and is useful to specify an overall maximum+ and/or minimum width, using the =-m/-M= arguments. =no= gives the+ total number of processes.++*** =TopMem Args RefreshRate=++ - Aliases to =topmem=+ - Args: default monitor arguments. The low and high thresholds (=-L= and+ =-H=) denote the percent of the process memory over the total amount+ of memory currently in use.+ - Variables that can be used with the =-t/--template= argument:+ =name1=, =mem1=, =both1=, =name2=, =mem2=, =both2=, ...+ - Default template: =<both1>=+ - Displays the name and RSS (resident memory size) of running processes+ (=bothn= displays both, and is useful to specify an overall maximum+ and/or minimum width, using the =-m/-M= arguments.+** Thermal Monitors+*** =ThermalZone Number Args RefreshRate=++ - Aliases to "thermaln": so =ThermalZone 0 []= can be used in template+ as =%thermal0%=++ - Thresholds refer to temperature in degrees++ - Args: default monitor arguments++ - Variables that can be used with the =-t/--template= argument: =temp=++ - Default template: =<temp>C=++ - This plugin works only on systems with devices having thermal zone.+ Check directories in =/sys/class/thermal= for possible values of the+ zone number (e.g., 0 corresponds to =thermal_zone0= in that+ directory).++ - Example:++ #+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+** Volume Monitors+*** =Volume Mixer Element Args RefreshRate=++ - Aliases to the mixer name and element name separated by a colon. Thus,+ =Volume "default" "Master" [] 10= can be used as =%default:Master%=.+ - Args: default monitor arguments. Also accepts:++ - =-O= /string/ On string++ - The string used in place of =<status>= when the mixer element is+ on. Defaults to "[on]".+ - Long option: =--on=++ - =-o= /string/ Off string++ - The string used in place of =<status>= when the mixer element is+ off. Defaults to "[off]".+ - Long option: =--off=++ - =-C= /color/ On color++ - The color to be used for =<status>= when the mixer element is on.+ Defaults to "green".+ - Long option: =--onc=++ - =-c= /color/ Off color++ - The color to be used for =<status>= when the mixer element is off.+ Defaults to "red".+ - Long option: =--offc=++ - =--highd= /number/ High threshold for dB. Defaults to -5.0.+ - =--lowd= /number/ Low threshold for dB. Defaults to -30.0.+ - =--volume-icon-pattern= /string/ dynamic string for current volume+ in =volumeipat=.+ - =-H= /number/ High threshold for volume (in %). Defaults to 60.0.++ - Long option: =--highv=++ - =-L= /number/ Low threshold for volume (in %). Defaults to 20.0.++ - Long option: =--lowv=++ - =-h=: /string/ High string++ - The string added in front of =<status>= when the mixer element is+ on and the volume percentage is higher than the =-H= threshold.+ Defaults to "".+ - Long option: =--highs=++ - =-m=: /string/ Medium string++ - The string added in front of =<status>= when the mixer element is+ on and the volume percentage is lower than the =-H= threshold.+ Defaults to "".+ - Long option: =--mediums=++ - =-l=: /string/ Low string++ - The string added in front of =<status>= when the mixer element is+ on and the volume percentage is lower than the =-L= threshold.+ Defaults to "".+ - Long option: =--lows=++ - Variables that can be used with the =-t/--template= argument:+ =volume=, =volumebar=, =volumevbar=, =volumeipat=, =dB=, =status=,+ =volumestatus=+ - Note that =dB= might only return 0 on your system. This is known to+ happen on systems with a pulseaudio backend.+ - Default template: =Vol: <volume>% <status>=+ - Requires the package [[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=.+** Mail Monitors+*** =Mail Args Alias=++ - Args: list of maildirs in form =[("name1","path1"),...]=. Paths may+ start with a '~' to expand to the user's home directory.++ - This plugin requires inotify support in your Linux kernel and the+ [[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++** Music Monitors+*** =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+** Network Monitors+*** =Network Interface Args RefreshRate=++ - Aliases to the interface name: so =Network "eth0" []= can be used as+ =%eth0%=+ - Thresholds refer to velocities expressed in 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.+** Weather Monitors+*** =Weather StationID Args RefreshRate=++ - Aliases to the Station ID: so =Weather "LIPB" []= can be used in+ template as =%LIPB%=+ - Thresholds refer to temperature in the selected units+ - Args: default monitor arguments, plus:++ - =--weathers= /string/ : display a default string when the =weather=+ variable is not reported.++ - short option: =-w=+ - Default: ""++ - =--useManager= /bool/ : Whether to use one single manager per+ monitor for managing network connections or create a new one every+ time a connection is made.++ - Short option: =-m=+ - Default: True++ - Variables that can be used with the =-t/--template= argument:+ =station=, =stationState=, =year=, =month=, =day=, =hour=,+ =windCardinal=, =windAzimuth=, =windMph=, =windKnots=, =windMs=,+ =windKmh= =visibility=, =skyCondition=, =weather=, =tempC=, =tempF=,+ =dewPointC=, =dewPointF=, =rh=, =pressure=+ - Default template: =<station>: <tempC>C, rh <rh>% (<hour>)=+ - Retrieves weather information from http://tgftp.nws.noaa.gov. Here is+ an [[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/>")=.+** Other Monitors+*** =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++*** =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++*** =CommandReader "/path/to/program" Alias=++ - Runs the given program, and displays its standard output.++*** =Uptime Args RefreshRate=++ - Aliases to =uptime=+ - Args: default monitor arguments. The low and high thresholds refer to+ the number of days.+ - Variables that can be used with the =-t/--template= argument: =days=,+ =hours=, =minutes=, =seconds=. The total uptime is the sum of all+ those fields. You can set the =-S= argument to =True= to add units to+ the display of those numeric fields.+ - Default template: =Up: <days>d <hours>h <minutes>m=++*** =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.++** Property-based Logging+*** =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.++*** =UnsafeXMonadLog=++ - Aliases to UnsafeXMonadLog+ - Displays any text received by xmobar on the =_XMONAD_LOG= atom.+ - Will not do anything to the text received. This means you can pass+ xmobar dynamic actions. Be careful to escape (using =<raw=…>=) or+ remove tags from dynamic text that you pipe through to xmobar in this+ way.++ - Sample usage: Send the list of your workspaces, enclosed by actions+ tags, to xmobar. This enables you to switch to a workspace when you+ click on it in xmobar!++ #+begin_src shell+ <action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action>+ #+end_src++ - If you use xmonad, 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++*** =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.++** Logging via Stdin+*** =StdinReader=++ - Aliases to StdinReader+ - Displays any text received by xmobar on its standard input.+ - Strips actions from the text received. This means you can't pass+ dynamic actions via stdin. This is safer than =UnsafeStdinReader=+ because there is no need to escape the content before passing it to+ xmobar's standard input.++*** =UnsafeStdinReader=++ - Aliases to UnsafeStdinReader+ - Displays any text received by xmobar on its standard input.+ - Similar to [[=UnsafeXMonadLog=][UnsafeXMonadLog]], in the sense that it does not strip any+ actions from the received text, only using =stdin= and not a property+ atom of the root window. Please be equally carefully when using this+ as when using =UnsafeXMonadLog=!++** Pipe-based Logging+*** =PipeReader "default text:/path/to/pipe" Alias=++ - Reads its displayed output from the given pipe.+ - Prefix an optional default text separated by a colon+ - Expands environment variables in the first argument of syntax =${VAR}=+ or =$VAR=++*** =MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias=++ - Generally equivalent to PipeReader++ - Text is displayed as marquee with the specified length, rate in 10th+ seconds and separator when it wraps around++ #+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++** Handle-based Logging+*** =HandleReader Handle Alias=++ - Display data from a Haskell =Handle=++ - This plugin is only useful if you are running xmobar from another+ Haskell program like XMonad.++ - You can use =System.Process.createPipe= to create a pair of =read= &+ =write= Handles. Pass the =read= Handle to HandleReader and write your+ output to the =write= Handle:++ #+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
+ doc/quick-start.org view
@@ -0,0 +1,361 @@+Xmobar can either be configured using the configuration language, or+used as a Haskell library (similar to xmonad) and compiled with your+specific configuration. For an example of the latter, you can have a+loot at [[../examples/xmobar.hs][examples/xmobar.hs]] or, for a more complicated example, peruse+[[https://gitlab.com/jaor/xmobar-config/][the author's configuration]].++There is also an example of a config using the configuration language+available [[http://github.com/jaor/xmobar/raw/master/examples/xmobar.config][here]].++* Configuration Options++Here are all the global configuration options that you can set within+the =Config= block in your configuration.++- =font= Name of the font to be used. Use the =xft:= prefix for XFT+ fonts.++- =additionalFonts= Haskell-style list of fonts to be used with the+ =fn=-template. Use the =xft:= prefix for XFT fonts. See also+ =textOffsets= below. For example:++ #+begin_src haskell+ additionalFonts = [iconFont, altIconFont]+ #+end_src++- =bgColor= Background color.++- =fgColor= Default font color.++- =alpha= The transparency. 0 is transparent, 255 is opaque.++- =position= Top, TopP, TopW, TopSize, Bottom, BottomP, BottomW,+ BottomSize or Static (with x, y, width and height).++ TopP and BottomP take 2 arguments: left padding and right padding.++ TopW and BottomW take 2 arguments: an alignment parameter (L for left,+ C for centered, R for Right) and an integer for the percentage width+ xmobar window will have in respect to the screen width.++ TopSize and BottomSize take 3 arguments: an alignment parameter, an+ integer for the percentage width, and an integer for the minimum pixel+ height that the xmobar window will have.++ For example:++ #+begin_src haskell+ position = BottomW C 75+ #+end_src++ to place xmobar at the bottom, centered with the 75% of the screen+ width. Or++ #+begin_src haskell+ position = BottomP 120 0+ #+end_src++ to place xmobar at the bottom, with 120 pixel indent of the left. Or++ #+begin_src haskell+ position = Static { xpos = 0 , ypos = 0, width = 1024, height = 15 }+ #+end_src++ or++ #+begin_src haskell+ position = Top+ #+end_src++- =textOffset= The vertical offset, in pixels, for the text baseline. If+ negative or not given, xmobar will try to center text vertically.++- =textOffsets= A list of vertical offsets, in pixels, for the text+ baseline, to be used with the each of the fonts in =additionalFonts=+ (if any). If negative or not given, xmobar will try to center text+ vertically for that font.++- =iconOffset= The vertical offset, in pixels, for icons bottom line. If+ negative or not given, xmobar will try to center icons vertically.++- =lowerOnStart= When True the window is sent the bottom of the window+ stack initially.++- =hideOnStart= When set to True the window is initially not mapped,+ i.e. hidden. It then can be toggled manually (for example using the+ dbus interface) or automatically (by a plugin) to make it reappear.++- =allDesktops= When set to True (the default), xmobar will tell the+ window manager explicitly to be shown in all desktops, by setting+ =_NET_WM_DESKTOP= to 0xffffffff.++- =overrideRedirect= If you're running xmobar in a tiling window+ manager, you might need to set this option to =False= so that it+ behaves as a docked application. Defaults to =True=.++- =pickBroadest= When multiple displays are available, xmobar will+ choose by default the first one to place itself. With this flag set to+ =True= (the default is =False=) it will choose the broadest one+ instead.++- =persistent= When True the window status is fixed i.e. hiding or+ revealing is not possible. This option can be toggled at runtime.+ Defaults to False.++- =border= TopB, TopBM, BottomB, BottomBM, FullB, FullBM or NoBorder+ (default).++ TopB, BottomB, FullB take no arguments, and request drawing a border+ at the top, bottom or around xmobar's window, respectively.++ TopBM, BottomBM, FullBM take an integer argument, which is the margin,+ in pixels, between the border of the window and the drawn border.++- =borderColor= Border color.++- =borderWidth= Border width in pixels.++- =iconRoot= Root folder where icons are stored. For =<icon=path/>= if+ path start with =/=, =./= or =../= it is interpreted as it is.+ Otherwise it will have++ #+begin_src haskell+ iconRoot ++ "/"+ #+end_src++ prepended to it. Default is =.=.++- =commands= For setting the options of the programs to run (optional).++- =sepChar= The character to be used for indicating commands in the+ output template (default '%').++- =alignSep= a 2 character string for aligning text in the output+ template. The text before the first character will be align to left,+ the text in between the 2 characters will be centered, and the text+ after the second character will be align to the right.++- =template= The output template.++- =wmClass= The value for the window's X11 WM_CLASS property. Defaults+ to "xmobar".++- =wmName= The value for the window's X11 WM_NAME property. Defaults to+ "xmobar".++** The Output =template=++The output template is how xmobar will end up printing all of your+configured commands. It must contain at least one command. Xmobar will+parse the template and search for the command to be executed in the+=commands= configuration option. First an =alias= will be searched (some+plugins, such as =Weather= or =Network=, have default aliases, see the+[[./plugins.org][plugin documentation]]). After that, the command name will be tried. If a+command is found, the arguments specified in the =commands= list will be+used.++If no command is found in the =commands= list, xmobar will ask the+operating system to execute a program with the name found in the+template. If the execution is not successful an error will be reported.++The syntax for the output template is as follows:++- =%command%= will execute command and print the output. The output may+ contain markups to change the characters' color.++- =<fc=#FF0000>string</fc>= will print =string= with =#FF0000= color+ (red). =<fc=#FF0000,#000000>string</fc>= will print =string= in red+ with a black background (=#000000=). Background absolute offsets can+ be specified for XFT fonts. =<fc=#FF0000,#000000:0>string</fc>= will+ have a background matching the bar's height.++- =<box>string</box>= will print string surrounded by a box in the+ foreground color. The =box= tag accepts several optional arguments to+ tailor its looks:++ - =type=: =Top=, =Bottom=, =VBoth= (a single line above or below+ string, or both), =Left=, =Right=, =HBoth= (single vertical lines),+ =Full= (a rectangle, the default).+ - =color=: the color of the box lines.+ - =width=: the width of the box lines.+ - =offset=: an alignment char (L, C or R) followed by the amount of+ pixels to offset the box lines; the alignment denotes the position+ of the resulting line, with L/R meaning top/bottom for the vertical+ lines, and left/right for horizontal ones.+ - =mt=, =mb=, =ml=, =mr= specify margins to be added at the top,+ bottom, left and right lines.++ For example, a box underlining its text with a red line of width 2:++ #+begin_src shell+ <box type=Bottom width=2 color=red>string</box>+ #+end_src++ and if you wanted an underline and an overline with a margin of 2+ pixels either side:++ #+begin_src shell+ <box type=VBoth mt=2 mb=2>string</box>+ #+end_src++- =<fn=1>string</fn>= will print =string= with the first font from+ =additionalFonts=. The index =0= corresponds to the standard font.++- =<icon=/path/to/icon.xbm/>= will insert the given bitmap. XPM image+ format is also supported when compiled with the =with_xpm= flag.++- =<action=`command` button=12345>= will execute given command when+ clicked with specified buttons. If not specified, button is equal to 1+ (left mouse button). Using old syntax (without backticks surrounding+ =command=) will result in =button= attribute being ignored.++- =<raw=len:str/>= allows the encapsulation of arbitrary text =str=+ (which must be =len= =Char=s long, where =len= is encoded as a decimal+ sequence). Careful use of this and =UnsafeStdinReader=, for example,+ permits window managers to feed xmobar strings with =<action>= tags+ mixed with un-trusted content (e.g. window titles). For example, if+ xmobar is invoked as++ #+begin_src shell+ xmobar -c "[Run UnsafeStdinReader]" -t "%UnsafeStdinReader%"+ #+end_src++ and receives on standard input the line++ #+begin_src shell+ <action=`echo test` button=1><raw=41:<action=`echo mooo` button=1>foo</action>/></action>`+ #+end_src++ then it will display the text+ =<action=`echo mooo` button=1>foo</action>=, which, when clicked, will+ cause =test= to be echoed.++*** Bitmap Icons++It's possible to insert in the global templates icon directives of the+form:++#+begin_src shell+ <icon=/path/to/bitmap.xbm/>+#+end_src++which will produce the expected result. Accepted image formats are XBM+and XPM (when =with_xpm= flag is enabled). If path does not start with+=/=, =./=, =../= it will have++#+begin_src haskell+ iconRoot ++ "/"+#+end_src++prepended to it.++*** Action Directives++It's also possible to use action directives of the form:++#+begin_src shell+ <action=`command` button=12345>+#+end_src++which will be executed when clicked on with specified mouse buttons.+This tag can be nested, allowing different commands to be run depending+on button clicked.++** The =commands= Configuration Option++The =commands= configuration option is a list of commands information+and arguments to be used by xmobar when parsing the output template.+Each member of the list consists in a command prefixed by the =Run=+keyword. Each command has arguments to control the way xmobar is going+to execute it.++The option consists in a list of commands separated by a comma and+enclosed by square parenthesis.++Example:++#+begin_src haskell+ [Run Memory ["-t","Mem: <usedratio>%"] 10, Run Swap [] 10]+#+end_src++to run the Memory monitor plugin with the specified template, and the+swap monitor plugin, with default options, every second. And here's an+example of a template for the commands above using an icon:++#+begin_src haskell+ template = "<icon=/home/jao/.xmobar/mem.xbm/><memory> <swap>"+#+end_src++This example will run "xclock" command when date is clicked:++#+begin_src haskell+ template = "<action=`xclock`>%date%</action>"+#+end_src++The only internal available command is =Com= (see below Executing+External Commands). All other commands are provided by plugins. xmobar+comes with some plugins, providing a set of system monitors, a standard+input reader, an Unix named pipe reader, a configurable date plugin, and+much more: we list all available plugins below.++Other commands can be created as plugins with the Plugin infrastructure.+See below.+** Running xmobar with =i3status=++xmobar can be used to display information generated by [[http://i3wm.org/i3status/][i3status]], a small+program that gathers system information and outputs it in formats+suitable for being displayed by the dzen2 status bar, wmii's status bar+or xmobar's =StdinReader=. See [[http://i3wm.org/i3status/manpage.html#_using_i3status_with_xmobar][i3status manual]] for further details.++** Dynamically sizing xmobar++See [[https://github.com/jaor/xmobar/issues/239#issuecomment-233206552][this idea]] by Jonas Camillus Jeppensen for a way of adapting+dynamically xmobar's size and run it alongside a system tray widget such+as trayer or stalonetray (although the idea is not limited to trays,+really). For your convenience, there is a version of Jonas' script in+[[../examples/padding-icon.sh][examples/padding-icon.sh]].++* Command Line Options++xmobar can be either configured with a configuration file or with+command line options. In the second case, the command line options will+overwrite the corresponding options set in the configuration file.++Example:++#+begin_src shell+ xmobar -B white -a right -F blue -t '%LIPB%' -c '[Run Weather "LIPB" [] 36000]'+#+end_src++This is the list of command line options (the output of =xmobar --help=):++#+begin_src shell+ Usage: xmobar [OPTION...] [FILE]+ Options:+ -h, -? --help This help+ -v --verbose Emit verbose debugging messages+ -r --recompile Force recompilation+ -V --version Show version information+ -f font name --font=font name Font name+ -N font name --add-font=font name Add to the list of additional fonts+ -w class --wmclass=class X11 WM_CLASS property+ -n name --wmname=name X11 WM_NAME property+ -B bg color --bgcolor=bg color The background color. Default black+ -F fg color --fgcolor=fg color The foreground color. Default grey+ -i path --iconroot=path Root directory for icon pattern paths. Default '.'+ -A alpha --alpha=alpha Transparency: 0 is transparent, 255 is opaque. Default: 255+ -o --top Place xmobar at the top of the screen+ -b --bottom Place xmobar at the bottom of the screen+ -d --dock Don't override redirect from WM and function as a dock+ -a alignsep --alignsep=alignsep Separators for left, center and right text+ alignment. Default: '}{'+ -s char --sepchar=char Character used to separate commands in+ the output template. Default '%'+ -t template --template=template Output template+ -c commands --commands=commands List of commands to be executed+ -C command --add-command=command Add to the list of commands to be executed+ -x screen --screen=screen On which X screen number to start+ -p position --position=position Specify position of xmobar. Same syntax as in config file++ Mail bug reports and suggestions to <mail@jao.io>+#+end_src
− readme.md
@@ -1,2087 +0,0 @@-[](http://hackage.haskell.org/package/xmobar)--<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->-**Table of Contents**--- [About](#about)-- [Installation](#installation)- - [Using cabal-install](#using-cabal-install)- - [From source](#from-source)- - [Optional features](#optional-features)-- [Running xmobar](#running-xmobar)- - [Signal Handling](#signal-handling)-- [Configuration](#configuration)- - [Quick Start](#quick-start)- - [Running xmobar with i3status](#running-xmobar-with-i3status)- - [Dynamically sizing xmobar](#dynamically-sizing-xmobar)- - [Command Line Options](#command-line-options)- - [The Output Template](#the-output-template)- - [The `commands` Configuration Option](#the-commands-configuration-option)-- [System Monitor Plugins](#system-monitor-plugins)- - [Icon patterns](#icon-patterns)- - [Default Monitor Arguments](#default-monitor-arguments)- - [`Uptime Args RefreshRate`](#uptime-args-refreshrate)- - [`Weather StationID Args RefreshRate`](#weather-stationid-args-refreshrate)- - [`WeatherX StationID SkyConditions Args RefreshRate`](#weatherx-stationid-skyconditions-args-refreshrate)- - [`Network Interface Args RefreshRate`](#network-interface-args-refreshrate)- - [`DynNetwork Args RefreshRate`](#dynnetwork-args-refreshrate)- - [`Wireless Interface Args RefreshRate`](#wireless-interface-args-refreshrate)- - [`Memory Args RefreshRate`](#memory-args-refreshrate)- - [`Swap Args RefreshRate`](#swap-args-refreshrate)- - [`Cpu Args RefreshRate`](#cpu-args-refreshrate)- - [`MultiCpu Args RefreshRate`](#multicpu-args-refreshrate)- - [`Battery Args RefreshRate`](#battery-args-refreshrate)- - [`BatteryP Dirs Args RefreshRate`](#batteryp-dirs-args-refreshrate)- - [`BatteryN Dirs Args RefreshRate Alias`](#batteryn-dirs-args-refreshrate-alias)- - [`TopProc Args RefreshRate`](#topproc-args-refreshrate)- - [`TopMem Args RefreshRate`](#topmem-args-refreshrate)- - [`DiskU Disks Args RefreshRate`](#disku-disks-args-refreshrate)- - [`DiskIO Disks Args RefreshRate`](#diskio-disks-args-refreshrate)- - [`ThermalZone Number Args RefreshRate`](#thermalzone-number-args-refreshrate)- - [`Thermal Zone Args RefreshRate`](#thermal-zone-args-refreshrate)- - [`CpuFreq Args RefreshRate`](#cpufreq-args-refreshrate)- - [`CoreTemp Args RefreshRate`](#coretemp-args-refreshrate)- - [`MultiCoreTemp Args RefreshRate`](#multicoretemp-args-refreshrate)- - [`Volume Mixer Element Args RefreshRate`](#volume-mixer-element-args-refreshrate)- - [`Alsa Mixer Element Args`](#alsa-mixer-element-args)- - [`MPD Args RefreshRate`](#mpd-args-refreshrate)- - [`MPDX Args RefreshRate Alias`](#mpdx-args-refreshrate-alias)- - [`Mpris1 PlayerName Args RefreshRate`](#mpris1-playername-args-refreshrate)- - [`Mpris2 PlayerName Args RefreshRate`](#mpris2-playername-args-refreshrate)- - [`Mail Args Alias`](#mail-args-alias)- - [`MailX Args Opts Alias`](#mailx-args-opts-alias)- - [`MBox Mboxes Opts Alias`](#mbox-mboxes-opts-alias)- - [`NotmuchMail Alias Args Rate`](#notmuchmail-alias-args-rate)- - [`XPropertyLog PropName`](#xpropertylog-propname)- - [`UnsafeXPropertyLog PropName`](#unsafexpropertylog-propname)- - [`NamedXPropertyLog PropName Alias`](#namedxpropertylog-propname-alias)- - [`UnsafeNamedXPropertyLog PropName Alias`](#unsafenamedxpropertylog-propname-alias)- - [`Brightness Args RefreshRate`](#brightness-args-refreshrate)- - [`Kbd Opts`](#kbd-opts)- - [`Locks`](#locks)- - [`CatInt n filename`](#catint-n-filename)- - [`UVMeter`](#uvmeter)-- [Executing External Commands](#executing-external-commands)-- [Other Plugins](#other-plugins)- - [`StdinReader`](#stdinreader)- - [`UnsafeStdinReader`](#unsafestdinreader)- - [`Date Format Alias RefreshRate`](#date-format-alias-refreshrate)- - [`DateZone Format Locale Zone Alias RefreshRate`](#datezone-format-locale-zone-alias-refreshrate)- - [`CommandReader "/path/to/program" Alias`](#commandreader-pathtoprogram-alias)- - [`PipeReader "default text:/path/to/pipe" Alias`](#pipereader-default-textpathtopipe-alias)- - [`MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias`](#marqueepipereader-default-textpathtopipe-length-rate-sep-alias)- - [`BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]`](#bufferedpipereader-alias-timeout-bool-pathtopipe1-)- - [`XMonadLog`](#xmonadlog)- - [`UnsafeXMonadLog`](#unsafexmonadlog)- - [`HandleReader Handle Alias`](#handlereader-handle-alias)-- [The DBus Interface](#the-dbus-interface)- - [Example for using the DBus IPC interface with XMonad](#example-for-using-the-dbus-ipc-interface-with-xmonad)-- [User plugins](#user-plugins)- - [Writing a Plugin](#writing-a-plugin)- - [Using a Plugin](#using-a-plugin)- - [Configurations written in pure Haskell](#configurations-written-in-pure-haskell)-- [Authors and credits](#authors-and-credits)- - [Thanks](#thanks)-- [Related](#related)-- [License](#license)--<!-- markdown-toc end -->--# About--Xmobar is a minimalistic status bar. It was originally designed and-implemented by Andrea Rossato to work with-[xmonad](http://xmonad.org), but it is actually usable with any window-manager.--Xmobar was inspired by the [Ion3](http://tuomov.iki.fi/software/)-status bar, and supports similar features, like dynamic color-management, icons, output templates, and extensibility through-plugins.--These are some xmobar [screenshots](doc/screenshots) using the-author's configuration:--------This is the [changelog](https://xmobar.org/changelog.html) for recent releases.--# Installation--## Using cabal-install--Xmobar is available from [Hackage], and you can install it using-`cabal-install`:-- cabal install xmobar--Xmobar versions >= 0.27 require GHC version >= 8.0.2. Due to an-intermittent bug in GHC, we recommend using either GHC 8.0.2, 8.2.2 or-8.6.--See below for a list of optional compilation flags that will enable-some optional plugins. For instance, to install xmobar with all the-bells and whistles, use:-- cabal install xmobar --flags="all_extensions"--## From source--If you don't have `cabal-install` installed, you can get xmobar's-source code in a variety of ways:-- - From [Hackage]. Just download the latest release from xmobar's- hackage page.- - From [Github]. You can also obtain a tarball in [Github's- downloads page]. You'll find there links to each tagged release.- - From the bleeding edge repo. If you prefer to live dangerously,- just get the latest and greatest (and buggiest, I guess) using- git:-- git clone git://github.com/jaor/xmobar---[Github's downloads page]: https://github.com/jaor/xmobar/downloads--If you have cabal installed, you can now use it from within xmobar's-source tree:-- cabal install -fall_extensions---There is also a barebones `stack.yaml` file that will allow you to-build the xmobar executable with stances of the form:-- stack install --flag xmobar:all_extensions---## Optional features--You can configure xmobar to include some optional plugins and-features, which are not compiled by default. To that end, you need to-add one or more flags to either the cabal install command or the-configure setup step, as shown in the examples above.--Extensions need additional libraries (listed below) that will be-automatically downloaded and installed if you're using cabal install.-Otherwise, you'll need to install them yourself.--- `with_dbus` Enables support for DBUS by making xmobar to publish a- service on the session bus. Requires the [dbus] package.--- `with_threaded` Uses GHC's threaded runtime. Use this option if- xmobar enters a high-CPU regime right after starting.--- `with_utf8` UTF-8 support. Requires the [utf8-string] package.--- `with_xft` Antialiased fonts. Requires the [X11-xft] package. This- option automatically enables UTF-8. To use XFT fonts you need to- use the `xft:` prefix in the `font` configuration option. For- instance:-- ``` haskell- font = "xft:Times New Roman-10:italic"- ```-- Or to have fallback fonts, just separate them by commas:-- ``` haskell- font = "xft:Open Sans:size=9,WenQuanYi Zen Hei:size=9"- ```--- `with_mpd` Enables support for the [MPD] daemon. Requires the- [libmpd] package.--- `with_mpris` Enables support for MPRIS v1/v2 protocol. Requires the- [dbus] and [text] packages.--- `with_inotify` Support for inotify in modern Linux kernels. This- option is needed for the MBox and Mail plugins to work. Requires the- [hinotify] package.--- `with_nl80211` Support for wireless cards on Linux via nl80211 (all- upstream drivers). Enables the Wireless plugin. Requires [netlink]- and [cereal] packages.--- `with_iwlib` Support for wireless cards via Wext ioctls- (deprecated). Enables the Wireless plugin. No Haskell library is- required, but you will need the [iwlib] C library and headers in your- system (e.g., install `libiw-dev` in Debian-based systems or- `wireless_tools` on Arch Linux). Conflicts with `with_nl80211`.--- `with_alsa` Support for ALSA sound cards. Enables the Volume- plugin. Requires the [alsa-mixer] package. To install the latter,- you'll need the [libasound] C library and headers in your system- (e.g., install `libasound2-dev` in Debian-based systems).--- `with_datezone` Support for other timezones. Enables the DateZone- plugin. Requires [timezone-olson] and [timezone-series] package.--- `with_xpm` Support for xpm image file format. This will allow loading- .xpm files in `<icon>`. Requires the [libXpm] C library.--- `with_uvmeter` Enables UVMeter plugin. The plugin shows UV data for- Australia.--- `with_weather` Support to display weather information. Enables- Weather plugin.--- `all_extensions` Enables all the extensions above.--# Running xmobar--You can now run xmobar with:-- xmobar /path/to/config &--or-- xmobar &--if you have the default configuration file saved as-`$XDG\_CONFIG\_HOME/xmobar/xmobarrc` (defaulting to-`~/.config/xmobar/xmobarrc`), or `~/.xmobarrc`.--## Signal Handling--Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2:--- After receiving SIGUSR1 xmobar moves its position to the next screen.--- After receiving SIGUSR2 xmobar repositions itself on the current screen.--# Configuration--## Quick Start--See [examples/xmobar.config] for an example.--[examples/xmobar.config]: http://github.com/jaor/xmobar/raw/master/examples/xmobar.config--For the output template:--- `%command%` will execute command and print the output. The output- may contain markups to change the characters' color.--- `<fc=#FF0000>string</fc>` will print `string` with `#FF0000` color- (red). `<fc=#FF0000,#000000>string</fc>` will print `string` in red with- a black background (`#000000`). Background absolute offsets can be specified- for XFT fonts. `<fc=#FF0000,#000000:0>string</fc>` will have a background- matching the bar's height.--- `<box>string</box>` will print string surrounded by a box in the- foreground color. The `box` tag accepts several optional arguments- to tailor its looks:- - `type`: `Top`, `Bottom`, `VBoth` (a single line above or below- string, or both), `Left`, `Right`, `HBoth` (single vertical- lines), `Full` (a rectangle, the default).- - `color`: the color of the box lines.- - `width`: the width of the box lines.- - `offset`: an alignment char (L, C or R) followed by the amount of- pixels to offset the box lines; the alignment denotes the position- of the resulting line, with L/R meaning top/bottom for the- vertical lines, and left/right for horizontal ones.- - `mt`, `mb`, `ml`, `mr` specify margins to be added at the top,- bottom, left and right lines.-- For example, a box underlining its text with a red line of width 2:-- <box type=Bottom width=2 color=red>string</box>-- and if you wanted an underline and an overline with a margin of 2- pixels either side:-- <box type=VBoth mt=2 mb=2>string</box>--- `<fn=1>string</fn>` will print `string` with the first font from- `additionalFonts`. The index `0` corresponds to the standard font.--- `<icon=/path/to/icon.xbm/>` will insert the given bitmap. XPM image- format is also supported when compiled with `--flags="with_xpm"`.--- ```<action=`command` button=12345>``` will execute given command- when clicked with specified buttons. If not specified, button is- equal to 1 (left mouse button). Using old syntax (without backticks- surrounding `command`) will result in `button` attribute being- ignored.--- `<raw=len:str/>` allows the encapsulation of arbitrary text `str` (which- must be `len` `Char`s long, where `len` is encoded as a decimal sequence).- Careful use of this and `UnsafeStdinReader`, for example, permits window- managers to feed xmobar strings with `<action>` tags mixed with un-trusted- content (e.g. window titles). For example, if xmobar is invoked as-- xmobar -c "[Run UnsafeStdinReader]" -t "%UnsafeStdinReader%"-- and receives on standard input the line-- <action=`echo test` button=1><raw=41:<action=`echo mooo` button=1>foo</action>/></action>`-- then it will display the text ```<action=`echo mooo` button=1>foo</action>```,- which, when clicked, will cause `test` to be echoed.--Other configuration options:--- `font` Name of the font to be used. Use the `xft:` prefix for XFT- fonts.--- `additionalFonts` Haskell-style list of fonts to be used with the- `fn`-template. Use the `xft:` prefix for XFT fonts. See also- `textOffsets` below.--- `bgColor` Background color.--- `fgColor` Default font color.--- `alpha` The transparency. 0 is transparent, 255 is opaque.--- `position` Top, TopP, TopW, TopSize, Bottom, BottomP, BottomW,- BottomSize or Static (with x, y, width and height).-- TopP and BottomP take 2 arguments: left padding and right padding.-- TopW and BottomW take 2 arguments: an alignment parameter (L for- left, C for centered, R for Right) and an integer for the percentage- width xmobar window will have in respect to the screen width.-- TopSize and BottomSize take 3 arguments: an alignment parameter, an- integer for the percentage width, and an integer for the minimum- pixel height that the xmobar window will have.-- For example:-- ``` haskell- position = BottomW C 75- ```-- to place xmobar at the bottom, centered with the 75% of the screen- width. Or-- ``` haskell- position = BottomP 120 0- ```-- to place xmobar at the bottom, with 120 pixel indent of the left.- Or-- ``` haskell- position = Static { xpos = 0 , ypos = 0, width = 1024, height = 15 }- ```-- or-- ``` haskell- position = Top- ```--- `textOffset` The vertical offset, in pixels, for the text baseline.- If negative or not given, xmobar will try to center text- vertically.--- `textOffsets` A list of vertical offsets, in pixels, for the text- baseline, to be used with the each of the fonts in- `additionalFonts` (if any). If negative or not given, xmobar will- try to center text vertically for that font.--- `iconOffset` The vertical offset, in pixels, for icons bottom line.- If negative or not given, xmobar will try to center icons- vertically.--- `lowerOnStart` When True the window is sent the bottom of the window- stack initially.--- `hideOnStart` When set to True the window is initially not mapped,- i.e. hidden. It then can be toggled manually (for example using the- dbus interface) or automatically (by a plugin) to make it reappear.--- `allDesktops` When set to True (the default), xmobar will tell the- window manager explicitly to be shown in all desktops, by setting- `_NET_WM_DESKTOP` to 0xffffffff.--- `overrideRedirect` If you're running xmobar in a tiling window- manager, you might need to set this option to `False` so that it- behaves as a docked application. Defaults to `True`.--- `pickBroadest` When multiple displays are available, xmobar will- choose by default the first one to place itself. With this flag set- to `True` (the default is `False`) it will choose the broadest one- instead.--- `persistent` When True the window status is fixed i.e. hiding or- revealing is not possible. This option can be toggled at- runtime. Defaults to False.--- `border` TopB, TopBM, BottomB, BottomBM, FullB, FullBM or NoBorder- (default).-- TopB, BottomB, FullB take no arguments, and request drawing a border- at the top, bottom or around xmobar's window, respectively.-- TopBM, BottomBM, FullBM take an integer argument, which is the- margin, in pixels, between the border of the window and the drawn- border.--- `borderColor` Border color.--- `borderWidth` Border width in pixels.--- `iconRoot` Root folder where icons are stored. For <icon=path/> if- path start with `"/"`, `"./"` or `"../"` it is interpreted as it is.- Otherwise it will have `iconRoot ++ "/"` prepended to it. Default is- `"."`.--- `commands` For setting the options of the programs to run- (optional).--- `sepChar` The character to be used for indicating commands in the- output template (default '%').--- `alignSep` a 2 character string for aligning text in the output- template. The text before the first character will be align to left,- the text in between the 2 characters will be centered, and the text- after the second character will be align to the right.--- `template` The output template.--- `wmClass` The value for the window's X11 WM_CLASS property.- Defaults to "xmobar".--- `wmName` The value for the window's X11 WM_NAME property. Defaults- to "xmobar".--### Running xmobar with i3status--xmobar can be used to display information generated by [i3status], a-small program that gathers system information and outputs it in-formats suitable for being displayed by the dzen2 status bar, wmii's-status bar or xmobar's `StdinReader`. See [i3status manual] for-further details.--### Dynamically sizing xmobar--See [this idea] by Jonas Camillus Jeppensen for a way of adapting-dynamically xmobar's size and run it alongside a system tray widget-such as trayer or stalonetray (although the idea is not limited to-trays, really). For your convenience, there is a version of Jonas'-script in [examples/padding-icon.sh](./examples/padding-icon.sh).--[this idea]: https://github.com/jaor/xmobar/issues/239#issuecomment-233206552--## Command Line Options--xmobar can be either configured with a configuration file or with-command line options. In the second case, the command line options-will overwrite the corresponding options set in the configuration-file.--Example:-- xmobar -B white -a right -F blue -t '%LIPB%' -c '[Run Weather "LIPB" [] 36000]'--This is the list of command line options (the output of-xmobar --help):-- Usage: xmobar [OPTION...] [FILE]- Options:- -h, -? --help This help- -V --version Show version information- -v --verbose Emit verbose debugging messages- -r --recompile Force recompilation (for Haskell FILE)- -f font name --font=font name Font name- -N font name --add-font=font name Add to the list of additional fonts- -w class --wmclass=class X11 WM_CLASS property- -n name --wmname=name X11 WM_NAME property- -B bg color --bgcolor=bg color Background color. Default black- -F fg color --fgcolor=fg color Foreground color. Default grey- -A alpha --alpha=alpha Transparency: 0 is transparent- and 255 (the default) is opaque- -o --top Place xmobar at the top of the screen- -b --bottom Place xmobar at the bottom of the screen- -p --position=position Specify position, same as in config file- -d --dock Try to start xmobar as a dock- -a alignsep --alignsep=alignsep Separators for left, center and right text- alignment. Default: '}{'- -s char --sepchar=char Character used to separate commands in- the output template. Default '%'- -t template --template=template Output template- -i path --iconroot=path Default directory for icon pattern files- -c commands --commands=commands List of commands to be executed- -C command --add-command=command Add to the list of commands to be executed- -x screen --screen=screen On which X screen number to start-- Mail bug reports and suggestions to <mail@jao.io>---## The Output Template--The output template must contain at least one command. xmobar will-parse the template and will search for the command to be executed in-the `commands` configuration option. First an `alias` will be searched-(plugins such as Weather or Network have default aliases, see below).-After that, the command name will be tried. If a command is found, the-arguments specified in the `commands` list will be used.--If no command is found in the `commands` list, xmobar will ask the-operating system to execute a program with the name found in the-template. If the execution is not successful an error will be-reported.--It's possible to insert in the global templates icon directives of the-form:-- <icon=/path/to/bitmap.xbm/>--which will produce the expected result. Accepted image formats are XBM-and XPM (when `with_xpm` flag is enabled). If path does not start with-`"/"`, `"./"`, `"../"` it will have `iconRoot ++ "/"` prepended to it.--It's also possible to use action directives of the form:-- <action=`command` button=12345>--which will be executed when clicked on with specified mouse buttons. This tag-can be nested, allowing different commands to be run depending on button clicked.--## The `commands` Configuration Option--The `commands` configuration option is a list of commands information-and arguments to be used by xmobar when parsing the output template.-Each member of the list consists in a command prefixed by the `Run`-keyword. Each command has arguments to control the way xmobar is going-to execute it.--The option consists in a list of commands separated by a comma and-enclosed by square parenthesis.--Example:-- ``` haskell- [Run Memory ["-t","Mem: <usedratio>%"] 10, Run Swap [] 10]- ```--to run the Memory monitor plugin with the specified template, and the-swap monitor plugin, with default options, every second. And here's-an example of a template for the commands above using an icon:-- ``` haskell- template="<icon=/home/jao/.xmobar/mem.xbm/><memory> <swap>"- ```--This example will run "xclock" command when date is clicked:-- ``` haskell- template="<action=`xclock`>%date%</action>- ```--The only internal available command is `Com` (see below Executing-External Commands). All other commands are provided by plugins. xmobar-comes with some plugins, providing a set of system monitors, a-standard input reader, an Unix named pipe reader, a configurable date-plugin, and 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,-- ``` haskell- Run Brightness- [ "-t", "<ipat>"- , "--"- , "--brightness-icon-pattern", "<icon=bright_%%.xpm/>"- ] 30- ```--Will display `bright_0.xpm` to `bright_8.xpm` depending on current brightness-value.--## Default Monitor Arguments--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.:-- ``` haskell- Run Weather "EGPF" ["-t", "<station>: <tempC>C"] 36000- ```--In this case xmobar will run the weather monitor, getting information-for the weather station ID EGPF (Glasgow Airport, as a homage to GHC)-every hour (36000 tenth of seconds), with a template that will output-something like:-- Glasgow Airport: 16.0C---## `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.--## `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:-- ``` 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- ```--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 `--flags="with_nl80211"` or- `--flags="with_iwlib"` 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-- ``` haskell- BatteryP ["BAT", "BAT0", "BAT1", "BAT2"] Args RefreshRate- ```--## `BatteryP Dirs Args RefreshRate`--- Aliases to `battery`--- Dirs: list of directories in `/sys/class/power_supply/` where to- look for the ACPI files of each battery. Example:- `["BAT0","BAT1","BAT2"]`. Only up to 3 existing directories will be- searched.--- Args: default monitor arguments, plus the following specific ones- (these options, being specific to the monitor, are to be specified- after a `--` in the argument list):- - `-O`: string for AC "on" status (default: "On")- - `-i`: string for AC "idle" status (default: "On")- - `-o`: string for AC "off" status (default: "Off")- - `-L`: low power (`watts`) threshold (default: 10)- - `-H`: high power threshold (default: 12)- - `-l`: color to display power lower than the `-L` threshold- - `-m`: color to display power lower than the `-H` threshold- - `-h`: color to display power higher than the `-H` threshold- - `-p`: color to display positive power (battery charging)- - `-f`: file in `/sys/class/power_supply` with AC info (default:- "AC/online")- - `-A`: a number between 0 and 100, threshold below which the action- given by `-a`, if any, is performed (default: 5)- - `-a`: a string with a system command that is run when the- percentage left in the battery is less or equal than the threshold- given by the `-A` option. If not present, no action is- undertaken.- - `-P`: to include a percentage symbol in `left`.- - `--on-icon-pattern`: dynamic string for current battery charge- when AC is "on" in `leftipat`.- - `--off-icon-pattern`: dynamic string for current battery charge- when AC is "off" in `leftipat`.- - `--idle-icon-pattern`: dynamic string for current battery charge- when AC is "idle" in `leftipat`.- - `--lows`: string for AC "off" status and power lower than the `-L`- threshold (default: "")- - `--mediums`: string for AC "off" status and power lower than the `-H`- threshold (default: "")- - `--highs`: string for AC "off" status and power higher than the `-H`- threshold (default: "")---- Variables that can be used with the `-t`/`--template` argument:- `left`, `leftbar`, `leftvbar`, `leftipat`, `timeleft`, `watts`, `acstatus`-- Default template: `Batt: <watts>, <left>% / <timeleft>`-- Example (note that you need "--" to separate regular monitor options from- Battery's specific ones):-- ``` 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- ```-- 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:-- ``` haskell- Run BatteryP ["BAT0"]- ["-t", "<acstatus>"- , "-L", "10", "-H", "80"- , "-l", "red", "-h", "green"- , "--", "-O", "Charging", "-o", "Battery: <left>%"- ] 10- ```--- The "idle" AC state is selected whenever the AC power entering the- battery is zero.--## `BatteryN Dirs Args RefreshRate Alias`--Works like `BatteryP`, but lets you specify an alias for the monitor-other than "battery". Useful in case you one separate monitors for-more than one battery.--## `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:-- ``` haskell- DiskU [("/", "<used>/<size>"), ("sdb1", "<usedbar>")]- ["-L", "20", "-H", "50", "-m", "1", "-p", "3"]- 20- ```--## `DiskIO Disks Args RefreshRate`--- Aliases to `diskio`-- Disks: list of pairs of the form (device or mount point, template),- where the template can contain `<total>`, `<read>`, `<write>` for- total, read and write speed, respectively, as well as `<totalb>`,- `<readb>`, `<writeb>`, which report number of bytes during the last- refresh period rather than speed. There are also bar versions of- each: `<totalbar>`, `<totalvbar>`, `<totalipat>`, `<readbar>`,- `<readvbar>`, `<readipat>`, `<writebar>`, `<writevbar>`, and- `<writeipat>`; and their "bytes" counterparts: `<totalbbar>`,- `<totalbvbar>`, `<totalbipat>`, `<readbbar>`, `<readbvbar>`,- `<readbipat>`, `<writebbar>`, `<writebvbar>`, and `<writebipat>`.-- Thresholds refer to speed in b/s-- Args: default monitor arguments. `-t`/`--template` is ignored. Plus- - `--total-icon-pattern`: dynamic string for total disk I/O in `<totalipat>`.- - `--write-icon-pattern`: dynamic string for write disk I/O in `<writeipat>`.- - `--read-icon-pattern`: dynamic string for read disk I/O in `<readipat>`.-- Default template: none (you must specify a template for each file system).-- Example:-- ``` haskell- DiskIO [("/", "<read> <write>"), ("sdb1", "<total>")] [] 10- ```--## `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:-- ``` haskell- Run ThermalZone 0 ["-t","<id>: <temp>C"] 30- ```--## `Thermal Zone Args RefreshRate`--- **This plugin is deprecated. Use `ThermalZone` instead.**--- Aliases to the Zone: so `Thermal "THRM" []` can be used in template- as `%THRM%`-- Args: default monitor arguments-- Thresholds refer to temperature in degrees-- Variables that can be used with the `-t`/`--template` argument:- `temp`-- Default template: `Thm: <temp>C`-- This plugin works only on systems with devices having thermal zone.- Check directories in /proc/acpi/thermal_zone for possible values.-- Example:-- ``` haskell- Run Thermal "THRM" ["-t","iwl4965-temp: <temp>C"] 50- ```--## `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:-- ``` haskell- Run CpuFreq ["-t", "Freq:<cpu0>|<cpu1>GHz", "-L", "0", "-H", "2",- "-l", "lightblue", "-n","white", "-h", "red"] 50- ```--## `CoreTemp Args RefreshRate`--- Aliases to `coretemp`-- Args: default monitor arguments-- Thresholds refer to temperature in degrees-- Variables that can be used with the `-t`/`--template` argument:- `core0`, `core1`, .., `coreN`-- Default template: `Temp: <core0>C`-- This monitor requires coretemp module to be loaded in kernel-- Example:-- ``` haskell- Run CoreTemp ["-t", "Temp:<core0>|<core1>C",- "-L", "40", "-H", "60",- "-l", "lightblue", "-n", "gray90", "-h", "red"] 50- ```--## `MultiCoreTemp Args RefreshRate`--- Aliases to `multicoretemp`-- Args: default monitor arguments, plus:- - `--max-icon-pattern`: dynamic string for overall cpu load in `maxipat`.- - `--avg-icon-pattern`: dynamic string for overall cpu load in `avgipat`.- - `--mintemp`: temperature in degree Celsius, that sets the lower- limit for percentage calculation.- - `--maxtemp`: temperature in degree Celsius, that sets the upper- limit for percentage calculation.- - `--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:-- ``` haskell- Run MultiCoreTemp ["-t", "Temp: <avg>°C | <avgpc>%",- "-L", "60", "-H", "80",- "-l", "green", "-n", "yellow", "-h", "red",- "--", "--mintemp", "20", "--maxtemp", "100"] 50- ```--## `Volume Mixer Element Args RefreshRate`--- Aliases to the mixer name and element name separated by a colon. Thus,- `Volume "default" "Master" [] 10` can be used as `%default:Master%`.-- Args: default monitor arguments. Also accepts:- - `-O` _string_ On string- - The string used in place of `<status>` when the mixer element- is on. Defaults to "[on]".- - Long option: `--on`- - `-o` _string_ Off string- - The string used in place of `<status>` when the mixer element- is off. Defaults to "[off]".- - Long option: `--off`- - `-C` _color_ On color- - The color to be used for `<status>` when the mixer element- is on. Defaults to "green".- - Long option: `--onc`- - `-c` _color_ Off color- - The color to be used for `<status>` when the mixer element- is off. Defaults to "red".- - Long option: `--offc`- - `--highd` _number_ High threshold for dB. Defaults to -5.0.- - `--lowd` _number_ Low threshold for dB. Defaults to -30.0.- - `--volume-icon-pattern` _string_ dynamic string for current volume in `volumeipat`.- - `-H` _number_ High threshold for volume (in %). Defaults to 60.0.- - Long option: `--highv`- - `-L` _number_ Low threshold for volume (in %). Defaults to 20.0.- - Long option: `--lowv`- - `-h`: _string_ High string- - The string added in front of `<status>` when the mixer element- is on and the volume percentage is higher than the `-H` threshold.- Defaults to "".- - Long option: `--highs`- - `-m`: _string_ Medium string- - The string added in front of `<status>` when the mixer element- is on and the volume percentage is lower than the `-H` threshold.- Defaults to "".- - Long option: `--mediums`- - `-l`: _string_ Low string- - The string added in front of `<status>` when the mixer element- is on and the volume percentage is lower than the `-L` threshold.- Defaults to "".- - Long option: `--lows`-- Variables that can be used with the `-t`/`--template` argument:- `volume`, `volumebar`, `volumevbar`, `volumeipat`, `dB`, `status`,- `volumestatus`-- Note that `dB` might only return 0 on your system. This is known- to happen on systems with a pulseaudio backend.-- Default template: `Vol: <volume>% <status>`-- Requires the package [alsa-core] and [alsa-mixer] installed in your- system. In addition, to activate this plugin you must pass- `--flags="with_alsa"` during compilation.--## `Alsa Mixer Element Args`--Like [Volume](#volume-mixer-element-args-refreshrate), 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 [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):-- ``` haskell- Run MPD ["-t",- "<composer> <title> (<album>) <track>/<plength> <statei> [<flags>]",- "--", "-P", ">>", "-Z", "|", "-S", "><"] 10- ```--## `MPDX Args RefreshRate Alias`--Like `MPD` but uses as alias its last argument instead of "mpd".--## `Mpris1 PlayerName Args RefreshRate`--- Aliases to `mpris1`-- Requires [dbus] and [text] packages.- To activate, pass `--flags="with_mpris"` 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:-- ``` haskell- Run Mpris1 "clementine" ["-t", "<artist> - [<tracknumber>] <title>"] 10- ```--## `Mpris2 PlayerName Args RefreshRate`--- Aliases to `mpris2`-- Requires [dbus] and [text] packages.- To activate, pass `--flags="with_mpris"` 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:-- ``` haskell- Run Mpris2 "spotify" ["-t", "<artist> - [<composer>] <title>"] 10- ```--## `Mail Args Alias`--- Args: list of maildirs in form- `[("name1","path1"),...]`. Paths may start with a '~'- to expand to the user's home directory.-- This plugin requires inotify support in your Linux kernel and the- [hinotify] package. To activate, pass `--flags="with_inotify"`- during compilation.-- Example:-- ``` haskell- Run Mail [("inbox", "~/var/mail/inbox"),- ("lists", "~/var/mail/lists")]- "mail"- ```--## `MailX Args Opts Alias`--- Args: list of maildirs in form- `[("name1","path1","color1"),...]`. Paths may start with a '~'- to expand to the user's home directory. When mails are present,- counts are displayed with the given name and color.-- Opts is a possibly empty list of options, as flags. Possible values:- -d dir --dir dir a string giving the base directory where maildir files with- a relative path live.- -p prefix --prefix prefix a string giving a prefix for the list- of displayed mail counts- -s suffix --suffix suffix a string giving a suffix for the list- of displayed mail counts-- This plugin requires inotify support in your Linux kernel and the- [hinotify] package. To activate, pass `--flags="with_inotify"`- during compilation.-- Example:-- ``` haskell- Run MailX [("I", "inbox", "green"),- ("L", "lists", "orange")]- ["-d", "~/var/mail", "-p", " ", "-s", " "]- "mail"- ```--## `MBox Mboxes Opts Alias`--- Mboxes a list of mbox files of the form `[("name", "path", "color")]`,- where name is the displayed name, path the absolute or relative (to- BaseDir) path of the mbox file, and color the color to use to display- the mail count (use an empty string for the default).-- Opts is a possibly empty list of options, as flags. Possible values:- -a --all (no arg) Show all mailboxes, even if empty.- -u (no arg) Show only the mailboxes' names, sans counts.- -d dir --dir dir a string giving the base directory where mbox files with- a relative path live.- -p prefix --prefix prefix a string giving a prefix for the list- of displayed mail counts- -s suffix --suffix suffix a string giving a suffix for the list- of displayed mail counts-- Paths may start with a '~' to expand to the user's home directory.-- This plugin requires inotify support in your Linux kernel and the- [hinotify] package. To activate, pass `--flags="with_inotify"`- 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`:-- ``` haskell- Run MBox [("I ", "inbox", "red"), ("O ", "~/foo/mbox", "")]- ["-d", "/var/mail/", "-p", " "] "mbox"- ```--## `NotmuchMail Alias Args Rate`--This plugin checks for new mail, provided that this mail is indexed by-`notmuch`. In the `notmuch` spirit, this plugin checks for new-**threads** and not new individual messages.--- Alias: What name the plugin should have in your template string.-- Args: A list of `MailItem`s of the form-- ``` haskell- [ MailItem "name" "address" "query"- ...- ]- ```-- or, using explicit record syntax:-- ``` haskell- [ MailItem- { name = "name"- , address = "address"- , query = "query"- }- ...- ]- ```-- where-- - `name` is what gets printed in the status bar before the number- of new threads.- - `address` is the e-mail address of the recipient, i.e. we only- query mail that was send to this particular address (in more- concrete terms, we pass the address to the `to:` constructor when- performing the search). If `address` is empty, we search through- all unread mail, regardless of whom it was sent to.- - `query` is funneled to `notmuch search` verbatim. For the general- query syntax, consult `notmuch search --help`, as well as- `notmuch-search-terms(7)`. Note that the `unread` tag is- **always** added in front of the query and composed with it via an- **and**.--- Rate: Rate with which to update the plugin (in deciseconds).-- Example:-- - A single `MailItem` that displays all unread threads from the given- address:-- ``` haskell- MailItem "mbs:" "soliditsallgood@mailbox.org" ""- ```-- - A single `MailItem` that displays all unread threads with- "[My-Subject]" somewhere in the title:-- ``` haskell- MailItem "S:" "" "subject:[My-Subject]"- ```-- - A full example of a `NotmuchMail` configuration:-- ``` 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- ```--## `XPropertyLog PropName`--- Aliases to `PropName`-- Reads the X property named by `PropName` (a string) and displays its- value. The [examples/xmonadpropwrite.hs script] in xmobar's- distribution can be used to set the given property from the output- of any other program or script.--[examples/xmonadpropwrite.hs script]: https://github.com/jaor/xmobar/raw/master/examples/xmonadpropwrite.hs--## `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:-- ``` haskell- Run Brightness ["-t", "<bar>"] 60- ```--## `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:-- ``` haskell- Run Kbd [("us(dvorak)", "DV"), ("us", "US")]- ```--## `Locks`--- Displays the status of Caps Lock, Num Lock and Scroll Lock.-- Aliases to `locks`-- Example:-- ``` haskell- Run Locks- ```--## `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:-- ``` haskell- Run CatInt 0 "/sys/devices/platform/thinkpad_hwmon/fan1_input" [] 50- ```--## `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:-- ``` haskell- Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900- ```--# 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.:-- ``` haskell- Run Com "uname" ["-s","-r"] "" 0- ```--can be used in the output template as `%uname%` (and xmobar will call-_uname_ only once), while-- ``` haskell- Run Com "date" ["+\"%a %b %_d %H:%M\""] "mydate" 600- ```--can be used in the output template as `%mydate%`.--Sometimes, you don't mind if the command executed exits with an error,-or you might want to display a custom message in that case. To that-end, you can use the `ComX` variant:--`ComX ProgramName Args ExitMessage Alias RefreshRate`--Works like `Com`, but displaying `ExitMessage` (a string) if the-execution fails. For instance:-- ``` haskell- Run ComX "date" ["+\"%a %b %_d %H:%M\""] "N/A" "mydate" 600- ```--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:- ```<action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action>```--## `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:-- ``` haskell- Run Date "%a %b %_d %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10- ```--## `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:-- ``` haskell- Run DateZone "%a %H:%M:%S" "de_DE.UTF-8" "Europe/Vienna" "viennaTime" 10- ```--## `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-- ``` haskell- Run MarqueePipeReader "/tmp/testpipe" (10, 7, "+") "mpipe"- ```--- Expands environment variables in the first argument--## `BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]`--- Display data from multiple pipes.-- Timeout (in tenth of seconds) is the value after which the previous- content is restored i.e. if there was already something from a- previous pipe it will be put on display again, overwriting the- current status.-- A pipe with Timeout of 0 will be displayed permanently, just like- `PipeReader`-- The boolean option indicates whether new data for this pipe should- make xmobar appear (unhide, reveal). In this case, the Timeout- additionally specifies when the window should be hidden again. The- output is restored in any case.-- Use it for OSD-like status bars e.g. for setting the volume or- brightness:-- ``` haskell- Run BufferedPipeReader "bpr"- [ ( 0, False, "/tmp/xmobar_window" )- , ( 15, True, "/tmp/xmobar_status" )- ]- ```-- Have your window manager send window titles to- `"/tmp/xmobar_window"`. They will always be shown and not reveal- your xmobar. Sending some status information to- `"/tmp/xmobar_status"` will reveal xmonad for 1.5 seconds and- temporarily overwrite the window titles.-- Take a look at [examples/status.sh]-- Expands environment variables for the pipe path--[examples/status.sh]: http://github.com/jaor/xmobar/raw/master/examples/status.sh---## `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 [here]):-- ``` haskell- main = do- spawn "xmobar"- xmonad $ defaultConfig {- logHook = dynamicLogString defaultPP >>= xmonadPropLog- }- ```-- This plugin can be used as a sometimes more convenient alternative- to `StdinReader`. For instance, it allows you to (re)start xmobar- outside xmonad.--[here]: http://xmonad.org/xmonad-docs/xmonad-contrib/XMonad-Hooks-DynamicLog.html--## `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:-- ``` haskell- myPP = defaultPP { ppTitle = xmobarStrip }- main = xmonad $ defaultConfig {- logHook = dynamicLogString myPP >>= xmonadPropLog- }- ```--## `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:-- ``` haskell- (readHandle, writeHandle) <- createPipe- xmobarProcess <- forkProcess $ xmobar myConfig- { commands =- Run (HandleReader readHandle "handle") : commands myConfig- }- hPutStr writeHandle "Hello World"- ```--# The DBus Interface--When compiled with the optional `with_dbus` flag, xmobar can be-controlled over dbus. All signals defined in [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.--[src/Signal.hs]: https://github.com/jaor/xmobar/blob/master/src/Xmobar/System/Signal.hs--- 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:-- dbus-send \- --session \- --dest=org.Xmobar.Control \- --type=method_call \- --print-reply \- '/org/Xmobar/Control' \- org.Xmobar.Control.SendSignal \- "string:Toggle 0"--It is also possible to send multiple signals at once:-- # send to another screen, reveal and toggle the persistent flag- dbus-send [..] \- "string:ChangeScreen 0" "string:Reveal 0" "string:TogglePersistent"--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.-- ``` haskell- ((0, xK_Alt_L ), return ())- ```--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).-- ``` 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- ```--# 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 2-optional ones (alias and rate):-- ``` haskell- start :: e -> (String -> IO ()) -> IO ()- run :: e -> IO String- rate :: e -> Int- alias :: e -> String- ```--`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 `examples/xmobar.hs` for an-example of a plugin that runs just once, and-`src/Xmobar/Plugins/Date.hs` for one that implements `rate`.--Notice that Date could be implemented as:-- ``` 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- ```--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 [the author's-configuration](https://gitlab.com/jaor/xmobar-config/).--# Authors and credits--Andrea Rossato originally designed and implemented xmobar up to-version 0.11.1. Since then, it is maintained and developed by-[jao](https://jao.io), with the help of the greater xmobar and Haskell-communities.--In particular, xmobar incorporates patches by Mohammed Alshiekh, Alex-Ameen, Axel Angel, Dhananjay Balan, Claudio Bley, Dragos Boca, Ben-Boeckel, Ivan Brennan, Duncan Burke, Roman Cheplyaka, Patrick Chilton,-Antoine Eiche, Nathaniel Wesley Filardo, John Goerzen, Reto Hablützel,-Juraj Hercek, Tomáš Janoušek, Ada Joule, Spencer Janssen, Roman Joost,-Jochen Keil, Lennart Kolmodin, Krzysztof Kosciuszkiewicz, Dmitry-Kurochkin, Todd Lunter, Vanessa McHale, Robert J. Macomber, Dmitry-Malikov, David McLean, Marcin Mikołajczyk, Dino Morelli, Tony Morris,-Eric Mrak, Thiago Negri, Edward O'Callaghan, Svein Ove, Martin Perner,-Jens Petersen, Alexander Polakov, Sibi Prabakaran, Pavan Rikhi, Petr-Rockai, Andrew Emmanuel Rosa, Sackville-West, Markus Scherer, Daniel-Schüssler, Olivier Schneider, Alexander Shabalin, Valentin Shirokov,-Peter Simons, Alexander Solovyov, Will Song, John Soros, Felix-Springer, Travis Staton, Artem Tarasov, Samuli Thomasson, Edward-Tjörnhammar, Sergei Trofimovich, Thomas Tuegel, John Tyree, Jan-Vornberger, Anton Vorontsov, Daniel Wagner, Zev Weiss, Phil Xiaojun-Hu, Edward Z. Yang and Norbert Zeh.--## Thanks--__Andrea Rossato__:--Thanks to Robert Manea and Spencer Janssen for their help in-understanding how X works. They gave me suggestions on how to solve-many problems with xmobar.--Thanks to Claus Reinke for make me understand existential types (or at-least for letting me think I grasp existential types...;-).--__jao__:--Thanks to Andrea for creating xmobar in the first place, and for-giving me the chance to contribute.--# Related--- To understand the internal mysteries of xmobar you may try reading- [this tutorial] on X Window Programming in Haskell.--[this tutorial]: http://www.haskell.org/haskellwiki/X_window_programming_in_Haskell--# License--This software is released under a BSD-style license. See [license] for-more details.--Copyright © 2010-2020 Jose Antonio Ortega Ruiz--Copyright © 2007-2010 Andrea Rossato--[Github]: http://github.com/jaor/xmobar/-[Github page]: http://github.com/jaor/xmobar-[Hackage]: http://hackage.haskell.org/package/xmobar/-[LICENSE]: https://github.com/jaor/xmobar/raw/master/license-[Mailing list]: http://projects.haskell.org/cgi-bin/mailman/listinfo/xmobar-[MPD]: http://mpd.wikia.com/-[X11-xft]: http://hackage.haskell.org/package/X11-xft/-[i3status]: http://i3wm.org/i3status/-[i3status manual]: http://i3wm.org/i3status/manpage.html#_using_i3status_with_xmobar-[iwlib]: http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html-[libasound]: http://packages.debian.org/stable/libasound2-dev-[hinotify]: http://hackage.haskell.org/package/hinotify/-[libmpd]: http://hackage.haskell.org/package/libmpd/-[dbus]: http://hackage.haskell.org/package/dbus-[text]: http://hackage.haskell.org/package/text-[sawfish]: http://sawfish.wikia.com/-[utf8-string]: http://hackage.haskell.org/package/utf8-string/-[alsa-core]: http://hackage.haskell.org/package/alsa-core-[alsa-mixer]: http://hackage.haskell.org/package/alsa-mixer-[timezone-olson]: http://hackage.haskell.org/package/timezone-olson-[timezone-series]: http://hackage.haskell.org/package/timezone-series-[libXpm]: http://cgit.freedesktop.org/xorg/lib/libXpm-[http-conduit]: http://hackage.haskell.org/package/http-conduit-[http-types]: http://hackage.haskell.org/package/http-types
+ readme.org view
@@ -0,0 +1,170 @@+[[http://hackage.haskell.org/package/xmobar][https://img.shields.io/hackage/v/xmobar.svg]]++* About++Xmobar is a minimalistic status bar. It was originally designed and+implemented by Andrea Rossato to work with [[http://xmonad.org][xmonad]], but it is actually+usable with any window manager.++Xmobar was inspired by the [[http://tuomov.iki.fi/software/][Ion3]] status bar, and supports similar+features, like dynamic color management, icons, output templates, and+extensibility through plugins.++These are some xmobar [[file:doc/screenshots][screenshots]] using the author's configuration:++[[file:doc/screenshots/xmobar-top.png]]++[[file:doc/screenshots/xmobar-bottom.png]]++[[file:doc/screenshots/xmobar-exwm.png]]++This is the [[https://xmobar.org/changelog.html][changelog]] for recent releases.++* Installation+** From your Systems Package Manager++Xmobar is probably available from your distributions package manager!+Most distributions compile xmobar with the =all_extensions= flag, so you+don't have to.++*** Arch Linux++#+begin_src shell+ pacman -S xmobar+#+end_src++*** Debian/Ubuntu based++#+begin_src shell+ apt install xmobar+#+end_src++*** OpenSUSE++#+begin_src shell+ zypper install xmobar+#+end_src++*** Void Linux++#+begin_src shell+ xbps-install xmobar+#+end_src++** Using cabal-install++Xmobar is available from [[http://hackage.haskell.org/package/xmobar/][Hackage]], and you can install it using+=cabal-install=:++#+begin_src shell+ cabal install xmobar+#+end_src++Starting with version 0.35.1, xmobar now requires at least GHC version+8.4.x. to build. See [[https://github.com/jaor/xmobar/issues/461][this issue]] for more information.++See [[file:doc/compiling.org][compiling]] for a list of optional compilation flags that will enable+some optional plugins. For instance, to install xmobar with all the+bells and whistles (this is probably what you want), use:++#+begin_src shell+ cabal install xmobar --flags="all_extensions"+#+end_src++** From source++See [[file:doc/compiling.org][compiling]].++* Running xmobar++You can run xmobar with:++#+begin_src shell+ xmobar /path/to/config &+#+end_src++or++#+begin_src shell+ xmobar &+#+end_src++if you have the default configuration file saved as+=$XDG\_CONFIG\_HOME/xmobar/xmobarrc= (defaulting to+=~/.config/xmobar/xmobarrc=), or =~/.xmobarrc=.++** Signal Handling++Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2:++- After receiving SIGUSR1 xmobar moves its position to the next screen.++- After receiving SIGUSR2 xmobar repositions itself on the current+ screen.++* Configuration and Further Links++- If you want to jump straight into configuring xmobar, head over to the+ [[./doc/quick-start.org][quick-start]] guide.++- If you want to get a detailed overview of all available plugins and+ monitors, visit the [[./doc/plugins.org][plugins]] file.++- If you want to know how to contribute to the xmobar project, check out+ [[contributing.org][contributing]].++- If you want to write your own plugins, see [[./doc/write-your-own-plugin.org][write-your-own-plugin]].++* Authors and credits++Andrea Rossato originally designed and implemented xmobar up to version+0.11.1. Since then, it is maintained and developed by [[https://jao.io][jao]], with the help+of the greater xmobar and Haskell communities.++In particular, xmobar incorporates patches by Mohammed Alshiekh, Alex+Ameen, Axel Angel, Dhananjay Balan, Claudio Bley, Dragos Boca, Ben+Boeckel, Ivan Brennan, Duncan Burke, Roman Cheplyaka, Patrick Chilton,+Antoine Eiche, Nathaniel Wesley Filardo, John Goerzen, Reto Hablützel,+Juraj Hercek, Tomáš Janoušek, Ada Joule, Spencer Janssen, Roman Joost,+Jochen Keil, Lennart Kolmodin, Krzysztof Kosciuszkiewicz, Dmitry+Kurochkin, Todd Lunter, Vanessa McHale, Robert J. Macomber, Dmitry+Malikov, David McLean, Marcin Mikołajczyk, Dino Morelli, Tony Morris,+Eric Mrak, Thiago Negri, Edward O'Callaghan, Svein Ove, Martin Perner,+Jens Petersen, Alexander Polakov, Sibi Prabakaran, Pavan Rikhi, Petr+Rockai, Andrew Emmanuel Rosa, Sackville-West, Markus Scherer, Daniel+Schüssler, Olivier Schneider, Alexander Shabalin, Valentin Shirokov,+Peter Simons, Alexander Solovyov, Will Song, John Soros, Felix Springer,+Travis Staton, Artem Tarasov, Samuli Thomasson, Edward Tjörnhammar,+Sergei Trofimovich, Thomas Tuegel, John Tyree, Jan Vornberger, Anton+Vorontsov, Daniel Wagner, Zev Weiss, Phil Xiaojun Hu, Edward Z. Yang and+Norbert Zeh.++** Thanks++*Andrea Rossato*:++Thanks to Robert Manea and Spencer Janssen for their help in+understanding how X works. They gave me suggestions on how to solve many+problems with xmobar.++Thanks to Claus Reinke for make me understand existential types (or at+least for letting me think I grasp existential types...;-).++*jao*:++Thanks to Andrea for creating xmobar in the first place, and for giving+me the chance to contribute.++* Related++- To understand the internal mysteries of xmobar you may try reading+ [[https://wiki.haskell.org/X_window_programming_in_Haskell][this tutorial]] on X Window Programming in Haskell.++* License++This software is released under a BSD-style license. See [[https://github.com/jaor/xmobar/raw/master/license][license]] for+more details.++Copyright © 2010-2020 Jose Antonio Ortega Ruiz++Copyright © 2007-2010 Andrea Rossato
src/Xmobar/App/Compile.hs view
@@ -165,7 +165,7 @@ #ifdef THREADED_RUNTIME ++ ["-threaded"] #endif-#ifdef DRTSOPTS+#ifdef RTSOPTS ++ ["-rtsopts", "-with-rtsopts", "-V0"] #endif ++ ["-o", bin]
src/Xmobar/Plugins/Monitors/Cpu.hs view
@@ -1,3 +1,4 @@+{-#LANGUAGE CPP #-} {-#LANGUAGE RecordWildCards#-} -----------------------------------------------------------------------------@@ -29,6 +30,9 @@ import Xmobar.Plugins.Monitors.Common import qualified Data.ByteString.Lazy.Char8 as B import Data.IORef (IORef, newIORef, readIORef, writeIORef)+#ifdef FREEBSD+import System.BSD.Sysctl (sysctlPeekArray)+#endif import System.Console.GetOpt import Xmobar.App.Timer (doEveryTenthSeconds) import Control.Monad (void)@@ -90,6 +94,43 @@ , iowaitField ] +data CpuData = CpuData {+ cpuUser :: !Float,+ cpuNice :: !Float,+ cpuSystem :: !Float,+ cpuIdle :: !Float,+ cpuIowait :: !Float,+ cpuTotal :: !Float+ }++#ifdef FREEBSD+-- kern.cp_time data from the previous iteration for computing the difference+type CpuDataRef = IORef [Word]++cpuData :: IO [Word]+cpuData = sysctlPeekArray "kern.cp_time" :: IO [Word]++parseCpu :: CpuDataRef -> IO CpuData+parseCpu cref = do+ prev <- readIORef cref+ curr <- cpuData+ writeIORef cref curr+ let diff = map fromIntegral $ zipWith (-) curr prev+ user = diff !! 0+ nice = diff !! 1+ system = diff !! 2+ intr = diff !! 3+ idle = diff !! 4+ total = user + nice + system + intr + idle+ return CpuData+ { cpuUser = user/total+ , cpuNice = nice/total+ , cpuSystem = (system+intr)/total+ , cpuIdle = idle/total+ , cpuIowait = 0+ , cpuTotal = user/total+ }+#else type CpuDataRef = IORef [Int] -- Details about the fields here: https://www.kernel.org/doc/Documentation/filesystems/proc.txt@@ -104,15 +145,6 @@ cpuParser :: B.ByteString -> [Int] cpuParser = map readInt . tail . B.words . head . B.lines -data CpuData = CpuData {- cpuUser :: !Float,- cpuNice :: !Float,- cpuSystem :: !Float,- cpuIdle :: !Float,- cpuIowait :: !Float,- cpuTotal :: !Float- }- convertToCpuData :: [Float] -> CpuData convertToCpuData (u:n:s:ie:iw:_) = CpuData@@ -137,6 +169,7 @@ v -> fromIntegral n / v percent = map safeDiv dif return $ convertToCpuData percent+#endif data Field = Field { fieldName :: !String,
src/Xmobar/X11/Draw.hs view
@@ -89,7 +89,7 @@ liftIO $ freeGC d gc liftIO $ freePixmap d p -- resync- liftIO $ sync d True+ liftIO $ sync d False verticalOffset :: (Integral b, Integral a, MonadIO m) => a -> Widget -> XFont -> Int -> Config -> m b
src/Xmobar/X11/MinXft.hsc view
@@ -161,16 +161,10 @@ foreign import ccall "XftDrawStringUtf8" cXftDrawStringUtf8 :: AXftDraw -> AXftColor -> AXftFont -> CInt -> CInt -> Ptr (#type FcChar8) -> CInt -> IO () --- Fixes https://github.com/jaor/xmobar/issues/476-utf8EncodeString :: Num b => String -> [b]-utf8EncodeString str = if UTF8.isUTF8Encoded str- then map (fi . ord) str- else map fi (UTF8.encode str)- drawXftString :: (Integral a1, Integral a) => AXftDraw -> AXftColor -> AXftFont -> a -> a1 -> String -> IO () drawXftString d c f x y string =- withArrayLen (utf8EncodeString string)+ withArrayLen (map fi (UTF8.encode string)) (\len ptr -> cXftDrawStringUtf8 d c f (fi x) (fi y) ptr (fi len)) drawXftString' :: AXftDraw ->
src/Xmobar/X11/Text.hs view
@@ -118,7 +118,7 @@ return (a,d) textExtents (Utf8 fs) s = do let (_,rl) = wcTextExtents fs s- ascent = fromIntegral $ - (rect_y rl)+ ascent = fromIntegral $ negate (rect_y rl) descent = fromIntegral $ rect_height rl + fromIntegral (rect_y rl) return (ascent, descent) #ifdef XFT
src/Xmobar/X11/Window.hs view
@@ -69,6 +69,7 @@ r = setPosition c (position c) srs (fromIntegral ht) moveResizeWindow d win (rect_x r) (rect_y r) (rect_width r) (rect_height r) setStruts r c d win srs+ sync d False return r fi :: (Integral a, Num b) => a -> b@@ -175,7 +176,7 @@ where st = cy + ch sb = rwh - cy xs = cx -- a simple calculation for horizontal (x) placement- xe = xs + cw+ xe = xs + cw - 1 getStaticStrutValues _ _ = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0] drawBorder :: Border -> Int -> Display -> Drawable -> GC -> Pixel
xmobar.cabal view
@@ -1,5 +1,5 @@ name: xmobar-version: 0.37+version: 0.38 homepage: http://xmobar.org synopsis: A Minimalistic Text Based Status Bar description: Xmobar is a minimalistic text based status bar.@@ -16,7 +16,8 @@ cabal-version: >= 1.10 build-type: Simple -extra-source-files: readme.md, changelog.md,+extra-source-files: readme.org, changelog.md,+ doc/quick-start.org, doc/plugins.org examples/padding-icon.sh, examples/xmobar.config, examples/xmobar.hs,@@ -98,6 +99,7 @@ exposed-modules: Xmobar, Xmobar.Plugins.Monitors.Common.Types, Xmobar.Plugins.Monitors.Common.Run,+ Xmobar.Plugins.Monitors.Common, Xmobar.Plugins.Monitors.Cpu other-modules: Paths_xmobar,@@ -143,7 +145,6 @@ Xmobar.Plugins.NotmuchMail, Xmobar.Plugins.Monitors, Xmobar.Plugins.Monitors.Batt,- Xmobar.Plugins.Monitors.Common, Xmobar.Plugins.Monitors.Common.Output, Xmobar.Plugins.Monitors.Common.Parsers, Xmobar.Plugins.Monitors.Common.Files,