int DialogBox(hInstance,lpTemplateName,hWndParent,lpDialogFunc)
This function creates a modal dialog box that has the size, style, and controls specified by the dialog-box template given by the lpTemplateName parameter. The hWndParent parameter identifies the application window that owns the dialog box. The callback function pointed to by the lpDialogFunc parameter processes any messages received by the dialog box.
The DialogBox function does not return control until the callback function terminates the modal dialog box by calling the EndDialog function.
| Parameter | Type/Description | |
| hInstance | HANDLE Identifies an instance of the module whose executable file contains the dialog-box template. | |
| lpTemplateName | LPSTR Points to a character string that names the dialog-box template. The string must be a null-terminated character string. | |
| hWndParent | HWND Identifies the window that owns the dialog box. | |
| lpDialogFunc | FARPROC Is the procedure-instance address of the dialog function. See the following “Comments” section for details. |
The return value specifies the value of the nResult parameter in the EndDialog function that is used to terminate the dialog box. Values returned by the application's dialog box are processed by Windows and are not returned to the application. The return value is –1 if the function could not create the dialog box.
The DialogBox function calls the GetDC function in order to obtain a display-context. Problems will result if all the display contexts in the Windows display-context cache have been retrieved by GetDC and DialogBox attempts to access another display context.
A dialog box can contain up to 255 controls.
The callback function must use the Pascal calling convention and must be declared FAR.
int FAR PASCAL DialogFunc(hDlg, wMsg, wParam, lParam)
HWND hDlg;
WORD wMsg;
WORD wParam;
DWORD lParam;
DialogFunc is a placeholder for the application-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the application's module-definition file.
| Parameter | Description | |
| hDlg | Identifies the dialog box that receives the message. | |
| wMsg | Specifies the message number. | |
| wParam | Specifies 16 bits of additional message-dependent information. | |
| lParam | Specifies 32 bits of additional message-dependent information. |
Return Value
The callback function should return nonzero if the function processes the message and zero if it does not.
Comments
Although the callback function is similar to a window function, it must not call the DefWindowProc function to process unwanted messages. Unwanted messages are processed internally by the dialog-class window function.
The callback-function address, passed as the lpDialogFunc parameter, must be created by using the MakeProcInstance function.