conf-statusbar.tex

   1 \section{The statusbar}
   2 \label{sec:statusbar}
   3
   4 The \file{mod\_statusbar} module provides a statusbar that adapts to
   5 layouts of tilings, using only the minimal space needed. Ion only
   6 supports one adaptive ``status display'' object per screen, so this
   7 statusbar is mutually exclusive with the embedded mode of \file{mod\_dock}
   8 docks.
   9
  10 The statusbar is configured in \file{cfg\_statusbar.lua}. Typically,
  11 the configuration consists of two steps: creating a statusbar with
  12 \fnref{mod\_statusbar.create}, and then launching the separate
  13 \command{ion-statusd} status daemon process with
  14 \fnref{mod_statusbar.launch_statusd}. This latter phase is done
  15 automatically, if it was not done by the configuration file, but
  16 the configuration file may pass extra parameters to \command{ion-statusd}
  17 monitors. (See Section \ref{sec:statusd} for more information on
  18 writing \command{ion-statusd} monitors.)
  19
  20 A typical \file{cfg\_statusbar.lua} configuration might look as follows:
  21
  22
  23 \begin{verbatim}
  24 -- Create a statusbar
  25 mod_statusbar.create{
  26     screen = 0,     -- First screen,
  27     pos = 'bl',     -- bottom left corner
  28     systray = true, -- Swallow systray windows
  29
  30     -- The template
  31     template = "[ %date || load:% %>load || mail:% %>mail_new/%>mail_total ]"
  32                .. " %filler%systray",
  33 }
  34
  35 -- Launch ion-statusd.
  36 mod_statusbar.launch_statusd{
  37     -- Date meter
  38     date={
  39         -- ISO-8601 date format with additional abbreviated day name
  40         date_format='%a %Y-%m-%d %H:%M',
  41     },
  42 }
  43 \end{verbatim}
  44
  45
  46 \subsection{The template}
  47
  48 The template specifies what is shown on the statusbar; for information
  49 on the other options to \fnref{mod_statusbar.create}, see the reference.
  50 Strings of the form \codestr{\%spec} tokens specially interpreter by
  51 the statusbar; the rest appears verbatim. The \code{spec} typically
  52 consists of the name of the value/meter to display (beginning with a latin
  53 alphabet), but may be preceded by an alignment specifier and a number
  54 specifying the minimum width. The alignment specifiers are: \codestr{>}
  55 for right, \codestr{<} for left,  and \codestr{|} for centring. Additionally,
  56 space following \codestr{\%} (that is, the string \codestr{\% }), adds
  57 ``stretchable space'' at that point. The special string \codestr{\%filler}
  58 may be used to flush the rest of the template to the right end of
  59 the statusbar.
  60
  61 The stretchable space works as follows: \file{mod\_statusbar} remembers
  62 the widest string (in terms of graphical presentation) that it has
  63 seen for each meter, unless the width has been otherwise constrained.
  64 If there is stretchable space in the template, it tries to make the
  65 meter always take this much space, by stretching any space found in
  66 the direction indicated by the alignment specifier: the opposite
  67 direction for left or right alignment, and both for centring.
  68
  69 \subsection{The systray}
  70
  71 The special \codestr{\%systray} and \codestr{\%systray\_*}
  72 (\codestr{*} varying) monitors indicate where to place system tray
  73 windows.  There may be multiple of these. KDE-protocol system tray
  74 icons are placed in \codestr{\%systray} automatically, unless disabled
  75 with the \var{systray} option. Otherwise the \var{statusbar} winprop may
  76 be used to place any window in any particular \codestr{\%systray\_*}.
  77
  78 \subsection{Monitors}
  79
  80 The part before the first
  81 underscore of each monitor name, describes the script/plugin/module
  82 that provides the meter, and any configuration should be passed
  83 in the a corresponding sub-table \fnref{mod_statusbar.launch_statusd}.
  84 Ion comes with date, load and mail (for plain old mbox)
  85 \command{ion-statusd} monitor scripts. More may be obtained from
  86 the scripts repository \cite{scripts}. These included scripts
  87 provide the following monitors and their options
  88
  89 \subsubsection{Date}
  90
  91 Options: \var{date_format}: The date format in as seen above,
  92 in the usual \code{strftime} format. \code{formats}: table of
  93 formats for additional date monitors, the key being the name
  94 of the monitor (without the \codestr{date\_} prefix).
  95
  96 Monitors: \codestr{date} and other user-specified ones with the
  97 \codestr{date\_} prefix.
  98
  99
 100 \subsubsection{Load}
 101
 102 Options: \var{update_interval}: Update interval in milliseconds
 103 (default 10s). \var{important_threshold}: Threshold above which
 104 the load is marked as important (default 1.5), so that the
 105 drawing engine may be suitably hinted. \var{critical_threshold}:
 106 Threshold above which  the load is marked as critical (default 4.0).
 107
 108
 109 Monitors: \codestr{load} (for all three values),
 110 \codestr{load\_1min}, \codestr{load\_5min} and \codestr{load\_15min}.
 111
 112
 113 \subsubsection{Mail}
 114
 115 Options: \var{update_interval}: Update interval in milliseconds
 116 (default 1min). \var{mbox}: mbox-format mailbox location
 117 (default \verb!$MAIL!).
 118 \var{files}: list of additional mailboxes, the key giving the
 119 name of the monitor.
 120
 121 Monitors: \codestr{mail\_new}, \codestr{mail\_unread},
 122 \codestr{mail\_total}, and corresponding
 123 \codestr{mail\_*\_new}, \codestr{mail\_*\_unread}, and \codestr{mail\_*\_total}
 124 for the additional mailboxes (\codestr{*} varying).