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 is 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 FILL BUFFER Trigger to fill the current page of a paged mode display array dynamic dialog. ON FILL BUFFER block
ON INSERT Row insertion action handler for a display array dynamic dialog. ON INSERT block
ON IDLE seconds Idle timout trigger. ON IDLE block
ON SORT Rowset sort event. ON SORT block
ON TIMER seconds Timer trigger. ON TIMER 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 DIALOG Initialization of the multiple dynamic dialog. BEFORE DIALOG block
AFTER DIALOG End of the multiple dynamic dialog. AFTER DIALOG block
BEFORE DISPLAY In singular dynamic dialog, initialization of the display array. In multiple dynamic dialog, when display array gets focus. BEFORE DISPLAY block
AFTER DISPLAY In singular dynamic dialog, end of the display array. In multiple dynamic dialog, when display array loses focus. AFTER DISPLAY block
BEFORE INPUT In singular dynamic dialog, initialization of the input by name. In multiple dynamic dialog, when input by name gets focus. BEFORE INPUT block
AFTER INPUT In singular dynamic dialog, end of the input by name. In multiple dynamic dialog, when input by name loses focus. AFTER INPUT block
BEFORE CONSTRUCT In singular dynamic dialog, initialization of the construct. In multiple dynamic dialog, when contruct gets focus. BEFORE INPUT block
AFTER CONSTRUCT In singular dynamic dialog, end of the construct. In multiple dynamic dialog, when construct loses focus. 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