6.10.7 Building a command line dialog box

When defining a tool, it is possible to show a dialog to the user, asking for additional arguments, using the $PROMPT(filename) command-macro. The Free Pascal distribution contains some ready-made dialogs, such as a ’grep’ dialog, a ’cvs checkout’ dialog and a ’cvs check in’ dialog. The files for these dialogs are in the binary directory and have an extension .tdf.

In this section, the file format for the dialog description file is explained. The format of this file resembles a windows .INI file, where each section in the file describes an element (or control) in the dialog. An OK and a Cancel button will be added to the bottom of the dialog, so these should not be specified in the dialog definition.

A special section is the Main section. It describes how the result of the dialog will be passed to the command line, and the total size of the dialog.

Remark Keywords that contain a string value should have the string value enclosed in double quotes as in

The Main section should contain the following keywords:

Title

The title of the dialog. This will appear in the frame title of the dialog. The string should be enclosed in quotes.

Size

The size of the dialog, this is formatted as (Cols,Rows), so

Size=(59,9)

means the dialog is 59 characters wide, and 9 lines high. This size does not include the border of the dialog.

CommandLine

specifies how the command line will be passed to the program, based on the entries made in the dialog. The text typed here will be passed on after replacing some control placeholders with their values.

A control placeholder is the name of some control in the dialog, enclosed in percent (%) characters. The name of the control will be replaced with the text associated with the control. Consider the following example:

CommandLine="-n %l% %v% %i% %w% %searchstr% %filemask%"

Here the values associated with the controls named l, v, i, w and searchstr and filemask will be inserted in the command line string.

Default

The name of the control that is the default control, i.e. the control that is to have the focus when the dialog is opened.

The following is an example of a valid main section:

After the Main section, a section must be specified for each control that should appear on the dialog. Each section has the name of the control it describes, as in the following example:

Each control section must have at least the following keywords associated with it:

Type

The type of control. Possible values are:

Label

A plain text label which will be shown on the dialog. A control can be linked to this label, so it will be focused when the user presses the highlighted letter in the label caption (if any).

InputLine

An edit field where a text can be entered.

CheckBox

A checkbox which can be in an on or off state.

Origin

Specifies where the control should be located in the dialog. The origin is specified as (left,top) and the top-left corner of the dialog has coordinate (1,1) (not counting the frame).

Size

Specifies the size of the control, which should be specified as (Cols,Rows).

Each control has some specific keywords associated with it; they will be described below.

A label (Type=Label) has the following extra keywords associated with it:

Text

the text displayed in the label. If one of the letters should be highlighted so it can be used as a shortcut, then it should be enclosed in tilde characters (˜). E.g. in

Text="~T~ext to find"

the T will be highlighted.

Link

The name of a control in the dialog may be specified. If specified, pressing the label’s highlighted letter in combination with the Alt key will put the focus on the control specified here.

A label does not contribute to the text of the command line; it is for informational and navigational purposes only. The following is an example of a label description section:

An edit control (Type=InputLine) allows entry of arbitrary text. The text of the edit control will be pasted in the command line if it is referenced there. The following keyword can be specified in a inputline control section:

Value

A standard value (text) for the edit control can be specified. This value will be filled in when the dialog appears.

The following is an example of an input line section:

A checkbox control (Type=CheckBox) presents a checkbox which can be in one of two states, on or off. With each of these states, a value can be associated which will be passed on to the command line. The following keywords can appear in a checkbox type section:

Name

The text that appears after the checkbox. If there is a highlighted letter in it, this letter can be used to set or unset the checkbox using the Alt-letter combination.

Default

Specifies whether the checkbox is checked or not when the dialog appears (value on or off).

On

The text associated with this checkbox if it is in the checked state.

Off

The text associated with this checkbox if it is in the unchecked state.

The following is an example of a valid checkbox description:

If the checkbox is checked, then the value -i will be added on the command line of the tool. If it is unchecked, no value will be added.