Using Dialogs

Using dialogs in  Emergence BASIC is similar to defining and opening a window. Many of the same window statements and functions apply to dialogs as well. Dialogs are first defined using the CREATEDIALOG statement and then shown elsewhere in your program with the DOMODAL or SHOWDIALOG commands. The syntax of the CREATEDIALOG statement is:

CREATEDIALOG variable, Left, Top, Width, Height, flags, parent, title, procedure

The variable must have been previously defined as type DIALOG with the DEF statement. Procedure refers to the address of the subroutine that will handle messages from this dialog, use the & operator to specify the address. Flags should contain @CAPTION for a title and @SYSMENU for the standard system menu and close button. If @CAPTION is omitted the dialog will not have a title bar and will be fixed in place.

It is important to note the difference between a dialog and a window. A window is created and shown with one statement, OPENWINDOW. A dialog is defined by the CREATEDIALOG statement but not shown until you use DOMODAL or SHOWDIALOG. This means a dialog is reusable and can be shown many times without having to recreate it each time.

The parent parameter specifies the owner window/dialog for this dialog. If used the CREATEDIALOG statement must appear after the parent is opened. To alleviate this restriction specify the parent window/dialog in the DOMODAL or SHOWDIALOG statements.

The Dialog Editor/GUI Designer provides an easy interface for designing dialogs and placing controls.

Showing the dialog

Add controls to the dialog after it is defined and show the dialog with the DOMODAL or SHOWDIALOG functions.

DOMODAL shows the dialog as modal. This means that all other windows in your program will be blocked until the dialog is closed. The DOMODAL function has the syntax of:

return = DOMODAL( variable [,parent] )

The variable must be of type DIALOG and defined with the CREATEDIALOG statement. DOMODAL will return the value given to the CLOSEDIALOG statement or @IDCANCEL if the user presses the <Esc> key to dismiss the dialog.  All input will be captured by the dialog while it is displayed. Note that any controls in the dialog cannot be initialized until the dialog is displayed. All control initialization should be done in the dialog handler subroutine in response to the @IDINITDIALOG message.

The optional parent parameter overrides the parent window/dialog specified in the CREATEDIALOG statement. It is preferable to specify the parent window/dialog when it is shown.

To show a non modal dialog use the SHOWDIALOG statement.  The syntax of SHOWDIALOG is:

SHOWDIALOG variable [,parent]

Once the dialog is displayed, your program continues to execute normally. A dialog shown with SHOWDIALOG requires a message loop to properly process and send message to the handler subroutine. In this respect a dialog shown with SHOWDIALOG operates in the same manner a normal window does with the benefits of a dialog.

The optional parent parameter overrides the parent window/dialog specified in the CREATEDIALOG statement. It is preferable to specify the parent window/dialog when it is shown.

Closing the dialog:

CLOSEDIALOG variable, return_value

The return_value can be any integer value, it is ignored for non modal dialogs shown with the SHOWDIALOG statement. You can use the predefined values of @IDOK and @IDCANCEL if  applicable.

When your dialog is about to be displayed, the handler for the dialog will receive the message @IDINITDIALOG. This is a good place to perform any initializations such as centering the dialog with the CENTERWINDOW statement and presetting any controls.

You should copy any control data before the dialog is closed. After a dialog is closed all of the controls are invalid and accessing them will fail.

Example:

DEF d1:DIALOG
DEF w:WINDOW
DEF result:INT
DEF answer:STRING
'Open our window and define a dialog
OPENWINDOW w,0,0,640,200,@SIZE,0,"Dialog Test",&wndproc
CREATEDIALOG d1,0,0,100,100,@CAPTION|@SYSMENU,w,"My Dialog",&dialoghandler
CONTROL d1,@BUTTON,"OK",25,75,50,20,@TABSTOP,1
CONTROL d1,@EDIT,"",15,45,70,14,@TABSTOP,10
'Show the dialog
result = DOMODAL d1
'Print the result
MOVE w,4,20
IF result = @IDOK
        PRINT w, answer
ELSE
        PRINT w, "DIALOG canceled"
ENDIF
'Just wait for the window to be closed
run=1
WAITUNTIL run = 0
CLOSEWINDOW w
END
 
'Our window subroutine
SUB wndproc
SELECT @MESSAGE
   CASE @IDCLOSEWINDOW
      run = 0
ENDSELECT
RETURN
ENDSUB
 
'Our dialog subroutine
SUB dialoghandler
SELECT @MESSAGE
    CASE @IDCONTROL
        SELECT @CONTROLID
            CASE 1
                answer = GETCONTROLTEXT(d1, 10)
                CLOSEDIALOG d1,@IDOK
        ENDSELECT
   'All controls should be initialized while processing the @IDINITDIALOG message
    CASE @IDINITDIALOG
        CENTERWINDOW d1
        SETCONTROLTEXT d1,10,"Yipee!"
ENDSELECT
RETURN
ENDSUB

The dialog can be created without a parent window in which case your program would be a dialog application.