tdeaddons/doc/kicker-applets/ktimemon.docbook

<chapter id="ktimemon">
<chapterinfo>

<title>&ktimemon;</title>

<authorgroup>
<author>
<firstname>Martin</firstname>
<surname>Maierhofer</surname>
<affiliation>
<address><email>m.maierhofer@tees.ac.uk</email></address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<date>2001-11-29</date>
<releaseinfo>0.03.01</releaseinfo>
<abstract>
<para>&ktimemon; is a system monitor for the Trinity Desktop Environment</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>ktimemon</keyword>
<keyword>system monitor</keyword>
<keyword>timemon</keyword>
</keywordset>
</chapterinfo>

<title>Introduction</title>

<para>&ktimemon; is a small program to keep track of your computer's system
usage. It can display bar graphs containing information about
<acronym>CPU</acronym>, memory, and swap usage as well as disk usage and
context switch activity. In keeping with the spirit of <ulink
url="http://www.kde.org/">KDE</ulink>, it supports configuration via a
graphical user interface. It also supports <emphasis>docking</emphasis>,
&ie; it can display information in the system panel tray.</para>

<note>
<para>Currently, &ktimemon; only supports a limited number of systems:
&Linux; based installations with the <filename>/proc</filename> file
system, &Solaris; based installations with the
<filename>kstat</filename> library, and Digital &UNIX; (formerly
DEC/OSF1) based installations with the
<command>table</command>(2) system call. Help with
porting it to other platforms is most welcome.
</para>
</note>

<para>
&ktimemon; can be started from the command line or from the &kde;
<guimenu>start</guimenu> menu (in the <guisubmenu>Utilities</guisubmenu>
submenu). If you choose to start from the command line, &ktimemon;
honors the usual &X-Window; program flags such as
<option>-geometry</option>. &ktimemon; is
<emphasis>session-aware</emphasis>, &ie; it keeps track of the current
state (colors, &etc;) and restores it in the user's next session.
</para>

<sect1 id="fund">
<title>Onscreen Fundamentals</title>

<para>
After starting &ktimemon; a small window will appear displaying
information gathered from the operating system. If you move the mouse 
pointer over the &ktimemon; window and let it rest for a small amount of 
time, a <emphasis>tool-tip</emphasis> (&ie; a small transient window)
will appear. The tool-tip contains numeric information about the system
parameters displayed by the bar graphs. Tool-tips can be disabled (refer
to <link linkend="config">Configuration</link>).
</para> 

<sect2 id="modes">
<title>Display Modes</title>

<para>
&ktimemon; can display two different sets of system information. As
explained in the <link linkend="config">Configuration</link> chapter,
mouse buttons can be bound to various actions. Per default, the left
mouse button is bound to the mode switch action, &ie; by clicking the
&LMB; mouse button anywhere in the &ktimemon; window, the displayed
information switches from <guilabel>Normal Mode</guilabel> (the default)
to <guilabel>Extended Mode</guilabel>, and vice versa.
</para>

<sect3 id="normalmode">
<title>Normal Mode</title>

<para>After starting &ktimemon; for the first time, it will show
information about the current CPU activity, as well as memory and swap
usage. Three bar graphs are used to show this information; they are
updated regularly (the default sample interval is 0.5s, but it can be
changed, see <link linkend="config">Configuration</link>). The three bar
graphs represent (from left to right):
<variablelist>
<varlistentry>
<term><acronym>CPU</acronym> usage.</term>
<listitem>
<para>&ktimemon; shows the bar in three different colors, representing
<acronym>CPU</acronym> time spent in various modes. From bottom to top
they are: kernel mode, user mode, and user mode with lowered priority
(<emphasis>nice</emphasis>) - since &Solaris; does not seem to support
statistics for nice mode, the topmost part of the bar represents time
spent in the <emphasis>wait</emphasis> state on such systems. The gap
from the top of the bar to the top of the window represents the
percentage the <acronym>CPU</acronym> idle time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Memory usage.</term>
<listitem>
<para>Similar to the <acronym>CPU</acronym> usage bar, this bar is
composed of three sub fields, representing (from bottom to top):
memory allocated by processes, memory used for I/O buffering, and
memory used for file caching. For Digital &UNIX; based systems, the
middle section represents <quote>inactive</quote> memory (&ie; memory
allocated and not used for a certain amount of time), and for
&Solaris; based systems, the middle section of the bar is not used,
and the topmost section represents the amount of memory used by the
kernel. Again, the gap from the top of the bar to the top of the
window represents free memory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Swap usage.</term>
<listitem>
<para>This bar consists of a single field representing
the current swap usage relative to the system's total amount of swap
space. </para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>Clicking the mouse button bound to <quote>mode switch</quote> in
the &ktimemon; window switches to <quote>Extended Mode</quote>.</para>

</sect3>

<sect3 id="xtndmode">
<title>Extended Mode </title>

<para>In this mode, the three bar graphs are used to display a different
set of system information. Again from left to right, they show:</para>

<variablelist>
<varlistentry>
<term>Paging activity.</term>
<listitem>
<para>This bar consists of two parts, the lower half
of which shows the number of memory pages written to secondary
storage in the last sample interval. Similarly, the upper half
indicates the number of pages read from secondary storage.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Swapping activity.</term>
<listitem>
<para>The second bar displays the analog
information for swap activity.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Context switches.</term>
<listitem>
<para>Again, this bar graph consists of a single
field which indicates the number of context switches in the last
sample interval.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Since there is no <quote>natural</quote> way of scaling the
information shown in <quote>Extended Mode</quote>, by default
&ktimemon; uses <emphasis>autoscaling</emphasis> (explained in the
<link linkend="autoscaling">Common Questions Section</link>). There
is, however, the possibility of specifying the scaling information,
see the <link linkend="config">Configuration</link> section.</para>

<para>Note that the two sets of bar graphs share the same colors, &ie;
the colors setup for <quote>Normal Mode</quote> is also used for
displaying information in <quote>Extended Mode</quote> (see also <link
linkend="config">Configuration</link> on how to change the color
scheme).</para>
</sect3>
</sect2>
  </sect1>

<sect1 id="menu">
<title>Menu Structure</title>

<para>
By default, the &RMB; mouse button is bound to the <quote>menu
pop-up</quote> action, &ie; clicking the right mouse button anywhere in
the &ktimemon; window brings up a menu, which is discussed in the
following sections.  
</para>

<sect2 id="config-menu">
<title><guimenuitem>Settings...</guimenuitem></title>

<para>The <guimenuitem>Settings...</guimenuitem> menu item is used to
pop up the configuration dialog. Configuration options are discussed in
section <link linkend="config">Configuration</link>.
</para> 
</sect2>

<sect2 id="docked-in-panel">
<title><guimenuitem>Docked In Panel</guimenuitem></title>

<para>
By selecting the <guimenuitem>Docked In Panel</guimenuitem> menu item,
&ktimemon; switches between its standard display (&ie; a normal window)
and the panelized state, where the &ktimemon; window disappears and a
smaller version is displayed in the system panel. Apart from the
reduction in size, the <quote>panelized</quote> &ktimemon; behaves
exactly like its big brother.
</para> 
</sect2>

<sect2 id="help">
<title><guimenu>Help</guimenu></title>

&help.menu.documentation;

</sect2>

<sect2 id="horizontal-bars">
<title><guimenuitem>Horizontal Bars</guimenuitem></title>

<para>By selecting the <guimenuitem>Horizontal Bars</guimenuitem> menu
entry, &ktimemon; switches from vertical bars to horizontal bars and
vice versa. Not very useful, but it was easy to implement ;-)
</para>
</sect2>

<sect2 id="quit">
<title><guimenuitem>Quit</guimenuitem></title>

<para>
The <guimenuitem>Quit</guimenuitem> menu item - surprise, surprise
-- is used to terminate &ktimemon;. It will save the current state
(&eg; the color scheme, window size, whether it is displayed in the
panel) and restore the state in the next invocation.
</para>

<para>
The configuration information is saved in the file
<filename>$<envar>HOME</envar>/.kde/share/config/ktimemonrc</filename>,
where <filename class="directory">$<envar>HOME</envar></filename> refers
to the user's home folder. If this file is deleted, &ktimemon; will
start in its default state in the next invocation.
</para> 
</sect2>
</sect1>

<sect1 id="config">
<title>Configuration</title>

<para>
&ktimemon; can be configured via a straight-forward dialog (see also the
discussion of the <link linkend="config-menu">Configuration
Menu</link>). On the <guilabel>General</guilabel> page, the sample
interval can be specified as well as scaling information (see also the
discussion of the <link linkend="xtndmode">extended mode</link>). If the
<guilabel>Autoscaling</guilabel> check box is ticked (autoscaling is
explained in the <link linkend="autoscaling">FAQ</link> section), the
scaling factors cannot be edited, since &ktimemon; determines them
automatically.  
</para>

<para>
The <guilabel>Colors</guilabel> page can be used to tailor the colors of
the bar graph to individual preferences. A small sample bar graph gives
immediate feedback.
</para>

<para>
In the <guilabel>Interaction</guilabel> page, mouse bindings can be
adapted. Clicking a mouse button on the &ktimemon; window can be
ignored, trigger a mode switch (see also <link
linkend="modes">Modes</link>), invoke the context menu (see also <link
linkend="menu">Menu</link>), or invoke an external process. The command
line specified for external processes is interpreted by the standard
shell, &ie; shell commands, environment variables, redirection &etc; can
be used.</para> 

<para>The <guilabel>Interaction</guilabel> page also contains a check
box which can be used to disable to automatic appearance of tool-tips
with numeric information about the bar graphs (compare <link
linkend="fund">Onscreen Fundamentals</link>).</para> 
</sect1>

<sect1 id="faq">
<title>Common Questions and Answers </title>

<qandaset>
<qandaentry>
<question>
<para>Which operating systems does &ktimemon; support?</para>
</question>
<answer>
<para>
&ktimemon; supports &Linux; based systems with the <filename
class="devicefile">/proc</filename> file system, &Solaris; based
systems with the <filename>kstat</filename> library, and Digital
&UNIX; (formerly DEC/OSF1) systems with the
<command>table</command>(2) system call interface. Only the &Linux;
version has been thoroughly tested, if you experience any problems
with the &Solaris;/Digital &UNIX; port, please do not hesitate to
contact me.
</para>

<para>
Also, contributions to &ktimemon; to adapt it to other platforms are
most welcome. Please contact me at
<email>m.maierhofer@tees.ac.uk</email> if you intend to port &ktimemon;
to other flavors of &UNIX;.
</para>
</answer>

</qandaentry>

<qandaentry id="autoscaling">
<question>
<para>
How does autoscaling work?
</para>
</question>
<answer>
<para>
Glad you asked. Since there is no sensible predetermined scaling factor
for paging/swapping operations and context switches (unlike &eg; memory
utilization, where you can take the total memory size as baseline),
&ktimemon; uses a semi-intelligent (well, ...) autoscaling
mechanism. Autoscaling works as follows:
</para>

<itemizedlist>
<listitem>
<para> 
Each of the three bar graphs as described in the <link
linkend="xtndmode">extended mode section</link> has an associated
scaling factor. The initial values of these factors are set to some
predetermined value.
</para> 
</listitem>
<listitem>
<para> 
Each time a new sample is displayed, the respective value is tentatively
scaled with the corresponding factor. If the value can be displayed in
the scale chosen by the factor, no change occurs (&ie; small changes in
the activity are reflected by a changing height of the bar).
</para>
</listitem>
<listitem>
<para> 
If the scaled value would be either too large or too small to be
displayed with the current scaling factor, the scaling is adjusted so
that the new value displayed is roughly halfway up the bar graph. Thus,
subsequent changes should have a good chance of getting displayed
relative to the current value, without having to change the scale again.
</para>
</listitem>
</itemizedlist>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
Why does a message box with <errorname>diagnostic output from child
command</errorname> pop up?
</para>
</question>
<answer>
<para>
If you bind a mouse button to an external command as described in the
<link linkend="config">Configuration</link> chapter, &ktimemon; does
not check for a valid command name.  Instead a command shell is invoked
to execute the statement, so shell commands, environment variables and
more can be used.  To allow some feedback to the user, &ktimemon;
monitors the <systemitem>stderr</systemitem> output of the command
shell, and reports it in this message box.
</para>

<para>
While this scheme can be helpful in case a command is not found, it can
be quite annoying if the invoked command prints harmless diagnostic
information on <systemitem>stderr</systemitem>.  A simple and elegant
solution to this problem is to add <userinput>2&gt;/dev/null</userinput>
at the end of the command specification.  This redirects diagnostic
messages to message nirvana, and stops the message box popping up.
</para>
</answer>
</qandaentry>

</qandaset>
</sect1>

<sect1 id="ktimemon-thanks-and-acknowledgements">
<title>Thanks and Acknowledgments</title>

<para>&ktimemon; is based on an Xt version by my brother.</para>

<para>Thanks to Tobe Toben,
<email>ttoben@artis.uni-oldenburg.de</email>, Cristian Tibirna
<email>ctibirna@gch.ulaval.ca</email>, Dirk A. Mueller
<email>dmuell@rhrk.uni-kl.de</email>, Mark Krischer
<email>krischem@amp.com</email>, and Lubos Lunak
<email>l.lunak@sh.cvut.cz</email> for bug reports, patches, comments,
suggestions.
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underGPL;

</sect1>
</chapter>

<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->