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:


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: 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}
[Prev] [Top]