Version 6.3.8 for Windows
 —  Programming Guide  —

How To Open and Close Dialogs

This document covers the following topics:


Opening a Dialog

An event-driven application is started by executing the base dialog. Events triggered by the end user will then typically cause other dialogs to be started. The application ends when the base dialog is closed.

Start of instruction setTo open a dialog from anywhere within an event-driven application

This statement causes the dialog to be loaded and the processing on its opening to be performed.

Control over processing returns from the opened dialog except for dialogs with the style "Dialog Box". For those dialog styles, control returns only after the dialog has ended.

The parameters passed are accessible only during the processing on the opening of a dialog (before-open and after-open events), except for when the parameters are declared as BY VALUE in the parameter data area of the opened dialog or when the dialog has the style "Dialog Box".

To open a dialog from anywhere within an event-driven Natural application, the following syntax is used:

OPEN DIALOG operand1   [USING]   [PARENT] operand2    
  [ [GIVING]   [DIALOG-ID] operand3 ]  
 

WITH

operand4...

  PARAMETERS-clause

Top of page

Operands

Operand1 is the name of the dialog to be opened. If the PARAMETERS-clause is used, operand1 must be a constant (the name of a cataloged dialog).

Operand2 is the handle name of the parent.

Operand3 is a unique dialog ID returned from the creation of the dialog. It must be defined with format/length I4.

Top of page

Passing Parameters to the Dialog

When a dialog is opened, parameters may be passed to this dialog.

As operand4 you specify the parameters that are passed to the dialog.

With the PARAMETERS-clause, parameters may be passed selectively:

PARAMETERS [parameter-name=operand 4] _ END-PARAMETERS

Note:
You may only use the PARAMETERS-clause if operand1 is an alphanumeric constant and if the dialog is cataloged.

Parameter-name is the name of the parameter as defined in the parameter data area section of the dialog.

To avoid format/length conflicts between operands and parameters passed, see the BY VALUE option of the DEFINE DATA statement in the Statements documentation.

When passing parameters only with operand4, a dialog may be opened as follows:

/* The following parameters are defined in the calling dialog's parameter 
/* data area (not in the parameter data area of the dialog to be opened):
 1 #MYDIALOG-ID (I4)
 1 #MYPARM1 (A10) 
/* Pass the operands #MYPARM1 and 'MYPARM2' to the parameters #DLG-PARM1 and 
/* #DLG-PARM2 defined in the dialog to be opened:
  OPEN DIALOG 'MYDIALOG' USING
  #DLG$WINDOW GIVING 
  #MYDIALOG-ID WITH 
  #MYPARM1 'MYPARM2'

When passing parameters selectively with the PARAMETERS-clause, a dialog may be opened as shown in the following example:

/* The following parameters are defined in the calling dialog's parameter 
/* data area (not in the parameter data area of the dialog to be opened): 
 1 #MYDIALOG-ID (I4) 
 1 #MYPARM1 (A10) 
/* Pass the operands #MYPARM1 and 'MYPARM2' to the parameters #DLG-PARM1 and 
/* #DLG-PARM2 defined in the dialog to be opened: 
  OPEN DIALOG 'MYDIALOG' USING 
  #DLG$WINDOW GIVING 
  #MYDIALOG-ID WITH PARAMETERS 
  #DLG-PARM1=#MYPARM1 
  #DLG-PARM2='MYPARM2' 
END-PARAMETERS

Top of page

Permanence in Creating, Passing and Checking Data

The term "permanence" is used in Natural to denote data defined in a base dialog's local data area whose existence is guaranteed throughout the whole lifetime of the dialog. Data defined in the global data area are not kept permanent because the global data area can be exchanged while the application is executed.

The reference to the permanent data is kept by saving the parameter data area internally during opening of the dialog. This reference is reused when

Parameters are accessible

The following example illustrates a case in which two parameters are kept permanently and one other is not. Assume the base dialog is dialog A. This base dialog now opens dialog B, passing parameters #X and #Y. After that, dialog B passes parameters #X and #Y on to dialog C. The #X and #Y parameters which are now in dialog C will be permanent, even if dialog B is closed. If, however, dialog B passes its own parameter #Z when opening dialog C, the parameter #Z is not permanent, because if dialog B is closed, the reference to its local data area is no longer valid. No parameter in dialog C is accessible (#Z does not reference the base dialog's local data area).

Open and close dialogs

Top of page

Processing Steps When Opening a Dialog

This section describes what happens when a dialog is opening. You can open a dialog either by executing it, for example from the command line, or by invoking it with an OPEN DIALOG statement.

Top of page

Closing Dialogs

To close a dialog dynamically, you specify the following:

CLOSE DIALOG [USING] [DIALOG-ID]

operand1

*DIALOG-ID

Operand1 is the identifier of the dialog as returned in the OPEN DIALOG statement.

Example:

CLOSE DIALOG *DIALOG-ID /* Close the current Dialog

The dialog will then be erased from the screen and removed from memory. All local data associated with the dialog will be gone.

Note:
If a modal dialog is a child in a hierarchy of dialogs, the modal dialog should not close its parent(s) because this will result in a deadlock.

operand1

Operand1 is the name of the dialog to be closed.

To close the current dialog, you specify *DIALOG-ID.

Top of page

Initializing Attribute Values

You can specify conditions for the opening and closing of a dialog: this applies to the before-open, after-open, and close events. These conditions can be used to initialize the attribute values in the dialog.

The following is an example of after-open event-handler code: Red foreground color is assigned to push buttons that the user must press after entering data in the associated input fields.

DEFINE DATA LOCAL
... 
  1  #OK-BUTTON HANDLE OF PUSHBUTTON 
  1 #CALC-BUTTON HANDLE OF PUSHBUTTON
  1 #SAVE-BUTTON HANDLE OF PUSHBUTTON 
  1 #CONVERT-BUTTON 
HANDLE OF PUSHBUTTON
... 
END-DEFINE
... 
#OK-BUTTON.FOREGROUND-COLOUR-NAME := RED 
#CALC-BUTTON.FOREGROUND-COLOUR-NAME := RED 
#SAVE-BUTTON.FOREGROUND-COLOUR-NAME := RED 
#CONVERT-BUTTON.FOREGROUND-COLOUR-NAME := RED

If you want to modify attribute values of dialog elements and of the dialog before the dialog is opened (and displayed to the end user), do not specify this in the "before open" event-handler code, because the dialog elements and the dialog window are not yet created. Instead, create the dialog with the dialog editor and set the attribute VISIBLE to FALSE in the Dialog Attributes window. Then modify all the attribute values in the after-open event-handler code (when the handles are available). Then make the dialog visible with VISIBLE = TRUE.

Example:

DEFINE DATA LOCAL 
... 
 1 #DIA-1 HANDLE OF DIALOG 
 1 #OK-BUTTON HANDLE OF PUSHBUTTON 
 1 #CALC-BUTTON HANDLE OF PUSHBUTTON
... 
END-DEFINE 
... 
/* AFTER OPEN event-handler code section 
... 
#OK-BUTTON.FOREGROUND-COLOUR-NAME := RED 
#CALC-BUTTON.FOREGROUND-COLOUR-NAME := RED 
#DIA-1.VISIBLE := TRUE

Top of page