Template body: definitions

Definition syntax

Definitions in QTPL take the form

varname { defname1 { defvalue1 } defname2 { defvalue2 } $\dots$ }

for a list of at least one name-value pair. Here varname is the name of the plug-in or the argument-variable for which something is being defined, defname is the keyword, and defvalue is the value defined for it expressed inside an ASCII-double-quoted string. Strings may contain any printable characters, and additionally the newline specifier $\backslash$n.

Plug-in mandatory definitions

The plug-in name-variable must have an OBJECT_FILE and an ENTRY_NAME defined as quoted text, in order that the plug-in may be located and loaded successfully.

OBJECT_FILE

is the shareable library from which to load the plug-in: it may be defined as a complete path (i.e. beginning with `/') which will be taken as literal, or as a filename. If no path is specified a search will be undertaken using the current working directory `.', then the user specific environment variable USER_LIB and finally the QSAS provided plug-in library QSAS_HOME/lib. The latter method is recommended so that templates may be portable between different users and systems without the need to edit the OBJECT_FILE definition.

ENTRY_NAME

is the function name of the plug-in wrapper. It is used to determine the entry point for the shareable library OBJECT_FILE which must be known in order to load it. Note: this supercedes the earlier plug-in syntax (QSAS version 1.3 and earlier) which required that the actual entry point string be specified here.

Plug-in optional definitions

The definitions below may optionally be set for the plug-in name variable to influence the appearance of the Plug-in Window and to provide on-line help when a plug-in is loaded.

PUBLIC_NAME,

if defined, is used in place of the plug-in's internal QTPL variable name for the title of the window. The PUBLIC_NAME may contain characters that would not be permitted in a QTPL variable name. This is recommended as a way to display the version number after the name, as in the example.

DESCRIPTION

of a plug-in provides the text to output when the user requests Brief description on the Plug-in Window Help menu, as shown figure 1.

Argument definitions (all optional)

Any QTPL variable may optionally have any or all of the following defined to influence its presentation in the Plug-in Window.

PUBLIC_NAME

of a variable is used to label the interface slot for that argument instead of the variable name; this permits more flexibility in composing useful labels, as a PUBLIC_NAME may contain spaces, newlines, and other characters not permitted in variable names.

DESCRIPTION

of non-function arguments provides additional labelling information for plug-in slots, as shown in figure 1.

DEFAULT_VALUE

provides a default for the specified argument which will be set when a template is first loaded, and subsequently if the user requests it with the QPLUGUI Default All button. Note that DEFAULT_VALUE is specified as quoted text even for numeric values, as it is copied to the corresponding plug-in slot without processing, just as if the user had typed-in the characters.