diff --git a/changelog.md b/changelog.md --- a/changelog.md +++ b/changelog.md @@ -1,4 +1,9 @@ -## Version 0.44.1 (July, 20022) +## Version 0.44.2 (August, 2022) + +- Documentation improvements. +- Missing doc files and xmobar.el added to distribution. + +## Version 0.44.1 (July, 2022) Repository moved to Codeberg. No code changes. diff --git a/doc/compiling.org b/doc/compiling.org new file mode 100644 --- /dev/null +++ b/doc/compiling.org @@ -0,0 +1,113 @@ +#+title: Compiling xmobar from source + +If you don't have =cabal-install= installed, you can get xmobar's source +code in a variety of ways: + +- From [[http://hackage.haskell.org/package/xmobar/][Hackage]]. Just download the latest release from xmobar's hackage + page. + +- From [[http://codeberg.org/xmobar/xmobar/][Codeberg]]. There are also tarballs available for every tagged + release on [[https://codeberg.org/xmobar/xmobar/releases][Codeberg's releases page]] + +- From the bleeding edge repo. If you prefer to live dangerously, just + get the latest and greatest (and buggiest, I guess) using git: + + #+begin_src shell + git clone git://codeberg.org/xmobar/xmobar + #+end_src + +If you have cabal installed, you can now use it from within xmobar's +source tree: + +#+begin_src shell + cabal install --flags="all_extensions" +#+end_src + +There is also a =stack.yaml= file that will allow you to install the +xmobar executable with + +#+begin_src shell + stack install +#+end_src + +See the =stack.yaml= file for the enabled extensions. You can also pass +them to =stack= directly: + +#+begin_src shell + stack install --flag xmobar:all_extensions +#+end_src + +** Optional features + :PROPERTIES: + :CUSTOM_ID: optional-features + :END: + + 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 [[http://hackage.haskell.org/package/dbus][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 [[http://hackage.haskell.org/package/utf8-string/][utf8-string]] package. + + - =with_xft= Antialiased fonts. Requires the [[http://hackage.haskell.org/package/X11-xft/][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: + + #+begin_src haskell + font = "xft:Times New Roman-10:italic" + #+end_src + + Or to have fallback fonts, just separate them by commas: + + #+begin_src haskell + font = "xft:Open Sans:size=9,WenQuanYi Zen Hei:size=9" + #+end_src + + - =with_mpd= Enables support for the [[http://mpd.wikia.com/][MPD]] daemon. Requires the [[http://hackage.haskell.org/package/libmpd/][libmpd]] + package. + + - =with_mpris= Enables support for MPRIS v1/v2 protocol. Requires the + [[http://hackage.haskell.org/package/dbus][dbus]] and [[http://hackage.haskell.org/package/text][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 + [[http://hackage.haskell.org/package/hinotify/][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 [[http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html][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 [[http://hackage.haskell.org/package/alsa-mixer][alsa-mixer]] package. To install the latter, you'll need + the [[http://packages.debian.org/stable/libasound2-dev][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 [[http://hackage.haskell.org/package/timezone-olson][timezone-olson]] and [[http://hackage.haskell.org/package/timezone-series][timezone-series]] package. + + - =with_xpm= Support for xpm image file format. This will allow loading + .xpm files in ==. Requires the [[http://cgit.freedesktop.org/xorg/lib/libXpm][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. diff --git a/doc/plugins.org b/doc/plugins.org --- a/doc/plugins.org +++ b/doc/plugins.org @@ -1,1371 +1,1591 @@ #+title: Plugins and monitors -* System Monitor Plugins - - This is the description of the system monitor plugins available in - xmobar. Some of them are only installed when an optional build - option is set: we mention that fact, when needed, in their - description. - - Each monitor has an =alias= to be used in the output - template. Monitors may have default aliases, see the documentation - of the monitor in question. - - There are two types of arguments: ones that all monitors share (the - so called /default monitor arguments/) and arguments that are specific - to a certain monitor. - - All Monitors accept a common set of arguments, described below in - [[Default Monitor Arguments]]. Some monitors also accept additional - options that are specific to them. When specifying the list of - arguments in your configuration, the common options come first, - followed by =--=, followed by any monitor-specific options. For - example, the following [[=Battery 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", "" - , "--Low" , "15" - -- battery specific options start here. - , "--" - , "--off" , " ()" - ] - 100 - #+end_src - - See also [[./window-managers.org][Interfacing with window managers]] for a collection of - plugins that let you interact and control xmobar from window - managers. - -*** Icon Patterns - - Some monitors allow usage of strings that depend on some integer - value from 0 to 8 by replacing all occurrences of =%%= with it - (i.e. == will be interpreted as - == when the value is =3=, also =%= is - interpreted as =%=, =%%= as =3=, =%%%= as =3%=, =%%%%= as =33= and so - on). Essentially it allows to replace vertical bars with custom - icons. For example, - - #+begin_src haskell - Run Brightness - [ "-t", "" - , "--" - , "--brightness-icon-pattern", "" - ] 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 (==) 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 - == (or ==) and ==. 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", ": 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= - :PROPERTIES: - :CUSTOM_ID: batteryp-dirs-args-refreshrate - :END: - - - 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: , % / = - - - Example (note that you need "--" to separate regular monitor options - from Battery's specific ones): - - #+begin_src haskell - Run BatteryP ["BAT0"] - ["-t", " (%)", - "-L", "10", "-H", "80", "-p", "3", - "--", "-O", "On - ", "-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 == and == fields, while those after the - separator affect how == is displayed. For this monitor, neither - the generic nor the specific options have any effect on ==. - 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", "" - , "-L", "10", "-H", "80" - , "-l", "red", "-h", "green" - , "--", "-O", "Charging", "-o", "Battery: %" - ] 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: %= - -***** =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: %= - -***** =CpuFreq Args RefreshRate= - - - Aliases to =cpufreq= - - - Args: default monitor arguments - - - Thresholds refer to frequency in GHz - - - Variables that can be used with the =-t/--template= argument: - =cpu0=, =cpu1=, .., =cpuN=, give the current frequency of the - respective CPU core, and =max=, =min= and =avg= the maximum, minimum - and average frequency over all available cores. - - - Default template: =Freq: GHz= - - - This monitor requires acpi_cpufreq module to be loaded in kernel - - - Example: - - #+begin_src haskell - Run CpuFreq ["-t", "Freq:|GHz", "-L", "0", "-H", "2", - "-l", "lightblue", "-n","white", "-h", "red"] 50 - - Run CpuFreq ["-t", "Freq: 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: C= - - - This monitor requires coretemp module to be loaded in kernel - - - Example: - - #+begin_src haskell - Run CoreTemp ["-t", "Temp:|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. - - =--hwmon-path=: this monitor tries to find coretemp devices by - looking for them in directories following the pattern - =/sys/bus/platform/devices/coretemp.*/hwmon/hwmon*=, but some - processors (notably Ryzen) might expose those files in a different - tree (e.g., Ryzen) puts them somewhere in "/sys/class/hwmon/hwmon*", - and the lookup is most costly. With this option, it is possible to - explicitly specify the full path to the directory where the - =tempN_label= and =tempN_input= files are located. - - - Thresholds refer to temperature in degree Celsius - - - Variables that can be used with the =-t/--template= argument: =max=, - =maxpc=, =maxbar=, =maxvbar=, =maxipat=, =avg=, =avgpc=, =avgbar=, - =avgvbar=, =avgipat=, =core0=, =core1=, ..., =coreN= - - The /pc, /bar, /vbar and /ipat variables are showing percentages on - the scale defined by =--mintemp= and =--maxtemp=. The max* and avg* - variables to the highest and the average core temperature. - - - Default template: =Temp: °C - %= - - - This monitor requires coretemp module to be loaded in kernel - - - Example: - - #+begin_src haskell - Run MultiCoreTemp ["-t", "Temp: °C | %", - "-L", "60", "-H", "80", - "-l", "green", "-n", "yellow", "-h", "red", - "--", "--mintemp", "20", "--maxtemp", "100"] 50 - #+end_src - -***** =K10Temp Slot Args RefreshRate= - - - Aliases to =k10temp= - - - Slot: The PCI slot address of the k10temp device as a string. You - can find it as a subdirectory in =/sys/bus/pci/drivers/k10temp/=. - - - Args: default monitor arguments - - - Thresholds refer to temperature in degrees - - - Variables that can be used with the =-t/--template= argument: - =Tctl=, =Tdie=, =Tccd1=, .., =Tccd8= - - - Default template: =Temp: C= - - - This monitor requires k10temp module to be loaded in kernel - - - It is important to note that not all measurements are available - on on all models of processor. Of particular importance - Tdie - (used in the default template) may not be present on processors - prior to Zen (17h). Tctl, however, may be offset from the real - temperature and so is not used by default. - - - Example: - - #+begin_src haskell - Run K10Temp "0000:00:18.3" - ["-t", "Temp: C|C", - "-L", "40", "-H", "60", - "-l", "lightblue", "-n", "gray90", "-h", "red"] - 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=. - - =--scale=: sizes (total, free, etc.) are reported in units of - ~Mb/scale~, with scale defaulting to 1.0. So, for - instance, to get sizes reported in Gb, set this parameter - to 1024. - - - Thresholds refer to percentage of used memory - - Variables that can be used with the =-t/--template= argument: - =total=, =free=, =buffer=, =cache=, =available=, =used=, =usedratio=, - =usedbar=, =usedvbar=, =usedipat=, =freeratio=, =freebar=, =freevbar=, - =freeipat=, =availableratio=, =availablebar=, =availablevbar=, - =availableipat= - - - Default template: =Mem: % (M)= - - - Examples: - - #+begin_src haskell - -- A monitor reporting memory used in Gb - Memory [ "-t", " Gb", "--", "--scale", "1024"] 20 - -- As above, but using one decimal digit to print numbers - Memory [ "-t", " Gb", "-d", "1", "--", "--scale", "1024"] 20 - #+end_src - -***** =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: %= - -*** 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 %H:%M:%S" "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 ==, ==, ==, == - or ==, ==, ==, ==, ==, - == or == 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 [("/", "/"), ("sdb1", "")] - ["-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 ==, ==, == for - total, read and write speed, respectively, as well as ==, - ==, ==, which report number of bytes during the last - refresh period rather than speed. There are also bar versions of each: - ==, ==, ==, ==, ==, - ==, ==, ==, and ==; and - their "bytes" counterparts: ==, ==, - ==, ==, ==, ==, - ==, ==, and ==. - - - 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 - ==. - - =--write-icon-pattern=: dynamic string for write disk I/O in - ==. - - =--read-icon-pattern=: dynamic string for read disk I/O in - ==. - - - Default template: none (you must specify a template for each file - system). - - - Example: - - #+begin_src haskell - DiskIO [("/", " "), ("sdb1", "")] [] 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 - -*** Load and Process Monitors -***** =Load Args RefreshRate= - - - Aliases to =load= - - - Args: default monitor arguments. The low and high thresholds - (=-L= and =-H=) refer to load average values. - - - Variables that can be used with the =-t/--template= argument: - =load1=, =load5=, =load15=. - - - Default template: =Load: =. - - - Displays load averages for the last 1, 5 or 15 minutes as - reported by, e.g., ~uptime(1)~. The displayed values are float, - so that the ~"-d"~ option will control how many decimal digits - are shown (zero by default). - - - Example: to have 2 decimal digits displayed, with a low - threshold at 1.0 and a high one at 3, you'd write something - like: - - #+begin_src haskell - Run Load ["-t" , " " - , "-L", "1", "-H", "3", "-d", "2"]) 300 - #+end_src - -***** =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: == - - 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: == - - 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: =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",": 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: 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: 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 == when the mixer element is - on. Defaults to "[on]". - - Long option: =--on= - - - =-o= /string/ Off string - - - The string used in place of == when the mixer element is - off. Defaults to "[off]". - - Long option: =--off= - - - =-C= /color/ On color - - - The color to be used for == when the mixer element is on. - Defaults to "green". - - Long option: =--onc= - - - =-c= /color/ Off color - - - The color to be used for == 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 == 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 == 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 == 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: % = - - 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 - - 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: = - - - Example (note that you need "--" to separate regular monitor options - from MPD's specific ones): - - #+begin_src haskell - Run MPD ["-t", - " (<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 B/s - - Args: default monitor arguments, plus: - - - =--rx-icon-pattern=: dynamic string for reception rate in =rxipat=. - - =--tx-icon-pattern=: dynamic string for transmission rate in - =txipat=. - - =--up=: string used for the =up= variable value when the interface - is up. - - - Variables that can be used with the =-t=/=--template= argument: =dev=, - =rx=, =tx=, =rxbar=, =rxvbar=, =rxipat=, =txbar=, =txvbar=, =txipat=, - =up=. Reception and transmission rates (=rx= and =tx=) are displayed - by default as KB/s, without any suffixes, but you can set the =-S= to - "True" to make them displayed with adaptive units (KB/s, MB/s, etc.). - - Default template: =<dev>: <rx>KB|<tx>KB= - -***** =DynNetwork Args RefreshRate= - - - Active interface is detected automatically - - Aliases to "dynnetwork" - - Thresholds are expressed in B/s - - Args: default monitor arguments, plus: - - - =--rx-icon-pattern=: dynamic string for reception rate in =rxipat=. - - =--tx-icon-pattern=: dynamic string for transmission rate in =txipat= - - =--devices=: comma-separated list of devices to show. - - - Variables that can be used with the =-t=/=--template= argument: - =dev=, =rx=, =tx=, =rxbar=, =rxvbar=, =rxipat=, =txbar=, =txvbar=, - =txipat=. - - Reception and transmission rates (=rx= and =tx=) are displayed in Kbytes - per second, and you can set the =-S= to "True" to make them displayed - with units (the string "KB/s"). - - Default template: =<dev>: <rx>KB|<tx>KB= - - Example of usage of =--devices= option: - - =["--", "--devices", "wlp2s0,enp0s20f41"]= - -***** =Wireless Interface Args RefreshRate= - - - If set to "", first suitable wireless interface is used. - - Aliases to the interface name with the suffix "wi": thus, - =Wireless "wlan0" []= can be used as =%wlan0wi%=, and - =Wireless "" []= as =%wi%=. - - Args: default monitor arguments, plus: - - - =--quality-icon-pattern=: dynamic string for connection quality in - =qualityipat=. - - - Variables that can be used with the =-t=/=--template= argument: - =ssid=, =signal=, =quality=, =qualitybar=, =qualityvbar=, - =qualityipat= - - Thresholds refer to link quality on a =[0, 100]= scale. Note that - =quality= is calculated from =signal= (in dBm) by a possibly lossy - conversion. It is also not taking into account many factors such as - noise level, air busy time, transcievers' capabilities and the others - which can have drastic impact on the link performance. - - Default template: =<ssid> <quality>= - - To activate this plugin you must pass the =with_nl80211= or the - =with_iwlib= flag during compilation. - -*** Weather Monitors - :PROPERTIES: - :CUSTOM_ID: weather-monitors - :END: -***** =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. Here is [[https://weather.rap.ucar.edu/surface/stations.txt][a sample list of station IDs]]. - -***** =WeatherX StationID SkyConditions Args RefreshRate= - - - Works in the same way as =Weather=, but takes an additional argument, - a list of pairs from sky conditions to their replacement (typically a - unicode string or an icon specification). - - Use the variable =skyConditionS= to display the replacement of the - corresponding sky condition. All other =Weather= template variables - are available as well. - - For example: - - #+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 - -* 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= +* 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 + + See also [[#interfacing-with-window-managers][Interfacing with window managers]] below for a collection of plugins + that let you interact and control xmobar from window managers. + +** Icon Patterns + + Some monitors allow usage of strings that depend on some integer + value from 0 to 8 by replacing all occurrences of =%%= with it + (i.e. =<icon=/path/to/icon_%%.xpm/>= will be interpreted as + =<icon=/path/to/icon_3.xpm/>= when the value is =3=, also =%= is + interpreted as =%=, =%%= as =3=, =%%%= as =3%=, =%%%%= as =33= and so + on). Essentially it allows to replace vertical bars with custom + icons. For example, + + #+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= + :PROPERTIES: + :CUSTOM_ID: batteryp-dirs-args-refreshrate + :END: + + - 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=, give the current frequency of the + respective CPU core, and =max=, =min= and =avg= the maximum, minimum + and average frequency over all available cores. + + - Default template: =Freq: <cpu0>GHz= + + - This monitor requires acpi_cpufreq module to be loaded in kernel + + - Example: + + #+begin_src haskell + Run CpuFreq ["-t", "Freq:<cpu0>|<cpu1>GHz", "-L", "0", "-H", "2", + "-l", "lightblue", "-n","white", "-h", "red"] 50 + + Run CpuFreq ["-t", "Freq:<avg> GHz", "-L", "0", "-H", "2", + "-l", "lightblue", "-n","white", "-h", "red"] 50 + #+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. + - =--hwmon-path=: this monitor tries to find coretemp devices by + looking for them in directories following the pattern + =/sys/bus/platform/devices/coretemp.*/hwmon/hwmon*=, but some + processors (notably Ryzen) might expose those files in a different + tree (e.g., Ryzen) puts them somewhere in "/sys/class/hwmon/hwmon*", + and the lookup is most costly. With this option, it is possible to + explicitly specify the full path to the directory where the + =tempN_label= and =tempN_input= files are located. + + - Thresholds refer to temperature in degree Celsius + + - Variables that can be used with the =-t/--template= argument: =max=, + =maxpc=, =maxbar=, =maxvbar=, =maxipat=, =avg=, =avgpc=, =avgbar=, + =avgvbar=, =avgipat=, =core0=, =core1=, ..., =coreN= + + The /pc, /bar, /vbar and /ipat variables are showing percentages on + the scale defined by =--mintemp= and =--maxtemp=. The max* and avg* + variables to the highest and the average core temperature. + + - Default template: =Temp: <max>°C - <maxpc>%= + + - This monitor requires coretemp module to be loaded in kernel + + - Example: + + #+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 + +*** =K10Temp Slot Args RefreshRate= + + - Aliases to =k10temp= + + - Slot: The PCI slot address of the k10temp device as a string. You + can find it as a subdirectory in =/sys/bus/pci/drivers/k10temp/=. + + - Args: default monitor arguments + + - Thresholds refer to temperature in degrees + + - Variables that can be used with the =-t/--template= argument: + =Tctl=, =Tdie=, =Tccd1=, .., =Tccd8= + + - Default template: =Temp: <Tdie>C= + + - This monitor requires k10temp module to be loaded in kernel + + - It is important to note that not all measurements are available + on on all models of processor. Of particular importance - Tdie + (used in the default template) may not be present on processors + prior to Zen (17h). Tctl, however, may be offset from the real + temperature and so is not used by default. + + - Example: + + #+begin_src haskell + Run K10Temp "0000:00:18.3" + ["-t", "Temp: <Tdie>C|<Tccd1>C", + "-L", "40", "-H", "60", + "-l", "lightblue", "-n", "gray90", "-h", "red"] + 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=. + - =--scale=: sizes (total, free, etc.) are reported in units of + ~Mb/scale~, with scale defaulting to 1.0. So, for + instance, to get sizes reported in Gb, set this parameter + to 1024. + + - Thresholds refer to percentage of used memory + - Variables that can be used with the =-t/--template= argument: + =total=, =free=, =buffer=, =cache=, =available=, =used=, =usedratio=, + =usedbar=, =usedvbar=, =usedipat=, =freeratio=, =freebar=, =freevbar=, + =freeipat=, =availableratio=, =availablebar=, =availablevbar=, + =availableipat= + + - Default template: =Mem: <usedratio>% (<cache>M)= + + - Examples: + + #+begin_src haskell + -- A monitor reporting memory used in Gb + Memory [ "-t", "<used> Gb", "--", "--scale", "1024"] 20 + -- As above, but using one decimal digit to print numbers + Memory [ "-t", "<used> Gb", "-d", "1", "--", "--scale", "1024"] 20 + #+end_src + +*** =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 and screen monitors +*** =Kbd Opts= + + - Registers to XKB/X11-Events and output the currently active keyboard + layout. Supports replacement of layout names. + + - Aliases to =kbd= + + - Opts is a list of tuples: + + - first element of the tuple is the search string + - second element of the tuple is the corresponding replacement + + - Example: + + #+begin_src haskell + Run Kbd [("us(dvorak)", "DV"), ("us", "US")] + #+end_src + +*** =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 +*** =Locks= + + - Displays the status of Caps Lock, Num Lock and Scroll Lock. + + - Aliases to =locks= + + - Example: + + #+begin_src haskell + Run Locks + #+end_src + +** Load and Process monitors +*** =Load Args RefreshRate= + + - Aliases to =load= + + - Args: default monitor arguments. The low and high thresholds + (=-L= and =-H=) refer to load average values. + + - Variables that can be used with the =-t/--template= argument: + =load1=, =load5=, =load15=. + + - Default template: =Load: <load1>=. + + - Displays load averages for the last 1, 5 or 15 minutes as + reported by, e.g., ~uptime(1)~. The displayed values are float, + so that the ~"-d"~ option will control how many decimal digits + are shown (zero by default). + + - Example: to have 2 decimal digits displayed, with a low + threshold at 1.0 and a high one at 3, you'd write something + like: + + #+begin_src haskell + Run Load ["-t" , "<load1> <load5> <load15>" + , "-L", "1", "-H", "3", "-d", "2"]) 300 + #+end_src + +*** =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 + + 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 B/s + - Args: default monitor arguments, plus: + + - =--rx-icon-pattern=: dynamic string for reception rate in =rxipat=. + - =--tx-icon-pattern=: dynamic string for transmission rate in + =txipat=. + - =--up=: string used for the =up= variable value when the interface + is up. + + - Variables that can be used with the =-t=/=--template= argument: =dev=, + =rx=, =tx=, =rxbar=, =rxvbar=, =rxipat=, =txbar=, =txvbar=, =txipat=, + =up=. Reception and transmission rates (=rx= and =tx=) are displayed + by default as KB/s, without any suffixes, but you can set the =-S= to + "True" to make them displayed with adaptive units (KB/s, MB/s, etc.). + - Default template: =<dev>: <rx>KB|<tx>KB= + +*** =DynNetwork Args RefreshRate= + + - Active interface is detected automatically + - Aliases to "dynnetwork" + - Thresholds are expressed in B/s + - Args: default monitor arguments, plus: + + - =--rx-icon-pattern=: dynamic string for reception rate in =rxipat=. + - =--tx-icon-pattern=: dynamic string for transmission rate in =txipat= + - =--devices=: comma-separated list of devices to show. + + - Variables that can be used with the =-t=/=--template= argument: + =dev=, =rx=, =tx=, =rxbar=, =rxvbar=, =rxipat=, =txbar=, =txvbar=, + =txipat=. + + Reception and transmission rates (=rx= and =tx=) are displayed in Kbytes + per second, and you can set the =-S= to "True" to make them displayed + with units (the string "KB/s"). + - Default template: =<dev>: <rx>KB|<tx>KB= + - Example of usage of =--devices= option: + + =["--", "--devices", "wlp2s0,enp0s20f41"]= + +*** =Wireless Interface Args RefreshRate= + + - If set to "", first suitable wireless interface is used. + - Aliases to the interface name with the suffix "wi": thus, + =Wireless "wlan0" []= can be used as =%wlan0wi%=, and + =Wireless "" []= as =%wi%=. + - Args: default monitor arguments, plus: + + - =--quality-icon-pattern=: dynamic string for connection quality in + =qualityipat=. + + - Variables that can be used with the =-t=/=--template= argument: + =ssid=, =signal=, =quality=, =qualitybar=, =qualityvbar=, + =qualityipat= + - Thresholds refer to link quality on a =[0, 100]= scale. Note that + =quality= is calculated from =signal= (in dBm) by a possibly lossy + conversion. It is also not taking into account many factors such as + noise level, air busy time, transcievers' capabilities and the others + which can have drastic impact on the link performance. + - Default template: =<ssid> <quality>= + - To activate this plugin you must pass the =with_nl80211= or the + =with_iwlib= flag during compilation. + +** Weather monitors + :PROPERTIES: + :CUSTOM_ID: weather-monitors + :END: +*** =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. Here is [[https://weather.rap.ucar.edu/surface/stations.txt][a sample list of station IDs]]. + +*** =WeatherX StationID SkyConditions Args RefreshRate= + + - Works in the same way as =Weather=, but takes an additional argument, + a list of pairs from sky conditions to their replacement (typically a + unicode string or an icon specification). + - Use the variable =skyConditionS= to display the replacement of the + corresponding sky condition. All other =Weather= template variables + are available as well. + + For example: + + #+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/>")=. + +*** =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 +** Other monitors +*** =CatInt n filename= + + - Reads and displays an integer from the file whose path is =filename= + (especially useful with files in =/sys=). + + - Aliases as =catn= (e.g. =Cat 0= as =cat0=, etc.) so you can have + several. + + - Example: + + #+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= + +* Interfacing with window managers + :PROPERTIES: + :CUSTOM_ID: interfacing-with-window-managers + :END: +** 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 [[../etc/xmonadpropwrite.hs][etc/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 [[../etc/status.sh][etc/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 + + +** Software Transactional Memory + + When invoking xmobar from other Haskell code it can be easier and more + performant to use shared memory. The following plugins leverage + =Control.Concurrent.STM= to realize these gains for xmobar. + +*** =QueueReader (TQueue a) (a -> String) String= + + - Display data from a Haskell =TQueue a=. + + - This plugin is only useful if you are running xmobar from another + haskell program like xmonad. + + - You should make an =IO= safe =TQueue a= with + =Control.Concurrent.STM.newTQueueIO=. Write to it from the user + code with =writeTQueue=, and read with =readTQueue=. A common use + is to overwite =ppOutput= from =XMonad.Hooks.DynamicLog= as shown + below. + + #+begin_src haskell + main :: IO () + main = do + initThreads + q <- STM.newTQueueIO @String + bar <- forkOS $ xmobar myConf + { commands = Run (QueueReader q id "XMonadLog") : commands myConf } + xmonad $ def { logHook = logWorkspacesToQueue q } + + logWorkspacesToQueue :: STM.TQueue String -> X () + logWorkspacesToQueue q = + dynamicLogWithPP def { ppOutput = STM.atomically . STM.writeTQueue q } + #+end_src + + Note that xmonad uses blocking Xlib calls in its event loop and isn't + normally compiled with + [[https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/using-concurrent.html][the threaded RTS]] + so an xmobar thread running inside xmonad will suffer from delayed + updates. It is thus necessary to enable =-threaded= when compiling + xmonad configuration (=xmonad.hs=), e.g. by using a custom + =~/.xmonad/build= script. + + + +* Executing external commands + + In order to execute an external command you can either write the + command name in the template, in this case it will be executed + without arguments, or you can configure it in the "commands" + configuration option list with the Com template command: + + =Com ProgramName Args Alias RefreshRate= + + - ProgramName: the name of the program + - Args: the arguments to be passed to the program at execution time + - RefreshRate: number of tenths of second between re-runs of the + command. A zero or negative rate means that the command will be + executed only once. + - Alias: a name to be used in the template. If the alias is en empty + string the program name can be used in the template. + + E.g.: + + #+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: diff --git a/doc/quick-start.org b/doc/quick-start.org --- a/doc/quick-start.org +++ b/doc/quick-start.org @@ -1,13 +1,10 @@ #+title: Quick start: using xmobar -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 [[https://codeberg.org/xmobar/xmobar/src/branch/master/examples/xmobar.config][here]]. +Xmobar can either be configured using the configuration language, or [[file:using-haskell.org][used as a +Haskell library]] (similar to xmonad) and compiled with your specific +configuration. For an example of a configuration file using the plain +configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you can have a look at +[[../etc/xmobar.hs][etc/xmobar.hs]] for an example of how to write your own xmobar using Haskell. * Command Line Options @@ -26,21 +23,21 @@ #+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 + -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 @@ -58,375 +55,436 @@ :PROPERTIES: :CUSTOM_ID: configuration-options :END: -*** Global options - Here are all the global configuration options that you can set within - the =Config= block in your configuration. +** Global 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. + - =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: + - =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 + #+begin_src haskell + additionalFonts = [iconFont, altIconFont] + #+end_src - - =bgColor= Background color. + - =bgColor= Background color. - - =fgColor= Default font color. + - =fgColor= Default font color. - - =alpha= The transparency. 0 is transparent, 255 is opaque. + - =alpha= The transparency. 0 is transparent, 255 is opaque. - - =position= Top, TopH, TopP, TopW, TopSize, Bottom, BottomH, - BottomP, BottomW, BottomSize or Static (with x, y, width and height). + - =position= Top, TopH, TopP, TopW, TopSize, Bottom, BottomH, + BottomP, BottomW, BottomSize or Static (with x, y, width and height). - TopP and BottomP take 2 arguments: left padding and right padding. + 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. + 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. + 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. - TopH and BottomH take one argument (Int) which adjusts the bar height. + TopH and BottomH take one argument (Int) which adjusts the bar height. - For example: + For example: - #+begin_src haskell - position = TopH 30 - #+end_src + #+begin_src haskell + position = TopH 30 + #+end_src - to make a 30 tall bar on the top, or + to make a 30 tall bar on the top, or - #+begin_src haskell - position = BottomH 30 - #+end_src + #+begin_src haskell + position = BottomH 30 + #+end_src - to make a 30 tall bar on the bottom of the screen. + to make a 30 tall bar on the bottom of the screen. - #+begin_src haskell - position = BottomW C 75 - #+end_src + #+begin_src haskell + position = BottomW C 75 + #+end_src - to place xmobar at the bottom, centered with the 75% of the screen - width. Or + to place xmobar at the bottom, centered with the 75% of the screen + width. Or - #+begin_src haskell - position = BottomP 120 0 - #+end_src + #+begin_src haskell + position = BottomP 120 0 + #+end_src - to place xmobar at the bottom, with 120 pixel indent of the left. Or + 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 + #+begin_src haskell + position = Static { xpos = 0 , ypos = 0, width = 1024, height = 15 } + #+end_src - or + or - #+begin_src haskell - position = Top - #+end_src + #+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. + - =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. + - =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. + - =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. + - =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. + - =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. + - =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=. + - =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. + - =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. + - =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). + - =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. + 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. + 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. + - =borderColor= Border color. - - =borderWidth= Border width in pixels. + - =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= 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 + #+begin_src haskell + iconRoot ++ "/" + #+end_src - prepended to it. Default is =.=. + prepended to it. Default is =.=. - - =commands= For setting the options of the programs to run (optional). + - =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 '%'). + - =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. + - =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. + - =template= The output template. - - =wmClass= The value for the window's X11 ~WM_CLASS~ property. Defaults - to "xmobar". + - =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". + - =wmName= The value for the window's X11 ~WM_NAME~ property. Defaults to + "xmobar". - - =textOutput= When True, instead of running as an X11 application, - write output to stdout, with optional color escape sequences. In - this mode, icon and action specifications are ignored. Default is - False. + - =textOutput= When True, instead of running as an X11 application, + write output to stdout, with optional color escape sequences. In + this mode, icon and action specifications are ignored. Default is + False. - - =textOutputFormat= Plain, Ansi or Pango, to emit, when in text - mode, escape color sequences using ANSI controls (for terminals) or - pango markup. Default is Plain. + - =textOutputFormat= Plain, Ansi or Pango, to emit, when in text + mode, escape color sequences using ANSI controls (for terminals) or + pango markup. Default is Plain. -*** The output =template= +** 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. + 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. + 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. -***** Template syntax +*** Template syntax - The syntax for the output template is as follows: + 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. + - =%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. + - =<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. - - =<fn=1>string</fn>= will print =string= with the first font from - =additionalFonts=. The index =0= corresponds to the standard font. + - =<fn=1>string</fn>= will print =string= with the first font from + =additionalFonts=. The index =0= corresponds to the standard font. - - =<hspace=X/>= will insert a blank horizontal space of =X= pixels. - For example, to add a blank horizontal space of 123 pixels, - =<hspace=123/>= may be used. + - =<hspace=X/>= will insert a blank horizontal space of =X= pixels. + For example, to add a blank horizontal space of 123 pixels, + =<hspace=123/>= may be used. - - =<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: see next section. + - =<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: see next section. - - =<icon=/path/to/icon.xbm/>= will insert the given bitmap. XPM image - format is also supported when compiled with the =with_xpm= flag. + - =<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. + - =<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 + - =<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 + #+begin_src shell + xmobar -c "[Run UnsafeStdinReader]" -t "%UnsafeStdinReader%" + #+end_src - and receives on standard input the line + 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 + #+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. + then it will display the text + =<action=`echo mooo` button=1>foo</action>=, which, when clicked, will + cause =test= to be echoed. - See the subsections below for more information on ~<box/>~, - ~<icon/>~ and ~<action/>~. + See the subsections below for more information on ~<box/>~, + ~<icon/>~ and ~<action/>~. -***** Boxes around text +*** Boxes around text - - =<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: + - =<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. + - =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: + 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 + #+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: + 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 + #+begin_src shell + <box type=VBoth mt=2 mb=2>string</box> + #+end_src - When xmobar is run in text mode with output format swaybar, box - types, colors and widths are valid too, but margins and offsets - are ignored. + When xmobar is run in text mode with output format swaybar, box + types, colors and widths are valid too, but margins and offsets + are ignored. -***** Bitmap Icons +*** Bitmap Icons - It's possible to insert in the global templates icon directives of the - form: + It's possible to insert in the global templates icon directives of the + form: - prepended to it. Default is =.=. + prepended to it. Default is =.=. - #+begin_src shell - <icon=/path/to/bitmap.xbm/> - #+end_src + #+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 + 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 + #+begin_src haskell + iconRoot ++ "/" + #+end_src - prepended to it. + prepended to it. - Icons are ignored when xmobar is run in text output mode. + Icons are ignored when xmobar is run in text output mode. -***** Action Directives +*** Action Directives - It's also possible to use action directives of the form: + It's also possible to use action directives of the form: - #+begin_src shell - <action=`command` button=12345> - #+end_src + #+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. + 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. - Actions work also when xmobar is run in text mode and used as - the status command of swaybar. + Actions work also when xmobar is run in text mode and used as + the status command of swaybar. -*** The =commands= configuration option +** 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 =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. + The option consists in a list of commands separated by a comma and + enclosed by square parenthesis. - Example: + Example: - #+begin_src haskell - [Run Memory ["-t","Mem: <usedratio>%"] 10, Run Swap [] 10] - #+end_src + #+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: + 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 + #+begin_src haskell + template = "<icon=/home/jao/.xmobar/mem.xbm/><memory> <swap>" + #+end_src - This example will run "xclock" command when date is clicked: + This example will run "xclock" command when date is clicked: - #+begin_src haskell - template = "<action=`xclock`>%date%</action>" - #+end_src + #+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. + 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. + Other commands can be created as plugins with the Plugin infrastructure. + See below. * Runtime behaviour -*** Running xmobar with =i3status= +** Running xmobar in text mode + :PROPERTIES: + :CUSTOM_ID: text-mode + :END: - 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. + By default, xmobar will run as an X11 application, in a docked window, but + it is possible to redirect xmobar's output to the standard output, + optionally with color escape sequences. In this mode, xmobar can be run + inside a terminal o console, or its output piped to other applications, and + there is no need for an X11 display (so, for instance, you could pipe + xmobar's output to a Wayland application, such as swaybar.) -*** Dynamically sizing xmobar + To run xmobar in text mode, either pass the =-T= flag to its + invocation: - See [[https://codeberg.org/xmobar/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]]. + #+begin_src shell + xmobar -T /path/to/config & + #+end_src -*** Signal Handling + or set the parameter =textOutput= to True in its configuration. You + can also specify the format of color escapes, for instance, + omitting them altogether with ~Plain~: - xmobar reacts to ~SIGUSR1~ and ~SIGUSR2~: + #+begin_src shell + xmobar -TPlain /path/to/config & + #+end_src - - After receiving ~SIGUSR1~ xmobar moves its position to the next screen. + Other options are ~Ansi~, ~Pango~, and ~Swaybar~. +** Showing xmobar output in Emacs tab or mode line + Using xmobar's ANSI color text ouput, one can plug it inside Emacs, and + display your monitors in the mode line or the tab bar. The [[../etc/xmobar.el][xmobar.el + package]] provides a simple way of doing it. +** Using xmobar in wayland with swaybar or waybar + :PROPERTIES: + :CUSTOM_ID: wayland + :END: - - After receiving ~SIGUSR2~ xmobar repositions itself on the current - screen. + In text mode, xmobar can be told to ouput its information using + pango markup for colors and fonts, and it that way you can use it + with swaybar or waybar, if you don't have actions or boxes in your + template. Here's a minimal ~bar~ configuration for sway's + configuration file: + + #+begin_src conf + bar { + status_command xmobar -TPango + pango_markup enabled + } + #+end_src + + In case you want to use boxes around text or click actions in your + template, you can use instead the format ~Swaybar~, which supports + both. This output format follows the JSON /swaybar-protocol/ + defined by swaybar. Configure it simply with: + + #+begin_src conf + bar { + status_command xmobar -TSwaybar + } + #+end_src + +** 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://codeberg.org/xmobar/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 + [[../etc/padding-icon.sh][etc/padding-icon.sh]]. + +** Signal handling + + 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. * The DBus Interface When compiled with the optional =with_dbus= flag, xmobar can be controlled @@ -446,7 +504,7 @@ An example using the =dbus-send= command line utility: #+begin_src shell - dbus-send \ + dbus-send \ --session \ --dest=org.Xmobar.Control \ --type=method_call \ @@ -461,7 +519,7 @@ #+begin_src shell # send to another screen, reveal and toggle the persistent flag dbus-send [..] \ - "string:ChangeScreen 0" "string:Reveal 0" "string:TogglePersistent" + "string:ChangeScreen 0" "string:Reveal 0" "string:TogglePersistent" #+end_src The =Toggle=, =Reveal=, and =Hide= signals take an additional integer @@ -469,5 +527,67 @@ before the command takes effect, while =SetAlpha= takes a new alpha value (also an integer, between 0 and 255) as argument. - See [[./window-managers.org::*Example of using][Interfacing with window managers]] for an example of how to use - the DBus interface from xmonad. +** Example: 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 diff --git a/doc/using-haskell.org b/doc/using-haskell.org new file mode 100644 --- /dev/null +++ b/doc/using-haskell.org @@ -0,0 +1,130 @@ +#+title: Using Haskell + +* Writing your own xmobar in Haskell + :PROPERTIES: + :CUSTOM_ID: xmobar-in-haskell + :END: + + Besides an standalone program, ~xmobar~ is also a Haskell library providing + an interface to write your own status bar. You can write, instead of a + configuration file, a real Haskell program that will be compiled and run + when you invoke =xmobar=. + + Make sure that ~ghc~ will be able to locate the xmobar library, e.g. with + + #+begin_src shell + cabal install --lib xmobar + #+end_src + + and then write your Haskell configuration and main function using the + functions and types exported in the library, which closely resemble those + used in configuration files. Here's a small example: + + #+begin_src haskell + import Xmobar + + config :: Config + config = + defaultConfig + { font = "xft:Terminus-8", + allDesktops = True, + alpha = 200, + commands = + [ Run XMonadLog, + Run $ Memory ["t", "Mem: <usedratio>%"] 10, + Run $ Kbd [], + Run $ Date "%a %_d %b %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10 + ], + template = "%XMonadLog% }{ %kbd% | %date% | %memory%", + alignSep = "}{" + } + + main :: IO () + main = xmobar config + #+end_src + + You can then for instance run =ghc --make xmobar.hs= to create a new xmobar + executable running exactly the monitors defined above. Or put your + =xmobar.hs= program in =~/.config/xmobar/xmobar.hs= and, when running the + system-wide xmobar, it will notice that you have your own implementation + and (re)compile and run it as needed. + +* Writing a plugin + :PROPERTIES: + :CUSTOM_ID: writing-a-plugin + :END: + Writing a plugin for xmobar is very simple! + + First, 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 one needed method (alternatively =start= or =run=) and 3 optional ones + (=alias=, =rate=, and =trigger=): + + #+begin_src haskell + start :: e -> (String -> IO ()) -> IO () + run :: e -> IO String + rate :: e -> Int + alias :: e -> String + trigger :: e -> (Maybe SignalType -> IO ()) -> IO () + #+end_src + + =start= must receive a callback to be used to display the =String= produced by + the plugin. This method can be used for plugins that need to perform + asynchronous actions. See =src/Xmobar/Plugins/PipeReader.hs= for an example. + + =run= can be used for simpler plugins. If you define only =run= the plugin + will be run every second. To overwrite this default you just need to + implement =rate=, which must return the number of tenth of seconds between + every successive runs. See [[../etc/xmobar.hs][etc/xmobar.hs]] for an example of a plugin + that runs just once, and [[../src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one that + implements =rate=. + + Notice that Date could be implemented as: + + #+begin_src haskell + instance Exec Date where + alias (Date _ a _) = a + start (Date f _ r) = date f r + + date :: String -> Int -> (String -> IO ()) -> IO () + date format r callback = do go + where go = do + t <- toCalendarTime =<< getClockTime + callback $ formatCalendarTime defaultTimeLocale format t + tenthSeconds r >> go + #+end_src + + Modulo some technicalities like refreshing the time-zone in a clever way, + 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. + + If your plugin only implements =alias= and =start=, then it is advisable to + put it into the =Xmobar/Plugins/Monitors= directory and use one of the many + =run*= functions in [[../src/Xmobar/Plugins/Monitors/Common/Run.hs][Xmobar.Plugins.Monitors.Run]] in order to define + =start=. The =Exec= instance should then live in [[../src/Xmobar/Plugins/Monitors.hs][Xmobar.Plugins.Monitors]]. + +* Using a plugin + + To use your new plugin, you just need to use a pure Haskell configuration + for xmobar (as explained [[#xmobar-in-haskell][above]]) and load your definitions in your =xmobar.hs= + file. You can see an example in [[../etc/xmobar.hs][etc/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! + +* Further links + + For an elaborated, experimental and underdocumented example of writing your + own repos and status bars using xmobar, see [[https://codeberg.org/jao/xmobar-config][this repo at jao/xmobar-config]]. diff --git a/etc/padding-icon.sh b/etc/padding-icon.sh new file mode 100644 --- /dev/null +++ b/etc/padding-icon.sh @@ -0,0 +1,56 @@ +#!/bin/bash + +# Detects the width of running window with name given as first +# argument (xprop name '$1') and creates an XPM icon of that width, +# 1px height, and transparent. Outputs an <icon>-tag for use in +# xmobar to display the generated XPM icon. +# +# Run script from xmobar and trayer: +# `Run Com "/where/ever/padding-icon.sh" ["panel"] "trayerpad" 10` +# and use `%trayerpad%` in your template. +# or, if you're using for instance stalonetray: +# `Run Com "/where/ever/padding-icon.sh" ["stalonetray"] "tray" 10` + +# Very heavily based on Jonas Camillus Jeppensen code +# https://codeberg.org/xmobar/xmobar/issues/239#issuecomment-233206552 + +# Function to create a transparent Wx1 px XPM icon +create_xpm_icon () { +timestamp=$(date) +pixels=$(for i in `seq $1`; do echo -n "."; done) + +cat << EOF > "$2" +/* XPM * +static char * trayer_pad_xpm[] = { +/* This XPM icon is used for padding in xmobar to */ +/* leave room for trayer-srg. It is dynamically */ +/* updated by by trayer-pad-icon.sh which is run */ +/* by xmobar. */ +/* Created: ${timestamp} */ +/* <w/cols> <h/rows> <colors> <chars per pixel> */ +"$1 1 1 1", +/* Colors (none: transparent) */ +". c none", +/* Pixels */ +"$pixels" +}; +EOF +} + +# panel window name +pname=${1:-panel} + +# Width of the trayer window +width=$(xprop -name $pname | grep 'program specified minimum size' | cut -d ' ' -f 5) + +# Icon file name +iconfile="/tmp/$pname-padding-${width:-0}px.xpm" + +# If the desired icon does not exist create it +if [ ! -f $iconfile ] +then + create_xpm_icon $width $iconfile +fi + +# Output the icon tag for xmobar +echo "<icon=${iconfile}/>" diff --git a/etc/xmobar.config b/etc/xmobar.config new file mode 100644 --- /dev/null +++ b/etc/xmobar.config @@ -0,0 +1,39 @@ +Config { font = "-misc-fixed-*-*-*-*-10-*-*-*-*-*-*-*" + , additionalFonts = [] + , borderColor = "black" + , border = TopB + , bgColor = "black" + , fgColor = "grey" + , alpha = 255 + , position = Top + , textOffset = -1 + , iconOffset = -1 + , lowerOnStart = True + , pickBroadest = False + , persistent = False + , hideOnStart = False + , iconRoot = "." + , allDesktops = True + , overrideRedirect = True + , textOutputFormat = Ansi + , commands = [ Run Weather "EGPF" ["-t","<station>: <tempC>C", + "-L","18","-H","25", + "--normal","green", + "--high","red", + "--low","lightblue"] 36000 + , Run Network "eth0" ["-L","0","-H","32", + "--normal","green","--high","red"] 10 + , Run Network "eth1" ["-L","0","-H","32", + "--normal","green","--high","red"] 10 + , Run Cpu ["-L","3","-H","50", + "--normal","green","--high","red"] 10 + , Run Memory ["-t","Mem: <usedratio>%"] 10 + , Run Swap [] 10 + , Run Com "uname" ["-s","-r"] "" 36000 + , Run Date "%a %b %_d %Y %H:%M:%S" "date" 10 + ] + , sepChar = "%" + , alignSep = "}{" + , template = "%cpu% | %memory% * %swap% | %eth0% - %eth1% }\ + \{ <fc=#ee9a00>%date%</fc>| %EGPF% | %uname%" + } diff --git a/etc/xmobar.el b/etc/xmobar.el new file mode 100644 --- /dev/null +++ b/etc/xmobar.el @@ -0,0 +1,164 @@ +;; xmobar.el --- Display xmobar text output -*- lexical-binding: t -*- + +;; Copyright 2022 jao <jao@gnu.org> +;; Version: 0.0.1 +;; Package-Requires: ((emacs "28.1")) +;; Keywords: unix + +;; Heavily inspired by Steven Allen's https://github.com/Stebalien/i3bar.el + +;; This file is not part of GNU Emacs. + +;; This file is free software; you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published by +;; the Free Software Foundation; either version 3, or (at your option) +;; any later version. + +;; This file is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. + +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs; see the file COPYING. If not, write to +;; the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +;; Boston, MA 02111-1307, USA. + +;;; Commentary: + +;; Displays the output of an xmobar command in the Emacs mode-line (or tab-line). + +;;; Code: + +(eval-when-compile (require 'cl-lib)) + +(require 'tab-bar) +(require 'xterm-color nil t) + +(defgroup xmobar nil + "xmobar status display for Emacs." + :version "0.0.1" + :group 'mode-line) + +(defcustom xmobar-command '("xmobar" "-TAnsi") + "The xmobar command and flags." + :type '(choice (string :tag "Shell Command") + (repeat (string)))) + +(defcustom xmobar-tab-bar t + "Whether to dispaly xmobar output in the tab bar." + :type 'boolean) + +(defcustom xmobar-tab-split nil + "Split on this string for `xmobar-left-string' and `xmobar-right-string'." + :type 'string) + +(defcustom xmobar-tab-bar-format + '(xmobar-left-string tab-bar-format-align-right xmobar-right-string) + "Format for the tab bar when `xmobar-tab-bar' is t." + :type 'list) + +(defvar xmobar--process nil + "The running xmobar process, if any.") + +(defvar xmobar--left-string "") + +(defvar xmobar-string "" + "The xmobar string to be displayed in the mode-line or tab-bar.") + +(put 'xmobar-string 'risky-local-variable t) + +(defvar xmobar--colorize-fn + (if (featurep 'xterm-color) #'xterm-color-filter #'ansi-color-apply)) + +(defvar xmobar--old-tab-format tab-bar-format) + +(defun xmobar-string () xmobar-string) +(defun xmobar-right-string () xmobar-string) +(defun xmobar-left-string () xmobar--left-string) + +;;;###autoload +(define-minor-mode xmobar-mode + "Display an xmobar in the mode-line." + :global t :group 'xmobar + (xmobar--stop) + (if xmobar-mode + (progn (if xmobar-tab-bar + (progn + (setq xmobar--old-tab-format tab-bar-format) + (setq tab-bar-format xmobar-tab-bar-format) + (tab-bar-mode 1)) + (or global-mode-string (setq global-mode-string '(""))) + (unless (memq 'xmobar-string global-mode-string) + (setq global-mode-string + (append global-mode-string '(xmobar-string))))) + (xmobar--start)) + (when xmobar-tab-bar (setq tab-bar-format xmobar--old-tab-format)))) + +(defun xmobar--update (update) + "Apply an UPDATE to the xmobar bar." + (when xmobar-mode + (let* ((str (funcall xmobar--colorize-fn update)) + (strs (and xmobar-tab-split (split-string str xmobar-tab-split)))) + (setq xmobar-string (if strs (cadr strs) str) + xmobar--left-string (or (car strs) ""))) + (force-mode-line-update t))) + +(defun xmobar--process-filter (proc string) + "Process output from the xmobar process." + (let ((buf (process-buffer proc))) + (when (buffer-live-p buf) + (with-current-buffer buf + ;; Write the input to the buffer (might be partial). + (save-excursion + (goto-char (process-mark proc)) + (insert string) + (set-marker (process-mark proc) (point))) + (when (string-match-p "\n$" string) + (xmobar--update (buffer-string)) + (delete-region (point-min) (point-max))))))) + +(defun xmobar--process-sentinel (proc status) + "Handle events from the xmobar process (PROC). +If the process has exited, this function stores the exit STATUS in +`xmobar-string'." + (unless (process-live-p proc) + (setq xmobar--process nil) + (let ((buf (process-buffer proc))) + (when (and buf (buffer-live-p buf)) (kill-buffer buf))) + (setq xmobar-string (format "xmobar: %s" status) xmobar--left-string ""))) + +(defun xmobar--start () + "Start xmobar." + (xmobar--stop) + (condition-case err + (setq xmobar--process + (make-process + :name "xmobar" + :buffer " *xmobar process*" + :stderr " *xmobar stderr*" + :command (ensure-list xmobar-command) + :connection-type 'pipe + :noquery t + :sentinel #'xmobar--process-sentinel + :filter #'xmobar--process-filter)) + (error + (setq xmobar-string + (format "starting xmobar: %s" (error-message-string err)) + xmobar--left-string "")))) + +(defun xmobar--stop () + "Stop xmobar." + (when (and xmobar--process (process-live-p xmobar--process)) + (delete-process xmobar--process)) + (setq xmobar-string "" xmobar--left-string "")) + +;;;###autoload +(defun xmobar-restart () + "Restart the xmobar program." + (interactive) + (unless xmobar-mode (user-error "The xmobar-mode is not enabled")) + (xmobar--start)) + +(provide 'xmobar) +;;; xmobar.el ends here diff --git a/etc/xmobar.hs b/etc/xmobar.hs new file mode 100644 --- /dev/null +++ b/etc/xmobar.hs @@ -0,0 +1,77 @@ +------------------------------------------------------------------------------ +-- | +-- Copyright: (c) 2018, 2019, 2022 Jose Antonio Ortega Ruiz +-- License: BSD3-style (see LICENSE) +-- +-- Maintainer: jao@gnu.org +-- Stability: unstable +-- Portability: portable +-- Created: Sat Nov 24, 2018 21:03 +-- +-- +-- An example of a Haskell-based xmobar. Compile it with +-- ghc --make -- xmobar.hs +-- with the xmobar library installed or simply call: +-- xmobar /path/to/xmobar.hs +-- and xmobar will compile and launch it for you and +------------------------------------------------------------------------------ + +import Xmobar + +-- Example user-defined plugin + +data HelloWorld = HelloWorld + deriving (Read, Show) + +instance Exec HelloWorld where + alias HelloWorld = "hw" + run HelloWorld = return "<fc=red>Hello World!!</fc>" + +-- Configuration, using predefined monitors as well as our HelloWorld +-- plugin: + +config :: Config +config = defaultConfig { + font = "xft:Sans Mono-9" + , additionalFonts = [] + , borderColor = "black" + , border = TopB + , bgColor = "black" + , fgColor = "grey" + , alpha = 255 + , position = Top + , textOffset = -1 + , iconOffset = -1 + , lowerOnStart = True + , pickBroadest = False + , persistent = False + , hideOnStart = False + , iconRoot = "." + , allDesktops = True + , overrideRedirect = True + , textOutputFormat = Ansi + , commands = [ Run $ Weather "EGPH" ["-t","<station>: <tempC>C", + "-L","18","-H","25", + "--normal","green", + "--high","red", + "--low","lightblue"] 36000 + , Run $ Network "eth0" ["-L","0","-H","32", + "--normal","green","--high","red"] 10 + , Run $ Network "eth1" ["-L","0","-H","32", + "--normal","green","--high","red"] 10 + , Run $ Cpu ["-L","3","-H","50", + "--normal","green","--high","red"] 10 + , Run $ Memory ["-t","Mem: <usedratio>%"] 10 + , Run $ Swap [] 10 + , Run $ Com "uname" ["-s","-r"] "" 36000 + , Run $ Date "%a %b %_d %Y %H:%M:%S" "date" 10 + , Run HelloWorld + ] + , sepChar = "%" + , alignSep = "}{" + , template = "%cpu% | %memory% * %swap% | %eth0% - %eth1% }\ + \ %hw% { <fc=#ee9a00>%date%</fc>| %EGPH% | %uname%" +} + +main :: IO () +main = configFromArgs config >>= xmobar diff --git a/etc/xmonadpropwrite.hs b/etc/xmonadpropwrite.hs new file mode 100644 --- /dev/null +++ b/etc/xmonadpropwrite.hs @@ -0,0 +1,41 @@ +-- Copyright Spencer Janssen <spencerjanssen@gmail.com> +-- Tomas Janousek <tomi@nomi.cz> +-- BSD3 (see LICENSE) +-- +-- Reads from standard input and writes to an X propery on root window. +-- To be used with XPropertyLog: +-- Add it to commands: +-- Run XPropertyLog "_XMONAD_LOG_CUSTOM" +-- Add it to the template: +-- template = "... %_XMONAD_LOG_CUSTOM% ..." +-- Run: +-- $ blah blah | xmonadpropwrite _XMONAD_LOG_CUSTOM + +import Control.Monad +import Graphics.X11 +import Graphics.X11.Xlib.Extras +import qualified Data.ByteString as B +import Foreign.C (CChar) +import System.IO +import System.Environment + +main = do + atom <- flip fmap getArgs $ \args -> case args of + [a] -> a + _ -> "_XMONAD_LOG" + + d <- openDisplay "" + xlog <- internAtom d atom False + ustring <- internAtom d "UTF8_STRING" False + + root <- rootWindow d (defaultScreen d) + + forever $ do + msg <- B.getLine + changeProperty8 d root xlog ustring propModeReplace (encodeCChar msg) + sync d True + + return () + +encodeCChar :: B.ByteString -> [CChar] +encodeCChar = map fromIntegral . B.unpack diff --git a/examples/padding-icon.sh b/examples/padding-icon.sh deleted file mode 100644 --- a/examples/padding-icon.sh +++ /dev/null @@ -1,56 +0,0 @@ -#!/bin/bash - -# Detects the width of running window with name given as first -# argument (xprop name '$1') and creates an XPM icon of that width, -# 1px height, and transparent. Outputs an <icon>-tag for use in -# xmobar to display the generated XPM icon. -# -# Run script from xmobar and trayer: -# `Run Com "/where/ever/padding-icon.sh" ["panel"] "trayerpad" 10` -# and use `%trayerpad%` in your template. -# or, if you're using for instance stalonetray: -# `Run Com "/where/ever/padding-icon.sh" ["stalonetray"] "tray" 10` - -# Very heavily based on Jonas Camillus Jeppensen code -# https://codeberg.org/xmobar/xmobar/issues/239#issuecomment-233206552 - -# Function to create a transparent Wx1 px XPM icon -create_xpm_icon () { -timestamp=$(date) -pixels=$(for i in `seq $1`; do echo -n "."; done) - -cat << EOF > "$2" -/* XPM * -static char * trayer_pad_xpm[] = { -/* This XPM icon is used for padding in xmobar to */ -/* leave room for trayer-srg. It is dynamically */ -/* updated by by trayer-pad-icon.sh which is run */ -/* by xmobar. */ -/* Created: ${timestamp} */ -/* <w/cols> <h/rows> <colors> <chars per pixel> */ -"$1 1 1 1", -/* Colors (none: transparent) */ -". c none", -/* Pixels */ -"$pixels" -}; -EOF -} - -# panel window name -pname=${1:-panel} - -# Width of the trayer window -width=$(xprop -name $pname | grep 'program specified minimum size' | cut -d ' ' -f 5) - -# Icon file name -iconfile="/tmp/$pname-padding-${width:-0}px.xpm" - -# If the desired icon does not exist create it -if [ ! -f $iconfile ] -then - create_xpm_icon $width $iconfile -fi - -# Output the icon tag for xmobar -echo "<icon=${iconfile}/>" diff --git a/examples/xmobar.config b/examples/xmobar.config deleted file mode 100644 --- a/examples/xmobar.config +++ /dev/null @@ -1,39 +0,0 @@ -Config { font = "-misc-fixed-*-*-*-*-10-*-*-*-*-*-*-*" - , additionalFonts = [] - , borderColor = "black" - , border = TopB - , bgColor = "black" - , fgColor = "grey" - , alpha = 255 - , position = Top - , textOffset = -1 - , iconOffset = -1 - , lowerOnStart = True - , pickBroadest = False - , persistent = False - , hideOnStart = False - , iconRoot = "." - , allDesktops = True - , overrideRedirect = True - , textOutputFormat = Ansi - , commands = [ Run Weather "EGPF" ["-t","<station>: <tempC>C", - "-L","18","-H","25", - "--normal","green", - "--high","red", - "--low","lightblue"] 36000 - , Run Network "eth0" ["-L","0","-H","32", - "--normal","green","--high","red"] 10 - , Run Network "eth1" ["-L","0","-H","32", - "--normal","green","--high","red"] 10 - , Run Cpu ["-L","3","-H","50", - "--normal","green","--high","red"] 10 - , Run Memory ["-t","Mem: <usedratio>%"] 10 - , Run Swap [] 10 - , Run Com "uname" ["-s","-r"] "" 36000 - , Run Date "%a %b %_d %Y %H:%M:%S" "date" 10 - ] - , sepChar = "%" - , alignSep = "}{" - , template = "%cpu% | %memory% * %swap% | %eth0% - %eth1% }\ - \{ <fc=#ee9a00>%date%</fc>| %EGPF% | %uname%" - } diff --git a/examples/xmobar.hs b/examples/xmobar.hs deleted file mode 100644 --- a/examples/xmobar.hs +++ /dev/null @@ -1,77 +0,0 @@ ------------------------------------------------------------------------------- --- | --- Copyright: (c) 2018, 2019, 2022 Jose Antonio Ortega Ruiz --- License: BSD3-style (see LICENSE) --- --- Maintainer: jao@gnu.org --- Stability: unstable --- Portability: portable --- Created: Sat Nov 24, 2018 21:03 --- --- --- An example of a Haskell-based xmobar. Compile it with --- ghc --make -- xmobar.hs --- with the xmobar library installed or simply call: --- xmobar /path/to/xmobar.hs --- and xmobar will compile and launch it for you and ------------------------------------------------------------------------------- - -import Xmobar - --- Example user-defined plugin - -data HelloWorld = HelloWorld - deriving (Read, Show) - -instance Exec HelloWorld where - alias HelloWorld = "hw" - run HelloWorld = return "<fc=red>Hello World!!</fc>" - --- Configuration, using predefined monitors as well as our HelloWorld --- plugin: - -config :: Config -config = defaultConfig { - font = "xft:Sans Mono-9" - , additionalFonts = [] - , borderColor = "black" - , border = TopB - , bgColor = "black" - , fgColor = "grey" - , alpha = 255 - , position = Top - , textOffset = -1 - , iconOffset = -1 - , lowerOnStart = True - , pickBroadest = False - , persistent = False - , hideOnStart = False - , iconRoot = "." - , allDesktops = True - , overrideRedirect = True - , textOutputFormat = Ansi - , commands = [ Run $ Weather "EGPH" ["-t","<station>: <tempC>C", - "-L","18","-H","25", - "--normal","green", - "--high","red", - "--low","lightblue"] 36000 - , Run $ Network "eth0" ["-L","0","-H","32", - "--normal","green","--high","red"] 10 - , Run $ Network "eth1" ["-L","0","-H","32", - "--normal","green","--high","red"] 10 - , Run $ Cpu ["-L","3","-H","50", - "--normal","green","--high","red"] 10 - , Run $ Memory ["-t","Mem: <usedratio>%"] 10 - , Run $ Swap [] 10 - , Run $ Com "uname" ["-s","-r"] "" 36000 - , Run $ Date "%a %b %_d %Y %H:%M:%S" "date" 10 - , Run HelloWorld - ] - , sepChar = "%" - , alignSep = "}{" - , template = "%cpu% | %memory% * %swap% | %eth0% - %eth1% }\ - \ %hw% { <fc=#ee9a00>%date%</fc>| %EGPH% | %uname%" -} - -main :: IO () -main = xmobar config diff --git a/examples/xmonadpropwrite.hs b/examples/xmonadpropwrite.hs deleted file mode 100644 --- a/examples/xmonadpropwrite.hs +++ /dev/null @@ -1,41 +0,0 @@ --- Copyright Spencer Janssen <spencerjanssen@gmail.com> --- Tomas Janousek <tomi@nomi.cz> --- BSD3 (see LICENSE) --- --- Reads from standard input and writes to an X propery on root window. --- To be used with XPropertyLog: --- Add it to commands: --- Run XPropertyLog "_XMONAD_LOG_CUSTOM" --- Add it to the template: --- template = "... %_XMONAD_LOG_CUSTOM% ..." --- Run: --- $ blah blah | xmonadpropwrite _XMONAD_LOG_CUSTOM - -import Control.Monad -import Graphics.X11 -import Graphics.X11.Xlib.Extras -import qualified Data.ByteString as B -import Foreign.C (CChar) -import System.IO -import System.Environment - -main = do - atom <- flip fmap getArgs $ \args -> case args of - [a] -> a - _ -> "_XMONAD_LOG" - - d <- openDisplay "" - xlog <- internAtom d atom False - ustring <- internAtom d "UTF8_STRING" False - - root <- rootWindow d (defaultScreen d) - - forever $ do - msg <- B.getLine - changeProperty8 d root xlog ustring propModeReplace (encodeCChar msg) - sync d True - - return () - -encodeCChar :: B.ByteString -> [CChar] -encodeCChar = map fromIntegral . B.unpack diff --git a/readme.org b/readme.org --- a/readme.org +++ b/readme.org @@ -33,133 +33,104 @@ :PROPERTIES: :CUSTOM_ID: installation :END: -*** From your system's package manager +** From your system's 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. + 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 + - Arch Linux + #+begin_src shell + pacman -S xmobar + #+end_src - - Debian/Ubuntu based - #+begin_src shell - apt install xmobar - #+end_src + - Debian/Ubuntu based + #+begin_src shell + apt install xmobar + #+end_src - - OpenSUSE - #+begin_src shell - zypper install xmobar - #+end_src + - OpenSUSE + #+begin_src shell + zypper install xmobar + #+end_src - - Void Linux - #+begin_src shell - xbps-install xmobar - #+end_src + - Void Linux + #+begin_src shell + xbps-install xmobar + #+end_src - - Gentoo - #+begin_src shell - emerge --ask xmobar - #+end_src + - Gentoo + #+begin_src shell + emerge --ask xmobar + #+end_src -*** Using cabal-install +** Using cabal-install - Xmobar is available from [[http://hackage.haskell.org/package/xmobar/][Hackage]], and you can install it 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 + #+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://codeberg.org/xmobar/xmobar/issues/461][this issue]] for more information. + Starting with version 0.35.1, xmobar now requires at least GHC version + 8.4.x. to build. See [[https://codeberg.org/xmobar/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: + See [[file:doc/compiling.org#optional-features][here]] 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 + #+begin_src shell + cabal install xmobar --flags="all_extensions" + #+end_src -*** From source +** From source - See [[file:doc/compiling.org][compiling]]. + 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=. - -*** Running xmobar in text mode - - By default, xmobar will run as an X11 application, in a docked - window, but it is possible to redirect xmobar's to the standard - output, optionally with color escape sequences. In this mode, - xmobar can be run inside a terminal o console, or its output piped - to other applications, and there is no need for an X11 display - (so, for instance, you could pipe xmobar's output to a Wayland - application, such as swaybar.) - - To run xmobar in text mode, either pass the =-T= flag to its - invocation: +** Running xmobar with a configuration file + You can run xmobar with: - #+begin_src shell - xmobar -T /path/to/config & - #+end_src + #+begin_src shell + xmobar /path/to/config & + #+end_src - or set the parameter =textOutput= to True in its configuration. You - can also specify the format of color escapes, for instance, - omitting them altogether with ~Plain~: + or - #+begin_src shell - xmobar -TPlain /path/to/config & - #+end_src + #+begin_src shell + xmobar & + #+end_src - Other options are ~Ansi~, ~Pango~, and ~Swaybar~. + if you have the default configuration file saved as + =$XDG_CONFIG_HOME/xmobar/xmobarrc= (defaulting to =~/.config/xmobar/xmobarrc=), + or =~/.xmobarrc=. -*** Using xmobar in Wayland with swaybar or waybar + All the available command line switches and configuration parameters are + described in [[file:quick-start.org][the quick start guide]] and [[file:doc/plugins.org][the plugins index]]. - In text mode, xmobar can be told to ouput its information using - pango markup for colors and fonts, and it that way you can use it - with swaybar or waybar, if you don't have actions or boxes in your - template. Here's a minimal ~bar~ configuration for sway's - configuration file: +** Writing your own xmobar in Haskell - #+begin_src conf - bar { - status_command xmobar -TPango - pango_markup enabled - } - #+end_src + As shown above, one can use ~xmobar~ as a regular program, via its + configuration file, without having to write any code. It also is possible + to install xmobar as a library and use it to write your own xmobar using + Haskell instead of using a configuration file. (This is very similar to + how [[http://xmonad.org][xmonad]] works.) That gives you the ability of using Haskell and its + libraries to extend xmobar to your heart's content. If you are a + programmer, take a look [[file:doc/using-haskell.org][here]] to learn more. - In case you want to use boxes around text or click actions in your - template, you can use instead the format ~Swaybar~, which supports - both. This output format follows the JSON /swaybar-protocol/ - defined by swaybar. Configure it simply with: +** Running xmobar in text mode - #+begin_src conf - bar { - status_command xmobar -TSwaybar - } - #+end_src + By default, xmobar will run as an X11 application, in a docked window, but + it is possible to redirect xmobar's output to the standard output, + optionally with color escape sequences. In this mode, xmobar can be run + inside a terminal o console, or its output piped to other applications, and + there is no need for an X11 display. See [[./doc/quick-start.org#text-mode][Running xmobar in text mode]] for + details. Using this mode, you could [[file:doc/quick-start.org#wayland][pipe xmobar's output to, say, swaybar]], + and use it in wayland, or, with the [[./etc/xmobar.el][xmobar.el]] package, show it in Emacs's + tab bar. -* Configuration and further Links +* Configuration and further documentation - If you want to jump straight into running xmobar, head over to the [[./doc/quick-start.org][quick start guide]]. @@ -167,20 +138,12 @@ - If you want to get a detailed overview of all available plugins and monitors, visit the [[./doc/plugins.org][plugins index]]. - - [[./doc/window-managers.org][Interfacing with window managers]] describes plugins and extensions - for interacting with xmobar from your window manager. + - For more information on how to use xmobar as a Haskell library see the + [[file:doc/using-haskell.org][using Haskell guide]]. - 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]]. - - - For elaborated examples of how to use xmobar as a Haskell library - to create your monitors, see [[https://codeberg.org/jao/xmobar-config][this repo at jao/xmobar-config]]. - - - 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. - * Authors and credits Andrea Rossato originally designed and implemented xmobar up to @@ -216,9 +179,9 @@ * License -This software is released under a BSD-style license. See [[https://codeberg.org/xmobar/xmobar/src/branch/master/license][license]] for more -details. + This software is released under a BSD-style license. See [[https://codeberg.org/xmobar/xmobar/src/branch/master/license][license]] for more + details. -Copyright © 2010-2022 Jose Antonio Ortega Ruiz + Copyright © 2010-2022 Jose Antonio Ortega Ruiz -Copyright © 2007-2010 Andrea Rossato + Copyright © 2007-2010 Andrea Rossato diff --git a/xmobar.cabal b/xmobar.cabal --- a/xmobar.cabal +++ b/xmobar.cabal @@ -1,5 +1,5 @@ name: xmobar -version: 0.44.1 +version: 0.44.2 homepage: https://codeberg.org/xmobar/xmobar synopsis: A Minimalistic Text Based Status Bar description: Xmobar is a minimalistic text based status bar. @@ -17,11 +17,15 @@ build-type: Simple extra-source-files: readme.org, changelog.md, - doc/quick-start.org, doc/plugins.org - examples/padding-icon.sh, - examples/xmobar.config, - examples/xmobar.hs, - examples/xmonadpropwrite.hs + doc/quick-start.org, + doc/plugins.org, + doc/compiling.org, + doc/using-haskell.org, + etc/padding-icon.sh, + etc/xmobar.config, + etc/xmobar.hs, + etc/xmonadpropwrite.hs, + etc/xmobar.el source-repository head type: git @@ -253,8 +257,8 @@ build-depends: alsa-mixer >= 0.3 && < 0.4 build-depends: alsa-core == 0.5.*, process >= 1.4.3.0 - other-modules: Xmobar.Plugins.Monitors.Volume - Xmobar.Plugins.Monitors.Alsa + other-modules: Xmobar.Plugins.Monitors.Volume, + Xmobar.Plugins.Monitors.Alsa cpp-options: -DALSA if flag(with_datezone) || flag(all_extensions) @@ -327,14 +331,14 @@ default-language: Haskell2010 hs-source-dirs: app main-is: Main.hs - build-depends: base, - containers, + build-depends: X11, async, - X11, + base, + containers, directory, filepath, - unix, parsec, + unix, xmobar ghc-options: -funbox-strict-fields -Wall -fno-warn-unused-do-bind @@ -354,25 +358,25 @@ type: exitcode-stdio-1.0 hs-source-dirs: src, test main-is: Spec.hs - build-depends: base, - containers, - regex-compat, - process, - old-locale, + build-depends: X11, + async, + base, bytestring, + containers, directory, - unix, - time, filepath, - transformers, - X11, + hspec == 2.*, mtl, + old-locale, parsec, parsec-numbers, + process, + regex-compat, stm, - async, temporary, - hspec == 2.*, + time, + transformers, + unix, xmobar other-modules: Xmobar.Plugins.Monitors.CommonSpec @@ -412,5 +416,5 @@ hs-source-dirs: bench ghc-options: -funbox-strict-fields -Wall -fno-warn-unused-do-bind -O2 - build-depends: base, gauge, xmobar, mtl, time + build-depends: base, gauge, mtl, time, xmobar default-language: Haskell2010