1 \section{The statusbar}
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}
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.)
20 A typical \file{cfg\_statusbar.lua} configuration might look as follows:
26 screen = 0, -- First screen,
27 pos = 'bl', -- bottom left corner
28 systray = true, -- Swallow systray windows
31 template = "[ %date || load:% %>load || mail:% %>mail_new/%>mail_total ]"
32 .. " %filler%systray",
35 -- Launch ion-statusd.
36 mod_statusbar.launch_statusd{
39 -- ISO-8601 date format with additional abbreviated day name
40 date_format='%a %Y-%m-%d %H:%M',
46 \subsection{The template}
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
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.
69 \subsection{The systray}
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\_*}.
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
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).
96 Monitors: \codestr{date} and other user-specified ones with the
97 \codestr{date\_} prefix.
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).
109 Monitors: \codestr{load} (for all three values),
110 \codestr{load\_1min}, \codestr{load\_5min} and \codestr{load\_15min}.
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
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).