WinDlgBox

This function loads and processes a modal dialog window and returns the result value established by the WinDismissDlg call.

Syntax

WinDlgBox(hwndParent, hwndOwner,pfnDlgProc, hmod, idDlg, pCreateParams);

Parameters

hwndParent (HWND) - input

Parent-window handle of the created dialog window.

HWND\_DESKTOP: The desktop window.

HWND\_OBJECT: Object window.

Other: Specified window.

hwndOwner (HWND) - input

Requested owner-window handle of the created dialog window.

The actual owner window is calculated using the algorithm specified in the description of the WinLoadDlg function.

pfnDlgProc (PFNWP) - input

Dialog procedure for the created dialog window.

hmod (HMODULE) - input

Resource identity containing the dialog template.

NULLHANDLE: Use the application's .EXE file.

Other: Module handle returned from the DosLoadModule or DosQueryModuleHandle call.

idDlg (ULONG) - input

Dialog-template identity within the resource file.

It is also used as the identity of the created dialog window. It must be greater than or equal to 0 and less than or equal to 0xFFFF.

pCreateParams (PVOID) - input

Pointer to application-defined data area.

This is passed to the dialog procedure in the WM_INITDLG message.

This parameter MUST be a pointer rather than a long.

Returns

ulResult (ULONG) - returns

Reply value.

Value established by the WinDismissDlg call or DID\_ERROR if an error occurs.

Errors

Possible returns from WinGetLastError

PMERR_INVALID_HWND (0x1001)

An invalid window handle was specified.

PMERR_INVALID_INTEGER_ATOM (0x1016)

The specified atom is not a valid integer atom.

PMERR_INVALID_ATOM_NAME (0x1015)

An invalid atom name string was passed.

PMERR_ATOM_NAME_NOT_FOUND (0x1017)

The specified atom name is not in the atom table.

PMERR_RESOURCE_NOT_FOUND (0x100A)

The specified resource identity could not be found.

Remarks

The use of parameters for this function is the same as those of the WinLoadDlg function.

This function should not be used while pointing device capture is set (see WinSetCapture).

This function does not return until WinDismissDlg is called.

This function is equivalent to:

 WinLoadDlg (., ., ., ., ., ., dlg);
 WinProcessDlg (dlg, result);
 WinDestroyWindow (dlg, success);
 return  (result);

and the remarks documented under these calls also apply.

If a dialog template (typically compiled using the resource compiler) references another resource (for example an icon resource for an icon static control), this function always searches for that resource in the .EXE file. If an application wishes to keep resources referenced by a dialog template in a .DLL library, these resources must be loaded by an explicit function call during the processing of the WM_INITDLG message.

This can be considered to be a customizable "read from screen" call. The caller supplies a data buffer (the pCreateParams parameter), filled with initial values. It receives a return code which indicates whether the data in the buffer has been updated and validated, or whether the end user cancelled the dialog. The end user interface is encapsulated within the dialog window. The dialog template provides a view of the current state of the data buffer, the dialog procedure defines how the user can change the data. The caller need know nothing about the details of the end user interface. It makes a single "read from screen" call and continues with its work.

Note

If a dialog box or a message box is up for a window, and the parent or owner of that window is destroyed, the code following the WinDlgBox or WinMessageBox call is executed even though the parent/owner window no longer exists. This can result in accessing data that no longer exists; especially data referenced in the window words. Therefore, it is extremely important to determine the state of your child-window procedure after this function returns. The most straightforward method for doing this is to call WinQueryWindowPtr to get a pointer to the window words. If the returned pointer is NULL, then you should exit immediately. Should this be the case, the bottom-up rule (that is, the child window gets WM_DESTROY messages first, then the parent window) still applies, and it becomes the child window procedure's responsibility to exit gracefully.

Example Code

Declaration:

#define INCL_WINDIALOGS /* Or use INCL_WIN, INCL_PM, Also in COMMON section */
#include <os2.h>

HWND     hwndParent;    /* Parent-window handle of the created dialog window. */
HWND     hwndOwner;     /* Requested owner-window handle of the created
                           dialog window. */
PFNWP    pfnDlgProc;    /* Dialog procedure for the created dialog window. */
HMODULE  hmod;          /* Resource identity containing the dialog template. */
ULONG    idDlg;         /* Dialog-template identity within the resource file. */
PVOID    pCreateParams; /* Pointer to application-defined data area. */
ULONG    ulResult;      /* Reply value. */

ulResult = WinDlgBox(hwndParent, hwndOwner,
                     pfnDlgProc, hmod, idDlg, pCreateParams);

This example processes an application-defined message (IDM_OPEN) and calls WinDlgBox to load a dialog box.

#define IDD_OPEN 1
#define INCL_WINDIALOGS         /* Window Dialog Mgr Functions  */
#include <os2.h>

HWND   hwndFrame;       /* frame window handle                  */
PFNWP  OpenDlg;

case IDM_OPEN:
    if (WinDlgBox(HWND_DESKTOP,
            hwndFrame,    /* handle of the owner         */
            OpenDlg,      /* dialog procedure address    */
            NULLHANDLE,   /* location of dialog resource */
            IDD_OPEN,     /* resource identifier         */
            NULL)) {      /* application-specific data   */
       .
       . /* code executed if dialog box returns TRUE */
       .
    }

Related Functions

• WinCreateDlg
• WinDefDlgProc
• WinDismissDlg
• WinGetDlgMsg
• WinLoadDlg
• WinProcessDlg

Related Messages

• WM_INITDLG