File: moodss.htm

package info (click to toggle)
moodss 5.0-2
links: PTS
area: main
in suites: slink
size: 1,104 kB
ctags: 430
sloc: tcl: 12,266; sh: 59; makefile: 43
file content (803 lines) | stat: -rw-r--r-- 39,609 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
   <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
   <META NAME="GENERATOR" CONTENT="Mozilla/4.06 [en] (X11; I; Linux 2.1.125 i686) [Netscape]">
   <META NAME="Author" CONTENT="Jean-Luc Fontaine">
   <META NAME="Description" CONTENT="user and reference manual for using moodss and writing modules">
   <TITLE>moodss (Modular Object Oriented Dynamic SpreadSheet)</TITLE>
</HEAD>
<BODY>

<CENTER><!--$Id: moodss.htm,v 1.35 1998/10/18 21:20:48 jfontain Exp $--></CENTER>

<CENTER>
<H1>
moodss</H1></CENTER>

<CENTER>
<H2>
(Modular Object Oriented Dynamic SpreadSheet)</H2></CENTER>

<H3>
Contents</H3>
<!-- beginning of contents -->
<UL>
<LI>
<A HREF="#about">1. About this document</A></LI>

<LI>
<A HREF="#introduction">2. Introduction</A></LI>

<LI>
<A HREF="#required">3. Required software</A></LI>

<LI>
<A HREF="#architecture">4. Architecture</A></LI>

<LI>
<A HREF="#core">5. Core</A></LI>

<UL>
<LI>
<A HREF="#userinterface">5.1. User interface</A></LI>

<UL>
<LI>
<A HREF="#draganddrop">5.1.1. Drag and drop</A></LI>

<UL>
<LI>
<A HREF="#dropsites">5.1.1.1. Drop sites</A></LI>

<LI>
<A HREF="#dragsites">5.1.1.2. Drag sites</A></LI>
</UL>

<LI>
<A HREF="#saving">5.1.2. Saving</A></LI>
</UL>

<LI>
<A HREF="#commandline">5.2. Command line</A></LI>
</UL>

<LI>
<A HREF="#modules">6. Modules</A></LI>

<UL>
<LI>
<A HREF="#source">6.1. Source</A></LI>

<UL>
<LI>
<A HREF="#namespace">6.1.1. Namespace</A></LI>

<LI>
<A HREF="#configuration">6.1.2. Configuration</A></LI>

<LI>
<A HREF="#variabledata">6.1.3. Variable data</A></LI>
</UL>

<LI>
<A HREF="#installation">6.2. Installation</A></LI>
</UL>

<LI>
<A HREF="#future">7. Future developments</A></LI>

<LI>
<A HREF="#misc">8. Miscellaneous information</A></LI>
</UL>
<!-- end of contents -->
<H3>
<A NAME="about"></A>1. About this document</H3>
This document contains general information, reference information and examples
designed to help the user understand the moodss application and the programmer
write modules for it.
<H3>
<A NAME="introduction"></A>2. Introduction</H3>
Quite often, one needs to monitor changing data, whether it might come
from a system, such as the different processes running on a Unix server,
or from a network, such as the kind and volume of traffic that runs through
it.
<P>Most often, such data can be organized in a table with rows of information,
each column representing a different type of data. For example, in the
case of processes running on a system, rows might be sorted according to
their unique process identifier, and columns might represent such values
as CPU usage, memory usage, owner's name, time of creation, ...
<P>The software used to view this type of information comes in different
forms and shapes. Unix users might be familiar with the "top" application
which presents rows of process data as lines of text, whereas RMON (Remote
MONitoring) SNMP software usually uses multiple windows with graphical
displays, curves, pie charts, multiple configuration dialog boxes, even
3D visualization modules to present network traffic, connection matrices,
...
<P>In most cases, data comes from one or several tables. A common interface,
graphical with menus, drag'n'drop capability, table widgets, textual and
graphical data viewers such as multiple line graphs, bar and pie charts,
could be used. The user could then sort table rows, select one or more
cells, rows, columns, to launch viewers such as other tables, charts, ...
best suited to the way data should be presented. In effect, what is needed
is a spreadsheet that is capable of dealing with dynamically changing data.
<P>Moodss (Modular Object Oriented Dynamic SpreadSheet) is an attempt at
answering these needs. It is composed of a main part (the core) and an
unlimited number of modules, loaded as the application is launched, each
module interfacing to a specific type of data. The core is written in the
great Tcl language (at <A HREF="http://www.scriptics.com/">http://www.scriptics.com/</A>)
using object oriented techniques thanks to the stooop and scwoop packages
(at <A HREF="http://www.mygale.org/~jfontain/">http://www.mygale.org/~jfontain/</A>).
The module function is to describe the type of data that it is also in
charge of retrieving and formatting. Modules can be written in plain Tcl
or C and optionally use dynamically linked libraries written in the C language
(modules are packages in the Tcl sense).
<P>Modules are loaded when moodss is started. One or more modules can be
handled concurrently (starting with moodss version 3.0). This way, you
may monitor data coming from any number of heterogeneous sources. Module
names are specified in the command line and cannot be dynamically unloaded.
<P>Versions 4.0 and up add a dashboard functionality: the current configuration
(modules, viewers, poll time, windows sizes and placement, ...) can be
saved in a file at any time, for later reuse (see the -f (--file) command
line switch documentation).
<P>Versions 4.3 and up support asynchronous modules (no polling needed
as module data may change on its own). Note that any number of asynchronous
and regular (synchronous) modules can be simultaneously loaded.
<P>Since module data access is entirely customizable (through C code, Tcl,
HTTP, ...) and since several modules can be loaded at once, applications
for moodss become limitless. For example, comparing a remote database server
CPU load and a network load from a probe on the same graph becomes possible.
<P>As features are added to moodss, different ways of viewing data will
be made available while the modules will stay the same. The goal of moodss
is to become a nice feature packed generic way of viewing data. Moodss
can be used to monitor any type of data, since the simplest cases can fit
in a table with a single row.
<P>As moodss is written in Tcl and uses well supported extensions (Tktable
and BLT), it will run on most Tcl/Tk supported platforms: UNIX and Windows
(I do not know if Tktable and BLT are available for the MacIntosh). Some
modules may be specific to a platform, but the core is guaranteed to run
on them all.
<P>After reading and understanding this document, you should be able to
write your own modules in order to monitor the data that you are interested
in.
<P>Moodss is free software. You can redistribute it and/or modify it under
the terms described in the COPYRIGHT file or use the main window Help Copyright
menu for more information.
<H3>
<A NAME="required"></A>3. Required software</H3>
If you are using a Linux Redhat system (5.1 or above), then use the moodss
rpm file (available (starting with 4.4) at <A HREF="http://www.mygale.org/~jfontain/">http://www.mygale.org/~jfontain/</A>)
for installation. It includes all the required software (except Tcl/Tk
8.x, of course). If you want to work on the moodss source code, see below,
otherwise you can skip the rest of this section.
<P>For the current version (5.0), the following packages must be installed
before attempting to install moodss (make sure to check the INSTALL file
for the latest information):
<UL>
<LI>
Tcl/Tk version 8.0 or above (at <A HREF="http://sunscript.sun.com/">http://sunscript.sun.com/</A>)</LI>

<LI>
tkTable version 2.0 or above (at <A HREF="http://oprs.mchh.siemens.de/tcl/capp/tkTable/">http://oprs.mchh.siemens.de/tcl/capp/tkTable/</A>)<B>*</B></LI>

<LI>
the BLT library version 2.4 (at <A HREF="ftp://ftp.tcltk.com/pub/blt/">ftp://ftp.tcltk.com/pub/blt/</A>)<B>*</B></LI>
</UL>

<DIV ALIGN=right><B>*</B><I> many thanks to the authors for these great
packages</I></DIV>

<P><BR>The pie widgets, stooop and scwoop libraries are included in the
self contained <I>moodss</I> application file. Therefore, it is not required
to install the stooop, scwoop and tkpiechart packages, unless you want
to work on the moodss source code itself. However, should you want to get
more information on those extensions, you could find the latest versions:
<UL>
<LI>
stooop version 3.6.1 or above</LI>

<LI>
switched version 1.4 or above (included in the stooop distribution)</LI>

<LI>
scwoop version 2.5 or above</LI>

<LI>
tkpiechart version 5.2 or above</LI>
</UL>
all at <A HREF="http://www.mygale.org/~jfontain/">http://www.mygale.org/~jfontain/</A>.
<H3>
<A NAME="architecture"></A>4. Architecture</H3>
The moodss application is composed of the core software and one or several
modules. Modules are implemented as Tcl packages and thus usually comprise
a Tcl source file and a pkgIndex.tcl file as required by the Tcl package
implementation.
<P>The core will load one or more modules, whose names were passed as command
line parameters or come from a save file, and will start displaying module
data in one or more tables. The tables are then updated at the frequency
defined by the poll time, which the user may change, or asynchronously
for the relevant modules. For example, to launch moodss with the random
module, just type:
<PRE>$ wish moodss random</PRE>
All the module code and data are kept in a separate namespace. The module
data is stored is a single array including some configuration data used
when the module is loaded by the core, and variable data (displayed in
the application table and eventual graphical viewers). If a module is synchronous,
it must start updating its data when requested by the core. If a module
is asynchronous, its data may be updated at any time. The synchronous or
asynchronous nature is specified in the configuration data for the module.
<P>The initial data tables represent the first data views, from which cells
can be selected and when dropped through a drag'n'drop operation into a
graph, bar chart, pie chart, summary table or free text iconic site, result
in the creation of data viewers. In turn, these viewers can display more
table cells, which when dropped into the viewer, result in the creation
of corresponding data graph lines, chart bars, pie slices, table rows or
text cells.
<P>Any draggable data can be dropped in valid drop sites at any time. It
is thus possible to drag several data cells from any table or any viewer
into other ones, the trash, ... even if the data comes from different modules.
<P>All data viewers can be moved and resized at will with the help of a
simple internal window manager.
<P>The current configuration (loaded modules, tables and viewers coordinates
and sizes, poll time, main window size, ...) can be saved in a file at
any time, so that an identical dashboard can be relaunched at a later time.
<H3>
<A NAME="core"></A>5. Core</H3>

<H4>
<A NAME="userinterface"></A>5.1. User interface</H4>
Soon after the application launch, tabular data is displayed in one or
more tkTable widgets with automatic scroll bars, between the menu bar,
the drop sites with graphical viewers, summary table, free text and trash
icons and a message area, as one can see below:
<CENTER>
<P><IMG SRC="moodss1.jpg" ALT="moodss initial main window view" HEIGHT=358 WIDTH=408></CENTER>

<P>The message area is used to display status information, such as when
the data is being updated, and help information, as the user moves the
mouse pointer over sensitive areas, such as table column headers. Further
help is provided through widget tips (also known as balloons) when appropriate,
and of course the Help menu.
<P>The window title shows the name of the loaded module(s) along with the
poll time.
<P>The <I>File</I> menu contains the <I>Save</I>, <I>Save As</I> and <I>Exit</I>
menu entries, used to save the current configuration (modules and viewers),
or gracefully quit the moodss application.
<P>The <I>Options</I> menu (may not exist, see below) contains the <I>Poll
time</I> entry which when selected launches the corresponding dialog box,
as shown below:
<CENTER>
<P><IMG SRC="moodss2.jpg" ALT="poll time dialog box" HEIGHT=238 WIDTH=226></CENTER>

<P>The user can select a new poll time among the module choices from a
spin entry widget, or directly type in a new value, as long as it is not
smaller than the module minimum poll time, in which case a message dialog
box warns the user.
<P>When several modules are used, the minimum poll time is the greater
of the minimum poll times of all modules. The default poll time (used when
moodss is started) is the greater of the default poll times of all modules.
The available choices in the poll time dialog box is the combination of
all modules poll times.
<P>The <I>Poll time</I> menu entry is available only when needed, which
is not the case if all the loaded modules are asynchronous. If this case,
the <I>Options</I> menu itself is not displayed.
<P>Any data displayed in a table can be sorted at any time by simply clicking
on a column title. Clicking on the same column title again sorts the data
in opposite order, thus toggling between increasing and decreasing orders.
<BR>When sorting, the selected column is used as a reference, meaning that
all rows will be rearranged so that the selected column appears sorted,
with values either increasing or decreasing.
<BR>A little arrow indicator is placed to the right of the reference column
title label, pointing up or down depending on whether the sorting order
is decreasing or increasing.
<BR>Table columns can be interactively resized by holding the first mouse
button down on a column border. The mouse cursor is changed to an horizontal
double arrow on column borders to show this capability.
<P>Aside from the main tables, graphical and textual viewers can be created
for viewing table cell data behavior over time. Viewers can also be deleted,
data views (such as pie slices, curves, ...) can be added or removed from
existing viewers, ... These functions are all implemented using the drag
and drop functionality described below.
<P>Graphical viewers available at this time are BLT graph viewers (such
as can be seen below), side-by-side bars charts, overlapped bars charts
(only available when the BLT version 2.4 library is used), stacked bars
charts, 2D pie charts and 3D pie charts*.
<P>*<I>note: if you know of any other nice viewers (like 3D graphs) that
work with Tcl, please let me know so I can integrate them. Many thanks
in advance...</I>
<BR>&nbsp;
<CENTER><TABLE COLS=2 WIDTH="100%" NOSAVE >
<TR ALIGN=CENTER VALIGN=CENTER NOSAVE>
<TD NOSAVE><IMG SRC="graph.jpg" ALT="graph viewer sample" HEIGHT=200 WIDTH=300></TD>

<TD><IMG SRC="overbar.jpg" ALT="overlap bar chart viewer sample" HEIGHT=200 WIDTH=300></TD>
</TR>

<TR ALIGN=CENTER VALIGN=CENTER NOSAVE>
<TD NOSAVE><IMG SRC="sidebar.jpg" ALT="side bar chart viewer sample" HEIGHT=200 WIDTH=300></TD>

<TD><IMG SRC="stackbar.jpg" ALT="stacked bar chart viewer sample" HEIGHT=200 WIDTH=300></TD>
</TR>

<TR ALIGN=CENTER VALIGN=CENTER NOSAVE>
<TD NOSAVE><IMG SRC="2dpie.jpg" ALT="2D pie chart viewer sample" HEIGHT=200 WIDTH=300></TD>

<TD><IMG SRC="3dpie.jpg" ALT="3D pie chart viewer sample" HEIGHT=200 WIDTH=300></TD>
</TR>
</TABLE></CENTER>

<CENTER><TABLE WIDTH="100%" NOSAVE >
<TR ALIGN=CENTER VALIGN=CENTER NOSAVE>
<TD WIDTH="58%" NOSAVE><IMG SRC="sumtable.jpg" ALT="summary table viewer sample" HEIGHT=200 WIDTH=350></TD>

<TD WIDTH="42%" NOSAVE><IMG SRC="freetext.jpg" ALT="free text viewer sample" HEIGHT=200 WIDTH=250></TD>
</TR>
</TABLE></CENTER>

<P>There are 2 textual viewers.
<BR>The summary table displays for each row the cell label, the current,
average, minimum and maximum values since the row was created.
<BR>The free text viewer is an editable Tcl text widget with any number
(including zero) of embedded data cell windows. Data cells can be inserted
one or several at a time through a simple drop, as with the other viewers.
New data cell windows are inserted at the current insertion cursor position.
Data cells can be deleted by selecting then dropping any number of them
into the trash drop site. They can also be deleted using the keyboard Delete
and Backspace keys, which also work on the regular text, as well as the
expected other key bindings. When dropping data cells, each data cell window
is preceded by a relevant label text for the cell, which can later be edited
at any time.
<P>Here is a screen shot of loaded <I>ps</I> and <I>cpustats</I> modules
with several graphical viewers:
<BR>&nbsp;
<CENTER>
<H5>
<IMG SRC="moodss3.jpg" ALT="moodss window with graph data viewers" HEIGHT=611 WIDTH=578></H5></CENTER>
All data viewers can be moved and resized thanks to handling areas in the
data viewer borders. When moving the mouse pointer over these areas, the
mouse cursor changes to indicate the possible action. Corner handles allow
resizing in both X and Y axis. Handles in the middle of the sides allow
resizing in either the X or Y axis direction. All other areas can be used
for moving the data viewer as shown by the quadruple arrow cursor. Clicking
on any part of the border changes the stacking order: the viewer being
clicked on either goes below (eventually becomes hidden) the other viewers,
or becomes fully visible (on top, eventually hiding other viewers). When
moving or resizing, the message area displays the current coordinates or
size in real time as the mouse is being moved. Further description of this
small window manager functionality is useless, as it behaves like a basic
window manager (let me know if it does not).
<P>Here is another shot featuring a free text viewer with loaded <I>cpustats</I>
and <I>memstats</I> modules:
<CENTER>
<P><IMG SRC="moodss4.jpg" HEIGHT=475 WIDTH=467></CENTER>

<P>The <I>Help</I> menu contains <I>Global</I> help (actually launches
an embedded HTML viewer with this very document), <I>Modules</I> help which
displays all the loaded modules help texts, <I>Copyright</I> which displays
the GPL (Gnu General Public License) document, <I>Source Versions </I>which
display all the source code file names with their versions and <I>About</I>
general information entries.
<H5>
<A NAME="draganddrop"></A>5.1.1 Drag and drop</H5>
Drag and drop in moodss tries to behave as the now familiar Windows functionality
(no, it doesn't mean I am a Bill Gates fan, as they probably stole the
idea from somebody else anyway :^). For example, to create a graphical
plot, one must first select one or more data cells in a data table, hold
down the first mouse button (the left one for a right handed user) while
dragging over to the left-most icon below the menu bar (when dragging an
object, as the mouse pointer passes over possible drop sites, they are
highlighted with a thin black border for user feedback). Releasing the
mouse button at this time results in the creation of a BLT graph viewer.
<P>Only valid drop sites for the data being dragged are highlighted when
the mouse cursor passes over them, thus guaranteeing error free operations
(if there are no bugs, that is :).
<P>In summary, data cells can be dragged from any table or any viewer into
any viewer drop site icon, any viewer or the trash can.
<H6>
<A NAME="dropsites"></A>5.1.1.1. Drop sites</H6>
All icons right below the menu bar are valid drop sites for data cells
(several may be dropped at the same time). From left to right:
<UL>
<LI>
graph viewer with one or more data curves created at once</LI>

<LI>
side by side bar chart with one or more data bars created at once</LI>

<LI>
stacked bar chart with one or more data bars created at once</LI>

<LI>
2D pie chart with one or more data slices created at once</LI>

<LI>
3D pie chart with one or more data slices created at once</LI>

<LI>
summary table with one or more data rows created at once</LI>

<LI>
free text with one or more labelled data cell windows created at once</LI>

<LI>
object trash with one or more data viewer elements deleted at once</LI>
</UL>
For example, a graph viewer with 1 curve is created by dropping 1 data
cell into the graph viewer icon.
<P>Once a viewer exists, it also acts as a drop site for data cells, which
may be dragged from any table or other viewers. Dropping one or more cells
directly in the viewer results in corresponding lines, bars, slices or
rows being created and automatically updated. Each new graphical element
is assigned a new and different color.
<P>You may delete one or more viewer elements (graph lines, bar chart bars,
pie charts slices, summary table rows or free text cell window) from a
viewer by selecting them (using the first mouse button) through their labels.
Several elements can be selected by depressing the control key as the first
mouse button is pressed. The selection can also be extended by depressing
the shift key along with the first mouse button. The pie slices can also
be directly selected by clicking on the slices themselves.
<BR>Then dragging from the viewer to the trash drop site (the bullet hole)
on the upper right side of the main window and releasing the first mouse
button result in the corresponding viewer elements to be destroyed. If
there are no remaining elements, the viewer itself (graph, bar chart, pie
or summary table) is destroyed. The free text viewer can only be deleted
when completely emptied of any text and data cell window:&nbsp;it can then
be dropped into the trash.
<H6>
<A NAME="dragsites"></A>5.1.1.2. Drag sites</H6>
A table is obviously a drag site. One or more cells can be dragged at once
after selection, using the traditional single/shift/control mouse click
technique.
<P>Any viewer is also a drag site. It requires selecting one or more viewer
elements before initiating the drag operation from any selected element
in the viewer. If there are no selected elements, dragging is impossible:
the mouse cursor is not changed into the drag circular cursor.
<P>If a viewer contains no elements, then the viewer itself can be dragged
and dropped into the trash.
<H5>
<A NAME="saving"></A>5.1.2 Saving</H5>
The current application configuration (including existing data viewers)
can be saved in a file, which achieves a dashboard functionality.
<P>Once moodss has been launched with one or several modules and tables
have been moved, resized, viewers created, moved and resized, the current
configuration can be saved in a .moo file, and later reused by passing
the corresponding file name with the -f (--file) command line switch.
<P>For moodss version 4.0 and above, the following information is saved
in the file (which is human readable):
<UL>
<LI>
moodss version</LI>

<LI>
date and time</LI>

<LI>
application window size</LI>

<LI>
poll time</LI>

<LI>
modules</LI>

<LI>
tables positions and sizes</LI>

<LI>
viewers types, positions, sizes and specific data</LI>
</UL>
When using the <I>File Save</I> menu for the first time, and if a file
name was not specified in the command line, the file selector dialog box
appears so that the user may choose a file name (with a .moo extension).
<P>The <I>File Save As</I> menu behaves as expected, with the user always
having to choose a file name.
<P>Once a file name has been specified (either through the command line
or the file selector dialog box), that file name is reused whenever the
<I>File Save</I> menu is used. The <I>File Save As</I> menu may be used
at any time to change the file name.
<H4>
<A NAME="commandline"></A>5.2. Command line</H4>
Launching moodss is very simple: just pass one or more data module names
as parameters, as in:
<PRE>$ wish moodss random</PRE>
or, for 2 modules at once:
<PRE>$ wish moodss ps cpustats</PRE>
You may not specify the same module more than once in the command line.
<P>You may eventually specify a poll time in seconds using:
<PRE>$ wish moodss -p 25 random</PRE>
Note that when all the specified modules are asynchronous, the poll time
option specifies the preferred interval for graph viewers.
<P>Once saved through the File Save menus (for example in save.moo) , the
configuration can be retrieved using:
<PRE>$ wish moodss -f save.moo</PRE>
which would result in the same modules being loaded, the same viewers displayed
at the same positions and sizes, the same poll time being used, as well
at the same application window size.
<P>Command line options include:
<UL>
<LI>
<B>-f</B> (or <B>--file</B>): specifies a configuration file name (incompatible
with modules)</LI>

<LI>
<B>-h</B> (or <B>--help</B>): displays some help text and exits</LI>

<LI>
<B>-p</B> (or <B>--poll-time</B>): specifies a poll time in seconds</LI>

<LI>
<B>-r</B> (or <B>--read-only</B>): disable viewer creation, editing, ...</LI>

<LI>
<B>-S</B> (or <B>--static</B>): disable internal window manager sizing
and moving</LI>

<LI>
<B>--version</B>: outputs version information and exits</LI>
</UL>

<H3>
<A NAME="modules"></A>6. Modules</H3>
All examples are drawn from the <I>random</I> sample module.
<H4>
<A NAME="source"></A>6.1. source</H4>
Since a module is a package, it must have a name in the Tcl sense. For
example, at the beginning of the <I>random.tcl</I> file, one can find the
following statement:
<PRE>package provide random 1.1</PRE>
This line simply states that this is the <I>1.1</I> version of the <I>random</I>
package. Please note that the package name must also be used as the module
namespace name (see below).
<H5>
<A NAME="namespace"></A>6.1.1. namespace</H5>
All module procedures and data are kept in a specific namespace bearing
the module name. For example (from the <I>random.tcl</I> source file):
<PRE>namespace eval random {
&nbsp;&nbsp;&nbsp; array set data {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...
&nbsp;&nbsp;&nbsp; }
&nbsp;&nbsp;&nbsp; proc update {} {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...
&nbsp;&nbsp;&nbsp; }
}</PRE>
The update procedure is not needed when the module is asynchronous.
<H5>
<A NAME="configuration"></A>6.1.2. configuration</H5>
The module configuration defines the data table column headers, help information,
... This data never changes during the lifetime of the application.
<P>All the module configuration data is stored as array members of the
array named <I>data</I> within the module namespace. For example:
<PRE>namespace eval random {
&nbsp;&nbsp;&nbsp; array set data {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; updates 0
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 0,label name 0,type ascii 0,message {user name}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1,label cpu 1,type real 1,message {cpu usage in percent}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2,label disk 2,type integer 2,message {disk usage in megabytes}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 3,label command 3,type dictionary 3,message {most time consuming command}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; pollTimes {10 5 20 30 60 120 300}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sort {1 decreasing}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; indexColumns {0 3}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; helpText {
This is a simple demonstration module ...
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }
&nbsp;&nbsp;&nbsp; }
&nbsp;&nbsp;&nbsp; ...
}</PRE>
The <I>updates</I> member is a counter used to keep track of the number
of times that the module data was updated, and is also used by the core
to detect when module data display should be updated (see <A HREF="#variabledata">variable
data</A> for more information).
<P>The <I>columns</I> member is obsolete and no longer used after and including
moodss version 3.5.
<P>The <I>n,label</I> members define the text to be displayed as column
titles. There must be as many <I>n,label</I> members as they are columns.
<BR>The <I>n,type</I> members define the type of the corresponding column
data. Valid types are simply those that the Tcl <I>lsort</I> command can
handle: <I>ascii</I>, <I>dictionary</I>, <I>integer</I> and <I>real</I>.
There must be as many <I>n,type</I> members as they are columns.
<BR>The <I>n,message</I> members define the text of the help message to
be displayed in the message area (see <A HREF="#architecture">User Interface</A>)
as the user moves the mouse pointer over column titles. It should be composed
of only a few words, just enough to actually help the user understand what
the column data means. There must be as many <I>n,message</I> members as
they are columns.
<BR>Note that column numbers start at 0.
<P>The <I>pollTimes</I> member is a list of valid poll times (in seconds)
for the module. The list is not ordered, as its first element represents
the default poll time value to be used when the moodss application starts.
This value may be overridden by a command line argument. The smallest value
in the list is used by the core as the lowest possible poll time and checked
against when the user enters a new value through the poll time dialog box.
The list must not be empty.
<BR>Note that the list is also used by moodss as a set of possible choices
in the dialog box used to set the new poll time. The user may still directly
input any value as long as it is greater than or equal to the minimum value.
<P>If the module is asynchronous (data can be updated at any time and not
in response to update procedure invocations (no polling required)), the
pollTimes member must be a single negative integer value representing the
preferred time interval for viewers that require one (only graphs at this
point). For example, if you wish graph viewers to have a display interval
of 10 seconds, use:
<PRE>namespace eval random {
&nbsp;&nbsp;&nbsp; array set data {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; pollTimes -10
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...
&nbsp;&nbsp;&nbsp; }
&nbsp;&nbsp;&nbsp; ...
}</PRE>
In this case, the graph viewers time range (knowing that they feature 100
time points) would be 1000 seconds. I guess that the value that you should
specify as the pollTimes member should be the expected average update interval
for your asynchronous data. Note that the graphical viewers x axis always
display properly labelled absolute time ticks in any case.
<P>When several asynchronous modules are loaded with no synchronous modules,
the interval used for all relevant viewers is the average (in absolute
value) of all module intervals. For example, if you load 2 asynchronous
modules, one with a pollTimes member of -10 and the other of -20, then
a 15 seconds interval value is retained. Note that the interval can be
forced through the --poll-time command line argument.
<P>If at least one synchronous module is loaded concurrently with any number
of asynchronous modules, the actual application poll time (the one that
can be set with the then available poll time dialog box) is used.
<P>The <I>visibleColumns</I> member is an optional list that specifies
the table columns that should be displayed. If not specified, all the table
columns are visible.
<P>The <I>sort</I> list defines the index of the column which should be
initially used as a reference for sorting the data table rows, and in which
order (<I>increasing</I> or <I>decreasing</I>) the rows should be sorted.
The column index for sorting works like the <I>-index</I> Tcl <I>lsort</I>
command option, that is rows are sorted so that that specific column appears
sorted in the specified order. The specified column must be visible (see
<I>visibleColumns</I>
member documentation above).
<P>The <I>indexColumns</I> list specifies the columns required to uniquely
identify a row in the table. In database talk, it represents the table
key. To maintain backward compatibility, it is optional and defaults to
0, the leftmost column. The index columns are used when creating data viewer
elements: their label is built by concatenating the key value for the cell
row with the cell column title. The key value is the concatenation of the
index column values for the cell. When specified, all the columns in the
list must be visible (see <I>visibleColumns</I> member documentation above).
<P>The <I>helpText</I> member specifies a text of any length, to be displayed
when the user requests help information on the current module from within
the help menu.
<P>The views member is optional. If specified, it defines one or more views
to be used in place of the default view. One table will be displayed per
view. Each view is a list of array members, suitable as an argument to
an "array set" command. For each view, 2 members must be defined: <I>visibleColumns</I>
and <I>sort</I> (syntax and usage are identical to the default table members).
<P>For example, a recent <I>random</I> module configuration is as follows:
<PRE>array set data {
&nbsp;&nbsp;&nbsp; updates 0
&nbsp;&nbsp;&nbsp; 0,label name 0,type ascii 0,message {user name}
&nbsp;&nbsp;&nbsp; 1,label cpu 1,type real 1,message {cpu usage in percent}
&nbsp;&nbsp;&nbsp; 2,label disk 2,type integer 2,message {disk usage in megabytes}
&nbsp;&nbsp;&nbsp; 3,label memory 3,type integer 3,message {memory usage in kilobytes}
&nbsp;&nbsp;&nbsp; 4,label command 4,type dictionary 4,message {command name}
&nbsp;&nbsp;&nbsp; pollTimes {10 5 20 30 60 120 300}
&nbsp;&nbsp;&nbsp; sort {1 decreasing}
&nbsp;&nbsp;&nbsp; indexColumns {0 4}
&nbsp;&nbsp;&nbsp; helpText {...}
&nbsp;&nbsp;&nbsp; views {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {visibleColumns {0 1 3 4} sort {1 decreasing}}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {visibleColumns {0 2 4} sort {2 decreasing}}
&nbsp;&nbsp;&nbsp; }
}</PRE>
In this case, data is presented in 2 tables: one for the CPU and memory
usage, the other for disk usage.
<H5>
<A NAME="variabledata"></A>6.1.3. variable data</H5>
The tabular data (variable data) that the module code must update is stored
in the same <I>data</I> array as the module configuration data.
<P>In case of a synchronous module, the core invokes the module <I>update</I>
procedure (which obviously must exist) when it is time to refresh the data
display (tables and eventually graphical viewers). At this time, the update
procedure may update the tabular data straight away (synchronous operation)
or launch a request for later data update (asynchronous operation).
<P>In case of an asynchronous module, variable data may be updated at any
time. The <I>update</I> procedure may not exist.
<P>For all module types, it actually does not matter when the data is updated.
The core will know that fresh data is available when the <I>updates</I>
array member is set (actually incremented as it also serves as a counter
for the number of updates so far).
<BR>It is the module programmer's responsibility to increment this counter
right after all tabular data has been updated.
<P>For example, retrieving information for the processes running on a machine
is a local operation that can be achieved in a reasonably small amount
of time. In such a case, data would be updated immediately and the <I>updates</I>
variable incremented at the same time.
<BR>But if the data has to be retrieved from across a network, waiting
for it to come back would cause a delay that the user would certainly notice,
as the application would not respond to mouse or keyboard input during
the whole time that it would take to fetch the whole data. In such cases,
it is easier to let the update procedure return immediately without setting
the <I>updates</I> variable, which would be incremented at a later time,
only when the data would become available. For example, when waiting for
data to come across a network connection, the Tcl <I>fileevent</I> command
could be used on a non blocking channel, where the script to be evaluated
when the channel becomes readable would increment the <I>updates</I> array
member.
<P>For example:
<PRE>namespace eval random {
&nbsp;&nbsp;&nbsp; ...
&nbsp;&nbsp;&nbsp; proc update {} {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; variable data
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; array set data "
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 0,0 john&nbsp;&nbsp;&nbsp; 0,1 1234 0,2 4567 0,3 cc
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1,0 william 1,1 8901 1,2 2345 1,3 xedit
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2,0 anny&nbsp;&nbsp;&nbsp; 2,1 6789 2,2 0123 2,3 ps
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 4,0 peter&nbsp;&nbsp; 4,1 4567 4,2 8901 4,3 ls
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 6,0 laura&nbsp;&nbsp; 6,1 2345 6,2 6789 6,3 emacs
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 3,0 robert&nbsp; 3,1 1234 3,2 5678 3,3 top
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; incr data(updates)
&nbsp;&nbsp;&nbsp; }
}</PRE>
The tabular data array index is the <I>row</I> number followed by the <I>column</I>
number separated by a <I>comma</I>. The column number must start from 0
up to the total number of columns minus 1 (no holes are allowed in the
column sequence).
<BR>The row number can take any integer value and be defined in any order,
as long as it is unique during the lifetime of the module data. If a new
row is created, it must take a value that was never used: the index of
a row that has disappeared cannot be reused. Row numbers need not be consecutive.
<P>When all rows (or only those table cells that have changed) have been
updated, the <I>updates</I> member array must be incremented so that the
core knows that it can update the table data display.
<P>The random module source code can be made to function asynchronously:
please look into the random.tcl file.
<H4>
<A NAME="installation"></A>6.2. installation</H4>
A module is a package in the Tcl sense. When writing a module, you must
then provide a <I>pkgIndex.tcl</I> file along with the module code file.
The <I>pkgIndex.tcl</I> file is very simple, as the following example shows:
<PRE>package ifneeded random 1.1 "source [file join $dir random.tcl]"</PRE>
The line above says that if the <I>random</I> package is needed, the Tcl
core should source the <I>random.tcl</I> module source code from the directory
where it was installed. <I>1.1</I> is the version number for the package.
<P>Modules can be installed at any valid place that the Tcl core allows
(look at the <I>pkg_mkIndex</I> manual page for more information).
<P>When you unpack moodss, you will find the sample modules in sub directories.
The current directory (.) is appended to the <I>auto_load</I> global list
variable so that sample modules can be found when moodss is run from the
unpacking directory.
<P>For example, if you unpacked moodss in <I>/home/joe/moodss-5.x/</I>,
you will find the random module package in <I>/home/joe/moodss-5.x/random/</I>
so that the following will work:
<PRE>$ cd /home/joe/moodss-5.x/
$ wish moodss random</PRE>
You can install your new modules in the default location: <I>/usr/local/lib/</I>
on Unix. For example, if you move the files in <I>/home/joe/moodss-4.x/random/</I>
to <I>/usr/local/lib/random/</I>, moodss (actually Tcl :) will still be
able to find the <I>random</I> module (again, look at the <I>pkg_mkIndex</I>
manual page for more information).
<P>Please take a look at the INSTALL file for the latest information on
how to install the moodss application itself.
<H3>
<A NAME="future"></A>7. Future developments</H3>
The following features will eventually be added to the core (also look
at the TODO file):
<UL>
<LI>
more Linux modules</LI>

<LI>
more data viewers</LI>

<LI>
table row and column selection</LI>

<LI>
writable table cells?</LI>
</UL>
I welcome any suggestion for new features that you may need in your specific
use of moodss.
<H3>
<A NAME="misc"></A>8. Miscellaneous information</H3>
For downloading Tcl software (such as stooop, scwoop, tkpiechart, ...),
visit my <A HREF="http://www.mygale.org/~jfontain/">web page</A>.
<P>Send your comments, complaints, ... to <A HREF="mailto:jfontain@mygale.org">Jean-Luc
Fontaine</A>.
</BODY>
</HTML>