Dialog_Box function
Description
Executes a specified OpenInsight window (form), as a modal dialog box.
In general terms, a dialog box is a window designed to collect information from the user, or to display a message that the user must acknowledge (commonly known as an "alert" window). In the majority of cases a dialog box is launched in modal format, which means it exhibits the following behavior:
*It must have an owner window
*The owner window is disabled for the lifetime of the dialog box
*The dialog box can return information direct to the calling process
Syntax
RetVal = Dialog_Box( DialogID, OwnerID, CreateParam, Options, AsyncParams )
Parameters
| Name | Required | Description |
|---|---|---|
| DialogID | Yes | Name of the window to execute. Must be in upper-case. |
| OwnerID | Yes | Name of the owner window. Must be in upper-case. This window is will disabled until the dialog box is destroyed. Note that is may be the ID of a docked window, or a child window like an MDI child. In this case the parent top-level frame will be disabled. |
| CreateParam | No | Data to pass to the window's CREATE event. This data is passed as the "CreateParam" argument when the CREATE event is triggered. It must not contain an @Rm system delimiter characters. |
| Options | No | A dynamic array of extra options for launching the window <3>If TRUE$ then disable ALL other windows owned by the OwnerID window, not just the OwnerID window itself. <4>GETPARENTFRAME override. The Dialog_Box stored procedure uses the WINDOW object GETPARENTFRAME method internally. This option allows it to be tweaked as desired. |
| AsyncParams | No | A dynamic array of options that control Asynchronous mode. When executed in this mode the returned data is not passed directly back to the calling stored procedure – rather it is passed back via the OwnerID's ENDDIALOG event. <1>If TRUE$ then the dialog will be executed in Asynchronous mode. <2>Contains a string argument passed back to the OwnerID's ENDDIALOG event. Useful for identifying the returned data. |
Returns
If the dialog box is executed in synchronous mode the return value is the data passed back from the End_Dialog call.
If the dialog is executed in asynchronous mode the return value will be the instance ID of the created dialog box. In this case the data passed back from the End_Dialog call will passed as an argument to the owner window's ENDDIALOG event.
If an error occurs the return value will be null.
Errors
Error information may be obtained via the Get_Status function.
Remarks
In previous version of OpenInsight all modal dialogs were executed in Synchronous mode, which made programming them very easy but imposed some constraints on the system if multiple nested Dialog_Box calls are made - a scenario that is quite possible in a modern multi-monitor, multi-window system. When this happens, the system must “stack” these calls in the order that they are made, which may not always match the order in which the user dismisses them, and this can lead to some confusion with the user interface.
To alleviate this OpenInsight 10 has introduced Asynchronous mode, which means that calling programs never wait for a direct answer from the dialog box so there is no need to form a stack of waiting programs. Instead any returned data is passed to the caller’s ENDDIALOG event when triggered by an End_Dialog call. The downside of this mode is that it is more difficult to program as the flow of the code must be broken up into a calling and receiving phase, rather than running in a linear sequence. Despite this drawback Asynchronous mode is the preferred method and will result in a better runtime performance when implemented
Example
For the purposes of this example we assume that we are going to launch a simple form called “MY_DIALOG_BOX” using the Dialog_Box function. The form contains a single EDITLINE control called “EDL_NAME”, and a button called “BTN_OK”. When BTN_OK is clicked it will get the text from EDL_NAME and return it to the owner with an End_Dialog call like so:
//// CLICK event script for MY_DIALOG_BOX.BTN_OK// //// Get the data the user entered// Name = Get_Property( @Window : ".EDL_NAME", "TEXT" ) //// Return it to the owner window// Call End_Dialog( @Window, Name )
Synchronous Mode Example
To launch MY_DIALOG_BOX in synchronous fashion, do the following from an event on the owner window:
//// Launches MY_DIALOG_BOX as a modal Dialog_Box in synchronous fashion passing//
//// it the contents of a variable called CurrName as the CreateParam.//
NewName = Dialog_Box( "MY_DIALOG_BOX", @Window, CurrName )
If BLen( NewName ) Then
//// The user entered a new name so process it//
Call Do_Something_With_This_Name( NewName )
End
In this mode the calling program will halt at he Dialog_Box call and wait for the user to close it, after which the text returned from the End_Dialog call on MY_DIALOG_BOX.BTN_OK will be placed in the NewName variable for subsequent processing.
Asynchronous Mode Example
To launch MY_DIALOG_BOX in asynchronous fashion, do the following from an event on the owner window:
//// Launches MY_DIALOG_BOX as a modal Dialog_Box in asynchronous fashion // //// passing it the contents of a variable called CurrName as the CreateParam.// AsyncParams = "" AsyncParams<1> = TRUE$ ; //// Aysnc mode// AsyncParams<2> = "GetName" ; //// Optional “AsyncID” param for the// // ENDDIALOG event// //// This code does not halt here - anything the user selects in the dialog//\ //// will be passed back in the ENDDIALOG event // DlgID = Dialog_Box( "MY_DIALOG_BOX", @Window, CurrName, "", AsyncParams )
In this mode the calling program will NOT halt at he Dialog_Box call and wait for the user to close it. Instead any data returned from the End_Dialog call on MY_DIALOG_BOX.BTN_OK will be passed as an argument to the calling window’s ENDDIALOG event.
The ENDDIALOG event would look something like this:
Function ENDDIALOG( CtrlEntID, CtrlClassID, DialogID, DialogValue, AsyncID )
//// This is an ENDDIALOG event that will be triggered by the End_Dialog //
//// call on MY_DIALOG_BOX.BTN_OK when launched in asynchronous mode,//
////
//// ENDDIALOG is passed three parameters://
////
//// DialogID //
//// DialogValue//
//// AsyncID//
Begin Case
Case ( DialogID = "MY_DIALOG_BOX" )
//// This is optional but we can check AsyncID if we wanted to have//
//// more fine grain control over how this event is processed.//
If ( AsyncID == "GetName" ) Then
Call Do_Something_With_This_Name( NewName )
End
End Case
Return 0
See Also
Create_Dialog function, End_Dialog subroutine, Start_Window subroutine, ENDDIALOG event, WINDOW CREATE event, WINDOW CLOSE method, WINDOW CLOSE event, WINDOW GETPARENTFRAME property.