Programmer Guide/Macro Library/DOMODALDIALOG



This function implements a package of commands to work with modal dialogs. The standard program flow for a modal dialog is:

[Macro DoModalDialogExample]

//  create the dialog item
#dlg := createmenu dialog * $#mac
if '$#dlg[?]' != 'menu' em -1 ; Failed to create the dialog $#mac
//  create a dialog map to map control ids to strings
#map := CDlgMap $#dlg
if '$#map[?]' != 'instance' em -1 ; Failed to create the dialog map

//  initialize dialog controls
$#dlg $($#map ci ok) BUTTON 0 0 '&OK' * 8
$#dlg $($#map ci cancel) BUTTON 1 0 '&Cancel' * 8

//  show the dialog
domodaldialog begin $#dlg

//  dialog loop
do forever
    //  write data from variables to the controls
    $#dlg * /W

    //  get dialog message
    readstr '$(domodaldialog loop $#dlg $($#map ci ok) $($#map ci cancel))' #id #par

    //  update variables with values from the controls
    $#dlg * /R

    //  process message
    if '$#id' == COMMAND then
        #ctl := set $($#map cn $#par) // get control string (as assigned on control creation)
        if '$#ctl' == 'ok' then
            //  OK - add code here to save changes & end loop
            break
        else if '$#ctl' == 'cancel' then
            //  Cancel - end loop
            break
        else
            //  process other messages
        end
    end
end
//  close dialog window and delete dialog item
domodaldialog end

// clean up
delete $#dlg $#map

exit 1 int 0

For simple dialogs the commands DOMODALDIALOG FOREVER (instead of the message loop) or DOMODALDIALOG BOX (instead of BEGIN, message loop and END) can be used. Instead of this function package also the dialog class MODALDIALOG can be used to implement modal dialogs.

Note that if you want a simple dialog which just displays a message, you can try BUTIL MSGBOX or UM.

Note also, that the class CDlgMap is a nice alternative to DOMODALDIALOG, since it has the same features, but uses control names rather than control indices.



BEGIN

Display a modal dialog. The dialog item dlg must be created and configured. For all other modal dialog functions which takes a dialog item argument, the same dialog item dlg as for BEGIN must be used.

Usage:

DOMODALDIALOG BEGIN dlg [ clt ] [ ; wndPos ]

Parameters:

dlg

The name of the dialog (menu) item.

ctl

The index of the control to receive the focus.

wndPos

The x and y positions of the window or the keywords left|center|right (x) or top|center|bottom (y) and the monitor in the following format:

x y ; monitor

If no monitor is specified, the first monitor is used.

Result:

void



BOX

This is an alternative message loop function for modal dialogs. The BOX function implements the whole dialog processing. First the dialog is displayed (BEGIN), the dialog loop is entered (FOREVER) and the dialog is removed (END). The programmer is only responible to create the dialog. The dialog can not use popup/context-menus and hotkeys.

Usage:

DOMODALDIALOG BOX dlg oclt cclt

Parameters:

dlg

The name of a dialog item.

oclt

The index of the OK control.

cclt

The index of the Cancel control.

Result:

The control index of the first command message.



END

Closes the last opened modal dialog window and deletes the dialog item.

Usage:

DOMODALDIALOG END

Result:

void



FOREVER

This is an alternative message loop function for modal dialogs. The command FOREVER stays in the message loop (using LOOP) until the first COMMAND message is received. The programmer is responsible to create the dialog and to call the BEGIN and END function. All message processing is performed by the FOREVER function. The dialog can not use popup/context-menus and hotkeys.

Usage:

DOMODALDIALOG FOREVER dlg oclt cclt

Parameters:

dlg

The name of a dialog item.

oclt

The index of the OK control.

cclt

The index of the Cancel control.

Result:

The control index of the first command message.



LOOP

The LOOP function implements the modal message loop. All non-dialog messages and messages not processed by previously installed message handlers are queued for later processing. The messages from the dialog are returned. Some messages are translated before they are returned.

The following dialog messages are directly returned to the caller:

• commands and updates ("COMMAND|UPDATE ctrlidx"),
• popup menu selections ("POPUP itemindex"),
• context menu selections ("CMSTAT ctrlidx") and
• key strokes ("KEY keycode keyname")

Translations are performed for the close/cancel-message ("COMMAND cclt") and the okay-message ("COMMAND oclt"). Because most macros bind local or instance variables to dialog controls, the data exchange must be performed in the calling macro.

Usage:

DOMODALDIALOG LOOP dlg oclt cclt

Parameters:

dlg

The name of dialog (menu) item.

oclt

The index of the OKAY control. This is used for translating close messages into a COMMAND oclt message.

cclt

The index of the CANCEL control. This is used for translating cancel messages into a COMMAND cclt message.

Result:

The id and parameters of dialog messages:

id par

Array