diff options
Diffstat (limited to 'doc/quick-start.org')
| -rw-r--r-- | doc/quick-start.org | 501 |
1 files changed, 328 insertions, 173 deletions
diff --git a/doc/quick-start.org b/doc/quick-start.org index d711138..fecd953 100644 --- a/doc/quick-start.org +++ b/doc/quick-start.org @@ -1,12 +1,12 @@ #+title: Quick start: using xmobar -Xmobar can either be configured using the configuration language, or [[file:using-haskell.org][used as a +Xmobar can either be configured using the configuration language, or [[https://codeberg.org/xmobar/xmobar/src/branch/master/doc/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. +configuration language, see [[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/xmobar.config][etc/xmobar.config]], and you can have a look at +[[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/xmobar.hs][etc/xmobar.hs]] for an example of how to write your own xmobar using Haskell. -* Command Line Options +* 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 @@ -20,7 +20,7 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you This is the list of command line options (the output of =xmobar --help=): - #+begin_src shell + #+begin_example Usage: xmobar [OPTION...] [FILE] Options: -h, -? --help This help @@ -38,187 +38,350 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you -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 - -T [format] --text[=format] Write output to stdout - - Mail bug reports and suggestions to <mail@jao.io> - #+end_src -* Configuration Options + -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 + -T [format] --text[=format] Write output to stdout + -D dpi --dpi=dpi The DPI scaling factor. Default 96.0 + + Mail bug reports and suggestions to <mail@jao.io> + #+end_example + +* Configuration options :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. + 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: - - =additionalFonts= Haskell-style list of fonts to be used with the - =fn=-template. See also =textOffsets= below. For example: + The following configuration options control the fonts used by xmobar: - #+begin_src haskell - additionalFonts = [iconFont, altIconFont] - #+end_src + - =font= Name, as a string, of the default font to use. - - =bgColor= Background color. + - =additionalFonts= Haskell-style list of fonts to us with the + =fn=-template. See also =textOffsets= below. For example: - - =fgColor= Default font color. + #+begin_src haskell + additionalFonts = [iconFont, altIconFont] + #+end_src + + - =dpi= The DPI scaling factor, as a decimal, to use. If 0, negative, or not + given, the default of 96 will be used, which corresponds to an average + screen. A 10pt font will therefore scale to 10pt * (1/72 pt/inch) * (96 + pixel/inch) = 13.3 pixel. This is especially useful for HiDPI displays. + + 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 + + #+begin_src + <fn=2>some text</fn> + #+end_src - - =alpha= The transparency. 0 is transparent, 255 is opaque. + will use, in the configuration above, ~altIconFont~ to display "some text". - - =position= Top, TopH, TopP, TopW, TopSize, Bottom, BottomH, - BottomP, BottomW, BottomSize or Static (with x, y, width and height). + Font names use the [[https://docs.gtk.org/Pango/type_func.FontDescription.from_string.html][Pango format]]. Here are a few simple examples: - TopP and BottomP take 2 arguments: left padding and right padding. + #+begin_example + DejaVu Sans Mono 10 - 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. + Iosevka Comfy Semi-Bold Italic 12 - 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. + Noto Color Emoji 10 + #+end_example - TopH and BottomH take one argument (Int) which adjusts the bar height. + 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. - For example: + There are many possible style options (if your font supports them). They + can be - #+begin_src haskell - position = TopH 30 - #+end_src + - *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. - to make a 30 tall bar on the top, or + So you can add up to 5 style options per family: - #+begin_src haskell - position = BottomH 30 - #+end_src + #+begin_example + Monospace Italic All-Small-Caps Extra-Light Thin North 12 + #+end_example - to make a 30 tall bar on the bottom of the screen. + 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. A bit confusingly, the styles and sizes come in reverse + order after the families: - #+begin_src haskell - position = BottomW C 75 - #+end_src + #+begin_example + Family 1, Family 2 Styles 2 Size 2, Styles 1 Size 1 + #+end_example - to place xmobar at the bottom, centered with the 75% of the screen - width. Or + For instance you could have: - #+begin_src haskell - position = BottomP 120 0 - #+end_src + #+begin_example + Souce Code Pro, Noto Color Emoji Regular 12, Semi-Bold 10 + #+end_example - to place xmobar at the bottom, with 120 pixel indent of the left. Or + 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. - #+begin_src haskell - position = Static { xpos = 0 , ypos = 0, width = 1024, height = 15 } - #+end_src +**** X11 Bitmap fonts - or + If you want to use traditional, non-aliased X11 fonts, you can do so via + the [[https://www.cl.cam.ac.uk/~mgk25/ucs-fonts.html][Unicode fonts and tools for X11]] package, which provides bitmap + versions of them, with a specification of the stytle ~"Fixed 8"~ for what + in the old days would have been something like + ~-Misc-Fixed-Medium-R-Normal--13-120-75-75-C-70-ISO10646-1~. See also + discussion in [[https://codeberg.org/xmobar/xmobar/issues/658][issue #658]]. - #+begin_src haskell - position = Top - #+end_src +*** Colors - - =textOffset= The vertical offset, in pixels, for the text baseline. If - negative or not given, xmobar will try to center text vertically. + - =bgColor= Background color. - - =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. + - =fgColor= Default font color. - - =iconOffset= The vertical offset, in pixels, for icons bottom line. If - negative or not given, xmobar will try to center icons vertically. + - =alpha= The transparency. 0 is transparent, 255 is opaque. - - =lowerOnStart= When True the window is sent the bottom of the window - stack initially. +*** Vertical offsets - - =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. + 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: - - =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. + - =textOffset= The vertical offset, in pixels, for the text baseline. If + negative or not given, xmobar will try to center text vertically. - - =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=. + - =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. - - =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. + - =iconOffset= The vertical offset, in pixels, for icons bottom line. If + negative or not given, xmobar will try to center icons vertically. - - =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. +*** Borders + + - =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 - - =border= TopB, TopBM, BottomB, BottomBM, FullB, FullBM or NoBorder - (default). + prepended to it. Default is =.=. - TopB, BottomB, FullB take no arguments, and request drawing a border - at the top, bottom or around xmobar's window, respectively. +*** Bar position - TopBM, BottomBM, FullBM take an integer argument, which is the margin, - in pixels, between the border of the window and the drawn border. + - =position= Top, TopH, TopHM, TopP, TopW, TopSize, Bottom, BottomH, BottomHM, + BottomP, BottomW, BottomSize or Static (with x, y, width and height). - - =borderColor= Border color. + TopP and BottomP take 2 arguments: left padding and right padding. - - =borderWidth= Border width in pixels. + 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. - - =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 + 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. - #+begin_src haskell - iconRoot ++ "/" - #+end_src + TopH and BottomH take one argument (Int) which adjusts the bar height. - prepended to it. Default is =.=. + For example: - - =commands= For setting the options of the programs to run (optional). + #+begin_src haskell + position = TopH 30 + #+end_src + + 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. The corresponding + variants ~TopHM~ and ~BottomHM~ allow you to specify, in addition to a + height, margins (in pixels) with the borders of the screen (left, right + top and bottom); so they take five integers as arguments. For instance, + if you one a margin of 2 pixels to the left of the top bar in the above + example and 4 to its right and top, you could use: + + #+begin_src haskell + position = TopHM 30 2 4 4 0 + #+end_src + + and similarly for ~BottomHM~. + + #+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 - - =sepChar= The character to be used for indicating commands in the - output template (default '%'). + or + + #+begin_src haskell + position = Top + #+end_src + + - =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. + + - =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". + +*** Text output + + - =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 [[https://codeberg.org/xmobar/xmobar/src/branch/master/doc/plugins.org][plugin documentation]] details all the + available monitors, and you can also create new ones using Haskell. See + the [[#commands-list][commands list section]] below for more. + + - =sepChar= The character to be used for indicating commands in the + output template (defaults to '%'). + + - =alignSep= a 2-character string for aligning text in the output + template. See [[#bar-sections][this section]] for details. + + - =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 - - =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. + 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: - - =template= The output template. + #+begin_src haskell + template = "<icon=/home/jao/.xmobar/mem.xbm/><memory> <swap>" + #+end_src - - =wmClass= The value for the window's X11 ~WM_CLASS~ property. Defaults - to "xmobar". + This example will run "xclock" command when date is clicked: - - =wmName= The value for the window's X11 ~WM_NAME~ property. Defaults to - "xmobar". + #+begin_src haskell + template = "<action=`xclock`>%date%</action>" + #+end_src - - =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. + 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. - - =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. + 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 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 + aliases, see the [[https://codeberg.org/xmobar/xmobar/src/branch/master/doc/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. @@ -242,7 +405,8 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you opacity, with two additional hex digits (e.g. #FF00000aa). - =<fn=1>string</fn>= will print =string= with the first font from - =additionalFonts=. The index =0= corresponds to the standard font. + =additionalFonts=. The index =0= corresponds to the standard font. The + standard font is also used if the index is out of bounds. - =<hspace=X/>= will insert a blank horizontal space of =X= pixels. For example, to add a blank horizontal space of 123 pixels, @@ -284,6 +448,37 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you See the subsections below for more information on ~<box/>~, ~<icon/>~ and ~<action/>~. + - The special characters =}= and ={= are used to delimit up to three sections + in the bar that are drawn and aligned independently. See [[#bar-sections][this section]] + for more. + +*** Bar sections + :PROPERTIES: + :CUSTOM_ID: bar-sections + :END: + + You can use the special characters =}= and ={= are used to delimit up to three + sections in the bar, which are aligned and, if needed, overlapped + according to these rules: + + - If the template has the form =L}M{R=, with L, R, M arbitrary specs, the + monitors in =L= are drawn first, aligned to the left, then =R=, aligned to + the right, and finally =M= is drawn centered in the bar. =R= is trimmed to + the space left by =L=, and =M= is trimmed to the space left by =L= and =R=. As + a particular case, =}M{= will draw a single segment centered in the bar. + + - If the template has the form =L}{R=, =L= is drawn aligned to the left first + and then =R=, aligned to the right and trimmed if needed to fit in the + space left by =L=. + + - If the template has the form =}L{R=, =R= is drawn first, aligned to the + right, and then =L=, aligned to the left and trimmed to the space left by + =R=. + + When needed, sections are always trimmed on the right. The section + delimiters can be changed using the configuration option =alignSep,= a + two-character string. + *** Boxes around text - =<box>string</box>= will print string surrounded by a box in the @@ -319,7 +514,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 +539,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 +*** Mouse actions It's also possible to use action directives of the form: @@ -359,46 +554,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: @@ -430,7 +585,7 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you 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 + display your monitors in the mode line or the tab bar. The [[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/xmobar.el][xmobar.el package]] provides a simple way of doing it. ** Using xmobar in wayland with swaybar or waybar :PROPERTIES: @@ -474,7 +629,7 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you 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]]. + [[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/padding-icon.sh][etc/padding-icon.sh]]. ** Signal handling @@ -484,10 +639,10 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you - After receiving ~SIGUSR2~ xmobar repositions itself on the current screen. -* The DBus Interface +* The DBus interface When compiled with the optional =with_dbus= flag, xmobar can be controlled - over dbus. All signals defined in [[../src/Xmobar/System/Signal.hs][src/Signal.hs]] as =data SignalType= can now + over dbus. All signals defined in [[https://codeberg.org/xmobar/xmobar/src/branch/master/src/Xmobar/System/Signal.hs][src/Signal.hs]] as =data SignalType= can now be sent over dbus to xmobar. Due to current limitations of the implementation only one process of xmobar |