summaryrefslogtreecommitdiffhomepage
path: root/doc/quick-start.org
diff options
context:
space:
mode:
authorjao <jao@gnu.org>2022-09-28 02:02:10 +0100
committerjao <jao@gnu.org>2022-09-28 02:02:10 +0100
commit2bc71d2f670de1a1156f74b2c9e1065758c9125e (patch)
treebb62b9a703debc64bca9da4daa65cbe4c0a01628 /doc/quick-start.org
parentf946b9c37b39a1b46bfe6433434f951ece531d94 (diff)
downloadxmobar-2bc71d2f670de1a1156f74b2c9e1065758c9125e.tar.gz
xmobar-2bc71d2f670de1a1156f74b2c9e1065758c9125e.tar.bz2
documentation updates
Diffstat (limited to 'doc/quick-start.org')
-rw-r--r--doc/quick-start.org387
1 files changed, 239 insertions, 148 deletions
diff --git a/doc/quick-start.org b/doc/quick-start.org
index d711138..ab7bab4 100644
--- a/doc/quick-start.org
+++ b/doc/quick-start.org
@@ -56,162 +56,293 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you
: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.
+ Here are all the global options that you can set within the =Config= block in
+ your configuration and will define the overall behaviour and looks of your
+ bar.
- - =font= Name of the font to be used.
+*** Fonts
+ :PROPERTIES:
+ :CUSTOM_ID: fonts
+ :END:
+
+ The following configuration options control the fonts used by xmobar:
+
+ - =font= Name, as a string, of the default font to use.
- - =additionalFonts= Haskell-style list of fonts to be used with the
- =fn=-template. See also =textOffsets= below. For example:
+ - =additionalFonts= Haskell-style list of fonts to us with the
+ =fn=-template. See also =textOffsets= below. For example:
- #+begin_src haskell
- additionalFonts = [iconFont, altIconFont]
- #+end_src
+ #+begin_src haskell
+ additionalFonts = [iconFont, altIconFont]
+ #+end_src
+
+ The global font is used by default when none of the others is specified
+ using the ~<fn=n>...</fn>~ markup, with ~n~ a 1-based index in the
+ ~additionalFonts~ array. So, for instance
- - =bgColor= Background color.
+ #+begin_src
+ <fn=2>some text</fn>
+ #+end_src
- - =fgColor= Default font color.
+ will use, in the configuration above, ~altIconFont~ to display "some text".
- - =alpha= The transparency. 0 is transparent, 255 is opaque.
+ Font names use the [[https://docs.gtk.org/Pango/type_func.FontDescription.from_string.html][Pango format]]. Here are a few simple examples:
- - =position= Top, TopH, TopP, TopW, TopSize, Bottom, BottomH,
- BottomP, BottomW, BottomSize or Static (with x, y, width and height).
+ #+begin_example
+ DejaVu Sans Mono 10
- TopP and BottomP take 2 arguments: left padding and right padding.
+ Iosevka Comfy Semi-Bold Italic 12
- 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.
+ Noto Color Emoji 10
+ #+end_example
- 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.
+ We start with a family name (DejaVu Sans Mono, Iosevka Comfy, etc.),
+ followed by optional, space-separated /style options/ (Semi-Bold Italic in
+ the second example above), and ending with a size, in points.
- TopH and BottomH take one argument (Int) which adjusts the bar height.
+ There are many possible style options (if your font supports them). They
+ can be
- For example:
+ - *Plain styles*: Normal, Roman, Oblique, Italic.
+ - *Variants*: Small-Caps, All-Small-Caps, Petite-Caps, All-Petite-Caps,
+ Unicase, Title-Caps.
+ - *Weights*: Thin, Ultra-Light, Extra-Light, Light, Semi-Ligh, Demi-Light,
+ Book, Regular, Medium, Semi-Bold, Demi-Bold, Bold, Ultra-Bold,
+ Extra-Bold, Heavy, Black, Ultra-Black, Extra-Black.
+ - *Strectch values:* Thin, Ultra-Light, Extra-Light, Light, Semi-Light,
+ Demi-Light, Book, Regular, Medium, Semi-Bold, Demi-Bold, Bold,
+ Ultra-Bold, Extra-Bold, Heavy, Black, Ultra-Black, Extra-Black.
+ - *Gravity values*: Not-Rotated, South, Upside-Down, North, Rotated-Left,
+ East, Rotated-Right, West.
- #+begin_src haskell
- position = TopH 30
- #+end_src
+ So you can add up to 5 style options per family:
- to make a 30 tall bar on the top, or
+ #+begin_example
+ Monospace Italic All-Small-Caps Extra-Light Thin North 12
+ #+end_example
- #+begin_src haskell
- position = BottomH 30
- #+end_src
+ It's also possible to specify a list of fonts, separating them by commas,
+ so that they act as fallbacks when the preceding one is not able to display
+ a given glyph. For instance you could have:
- to make a 30 tall bar on the bottom of the screen.
+ #+begin_example
+ Souce Code Pro, Not Color Emoji Semi-Bold, Regular 10, 12
+ #+end_example
- #+begin_src haskell
- position = BottomW C 75
- #+end_src
+ to use Source Code Pro Semi-Bold 10 when possible, and fall back to Noto
+ Color Emoji Regular 12 for characters that the former cannot display.
- to place xmobar at the bottom, centered with the 75% of the screen
- width. Or
+*** Colors
- #+begin_src haskell
- position = BottomP 120 0
- #+end_src
+ - =bgColor= Background color.
- to place xmobar at the bottom, with 120 pixel indent of the left. Or
+ - =fgColor= Default font color.
- #+begin_src haskell
- position = Static { xpos = 0 , ypos = 0, width = 1024, height = 15 }
- #+end_src
+ - =alpha= The transparency. 0 is transparent, 255 is opaque.
- or
+*** Vertical offsets
- #+begin_src haskell
- position = Top
- #+end_src
+ By default, all text and icons in the bar will be vertically centered
+ according to the configured height of the bar. You can override that
+ behaviour with the following options:
- - =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.
+*** Borders
- - =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.
+ - =border= TopB, TopBM, BottomB, BottomBM, FullB, FullBM or NoBorder
+ (default).
- - =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.
+ TopB, BottomB, FullB take no arguments, and request drawing a border
+ at the top, bottom or around xmobar's window, respectively.
- - =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=.
+ TopBM, BottomBM, FullBM take an integer argument, which is the margin,
+ in pixels, between the border of the window and the drawn border.
- - =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.
+ - =borderColor= Border color.
- - =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.
+ - =borderWidth= Border width in pixels.
- - =border= TopB, TopBM, BottomB, BottomBM, FullB, FullBM or NoBorder
- (default).
+ - =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
- TopB, BottomB, FullB take no arguments, and request drawing a border
- at the top, bottom or around xmobar's window, respectively.
+ #+begin_src haskell
+ iconRoot ++ "/"
+ #+end_src
- TopBM, BottomBM, FullBM take an integer argument, which is the margin,
- in pixels, between the border of the window and the drawn border.
+ prepended to it. Default is =.=.
- - =borderColor= Border color.
+*** Bar position
- - =borderWidth= Border width in pixels.
+ - =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.
+
+ 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.
+
+ TopH and BottomH take one argument (Int) which adjusts the bar height.
+
+ For example:
+
+ #+begin_src haskell
+ position = TopH 30
+ #+end_src
- - =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
+ to make a 30 tall bar on the top, or
+
+ #+begin_src haskell
+ position = BottomH 30
+ #+end_src
+
+ to make a 30 tall bar on the bottom of the screen.
+
+ #+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
- #+begin_src haskell
- iconRoot ++ "/"
- #+end_src
+ - =lowerOnStart= When True the window is sent the bottom of the window
+ stack initially.
- prepended to it. Default is =.=.
+ - =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.
- - =commands= For setting the options of the programs to run (optional).
+ - =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.
- - =sepChar= The character to be used for indicating commands in the
- output template (default '%').
+ - =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=.
- - =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.
+ - =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.
- - =template= The output template.
+ - =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.
- - =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.
+*** Text output
- - =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.
+ - =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.
+
+*** Commands and monitors
+
+ - =commands= The list of monitors and plugins to run, together with their
+ individual configurations. The [[./plugins.org][plugin documentation]] details all the
+ available monitors, and you can also create new ones using Haskell. See
+ [[#commands-list][The commands list]] section below for more.
+
+ - =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: a string telling xmobar how to display the
+ outputs of all the =commands= above. See [[#output-template][the next section]] for a full
+ description.
+
+** The =commands= list
+ :PROPERTIES:
+ :CUSTOM_ID: commands-list
+ :END:
+
+ 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 options consist 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.
** The output =template=
+ :PROPERTIES:
+ :CUSTOM_ID: output-template
+ :END:
The output template is how xmobar will end up printing all of your
configured commands. It must contain at least one command. Xmobar
@@ -319,7 +450,7 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you
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:
@@ -344,7 +475,7 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you
Icons are ignored when xmobar is run in text output mode.
-*** Action Directives
+*** Using the mouse: Action directives
It's also possible to use action directives of the form:
@@ -359,46 +490,6 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you
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 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.
-
* Runtime behaviour
** Running xmobar in text mode
:PROPERTIES: