ON ACTION block

The ON ACTION blocks execute a sequence of instructions when the user triggers a specific action. This is the preferred solution compared to ON KEY blocks, because ON ACTION blocks use abstract names to control user interaction.

Action blocks will be bound by name to action views (like buttons) in the current form. When an action handler block is defined in a DIALOG instruction, all corresponding action views will be automatically enabled on the front-end side. When the user clicks on one of the action views or presses one of the accelerator keys defined for the action, the corresponding action block is executed on the application server side.

The name of the action must follow the ON ACTION keywords. The fglcomp and fglform compilers convert action names to lowercase, but resource files such as .4ad action defaults files are XML files where action names are case-sensitive. To avoid any confusion, always write your action names in lowercase.

The next example defines an action block to open a typical zoom window and let the user select a customer record:

   ON ACTION zoom 
      CALL zoom_customers() RETURNING st, cust_id, cust_name

The DIALOG instruction supports dialog actions and sub-dialog actions. The dialog actions are global to the dialog and can be invoked wherever the focus is. You defined a dialog action by writing the ON ACTION block outside any sub-dialog. The sub-dialog actions are specific to sub-dialogs. You create a sub-dialog action when the ON ACTION block is defined inside a sub-dialog. The sub-dialog actions get an implicit prefix identifying the sub-dialog:

DIALOG
   INPUT BY NAME ... ATTRIBUTES (NAME = "cust")
      ON ACTION suspend -- this is the local sub-dialog action "cust.suspend"
      ...
   END INPUT
   BEFORE DIALOG
      ...
   ON ACTION close -- this is the dialog action "close"
      ...
END DIALOG

Actions can be individually enabled or disabled with a dialog class method called DIALOG.setActionActive():

   BEFORE ROW s_items 
      CALL DIALOG.setActionActive("show_item_details", TRUE)

In UNBUFFERED mode, before an ON ACTION block is executed, the value of the current field is validated and copied to the program variable. You can prevent field validation by using the VALIDATE action default attribute. In buffered mode (the default), when the user triggers an action, DIALOG suspends input to the current field and preserves the input buffer that contains the characters typed by the user before the ON ACTION block is executed. After the block is executed, DIALOG restores the input buffer to the current field and resumes input on the same field, unless a control instruction such as NEXT FIELD or EXIT DIALOG was issued in the block.

Some action names such as "close" and "interrupt" are predefined for a specific purpose. The close action will be automatically bound to the option or button closing the graphical window, to trigger specific code when the user wants to close the window. The interrupt action is dedicated to sending an interruption event when the program is processing in a batch loop. The interrupt action does not require an ON ACTION block: Any action view with this name will automatically be enabled when the program is in processing mode. These special actions are discussed in Programming with DIALOG.

When a ON ACTION uses the same name as an implicit action such as insert, append or delete, either the implicit action or the user action will be executed, according to the context: The implicit action is always executed if the focus is in the sub-dialog of fields the action is designed for. Otherwise, the user code will be executed instead. For example, ON ACTION delete handler will only be executed if there is no INPUT ARRAY having the focus.

Field-specific action handlers can be defined with the ON ACTION action-name INFIELD field-name clause. The runtime system will enable/disable the action automatically when the focus enters/leaves the specified field:

   ON ACTION zoom INFIELD customer_city 
      LET rec.customer_city = zoom_city()