3 Description Files

Contents of this section

3.1 Shell Variables

Any environment variable may appear in the description file, for evaluation and substitution when the line is parsed. Environment variables are denoted by prefixing them with a $ symbol, just as in any shell script. A variable name is considered to continue until the next whitespace; where this would lead to an incorrect name being searched for, it may be bracketed by {}, ie.


        f.mail-box      "$USER %d" ${HOME}/Mail

Would be interpreted the same as:-
        f.mail-box      "vanye %d" /home/vanye/Mail

Here $USER is terminated by a space, whereas $HOME isn"t, hense the need to enclose it in {}.

3.2 Options

There area number of options that may be applied to enhance or otherwise affect a specific entry in a menu or panel. Options are included in square brackets ([]) after the label (and before anything else on the line), whitespace is used to separate multiple options inside the [].

Not all options are available on every entry, see the entry for details of those allowed.

H=name

This entry has some help text, called name associated with it. The help text may be either plain ascii of HTML text.

F=file

This entry has a help file associated with it. The file may contain either plain, formatted text or HTML source, and the appropriate browser will be selected (to be interpreted as HTML a file must have < as its first character). If no file is specfied, then a file with the same name as the first word in the entries label will be searched for. The file must not be fully specifed, it will be seached for in the directory list gived by the X-resource helpFilePath.

I=file

Specifies an X bitmap (or alternatively if colour icons are supported---X pixmap) file to be used instead of the text label for the entry. The file will be searched for in the directory path specified in iconFilePath.

N=number

Limits the number of times this entry may be executed. Once this limit is reached, trying to run anymore will be ignored and a message will be displayed.

T=number

Specifies a time, in minutes (or seconds if the number is suffixed with s).

D=cmd

Specifies a default. this is only used inside panel definitions. The cmd should be the actual default, not the name of the default.

3.3 Menu Syntax

For an example of the syntax in use, see Appendix Annotated Example of Description Syntax .

Menu menu name

Starts a menu definition, called menu name. Any number of entries may appear between this and the corresponding EndMenu. Note: the effect of starting another menu before finishing the first is undetermined (ie. don"t do it).

AddToMenu menu name

Adds the following entries (until the next EndMenu) to the menu menu name. If menu name hasn"t already been defined the results are unspecified (that well known euphamism for "will probably crash").

EndMenu

Ends a menu definition started with Menu or AddToMenu.

f.button "button" cmd

Creates a button in the current menu. The button will be labeled button, and when selected will execute the shell command cmd.

Relevent options: H, F, I, N, T.

If the T option is specified, this will display a dialog informing the user that the command has been started and to please wait. After the time expires the dialog will be destroyed.

f.menu "label" menu name

Creates a button (labeled label) that when selected pulls down the menu menu name.

Relevent options: H, F, I.

f.label "label"

Creates a simple label. This can be used as a title in a pulldown menu.

Relevent options: I.

f.separator ""

Creates a separator.

f.quit "label"

Creates a button (labeled label) that when selected brings up a dialog to confirm whether you wish to quit rTc. Valid responses are, Yes, No or Restart. Restart terminates the current rTc and restarts it---re-reading the description files.

Relevent options: H, F, I.

These are the basics, others (optional) are discussed on a package-by-package basis in the next section.

3.4 Optional Packages

The Mail-Box watcher

This is a simple package that provides visual feedback when new mail arrives, ala biff. Any number of mailboxes can be watched (although read access is requred), with differing frequencies of checking for new mail.

When new mail does arrive the mail-box label is flashed at an increasing rate.

f.mail-box "label" mail box

Creates a button (labeled label) that displays the number of messages in the mail box mail box. The label label should have a place holder for the number of messages to be put (denoted by %d), ie "$USER~%d", would display as something like "vanye~27" (if I had 27 messages in my mailbox).

If the time option is set, the mail box is only checked when the period expires. If no time option is explicitly set the file is checked only every 15minutes.

If the mail box is selected, the number of messages is re-counted there and then, without waiting for the next timed update.

Relevent options: H, F, T.

The Disk-Space Watcher

This package displays the amount of free disk space, colour coded, of a specified partition. The colours are specified on the line (and are therefore specific to that one instance of the disk space watcher.

f.disk-space "label" partition colour_1=max_1:min_1colour_n=max_n:min_n

Calculates the free space in the partition (in Mbyte), and displays it in the label (which should have a place holder marked by %g).

The text string is coloured depending on the free space and the break points specified in max and min. Perhaps the easiest way to explain is through an example:


        f.disk-space "%.4gMb in /" / green=:5 yellow=5:3 orange=3:1 red=1:

this keeps a monitor on the slash (/) partition and colours it according to these rules :-

  1. If there is more than 5Mb of space then colour it green.
  2. If there is bewteen 5Mb and 3Mb then colour it yellow.
  3. If there is betwenn 3Mb and 3Mb then colour it orange.
  4. If there is less than 1Mb then colour it red.

If one of max or min is not specified then it is taken to be infinity (positive if the max is missing, negitive if the min is missing).

If an optional time is not specified, the values are updated every 30 minutes.

If the label is selected, the disk space is re-calculated, without waiting for the next timed update.

Relevent options are H, F, T.

The Clock and Reminder

The clock (or rather the reminder) has been considerablt enhanced in this version, it is now possible to save reminders between invocations of rTc in a reminder file.

f.clock "label"

The label string is used to format the display via the strftime(3) library function. This allows place holders to be put in the label, and these will be substituted for when it becomes time for the label to be updated. The actual place holders are likely to be system dependent, but the more common ones are below:-


Place HolderMeaning


%H The hour (24 hour clock)
%I The hour (12 hour clock)
%M The minute
%S The second
%p Either "am" or "pm"

The time will be updated every minute unless overrode by setting the time option.

If the clock is selected, a reminder pop-up will appear. This panel is spilt into four main sections:- the date/time section; the reminder action area; a list of all reminders; and an area for the entry of the reminder text.

To Add a Reminder

  1. set the correct date and time, using the sliders.
  2. type the text into the message field.
  3. click the button labeled ->. This adds the reminder to the list.
  4. repeat until all the required reminders have been set.
  5. click on button labelled OK to save the new reminders.

Removing a Reminder

  1. select the reminder you want to remove in the list.
  2. click on the button labelled Del..
  3. repeat until all the required reminders have been deleted.
  4. click on button labelled OK to update the reminder file.

Changing a Reminder

  1. select the reminder you want to edit in the list.
  2. click the button labeled <-. This loads the reminder into the date/time and message fields.
  3. set the correct date/time and message.
  4. click the button labeled ->. This updates the reminder in the list.
  5. repeat until all the required reminders have been changed.
  6. click on button labelled OK to save the new reminders.

The Help System

The help system now encompasses two means of describing the message (files and embedded text), and two formats of text (HTML and plain formatted ascii). A context---sensitive option is provided as well as the facility to hand-craft a help menu (and add any number of entries to it).

Two browsers are available, one for plain formatted text, the other (optional) for HTML text. The actual one used is determined by whether the first character of the text is < This is avery loose definition, which has been forced on me since there is no standard language definition . If it is (and support for HTML is built in) the text will be interpreted as HTML, otherwise it is assumed to be plain ascii text.

The HTML viewer is not meant to replace Mosaic, it can only read files via NFS, only GIF pictures may be embedded, the spawning of external viewers is not supported, and it does not store a history of files it has viewed, so movement betwen pages has to be written into the pages themselves.

f.help-menu "label" menu name

This has the same syntax (ans effect) as f.menu, the only difference is that the Motif style guide will be followed by making the menu button appear on the right hand side of the menu-bar. An extra feature has been built in, if you request context sensitive help for this button, a copyright panel with configuration information (indicates which options are supported) will be dispalyed.

Valid options are H, F, I.

f.help-on-context "label"

Creates a button in the current menu, that, when selected will start the context sensitive system: the mouse cursor will change shape; an object should be selected (ie. clicked on); any help registered for that object will be displayed.

To obtain context help for an object that is not immediately visible (ie. in a menu not currently poped-up), give the object keyboard focus and press the help key (this is usually F1).

f.help-text "label" name

Creates a button that when selected displays the help stored in the help object name. See HelpText/EndHelp for more details.

Valid options are H, F, I.

f.help-file "label" filename

Creates a button (labelled label) that when selected reads that file filename and dispalys it according to its type (plain of HTML). The file will be searched for in the directories given by the X-resource helpFilePath.

Valid options are H, F, I.

HelpText name

Starts reading the file and storing the text as the object named name. Reading will only be terminated by the word EndHelp appearing at the beginning of a line.

EndHelp

Ends a help text definition started with HelpText.

Panels

This is the largest of all the optional features, purely because of the number of new keywords added to the description syntax.

Panel name

Starts a panel definition, called name.

EndPanel

Ends a panel definition previously started with Panel.

f.panel "label" panel name

Creates a button in the current menu, (labeled label) that when selected pops up the panel panel name.

f.command cmd

This will be the command executed when the Execute button (located at the bottom of the panel) is pressed. The string cmd may contain both environment variables (denoted by $name) and rTc variables (denoted by @name). An rTc variable may only be set by another object in the same panel.

The command object is never seen, it is simply a convenient metaphor for storing information accessed by the rest of the panel.

f.text "prompt" =name

Creates a text entry object in the current panel, the string prompt is used as a prompt. When requested the current contents of the textfield are put in the rTc variable name

f.file "prompt" =name dir

Creates a file selector with a prompt prompt. The directory dir is used as the starting directory. The current file selected is put into the rTc variable name.

The file selector comprises: a scrollable list of files, a text entry (so new filenames may be entered) and a directory label. In the list of files, files are represented by a light font, directories by a bold one. Note: This is a brand new Motif Widget, there may be some problems with it, see Appendix optional-features for more details.

f.scale "prompt" =name {min,max,incr}

Creates a scale setting the current value to the rTc variable name. The scale ranges between min and max in steps of incr (only via the keyboard). If none of these are specified the defaults are 0, 100, 1 respectively.

f.list "prompt" =name {item 1} {item 2} …

Creates a list containing item 1, item 2 etc and setting name to be the currently selected item. Only one item may be selected at any time.

f.toggle "prompt" =name {label,cmd} {label,cmd} …

Creates a series of toggles (only one of which may be set at any time). Each toggle will be labelled with the correspoding label, and when set, the rTc variable name will be set to the respective cmd.

3.5 Command Execution

When it comes time to execute a command, the shell given by the environment variable SHELL is used (rather than forcing all comands through sh. Of course if SHELL is not set, then there is no choice, but to hope that /bin/sh is available.

If the msgLevel has been set to Information (this requires userType to be Expert), then any output generated by the executed program is captured and presented to the user. either via the status area or dialogs as required.

Next Chapter, Previous Chapter

Table of contents of this chapter, General table of contents

Top of the document, Beginning of this Chapter