ui.Dialog.nextEvent

Waits for a dialog event.

Syntax

nextEvent()
   RETURNS STRING
  1. event is the name of the dialog event that raised.

Usage

The nextEvent() waits for a dialog event to occur, and returns a string that identifies the dialog event that has raised.

This method is typically used in a WHILE loop, to implement a dynamic dialog.

The method can return NULL, if a dialog error occurs, or if the dialog terminates (with ui.Dialog.close()).

The recommended programming pattern for the event WHILE loop is to test for nulls:
DEFINE d ui.Dialog,
       t STRING
...
WHILE (t := d.nextEvent()) IS NOT NULL
    CASE t
        WHEN "BEFORE FIELD cust_name"
...

A dialog event can be a user-defined trigger such as "ON ACTION print", or an implicit trigger such as "BEFORE ROW", corresponding to the control blocks that can be defined in static dialog instructions such as DISPLAY ARRAY.

User-defined triggers are added to the dynamic dialog with the addTrigger() method:

Table 1. User-defined triggers for dynamic dialogs
Trigger name Description Dialog block equivalent
ON ACTION action-name Action handler for the action identified by action-name. ON ACTION block
ON APPEND Row addition action handler for a display array dynamic dialog. ON APPEND block
ON DELETE Row deletion action handler for a display array dynamic dialog. ON DELETE block
ON INSERT Row insertion action handler for a display array dynamic dialog. ON INSERT block
ON UPDATE Row modification action handler for a display array dynamic dialog. ON UPDATE block

Implicit dialog triggers are predefined and can be detected and handled in the dialog WHILE loop if needed:

Table 2. Implicit triggers for dynamic dialogs
Trigger name Description Dialog block equivalent
BEFORE DISPLAY Initialization of the display array dynamic dialog. BEFORE DISPLAY block
AFTER DISPLAY End of the display array dynamic dialog. AFTER DISPLAY block
BEFORE INPUT Initialization of the input by name dynamic dialog. BEFORE INPUT block
AFTER INPUT End of the input by name dynamic dialog. AFTER INPUT block
BEFORE CONSTRUCT Initialization of the query by example dynamic dialog. BEFORE INPUT block
AFTER CONSTRUCT End of the query by example dynamic dialog. AFTER INPUT block
BEFORE ROW Moving to a new row in a display array or input array dynamic dialog. BEFORE ROW block
AFTER ROW Leaving the current row in a display array or input array dynamic dialog. AFTER ROW block
BEFORE INSERT Before a new row is created in an input array dynamic dialog. BEFORE INSERT block
AFTER INSERT After a new row is created in an input array dynamic dialog. AFTER INSERT block
BEFORE DELETE Before a new row is deleted in an input array dynamic dialog. BEFORE DELETE block
AFTER DELETE After a new row is deleted in an input array dynamic dialog. AFTER DELETE block
BEFORE FIELD field-name Entering the field field-name in an input dynamic dialog. BEFORE FIELD block
AFTER FIELD field-name Leaving the field field-name in an input dynamic dialog. AFTER FIELD block
ON CHANGE field-name Value of field field-name changed in an input dynamic dialog. ON CHANGE block