COMMAND [KEY] block

Use COMMAND [KEY] blocks as global DIALOG action handler to execute a sequence of instructions when the user clicks on a button or presses a specific key. COMMAND defines the text and comment decoration attributes as well as accelerator keys for a specific action. COMMAND is especially useful when writing TUI programs, however, it's legal to use such handler when programming new GUI dialogs, especially when the action view (BUTTON in form) must take the focus.

Declaring a COMMAND block in DIALOG is similar to an ON ACTION block, except that COMMAND defines an implicit text and comment decoration attribute. The name of the action will be the command text converted to lowercase letters. For example, with the following code:

COMMAND "Open" "Opens a new file"

The name of the action will be "open", and the default decoration text will be "Open" with a capital letter.

Note that if you use an ampersand (&) in the command name, some front-ends consider the letter following & as an Alt-key accelerator, and the letter will be underscored. However the ampersand forms part of the action name. For example, COMMAND "&Save" will create an action with the name "&save". It is not recommended to use & ampersand characters in action names.

Unlike ON KEY actions, if no explicit action view is defined in the form, the default action view will be visible for a COMMAND hander (i.e. the automatic button will appear for this action on the front-end).

Action defaults will be applied by using the action name. For explicit action views such as a BUTTON in the form layout, the text/comment defined in the corresponding action default entry will overwrite the values used in the COMMAND handler. When no explicit action view is defined in the form, the text/comment defined in the program COMMAND clause take precedence over action defaults, to display the default action view (button on action frame).

Inside DIALOG instruction, COMMAND blocks can only be defined as global dialog actions; Sub-dialog specific COMMAND handlers cannot be defined. When binding a form BUTTON to a COMMAND handler, the button can get the focus and will be managed in the tabbing list, using preferably the FIELD ORDER FORM option.

When using the optional KEY clause, COMMAND defines also an implicit accelerator key. The key name must be specified between parentheses with COMMAND KEY:

COMMAND KEY (F5) "Open" "Opens a new file"

The COMMAND KEY syntax allows multiple key names in the syntax. When using multiple keys in an COMMAND KEY clause, the DIALOG instruction will assign the specified keys as accelerators:

COMMAND KEY (F5, CONTROL-P, CONTROL-Z) "Open" "Opens a new file"

With the above code example, the action name will be "open" and accelerators will be F5, CONTROL-P and CONTROL-Z.

The keys defined by program will take precedence over the accelerators defined in the action default entry corresponding to the action.

The COMMAND [KEY] block specification can also define a help number with the HELP clause, to display the corresponding text of the current help file.

COMMAND "Open" "Opens a new file" HELP 34