Connecting RDF programs to Tkplay
Version 1.0
(proposed)
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 should contain several fields to desribe
the program and prepare Tkplay for the argument descriptions to follow.
Each field is a key-value pair, with the key and value separated by a colon.
The value for each pair must be enclosed in curly braces so that there is
no confusion with values that contain spaces:
NAME:programname FLAGLIST:flaglist SDESC:{short description} LDESC:{long description} VERSION:{version}
The following keys are accepted for a program description. Keys which are required
are described as such.
NAME
(required)
- 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
(required)
- flaglist is a listing of each flag that the filter accepts.
The flags should be separated by whitespace. Each should include
the leading -. See below for an example.
SDESC
(required)
- 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.
LDESC
(required)
- 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.
VERSION
(required)
- The version string is used to help Tkplay figure out how to deal
with filters that do not use the most recent format specification
ITYPE
- The input file type for this filter. Tkplay recognizes the following
input types:
OTYPE
- The output type for this filter. TKnowing the output type of the
filter ahead of time helps Tkplay to prepare the appropriate callbacks
before running the filter. kplay recognizes the following output
types:
- RDF
- Text
- Polar Graph
- XY Graph
Example program descriptions:
NAME:rdft87 FLAGLIST:{-i -o -p} SDESC:{T87 Listing} LDESC:{Produces listing of cross-section values.}
NAME:rdffreqplot FLAGLIST:{-i -o -s -R -r -T -f} SDESC:{Plot Spectra} LDESC:{Generates plots of spectra} ITYPE:{RDF} OTYPE:{XY Graph} VERSION:{1.0}
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.
The format for the flag descriptions is similar to the format for the
program description. Only the names of the keys have changed:
NAME:programname FLAG:{flag} TYPE:{type} REQUIRED:{required} SDESC:{short description} LDESC:{long description} HIDDEN:{state}
The following keys are recognized for flag descriptions:
NAME
(required)
- This field must match the program name above. This lets Tkplay
know which program this flag description is for.
FLAG
(required)
- This is the flag as it is to be used on the commmand line.
The leading - must be included.
ARG
- If the flag takes an argument, it can be named here. If the
flag is a boolean flag then this should remain as an empty set
of curly braces. This field currently serves no purpose.
TYPE
(required)
- 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.
multiple-string, multiple-integer, multiple-float
flags are presented as a combobox to the user. The combobox
is composed of an entryfield above a listbox. The user enters
a value in the entryfield and presses «Return»
to insert a value into the listbox. To delete an item from
the listbox, the user right-clicks on the listbox item.
The multiple in these types mean that the filter can
accept multiple instances of this filter
(ie: filter -i a -i b -o c
). Each value
in the listbox is used for one instance of the flag.
There is not yet documentation for group
types.
REQUIRED
- The value for this field should be on of
1
or 0
.
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
assume that the flag is optional. Input and Output file
flags should be described as required
SDESC
(required)
- 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.
LDESC
- 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: this has only been implemented for entry widgets,
that is, flags of type integer
, float
,
or string.
HIDDEN
- The value for this field should be on of
1
or 0
. If the value is 0
,
then Tkplay will not display the entry for this field,
but will use a default value instead.
DEFAULT
- This field is mostly used to set the input and output flags
so that Tkplay can supply values for the input and output
files. If the default value is
%i
, then Tkplay
will insert the name of the currently selected file.
If the default value is %o
, then Tkplay will
insert a name for an output file.
Example flag descriptions:
NAME:{rdft87} FLAG:{-i} TYPE:{string} DEFAULT:{%i} REQUIRED:{1} SDESC:{Input File} HIDDEN:{1}
NAME:{rdf2asc} FLAG:{-a} TYPE:{boolean} REQUIRED:{0} SDESC:{List All Tags} HIDDEN:{0}
NAME:{rdffs} FLAG:{-e} TYPE:{float} REQUIRED:{1} SDESC:{Effective Filter Bandwidth} LDESC:{The effective bandwidth requested, in Hz}
NAME:{rdffreqplot} FLAG:{-T} TYPE:{boolean} REQUIRED:{1} SDESC:{Send output to Tkplay} HIDDEN:{1}