--- /dev/null
+\section{The statusbar}
+\label{sec:statusbar}
+
+The \file{mod\_statusbar} module provides a statusbar that adapts to
+layouts of tilings, using only the minimal space needed. Ion only
+supports one adaptive ``status display'' object per screen, so this
+statusbar is mutually exclusive with the embedded mode of \file{mod\_dock}
+docks.
+
+The statusbar is configured in \file{cfg\_statusbar.lua}. Typically,
+the configuration consists of two steps: creating a statusbar with
+\fnref{mod\_statusbar.create}, and then launching the separate
+\command{ion-statusd} status daemon process with
+\fnref{mod_statusbar.launch_statusd}. This latter phase is done
+automatically, if it was not done by the configuration file, but
+the configuration file may pass extra parameters to \command{ion-statusd}
+monitors. (See Section \ref{sec:statusd} for more information on
+writing \command{ion-statusd} monitors.)
+
+A typical \file{cfg\_statusbar.lua} configuration might look as follows:
+
+
+\begin{verbatim}
+-- Create a statusbar
+mod_statusbar.create{
+ screen = 0, -- First screen,
+ pos = 'bl', -- bottom left corner
+ systray = true, -- Swallow systray windows
+
+ -- The template
+ template = "[ %date || load:% %>load || mail:% %>mail_new/%>mail_total ]"
+ .. " %filler%systray",
+}
+
+-- Launch ion-statusd.
+mod_statusbar.launch_statusd{
+ -- Date meter
+ date={
+ -- ISO-8601 date format with additional abbreviated day name
+ date_format='%a %Y-%m-%d %H:%M',
+ },
+}
+\end{verbatim}
+
+
+\subsection{The template}
+
+The template specifies what is shown on the statusbar; for information
+on the other options to \fnref{mod_statusbar.create}, see the reference.
+Strings of the form \codestr{\%spec} tokens specially interpreter by
+the statusbar; the rest appears verbatim. The \code{spec} typically
+consists of the name of the value/meter to display (beginning with a latin
+alphabet), but may be preceded by an alignment specifier and a number
+specifying the minimum width. The alignment specifiers are: \codestr{>}
+for right, \codestr{<} for left, and \codestr{|} for centring. Additionally,
+space following \codestr{\%} (that is, the string \codestr{\% }), adds
+``stretchable space'' at that point. The special string \codestr{\%filler}
+may be used to flush the rest of the template to the right end of
+the statusbar.
+
+The stretchable space works as follows: \file{mod\_statusbar} remembers
+the widest string (in terms of graphical presentation) that it has
+seen for each meter, unless the width has been otherwise constrained.
+If there is stretchable space in the template, it tries to make the
+meter always take this much space, by stretching any space found in
+the direction indicated by the alignment specifier: the opposite
+direction for left or right alignment, and both for centring.
+
+\subsection{The systray}
+
+The special \codestr{\%systray} and \codestr{\%systray\_*}
+(\codestr{*} varying) monitors indicate where to place system tray
+windows. There may be multiple of these. KDE-protocol system tray
+icons are placed in \codestr{\%systray} automatically, unless disabled
+with the \var{systray} option. Otherwise the \var{statusbar} winprop may
+be used to place any window in any particular \codestr{\%systray\_*}.
+
+\subsection{Monitors}
+
+The part before the first
+underscore of each monitor name, describes the script/plugin/module
+that provides the meter, and any configuration should be passed
+in the a corresponding sub-table \fnref{mod_statusbar.launch_statusd}.
+Ion comes with date, load and mail (for plain old mbox)
+\command{ion-statusd} monitor scripts. More may be obtained from
+the scripts repository \cite{scripts}. These included scripts
+provide the following monitors and their options
+
+\subsubsection{Date}
+
+Options: \var{date_format}: The date format in as seen above,
+in the usual \code{strftime} format. \code{formats}: table of
+formats for additional date monitors, the key being the name
+of the monitor (without the \codestr{date\_} prefix).
+
+Monitors: \codestr{date} and other user-specified ones with the
+\codestr{date\_} prefix.
+
+
+\subsubsection{Load}
+
+Options: \var{update_interval}: Update interval in milliseconds
+(default 10s). \var{important_threshold}: Threshold above which
+the load is marked as important (default 1.5), so that the
+drawing engine may be suitably hinted. \var{critical_threshold}:
+Threshold above which the load is marked as critical (default 4.0).
+
+
+Monitors: \codestr{load} (for all three values),
+\codestr{load\_1min}, \codestr{load\_5min} and \codestr{load\_15min}.
+
+
+\subsubsection{Mail}
+
+Options: \var{update_interval}: Update interval in milliseconds
+(default 1min). \var{mbox}: mbox-format mailbox location
+(default \verb!$MAIL!).
+\var{files}: list of additional mailboxes, the key giving the
+name of the monitor.
+
+Monitors: \codestr{mail\_new}, \codestr{mail\_unread},
+\codestr{mail\_total}, and corresponding
+\codestr{mail\_*\_new}, \codestr{mail\_*\_unread}, and \codestr{mail\_*\_total}
+for the additional mailboxes (\codestr{*} varying).
projects / ion3-doc.git / blobdiff