Setting action key labels

Labels can be defined to decorate buttons controlled by ON KEY / COMMAND KEY action handlers.

Important:

Key label configuration is provided for backward compatibility. Consider using action configuration in new programs. However, key labels can be used to easily improve the graphical rendering of your application, without touching legacy code using ON KEY / COMMAND KEY in dialogs.

Syntax

Key label configuration can take place at different levels.

FGLPROFILE definitions
```
key.key-name.text = "label"
```

Program-level key labels

CALL fgl_setkeylabel( "key-name", "label" )

Form level key labels (in KEYS section)
```
KEYS key-name = [%]"label"
[...]
[END]
```

Dialog level key labels

CALL fgl_dialog_setkeylabel( "key-name", "label" )

Form field level key labels (in field definition)
```
KEY key-name = [%]"label"  
```

key-name is the name of the key.
label is the text to be displayed in the default action view (button).

Usage

In GUI mode, ON KEY and COMMAND KEY action handlers in dialogs can be shown as form buttons when a label text is defined for the key. By defining a label for a key, the runtime system will automatically show a default button for the key action.

In the example, the function key F10 is used to show a detail window in this interactive dialog:

INPUT BY NAME myrecord.*
  ON KEY (F10)
    CALL ShowDetail()
END INPUT

By default, if you do not specify a label for F10, no default action button is displayed for a function key or control key. Furthermore, if the text provided for the key label is empty or null, the default action button will not be displayed.

In order to get a default action view button for F10, define for example the KEY attribute in the form file, for the corresponding fields where this action can be fired:

ATTRIBUTES
...
f07 = customer.cust_city, KEY F10 = "City list";
f08 = customer.cust_state, KEY F10 ="State list";
...

Table 1. Key names recognized by the runtime system
Key Name	Description
`f1` to `f255`	Function keys.
`control-a` to `control-z`	Control keys.
`accept`	Predefined dialog validation action.
`interrupt`	Predefined dialog cancellation action. The action name is cancel, not interrupt.
`insert`	Predefined `INPUT ARRAY` dialog row insertion action.
`append`	Predefined `INPUT ARRAY` dialog row addition action.
`delete`	Predefined `INPUT ARRAY` dialog row deletion action.
`help`	Predefined help action.

Key labels can be defined at different levels. The order of precedence for key label definition is the following:

The label defined with the KEY attribute of the form field.
The label defined for the current dialog, using the FGL_DIALOG_SETKEYLABEL function.
The label defined in the KEYS section of the form specification file.
The label defined as default for a program, using the FGL_SETKEYLABEL function.
The label defined in the FGLPROFILE configuration file (key.key-name.text entries).

In Genero, you typically define action labels with action attributes. However, if key labels are defined, they will overwrite the text defined in action attributes for the corresponding key action. In BDS 3.xx versions, default key labels are defined in $FGLDIR/etc/fglprofile. These defaults have been commented out in Genero to have action attribute text applied (In Genero, by default, fgl_getkeylabel() returns NULL for all keys). If you want to get the same default key labels as in BDS 3.xx, uncomment the key.* lines in $FGLDIR/etc/fglprofile.

You can query the label defined at the program level with the FGL_GETKEYLABEL function and, for the current interactive instruction, with the FGL_DIALOG_GETKEYLABEL function.