Connecting RDF programs to Tkplay
Tkplay can be used as a front-end for processing
RDF files. Tkplay does not contain any code for doing actual processing,
but relies on outside filters to perform the work. This allows quick
and easy integration of new RDF tools into Tkplay.
Before Tkplay can use a filter, the filter must tell Tkplay how it is
to be used. This includes telling Tkplay what flags the filter
accepts, the types of options each flag can accept, and descriptions of
the flag. This document describes the protocol that RDF programs must
use so that Tkplay will understand how to use them.
Requirements
To be used in Tkplay, a RDF filter must respond to the "-N"
flag. Tkplay runs the filter with the "-N" flag to get the information
about how to run the filter. In response, the filter should print out
the appropriate information and exit.
The output from using the -N flag should contain one line for a description
of the filter itself, and one line for a description of each flag that
the program accepts. The first line must contain 4 fields each separated
by whitespace:
programname {flaglist} {short description} {long description}
Note that every field after the first must be surrounded by curly braces
programname- This is the name of the filter as it should be run by Tkplay.
When the filter is run, Tkplay will execute a system call with this
as the first argument.
{flaglist}- flaglist is a listing of each flag that the filter accepts.
The flags should be separated by whitespace. Each should include
the leading -.
{short description}- This is a short description of what the program does. This
description should only be a couple of words long and is
displayed in Tkplay's
Filter Listbox.
{long description}- The long description of the program can be of any length.
One or two sentences can usually suffice. This long description
is displayed at the top of the
Filter Input Area when the
user selects this filter.
For example, the filter rdft87 produces the following:
rdft87 {-i -o -p} {T87 Listing} {Produces listing of cross-section values.}
The second and subsequent lines output from using the "-N" flag are
descriptions of the arguments that the program can accept. Each of these flags
must have been listed in the {flaglist} field above. Conversely,
each entry in the {flaglist} field must have a corresponding line
in this section. Each of these lines must contain 7 fields each separated
by whitespace:
programname {flag} {argument} {type} {required} {short description} {long description}
Note that every field after the first must be surrounded by curly braces
programname- This field must match the program name above. This lets Tkplay
know which program this flag description is for.
{flag}- This is the flag as it is to be used on the commmand line.
The leading - must be included.
{argument}- If the flag takes an argument, it should be named here. If the
flag is a boolean flag then this should remain as an empty set
of curly braces.
If the argument is listed as "RDF Input File" then Tkplay won't list
the flag in the Filter Input
Area. Instead, the file currently selected in the
File Listbox will be used.
If the argument is listed as "RDF Output File" then the argument
is still not listed. This will indicate to Tkplay that when
the filter has finished running the output file is a valid RDF
file and will be loaded into Tkplay.
If the argument is listed as "Text Output File" argument or
simply "Output File" then the is again not listed. This will
indicate to Tkplay that the output from the filter is to be
displayed in the Text Display window.
{type}- This is the type of argument from above. It must be either
blank or contain one of the following:
- boolean
- string
- float
- integer
- group
- multiple-float
- multiple-integer
- multiple-string
- multiple-group
If the type is specified as boolean then the
flag is presented to the user as a checkbutton. If the checkbutton
has been selected then the filter is run with this flag included
in the argument list. If the checkbutton has not been selected,
then this flag will not be present in the argument list when
the filter is run.
If the type is float or integer,
then the flag will be displayed as an entry widget. This entry
widget will only accept values of the appropriate type. For
example, if the flag takes an integer argument,
then the entry area will only allow the user to enter integers
as values.
string arguments are also presented to the user as
entry areas, but no restrictions are placed on the values
which may be supplied by the user.
There is not yet documentation for multiple-*
or group types.
{required}- This field should contain either the word
required
or optional. The usage of this field indicates to
Tkplay if the filter needs this flag to be run correctly. If a
value is not supplied by the user then Tkplay will warn the user
that they need to enter a value. Input and Output file flags
should be described as required
{short description}- This is a short description of the flag which will be presented
to the user in the filter's
Input Area.
This description is usually displayed as a label to the checkbutton
/ entry widget. A recommended length for this field is 3 words or
less.
{long description}- The long description of the flag is used to provide more information
about the flag to the user if the short description is not enough.
The long description is displayed in Tkplay's
Help Entry Area when the mouse
is positioned over the entry area or label. If the long description
is more than about 80 characters it may be cut off on the right in
the Help Entry Area.
Note that this has only been implemented for entry widgets,
that is, flags of type integer, float,
or string.
Examples coming soon
