GHS BULLETIN

GHS BULLETIN Template dialog boxes in GHS

(c) 2002 by Creative Systems, Inc.

I. Template Command

The TEMPLATE command creates interactive dialog boxes. Its syntax is:

    TEMplate name ["title"] [param]...

If a "title" is present, then it appears in the title bar of the dialog box when the template is executed; if not, the template name is the default title.

The TEMPLATE command is followed by a series of lines specifying the layout of the template dialog box, terminated by a "/" line.

The following optional parameters may appear on the TEMPLATE command line:

    /POS: position

Specifies the location of the dialog box relative to the parent window. Valid position choices are: MIDDLE (default), TOPLEFT, TOPRIGHT, BOTTOMLEFT, BOTTOMRIGHT (the four corners), LEFT, RIGHT (at vertical middle), TOP, BOTTOM (at horizontal middle), CENTER (center of screen), and MOUSE (centered under the current position of the mouse).

    /SIZE: size

Specifies the dialog font size. Valid size choices are: MEDIUM (default; corresponds to command area character size), SMALL (menu character size), and LARGE (maximized character size).

    /FONT: "font,..."

Specifies a list of one or more fonts used for the dialog box. If the first font is not found on the system, then any further fonts are tried in order; if none are found, then MS Sans Serif is used if the /SIZE parameter is present; otherwise the Windows System font is used as the default font.

    /BEEP

Beeps before popping up the dialog box (useful for warning messages).

II. Template Execution

Templates are executed using the command "EXecute name" (or ".name"), where "name" is the template name. Any parameters following ".name" are substituted for "%1", "%2", etc. appearing inside the template (the same as for macros).

When a template is executed, a dialog box pops up containing the specified fields arranged neatly in rows and columns. Data can be edited in variable fields, or in the case of multiple choice variables, a label can be picked from a drop-down list to assign the variable the corresponding value.

Other fields appear as labeled buttons. Pressing a button triggers an action, after which control returns to the dialog, or the dialog exits if the button field was marked with the word "EXIT".

III. Template Format

Templates are composed of multiple lines containing one or more fields, with "|" separating multiple fields within a line. The template is terminated by a "/" line. Each field has the following general syntax:

    ["label"[:value]...]  [EXIT]  [type]  [name]  [param]...

Here are the specific formats for each valid field type:

    "text"
    ["label"[:value]...]      [VARI] name
    ["label"]        [EXIT] FILE|DIR name [/EXT:"exts"] [/SHORT] [/EXIST] [/START]
    ["label"]        [EXIT]        . name [(rep)] [param]...  [/NOVERify] [/START]
    ["ok" ["cancel"]] EXIT

Blank lines in a template create blank lines in the corresponding dialog box.

IV. Template Field Types

A. Text Fields

    "text"

Text fields are surrounded by quotes and appear verbatim in the dialog box. If a text field precedes a non-text field on the same line, then it appears right-justified as a tag before the non-text field.

B. Input Variable Fields

    ["label"]  [VARIable]  name

An unquoted variable name appears in the dialog box as an edit field control, initially set to the value of the variable. The user can edit this value or input a new one. The named variable is updated with the new value only when the dialog box exits or an execute button is pressed.

The variable name may optionally be preceded by the "VARIable" field type; this is only necessary if the variable has an ambiguous name such as "EXIT" or "FILE". If a "label" is present, it appears as a right-justified tag, as if "|" had been used to separate a text field followed by a variable field.

C. Multiple Choice Variable Fields

    "label"[:value]...  [VARIable]  name

If more than one "label" or value is present before the variable name, then a drop-down list control appears, which the user can click to choose any "label" from the list. The named variable is updated with the selected "label" choice when the dialog box exits or an execute button is pressed. However, if the "label" is followed by ":" and a value, then the named variable is updated with that value (either a number or a quoted string) instead of the "label" appearing in the drop-down list.

D. File and Directory Button Fields

    ["label"] [EXIT] FILE|DIR name [/EXT:"exts"] [/SHORT] [/EXIST] [/START]

FILE and DIR fields appears as push buttons which pop up file and directory selection dialog boxes. If this selection box is not canceled, the named variable is updated with the selected long pathname when the template dialog box exits or an execute button is pressed. The variable name appears on the button face, replaced by "label" if present.

If FILE or DIR is the only field in a template, then the template dialog is bypassed when executed, going directly to the file or directory dialog box.

If /EXT:"exts" is present, then only files or directories ending in the specified comma-separated list of extensions (which may contain "*" and "?" wildcards) are listed and can be selected from the dialog box. If one of these extensions is "*", then the others are the default "Files of type", with "All files" available from the "Files of type" drop-down list.

If /EXIST is present, the user is forced to select an existing file or directory from the dialog box, rather than potentially create a new one.

If /SHORT is present, the selected file or directory must reside in the starting directory, which is trimmed from the long pathname before storing the filename and extension in the named variable (or just a short filename and extension if the named variable was sized as a 12 character maximum string). If a single non-wildcard extension was given with the /EXT parameter, then just the long filename is stored in the named variable (or just the short filename for a 8 character maximum variable).

FILE and DIR dialog boxes start in any directory preset in the named variable, or the current directory if none. For the simplified DIR dialog box that appears when /SHORT is present, any preset directory is the initial selection and its parent directory is the starting directory; to specify a starting directory with no initial selection, preset a directory name ending in "\".

If EXIT is present, the template dialog box exits instead of being restored following processing of a pressed FILE or DIR button. If /START is present, the FILE or DIR button has startup focus, triggered when Enter is pressed.

E. Execute Button Fields

    ["label"] [EXIT] . name  [(rep)] [param]...  [/NOVERify] [/START]

An execute button field appears as a push button which executes the named macro or subtemplate. The original template dialog box is hidden while execution is in progress. Since any GHS command is available within a macro, execute buttons can be used to create very powerful control panel dialogs. The macro or template name appears on the button face, replaced by "label" if present.

The syntax for the execute button field corresponds closely to that of the EXECUTE command. As such, "EXecute" can be used in place of "." before the macro or subtemplate name; also, if EXIT is present, then "." is optional. A repetition factor in parentheses can be specified for macro execution. Any parameters following .name are passed to the named macro or subtemplate to substitute for "%1", "%2", etc. (Note that these parameters may not begin with "/" unless enclosed in quotes.)

If EXIT is present, the template dialog box exits instead of being restored following execution of the named macro or subtemplate. If /START is present, then the execution button has startup focus, triggered when Enter is pressed. If /NOVERify is present, any invalid variable values are discarded before execution, instead of popping up a warning box.

F. Exit Button Fields

    ["ok" ["cancel"]] EXIT

Exit buttons are added by default at the bottom of a template dialog box; normally "OK" and "Cancel" buttons are added, but if the template contains no variable, FILE, or DIR fields, then the "Cancel" button is suppressed. However, if any explicit EXIT buttons are present (including EXIT by itself), then no default "OK" or "Cancel" buttons appear.

If EXIT is preceded by a single "ok" label, this renames the "OK" button and the "Cancel" button is omitted. If EXIT includes both "ok" and "cancel" labels, then these labels rename the corresponding buttons.

V. Keyboard Shortcuts For Template Buttons

The first capitalized letter in a button field label is underlined and acts as a keyboard shortcut when not editing a variable field, or any time if used together with the Alt key. To specify a different label character as the shortcut, precede that character with an underline ("_"). To prevent any character from being an underlined shortcut, end the label with "_". A doubled underline "__" causes single non-shortcut "_" to appear in a label. "OK" and "Cancel" buttons do not have automatic underlined keyboard shortcuts unless "_" is explicitly used; note Esc is always a shortcut for "Cancel".

VI. Template Startup Focus

If an "OK" button is present in a TEMPLATE, it is highlighted as the starting button triggered when Enter is pressed; this input focus button can be moved forward or back by pressing Tab or Shift-Tab. If there is no "OK" button, the first button field is the starting button. A different starting button can be specified by including the /START parameter after a button field. If any variable fields exist, the first variable field begins with the keyboard focus for data entry, and the starting button is triggered if Enter is pressed.

VII. Template Verification

All variable, FILE, and DIR fields in a template are verified to check that they contain valid input values before storing them into their associated variables. (For example, if a variable was defined using the "VARIABLE X:2:3" command, then any value less than 2 or greater than 3 would be invalid.) If a field is invalid, then a warning box pops up explaining the problem, and the dialog box resumes with focus on the invalid field.

Verification takes places before a template dialog exits or executes a macro or subtemplate. Verification may be turned off for a particular button by including the "/NOVERify" parameter, which discards any invalid values.

VIII. Template Exit Status

The TEMPLOK system variable stores the ordinal number of the field button which was pressed to exit the most recent template dialog box, or else it stores 0 if "Cancel" or the dialog title bar close button was pressed. (For example, if a template contains a text tag, a variable field, "OK", and "Cancel", pressing "OK" would set TEMPLOK to 3.) Normally this variable would just be checked for non-zero to make sure the dialog wasn't cancelled, but when multiple EXIT buttons are present, TEMPLOK could be used to determine which EXIT button was selected by the user.

IX. Similarities Between Templates and Macros

Templates and macros share the following features:

1. TEMPLATE name [EDIT] command behaves the same as the MACRO command,
introducing a series of lines terminated by a "/" line;

2. LIST command shows templates along with macros;

3. IF EXIST also checks for template existence;

4. WRITE (MACROS) command also writes templates to the specified file;

5. GHS32 Macro menu also works with templates;

6. EXECUTE (or ".") command runs both macros and templates.

If you would like to see another bulletin created regarding a specific topic, please email Creative Systems, Inc. at support@ghsport.com.