diff options
| -rw-r--r-- | doc/quick-start.org | 387 |
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: |