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