Understanding multiple dialogs

Multiple dialogs are defined with DIALOG blocks inside a FUNCTION.

The concept of multiple dialogs refers to the usage of a procedural DIALOG block, to control several elements of a form. During the execution of a procedural dialog, no other window/form can be accessed: multiple dialogs are in the category of modal dialogs.

The DIALOG procedural instruction handles different parts of a form simultaneously, including simple display fields, simple input fields, read-only list of records, editable list of records, query by example fields, and action views. The DIALOG instruction acts as a collection of singular dialogs working in parallel.

"Singular interactive instructions" refer to INPUT, CONSTRUCT, DISPLAY ARRAY and INPUT ARRAY independent blocks not surrounded by the DIALOG / END DIALOG keywords. While the DIALOG instruction reuses some of the semantics and behaviors of singular interactive instructions, there are some differences.

Like the singular interactive instructions, DIALOG is an interactive instruction. You can execute a DIALOG instruction from one of the singular dialogs, or execute a singular dialog from a DIALOG block. The parent dialog will be disabled until the child dialog returns.

A DIALOG procedural instruction consist of several sub-dialog blocks declared inside the DIALOG instruction, or external dialog blocks declared in scope outside of the current function. The external dialogs are attached to the current dialog with the SUBDIALOG clause.

The DIALOG instruction binds program variables (such as simple records or arrays of records) with a screen-record or screen-array defined in a form, allowing the user to view and update application data.

When a DIALOG block executes, it activates the current form (the form most recently displayed or the form in the current window). When the statement completes execution, the form is deactivated.

The syntax of the DIALOG instruction is very close to singular dialogs, using common triggers such as BEFORE FIELD, ON ACTION, and so on. Despite the similarities, the behavior and semantics of DIALOG are a bit different from singular dialogs.

Understand that the DIALOG instruction is not provided to replace singular dialogs. Singular dialogs are still supported. It is recommended that you use singular dialogs if no multiple dialog is required.

Unlike singular dialogs, the DIALOG instruction does not use the INT_FLAG variable. You must implement ON ACTION accept or ON ACTION cancel to handle dialog validation or cancellation. These actions do not exist by default in DIALOG.

Unlike singular dialogs creating implicit accept and cancel actions, by default there is no way to quit the DIALOG instruction. You must implement your own action handler and execute EXIT DIALOG or ACCEPT DIALOG.

A good practice is to write a setup dialog function to centralize all field and action activations for a specific context. Call that setup function at any place in the DIALOG code where the field and action activation rules may change.

While static arrays are supported by the DIALOG instruction, it is strongly recommended that you use dynamic arrays instead. With a dynamic array, the actual number of rows is automatically defined by the array variable, while static arrays need an additional step to define the total number of rows.

When needed, use the UNBUFFERED mode with multiple dialogs to force model/view synchronization, and use the FIELD ORDER FORM option to follow the TABINDEX definitions in the form file.

SCHEMA stores 
DEFINE p_customer RECORD LIKE customer.*
DEFINE p_orders DYNAMIC ARRAY OF RECORD LIKE order.*
FUNCTION customer_dialog()
  DIALOG ATTRIBUTES(UNBUFFERED, FIELD ORDER FORM)
    INPUT BY NAME p_customer.*
      AFTER FIELD cust_name 
        CALL setup_dialog(DIALOG)
    END INPUT
    DISPLAY ARRAY p_orders TO s_orders.*
      BEFORE ROW
        CALL setup_dialog(DIALOG)
    END DISPLAY
    SUBDIALOG common_footer
    ON ACTION close 
      EXIT DIALOG
  END DIALOG
END FUNCTION

All elements of the dialog are active at the same time, so you must handle tabbing order properly. By default - as in singular dialogs - the tabbing order is driven by the binding list (order of program variables). It is strongly recommended that you use the FIELD ORDER FORM option and the TABINDEX field attributes instead.

Like the singular INPUT ARRAY instruction, DIALOG creates implicit insert, append, and delete actions. These actions are only active when the focus is in the list.

When the user moves from field to field, changes values, or browses a list, dialog control blocks such as BEFORE FIELD, BEFORE ROW, BEFORE INPUT, BEFORE DISPLAY are executed.

When the user clicks on an action view (button), or when an asynchronous event occurs, dialog interaction blocks like ON ACTION are executed.

The code inside a DIALOG / END DIALOG dialog can use control instructions, dialog control functions, and the ui.Dialog class, to implement the dialog behavior.