path: root/readme.org

[[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
** 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 =<icon>=. 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.

- =<fc=#FF0000>string</fc>= will print =string= with =#FF0000= color
  (red). =<fc=#FF0000,#000000>string</fc>= will print =string= in red
  with a black background (=#000000=). Background absolute offsets can
  be specified for XFT fonts. =<fc=#FF0000,#000000:0>string</fc>= will
  have a background matching the bar's height.

- =<box>string</box>= will print string surrounded by a box in the
  foreground color. The =box= tag accepts several optional arguments to
  tailor its looks:

  - =type=: =Top=, =Bottom=, =VBoth= (a single line above or below
    string, or both), =Left=, =Right=, =HBoth= (single vertical lines),
    =Full= (a rectangle, the default).
  - =color=: the color of the box lines.
  - =width=: the width of the box lines.
  - =offset=: an alignment char (L, C or R) followed by the amount of
    pixels to offset the box lines; the alignment denotes the position
    of the resulting line, with L/R meaning top/bottom for the vertical
    lines, and left/right for horizontal ones.
  - =mt=, =mb=, =ml=, =mr= specify margins to be added at the top,
    bottom, left and right lines.

  For example, a box underlining its text with a red line of width 2:

  #+begin_src shell
    <box type=Bottom width=2 color=red>string</box>
  #+end_src

  and if you wanted an underline and an overline with a margin of 2
  pixels either side:

  #+begin_src shell
    <box type=VBoth mt=2 mb=2>string</box>
  #+end_src

- =<fn=1>string</fn>= will print =string= with the first font from
  =additionalFonts=. The index =0= corresponds to the standard font.

- =<icon=/path/to/icon.xbm/>= will insert the given bitmap. XPM image
  format is also supported when compiled with the =with_xpm= flag.

- =<action=`command` button=12345>= will execute given command when
  clicked with specified buttons. If not specified, button is equal to 1
  (left mouse button). Using old syntax (without backticks surrounding
  =command=) will result in =button= attribute being ignored.

- =<raw=len:str/>= allows the encapsulation of arbitrary text =str=
  (which must be =len= =Char=s long, where =len= is encoded as a decimal
  sequence). Careful use of this and =UnsafeStdinReader=, for example,
  permits window managers to feed xmobar strings with =<action>= tags
  mixed with un-trusted content (e.g. window titles). For example, if
  xmobar is invoked as

  #+begin_src shell
    xmobar -c "[Run UnsafeStdinReader]" -t "%UnsafeStdinReader%"
  #+end_src

  and receives on standard input the line

  #+begin_src shell
    <action=`echo test` button=1><raw=41:<action=`echo mooo` button=1>foo</action>/></action>`
  #+end_src

  then it will display the text
  =<action=`echo mooo` button=1>foo</action>=, which, when clicked, will
  cause =test= to be echoed.

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 =<icon=path/>= if
  path start with =/=, =./= or =../= it is interpreted as it is.
  Otherwise it will have

  #+begin_src haskell
    iconRoot ++ "/"
  #+end_src

  prepended to it. Default is =.=.

- =commands= For setting the options of the programs to run (optional).

- =sepChar= The character to be used for indicating commands in the
  output template (default '%').

- =alignSep= a 2 character string for aligning text in the output
  template. The text before the first character will be align to left,
  the text in between the 2 characters will be centered, and the text
  after the second character will be align to the right.

- =template= The output template.

- =wmClass= The value for the window's X11 WM_CLASS property. Defaults
  to "xmobar".

- =wmName= The value for the window's X11 WM_NAME property. Defaults to
  "xmobar".

*** Running xmobar with i3status

xmobar can be used to display information generated by [[http://i3wm.org/i3status/][i3status]], a small
program that gathers system information and outputs it in formats
suitable for being displayed by the dzen2 status bar, wmii's status bar
or xmobar's =StdinReader=. See [[http://i3wm.org/i3status/manpage.html#_using_i3status_with_xmobar][i3status manual]] for further details.

*** Dynamically sizing xmobar

See [[https://github.com/jaor/xmobar/issues/239#issuecomment-233206552][this idea]] by Jonas Camillus Jeppensen for a way of adapting
dynamically xmobar's size and run it alongside a system tray widget such
as trayer or stalonetray (although the idea is not limited to trays,
really). For your convenience, there is a version of Jonas' script in
[[./examples/padding-icon.sh][examples/padding-icon.sh]].

** Command Line Options

xmobar can be either configured with a configuration file or with
command line options. In the second case, the command line options will
overwrite the corresponding options set in the configuration file.

Example:

#+begin_src shell
  xmobar -B white -a right -F blue -t '%LIPB%' -c '[Run Weather "LIPB" [] 36000]'
#+end_src

This is the list of command line options (the output of xmobar --help):

#+begin_src shell
  Usage: xmobar [OPTION...] [FILE]
  Options:
    -h, -?        --help                 This help
    -v            --verbose              Emit verbose debugging messages
    -r            --recompile            Force recompilation
    -V            --version              Show version information
    -f font name  --font=font name       Font name
    -N font name  --add-font=font name   Add to the list of additional fonts
    -w class      --wmclass=class        X11 WM_CLASS property
    -n name       --wmname=name          X11 WM_NAME property
    -B bg color   --bgcolor=bg color     The background color. Default black
    -F fg color   --fgcolor=fg color     The foreground color. Default grey
    -i path       --iconroot=path        Root directory for icon pattern paths. Default '.'
    -A alpha      --alpha=alpha          Transparency: 0 is transparent, 255 is opaque. Default: 255
    -o            --top                  Place xmobar at the top of the screen
    -b            --bottom               Place xmobar at the bottom of the screen
    -d            --dock                 Don't override redirect from WM and function as a dock
    -a alignsep   --alignsep=alignsep    Separators for left, center and right text
                                         alignment. Default: '}{'
    -s char       --sepchar=char         Character used to separate commands in
                                         the output template. Default '%'
    -t template   --template=template    Output template
    -c commands   --commands=commands    List of commands to be executed
    -C command    --add-command=command  Add to the list of commands to be executed
    -x screen     --screen=screen        On which X screen number to start
    -p position   --position=position    Specify position of xmobar. Same syntax as in config file

  Mail bug reports and suggestions to <mail@jao.io>
#+end_src

** 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
  <icon=/path/to/bitmap.xbm/>
#+end_src

which will produce the expected result. Accepted image formats are XBM
and XPM (when =with_xpm= flag is enabled). If path does not start with
=/=, =./=, =../= it will have

#+begin_src haskell
  iconRoot ++ "/"
#+end_src

prepended to it.

It's also possible to use action directives of the form:

#+begin_src shell
  <action=`command` button=12345>
#+end_src

which will be executed when clicked on with specified mouse buttons.
This tag can be nested, allowing different commands to be run depending
on button clicked.

** The =commands= Configuration Option

The =commands= configuration option is a list of commands information
and arguments to be used by xmobar when parsing the output template.
Each member of the list consists in a command prefixed by the =Run=
keyword. Each command has arguments to control the way xmobar is going
to execute it.

The option consists in a list of commands separated by a comma and
enclosed by square parenthesis.

Example:

#+begin_src haskell
  [Run Memory ["-t","Mem: <usedratio>%"] 10, Run Swap [] 10]
#+end_src

to run the Memory monitor plugin with the specified template, and the
swap monitor plugin, with default options, every second. And here's an
example of a template for the commands above using an icon:

#+begin_src haskell
  template="<icon=/home/jao/.xmobar/mem.xbm/><memory> <swap>"
#+end_src

This example will run "xclock" command when date is clicked:

#+begin_src haskell
  template="<action=`xclock`>%date%</action>
#+end_src

The only internal available command is =Com= (see below Executing
External Commands). All other commands are provided by plugins. xmobar
comes with some plugins, providing a set of system monitors, a standard
input reader, an Unix named pipe reader, a configurable date plugin, and
much more: we list all available plugins below.

Other commands can be created as plugins with the Plugin infrastructure.
See below.

* 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