Create_Dialog function

Description

Executes a specified OpenInsight window (form), as a modal or modeless 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 when used with Create_Dialog():

*

*It must have an owner window

*The owner window is disabled for the lifetime of the dialog box (Optionally all other windows belonging to the owner window may be disabled).

(Note however that unlike a model dialog box executed via the Dialog_Box() function, a modal dialog box executed with the Create_Dialog() function cannot return a value to its caller.)

When executed in non-modal format it simple behaves as any other window that has an owner.

RetVal = Create_Dialog( DialogID, OwnerID, Mode, CreateParam, Options )

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 if the Mode is FALSE$ (i.e. non-modal) Note that this 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.
Mode	No	Set to TRUE$ to create a non-modal dialog,or FALSE$ (the default) to create a modal one.
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 <1>If TRUE$ then disable ALL other windows owned by the OwnerID window, not just the OwnerID window itself. <2>GETPARENTFRAME override. The Dialog_Box stored procedure uses the WINDOW object GETPARENTFRAME method internally. This option allows it to be tweaked as desired.

The Instance ID of the newly executed dialog box is returned if successful. Null is returned if the dialog box fails to start. The instance ID is usually the same as the passed DialogID, but if the window is flagged as multi-instance then the PS can append a unique number (delimited with an "*" character) to the returned ID to ensure that there are no conflicts with existing windows.

Error information may be obtained via the Get_Status function.

This function can be considered deprecated for launching modal dialog boxes. The Dialog_Box() function should be used instead.

The End_Dialog() subroutine or the WINDOW CLOSE method can be used to close a dialog box executed with Create_Dialog().

 
// Example - launch a non-modal dialog //
   
   CurrVal  = Get_Property( CtrlEntID, "TEXT" )
   DlgOpt   = ""
   
   DialogID = Create_Dialog( "MY_DIALOG_BOX", @Window, TRUE$, CurrVal, DlgOpt )

Dialog_Box function, End_Dialog subroutine, Start_Window function, ENDDIALOG event, WINDOW CREATE event, WINDOW CLOSE method, WINDOW CLOSE event, WINDOW GETPARENTFRAME property.