Configuring actions

Action attributes related to decoration, keyboard shortcuts, and behavior can be defined with action attributes.

Action attributes define attributes for actions, including decoration such as text, icon, comment, as well as keyboard accelerator (Ctrl-?, function keys), and also semantics such as current field validation control when an action is fired.

The action attributes can be defined in different ways:

Common action attributes can be centralized in a global action defaults file with the .4ad extension.
Form-specific action attributes can be defined in the ACTION DEFAULTS section of a form definition file.
Dialog-specific action attributes can be defined in programs with the ATTRIBUTES() clause of ON ACTION handlers.
Form-item specific action view attributes (decoration only) can be defined directly at the item level (labels, icons, comments).
Default action views can be configured dynamically with ui.Dialog.setAction*() methods.

Action attributes do not only define action view decoration; it is possible to define the semantics of an action, for example by using the VALIDATE action default attribute. Functional attributes take effect for a given action when the dialog implementing the action handler becomes active.

Action attributes are particularly important for rendering the default action view (when there is no explicit action view defined in the form). This is typically the case when no form is associated with the dialog.

Action attributes can be defined with action defaults. Common action defaults are defined in a global action defaults (.4ad) file, while form specific actions are define within the ACTION DEFAULTS section of form files.

If a dialog is not attached to a specific form such as an independent MENU, define the action attributes with the ATTRIBUTES clause of ON ACTION handlers, to render the default view and configure the action semantics. Attributes defined by ON ACTION action-name ATTRIBUTES() will only be applied to the default action view: The elements in the forms do not get decoration attributes defined by dialog action handlers.

The final decoration and functional attribute values are set in this order of precedence:

The attribute defined in the action view element definition itself (local form element decoration) - For default action views, the attributes are defined with ui.Dialog.setAction*() methods.
The attribute defined in the ATTRIBUTES clause of an ON ACTION handler.
The attribute defined for the action in the ACTION DEFAULTS section of the current form.
The attribute defined for the action in the global action defaults file (.4ad).

Note: The global action defaults can be loaded at runtime with ui.Interface.loadActionDefaults, and the form-specific

ACTION
DEFAULTS

section can be loaded with ui.Form.loadActionDefaults. These solutions are typically used in a migration process, to get action views decoration without modifying existing .per forms.

The syntax for defining action attributes depends on the context where the action attributes are defined:

In the .4ad file, the syntax follows XML standards, as defined in Action default attributes reference (.4ad).
In the .per files, the syntax follows the form specification file attributes, as defined in ACTION DEFAULTS section.
In the .4gl files (in dialog action handlers), the syntax follows the language syntax, as defined in ON ACTION block.

Example

Consider the following parts of code related to the same action definition, namely "print":

1. A BUTTON item defined in the form specification file:

ATTRIBUTES
 BUTTON b1: print, TEXT="Print item";
END

2. A dialog instruction with code defining the ON ACTION handler with an ATTRIBUTES clause:

DIALOG ...
   ...
   ON ACTION print
      ATTRIBUTES( ROWBOUND, IMAGE = "printer_2" )
      ...

3. The form ACTION DEFAULTS section defining:

form.per:
ACTION DEFAULTS
  ACTION print (IMAGE="printer_1",
                COMMENT="Print the order",
                ACCELERATOR=Control-P,
                CONTEXTMENU=NO)
END

4. A global .4ad action defaults file defining:

<ActionDefaultList>
  <ActionDefault name="print" text="Print" image="smiley" />
</ActionDefaultList>

When the dialog executes, the "print" action will get the following functional attributes:

acceleratorName = "control-p" - from the form ACTION DEFAULTS section
rowBound = "yes" - from the dialog ON ACTION handler
contextMenu = "no" - from the form ACTION DEFAULTS section

The form button (the action view) will get the following decoration attribute values:

text = "Print item" - from the BUTTON form item
image = "printer_2" - from the dialog ON ACTION handler
comment = "Print the order" - from the form ACTION DEFAULTS section