COMMAND [KEY()] "option" block

The COMMAND [KEY(key-name)] "option-name" clause defines a menu action handler with a set of instructions to be executed when an action is invoked. The option text (option-name), converted to lowercase letters, defines the name of the action.

For example, when defining:

COMMAND "Hello"

The name of the action will be "hello" (not "Hello" with a capital H).

When used with the KEY() clause, the command specifies both accelerator keys and an option text.

Note: The KEY() clause allows a comma-separated list of keys. Up to four keys can be specified. For new developments, consider using a single key, or prefer ON ACTION handlers with a single accelerator definition in action defaults.

Action defaults will be applied by using the action name defined by the option text (converted to lowercase).

Explicit action views defined in the form (BUTTON in layout, TOPMENU or TOOLBAR items) will get all action defaults associated to the menu command, while default action views (i.e. buttons in the action frame) will be decorated with the menu option text and comment specified in the program (this means that the TEXT and COMMENT attributes of the corresponding action defaults entry are not used for the default action views). However, other attributes such as the IMAGE will also be applied to default action views.

For example, when defining:

COMMAND "Hello" "This is the Hello option"

The name of the action will become "hello", the default action view button text will be "Hello", and the button hint will be "This is the Hello option", even if an action default defines a different text or comment for the "hello" action. If the corresponding action default defines an IMAGE icon, it will display in the default action view button.

Note: The keys defined with the KEY() clause will take precedence over accelerators defined with action defaults corresponding to the action name.

The first letter of the display text of a COMMAND menu clause can be used as default accelerator. When this first letter is not used by other menu option labels, pressing the key corresponding to that letter will execute that action. When the first letter is also used in other menu options, pressing the key will toggle the focus between all default action views that share the same letter. For example:

MENU 
  COMMAND "Start"
    DISPLAY "Start"     
  COMMAND "Stop"
    DISPLAY "Stop"
  COMMAND "Quit"
    EXIT MENU
END MENU

In this example, when pressing S on the keyboard, the focus will toggle between "Start" and "Stop"buttons, and the current option can be selected with the Return or Space key. When pressing Q, the "Quit" action will be fired.

To write abstract code without decoration in your programs, use the ON ACTION clause instead of COMMAND [KEY], except if the action view must get the focus.

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".

In TUI mode, actions created with COMMAND [KEY] do not get accelerators from action defaults; only actions defined with ON ACTION will get accelerators of action defaults.