The Dialog class

Summary:

Basics
Examples

Basics

Purpose:

The Dialog class is a built-in class that provides an interface to an interactive instruction such as INPUT.

Syntax:

ui.Dialog

Methods:

Object Methods
Name	Description
`getForm()` `RETURNING` `ui.Form`	Returns the user-defined tag of this object.
`setActionHidden( name` `STRING, vINTEGER)`	Hides or shows the default action view identified by name. Values of v can be 0 or 1.
`setActionActive( name` `STRING, vINTEGER` `)`	Enables or disables the action identified by name. Values of v can be 0 or 1.
`setFieldActive( name` `STRING, vINTEGER` `)`	Enables or disables the field identified by name. The name is a string containing the field qualifier, with an optional prefix ("`[table.]column`"). Values of v can be 0 or 1.
`setDefaultUnbuffered( v` `INTEGER` `)`	Sets the default of the `UNBUFFERED` attribute for next dialogs.
`setCellAttributes( attarr` `ARRAY OF RECORD)`	Defines decoration attributes for each cell.

Usage:

This class provides an interface to the interactive instructions INPUT, INPUT ARRAY, DISPLAY ARRAY, CONSTRUCT, and MENU.

To get an instance of this class, you must use the 'DIALOG' keyword inside the interactive instruction block, as a predefined object variable:

01 INPUT BY NAME custid, custname
02   ON ACTION disable
03     CALL DIALOG.setFieldActive("custid",0)
04 END INPUT

The dialog object is only valid during the execution of the interactive instruction. You get a compilation error when using the DIALOG keyword outside a dialog instruction block. However, you can pass the object to a function to write common dialog configuration code:

01 INPUT BY NAME custid, custname
02   BEFORE INPUT
03     CALL setupDialog(DIALOG)
04 END INPUT
05 
06 FUNCTION setupDialog(d)
07   DEFINE d ui.Dialog
08   IF user_group = "admin" THEN
09      CALL d.setActionActive("delete",1)
10      CALL d.setActionActive("convert",1)
11   ELSE
12      CALL d.setActionActive("delete",0)
13      CALL d.setActionActive("convert",0)
14   END IF
15 END FUNCTION

The getForm() method returns a ui.Form object as a handle of the current form used by the dialog. Use this form object to modify elements of the current form. For example, you can hide some parts of the form with the ui.Form.setElementHidden() method. The runtime system is able to detect hidden fields to exclude them from the input list.

Dialog actions can be enabled/disabled with the setActionActive() method. The action name must be passed in lowercase letters and the value can be any boolean expression that evaluates to 0 or 1. If needed, default action views can be hidden/shown with the setActionHidden() method.

Form fields used by the dialog can be enabled/disabled with the setFieldActive() method. The fields are identified by the field name used in the dialog, with an optional table prefix ("column", "table.column" or "formonly.field"). When a field is disabled, it is still visible, but the user cannot edit the value.

By default dialogs are not sensitive to variable changes. To make a dialog sensitive, you must use the UNBUFFERED attribute in the dialog instruction definition. However, you can define the default for all next dialogs by using the setDefaultUnbuffered() class method:

01 CALL ui.Dialog.setDefaultUnbuffered(TRUE)

Examples

Example 1: Disabling fields dynamically.

01 MAIN
02    DEFINE custid INTEGER
03    DEFINE custname CHAR(10)
04    INPUT BY NAME custid, custname
05      ON ACTION enable
06        CALL DIALOG.setFieldActive("custid",1)
07      ON ACTION disable
08        CALL DIALOG.setFieldActive("custid",0)
09    END INPUT
10 END MAIN

Example 2: Get the form and hide fields.

01 MAIN
02    DEFINE f ui.Form
03    DEFINE custid INTEGER
04    DEFINE custname CHAR(10)
05    INPUT BY NAME custid, custname
06      BEFORE INPUT
08        LET f = DIALOG.getForm()
09        CALL f.setElementHidden("customer.custid",1)
10    END INPUT
11 END MAIN