[[http://hackage.haskell.org/package/xmobar][https://img.shields.io/hackage/v/xmobar.svg]] * About Xmobar is a minimalistic status bar. It was originally designed and implemented by Andrea Rossato to work with [[http://xmonad.org][xmonad]], but it is actually usable with any window manager. Xmobar was inspired by the [[http://tuomov.iki.fi/software/][Ion3]] status bar, and supports similar features, like dynamic color management, icons, output templates, and extensibility through plugins. These are some xmobar [[file:doc/screenshots][screenshots]] using the author's configuration: [[file:doc/screenshots/xmobar-top.png]] [[file:doc/screenshots/xmobar-bottom.png]] [[file:doc/screenshots/xmobar-exwm.png]] This is the [[https://xmobar.org/changelog.html][changelog]] for recent releases. * Installation ** From your Systems Package Manager Xmobar is probably available from your distribution package manager! Most distributions do compile with the =all_extensions= flag, so you don't have to. For more information on that, see the [[Optional features][optional features]] item below. *** Arch Linux #+begin_src shell pacman -S xmobar #+end_src *** Debian/Ubuntu based #+begin_src shell apt install xmobar #+end_src *** Void Linux #+begin_src shell xbps-install xmobar #+end_src ** Using cabal-install Xmobar is available from [[http://hackage.haskell.org/package/xmobar/][Hackage]], and you can install it using =cabal-install=: #+begin_src shell cabal install xmobar #+end_src Starting with version 0.35.1, xmobar now requires at least GHC version 8.4.x. to build. See [[https://github.com/jaor/xmobar/issues/461][this issue]] for more information. See below for a list of optional compilation flags that will enable some optional plugins. For instance, to install xmobar with all the bells and whistles, use: #+begin_src shell cabal install xmobar --flags="all_extensions" #+end_src ** 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://github.com/jaor/xmobar/][Github]]. There are also tarballs available for every tagged release on [[https://github.com/jaor/xmobar/releases][Github'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://github.com/jaor/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 barebones =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 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. * Running xmobar You can now run xmobar with: #+begin_src shell xmobar /path/to/config & #+end_src or #+begin_src shell xmobar & #+end_src if you have the default configuration file saved as =$XDG\_CONFIG\_HOME/xmobar/xmobarrc= (defaulting to =~/.config/xmobar/xmobarrc=), or =~/.xmobarrc=. ** Signal Handling Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2: - After receiving SIGUSR1 xmobar moves its position to the next screen. - After receiving SIGUSR2 xmobar repositions itself on the current screen. * Configuration ** Quick Start See [[http://github.com/jaor/xmobar/raw/master/examples/xmobar.config][examples/xmobar.config]] for an example. For the output template: - =%command%= will execute command and print the output. The output may contain markups to change the characters' color. - =string= will print =string= with =#FF0000= color (red). =string= will print =string= in red with a black background (=#000000=). Background absolute offsets can be specified for XFT fonts. =string= will have a background matching the bar's height. - =string= will print string surrounded by a box in the foreground color. The =box= tag accepts several optional arguments to tailor its looks: - =type=: =Top=, =Bottom=, =VBoth= (a single line above or below string, or both), =Left=, =Right=, =HBoth= (single vertical lines), =Full= (a rectangle, the default). - =color=: the color of the box lines. - =width=: the width of the box lines. - =offset=: an alignment char (L, C or R) followed by the amount of pixels to offset the box lines; the alignment denotes the position of the resulting line, with L/R meaning top/bottom for the vertical lines, and left/right for horizontal ones. - =mt=, =mb=, =ml=, =mr= specify margins to be added at the top, bottom, left and right lines. For example, a box underlining its text with a red line of width 2: #+begin_src shell string #+end_src and if you wanted an underline and an overline with a margin of 2 pixels either side: #+begin_src shell string #+end_src - =string= will print =string= with the first font from =additionalFonts=. The index =0= corresponds to the standard font. - == will insert the given bitmap. XPM image format is also supported when compiled with the =with_xpm= flag. - == 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. - == 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 == tags mixed with un-trusted content (e.g. window titles). For example, if xmobar is invoked as #+begin_src shell xmobar -c "[Run UnsafeStdinReader]" -t "%UnsafeStdinReader%" #+end_src and receives on standard input the line #+begin_src shell foo/>` #+end_src then it will display the text =foo=, which, when clicked, will cause =test= to be echoed. Other configuration options: - =font= Name of the font to be used. Use the =xft:= prefix for XFT fonts. - =additionalFonts= Haskell-style list of fonts to be used with the =fn=-template. Use the =xft:= prefix for XFT fonts. See also =textOffsets= below. - =bgColor= Background color. - =fgColor= Default font color. - =alpha= The transparency. 0 is transparent, 255 is opaque. - =position= Top, TopP, TopW, TopSize, Bottom, BottomP, BottomW, BottomSize or Static (with x, y, width and height). TopP and BottomP take 2 arguments: left padding and right padding. TopW and BottomW take 2 arguments: an alignment parameter (L for left, C for centered, R for Right) and an integer for the percentage width xmobar window will have in respect to the screen width. TopSize and BottomSize take 3 arguments: an alignment parameter, an integer for the percentage width, and an integer for the minimum pixel height that the xmobar window will have. For example: #+begin_src haskell position = BottomW C 75 #+end_src to place xmobar at the bottom, centered with the 75% of the screen width. Or #+begin_src haskell position = BottomP 120 0 #+end_src to place xmobar at the bottom, with 120 pixel indent of the left. Or #+begin_src haskell position = Static { xpos = 0 , ypos = 0, width = 1024, height = 15 } #+end_src or #+begin_src haskell position = Top #+end_src - =textOffset= The vertical offset, in pixels, for the text baseline. If negative or not given, xmobar will try to center text vertically. - =textOffsets= A list of vertical offsets, in pixels, for the text baseline, to be used with the each of the fonts in =additionalFonts= (if any). If negative or not given, xmobar will try to center text vertically for that font. - =iconOffset= The vertical offset, in pixels, for icons bottom line. If negative or not given, xmobar will try to center icons vertically. - =lowerOnStart= When True the window is sent the bottom of the window stack initially. - =hideOnStart= When set to True the window is initially not mapped, i.e. hidden. It then can be toggled manually (for example using the dbus interface) or automatically (by a plugin) to make it reappear. - =allDesktops= When set to True (the default), xmobar will tell the window manager explicitly to be shown in all desktops, by setting =_NET_WM_DESKTOP= to 0xffffffff. - =overrideRedirect= If you're running xmobar in a tiling window manager, you might need to set this option to =False= so that it behaves as a docked application. Defaults to =True=. - =pickBroadest= When multiple displays are available, xmobar will choose by default the first one to place itself. With this flag set to =True= (the default is =False=) it will choose the broadest one instead. - =persistent= When True the window status is fixed i.e. hiding or revealing is not possible. This option can be toggled at runtime. Defaults to False. - =border= TopB, TopBM, BottomB, BottomBM, FullB, FullBM or NoBorder (default). TopB, BottomB, FullB take no arguments, and request drawing a border at the top, bottom or around xmobar's window, respectively. TopBM, BottomBM, FullBM take an integer argument, which is the margin, in pixels, between the border of the window and the drawn border. - =borderColor= Border color. - =borderWidth= Border width in pixels. - =iconRoot= Root folder where icons are stored. For == if path start with =/=, =./= or =../= it is interpreted as it is. Otherwise it will have #+begin_src haskell iconRoot ++ "/" #+end_src prepended to it. Default is =.=. - =commands= For setting the options of the programs to run (optional). - =sepChar= The character to be used for indicating commands in the output template (default '%'). - =alignSep= a 2 character string for aligning text in the output template. The text before the first character will be align to left, the text in between the 2 characters will be centered, and the text after the second character will be align to the right. - =template= The output template. - =wmClass= The value for the window's X11 WM_CLASS property. Defaults to "xmobar". - =wmName= The value for the window's X11 WM_NAME property. Defaults to "xmobar". *** Running xmobar with i3status xmobar can be used to display information generated by [[http://i3wm.org/i3status/][i3status]], a small program that gathers system information and outputs it in formats suitable for being displayed by the dzen2 status bar, wmii's status bar or xmobar's =StdinReader=. See [[http://i3wm.org/i3status/manpage.html#_using_i3status_with_xmobar][i3status manual]] for further details. *** Dynamically sizing xmobar See [[https://github.com/jaor/xmobar/issues/239#issuecomment-233206552][this idea]] by Jonas Camillus Jeppensen for a way of adapting dynamically xmobar's size and run it alongside a system tray widget such as trayer or stalonetray (although the idea is not limited to trays, really). For your convenience, there is a version of Jonas' script in [[./examples/padding-icon.sh][examples/padding-icon.sh]]. ** Command Line Options xmobar can be either configured with a configuration file or with command line options. In the second case, the command line options will overwrite the corresponding options set in the configuration file. Example: #+begin_src shell xmobar -B white -a right -F blue -t '%LIPB%' -c '[Run Weather "LIPB" [] 36000]' #+end_src This is the list of command line options (the output of xmobar --help): #+begin_src shell Usage: xmobar [OPTION...] [FILE] Options: -h, -? --help This help -v --verbose Emit verbose debugging messages -r --recompile Force recompilation -V --version Show version information -f font name --font=font name Font name -N font name --add-font=font name Add to the list of additional fonts -w class --wmclass=class X11 WM_CLASS property -n name --wmname=name X11 WM_NAME property -B bg color --bgcolor=bg color The background color. Default black -F fg color --fgcolor=fg color The foreground color. Default grey -i path --iconroot=path Root directory for icon pattern paths. Default '.' -A alpha --alpha=alpha Transparency: 0 is transparent, 255 is opaque. Default: 255 -o --top Place xmobar at the top of the screen -b --bottom Place xmobar at the bottom of the screen -d --dock Don't override redirect from WM and function as a dock -a alignsep --alignsep=alignsep Separators for left, center and right text alignment. Default: '}{' -s char --sepchar=char Character used to separate commands in the output template. Default '%' -t template --template=template Output template -c commands --commands=commands List of commands to be executed -C command --add-command=command Add to the list of commands to be executed -x screen --screen=screen On which X screen number to start -p position --position=position Specify position of xmobar. Same syntax as in config file Mail bug reports and suggestions to #+end_src ** The Output Template The output template must contain at least one command. xmobar will parse the template and will search for the command to be executed in the =commands= configuration option. First an =alias= will be searched (plugins such as Weather or Network have default aliases, see below). After that, the command name will be tried. If a command is found, the arguments specified in the =commands= list will be used. If no command is found in the =commands= list, xmobar will ask the operating system to execute a program with the name found in the template. If the execution is not successful an error will be reported. It's possible to insert in the global templates icon directives of the form: #+begin_src shell #+end_src which will produce the expected result. Accepted image formats are XBM and XPM (when =with_xpm= flag is enabled). If path does not start with =/=, =./=, =../= it will have #+begin_src haskell iconRoot ++ "/" #+end_src prepended to it. It's also possible to use action directives of the form: #+begin_src shell #+end_src which will be executed when clicked on with specified mouse buttons. This tag can be nested, allowing different commands to be run depending on button clicked. ** The =commands= Configuration Option The =commands= configuration option is a list of commands information and arguments to be used by xmobar when parsing the output template. Each member of the list consists in a command prefixed by the =Run= keyword. Each command has arguments to control the way xmobar is going to execute it. The option consists in a list of commands separated by a comma and enclosed by square parenthesis. Example: #+begin_src haskell [Run Memory ["-t","Mem: %"] 10, Run Swap [] 10] #+end_src to run the Memory monitor plugin with the specified template, and the swap monitor plugin, with default options, every second. And here's an example of a template for the commands above using an icon: #+begin_src haskell template=" " #+end_src This example will run "xclock" command when date is clicked: #+begin_src haskell template="%date% #+end_src The only internal available command is =Com= (see below Executing External Commands). All other commands are provided by plugins. xmobar comes with some plugins, providing a set of system monitors, a standard input reader, an Unix named pipe reader, a configurable date plugin, and much more: we list all available plugins below. Other commands can be created as plugins with the Plugin infrastructure. See below. * Authors and credits Andrea Rossato originally designed and implemented xmobar up to version 0.11.1. Since then, it is maintained and developed by [[https://jao.io][jao]], with the help of the greater xmobar and Haskell communities. In particular, xmobar incorporates patches by Mohammed Alshiekh, Alex Ameen, Axel Angel, Dhananjay Balan, Claudio Bley, Dragos Boca, Ben Boeckel, Ivan Brennan, Duncan Burke, Roman Cheplyaka, Patrick Chilton, Antoine Eiche, Nathaniel Wesley Filardo, John Goerzen, Reto Hablützel, Juraj Hercek, Tomáš Janoušek, Ada Joule, Spencer Janssen, Roman Joost, Jochen Keil, Lennart Kolmodin, Krzysztof Kosciuszkiewicz, Dmitry Kurochkin, Todd Lunter, Vanessa McHale, Robert J. Macomber, Dmitry Malikov, David McLean, Marcin Mikołajczyk, Dino Morelli, Tony Morris, Eric Mrak, Thiago Negri, Edward O'Callaghan, Svein Ove, Martin Perner, Jens Petersen, Alexander Polakov, Sibi Prabakaran, Pavan Rikhi, Petr Rockai, Andrew Emmanuel Rosa, Sackville-West, Markus Scherer, Daniel Schüssler, Olivier Schneider, Alexander Shabalin, Valentin Shirokov, Peter Simons, Alexander Solovyov, Will Song, John Soros, Felix Springer, Travis Staton, Artem Tarasov, Samuli Thomasson, Edward Tjörnhammar, Sergei Trofimovich, Thomas Tuegel, John Tyree, Jan Vornberger, Anton Vorontsov, Daniel Wagner, Zev Weiss, Phil Xiaojun Hu, Edward Z. Yang and Norbert Zeh. ** Thanks *Andrea Rossato*: Thanks to Robert Manea and Spencer Janssen for their help in understanding how X works. They gave me suggestions on how to solve many problems with xmobar. Thanks to Claus Reinke for make me understand existential types (or at least for letting me think I grasp existential types...;-). *jao*: Thanks to Andrea for creating xmobar in the first place, and for giving me the chance to contribute. * Related - To understand the internal mysteries of xmobar you may try reading [[http://www.haskell.org/haskellwiki/X_window_programming_in_Haskell][this tutorial]] on X Window Programming in Haskell. * License This software is released under a BSD-style license. See [[https://github.com/jaor/xmobar/raw/master/license][license]] for more details. Copyright © 2010-2020 Jose Antonio Ortega Ruiz Copyright © 2007-2010 Andrea Rossato