WinLoadDlg
This function creates a dialog window from the dialog template idDlg in hmod and returns the dialog window handle.
Syntax
WinLoadDlg(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 below.
- 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 functions.
- idDlg (ULONG) - input
- Dialog-template identity within the resource file.
- It is also used as the identity of the created dialog window.
- 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
- hwndDlg (HWND) - returns
- Dialog-window handle.
- NULL: Dialog window not created.
- Other: Dialog window handle.
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
Unless window style WS_VISIBLE is specified for the dialog window in the DIALOG statement within the dialog template, the dialog window is created as an invisible window.
The dialog window owner may be modified, in order to ensure acceptable results if it is later processed as a modal dialog using the WinProcessDlg or WinGetDlgMsg functions. A search is made up the parent hierarchy, starting at the window specified by the hwndOwner parameter, until a child of the window specified by the hwndParent is found. If such a window exists, it is made the actual owner of the dialog. If no such window exists the actual owner of the dialog is set to NULLHANDLE.
This function returns immediately after creating the dialog window. A WM_INITDLG (Default Dialogs) message is sent to the dialog procedure before this function returns.
This function should not be used while pointing device capture is set (see WinSetCapture).
As each of the controls defined within the template of this dialog window is created during the processing of this function, the dialog procedure may receive various control notifications before this function returns.
A dialog window can be destroyed with the WinDestroyWindow function.
Because windows are created from the template, strings in the template are processed with WinSubstituteStrings. Any resultant WM_SUBSTITUTESTRING messages are sent to the dialog procedure before this function returns.
When the child windows of the dialog are created, the WinSubstituteStrings function is used to allow the child windows to perform text substitutions in their window text. If any of the child window text strings contain the percent (%) substitution character, there is an upper limit of 256 on the length of the text string, after it is returned from the substitution.
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.
- Note
- In general, it is better to create the dialog window invisible as this allows for optimization. In particular, an experienced user can type ahead, anticipating the processing in the dialog window.
In this instance, there may be no need to display the dialog window at all, as the user might have finished the interaction before the window can be displayed.
This is in fact how the WinProcessDlg function works; it does not display the dialog window while there are still WM_CHAR messages in the input queue, but allows these to be processed first.
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. */ HWND hwndDlg; /* Dialog-window handle. */ hwndDlg = WinLoadDlg(hwndParent, hwndOwner, pfnDlgProc, hmod, idDlg, pCreateParams);
This example uses WinLoadDlg to load a dialog template from the application's .EXE file.
#define INCL_WINDIALOGS /* Window Dialog Mgr Functions */ #include <os2.h> HWND hwndOwner; /* owner window */ HWND hwndDlg; /* Dialog-window handle */ PFNWP GenericDlgProc; /* dialog process */ hwndDlg = WinLoadDlg(HWND_DESKTOP, /* parent is desk top */ hwndOwner, /* owner is main frame */ GenericDlgProc, /* dialog procedure */ 0L, /* load from resource file */ DLG_ID, /* dialog resource id */ NULL); /* no dialog parameters */