Developer Guide and Reference

ID 767251
Date 10/31/2024
Public
Document Table of Contents

DLGMODAL, DLGMODALWITHPARENT

Dialog Functions: Display a dialog box and process user control selections made within the box. This routine is only available for Windows.

Module

USE IFLOGM

result = DLGMODAL (dlg)

result = DLGMODAL (dlg, hwndParent)

dlg

(Input) Derived type dialog. Contains dialog box parameters. The components of the type dialog are defined with the PRIVATE attribute, and cannot be changed or individually accessed by the user.

hwndParent

(Input) Integer. Specifies the parent window for the dialog box. If omitted, the value is determined in this order:

  1. If DLGMODAL is called from the callback of a modal or modeless dialog box, then that dialog box is the parent window.

  2. If it is a QuickWin or Standard Graphics application, then the frame window is the parent window.

  3. The Windows* desktop window is the parent window.

Results

The result type is INTEGER(4). By default, if successful, it returns the identifier of the control that caused the dialog to exit; otherwise, it returns -1. The return value can be changed with the DLGSETRETURN subroutine.

During execution, DLGMODAL displays a dialog box and then waits for user control selections. When a control selection is made, the callback routine, if any, of the selected control (set with DLGSETSUB) is called.

The dialog remains active until an exit control is executed: either the default exit associated with the OK and Cancel buttons, or DLGEXIT within your own control callbacks. DLGMODAL does not return a value until the dialog box is exited.

The default return value for DLGMODAL is the identifier of the control that caused it to exit (for example, IDOK for the OK button and IDCANCEL for the Cancel button). You can specify your own return value with DLGSETRETURN from within one of your dialog control callback routines. You should not specify -1 as your return value, because this is the error value DLGMODAL returns if it cannot open the dialog.

Use DLGMODALWITHPARENT when you want the parent window to be other than the default value (see argument hwndParent above). In particular, in an SDI or MDI Windows application, you may want the parent window to be the main application window. The parent window is disabled for user input while the modal dialog box is displayed.

Example

USE IFLOGM
INCLUDE "MYDLG.FD"
INTEGER return
TYPE (DIALOG) mydialog
...
return = DLGMODAL (mydialog)
...