2.4.3 Creating a Dialog Box Procedure

A dialog box is a special kind of window whose window procedure is built into Windows. For every dialog box an application has, the application must have a corresponding dialog box procedure. The Windows built-in window procedure calls a dialog box procedure to handle input messages that can be interpreted only by the application.

The procedure that processes input for Generic's About dialog box is called About. This procedure, like other dialog box procedures, uses the same parameters as a window procedure but processes only messages that are not handled by Windows default processing. (The dialog box procedure returns TRUE if it processes a message and FALSE if it does not.) The dialog box procedure, like the window procedure, requires the PASCAL calling convention and the FAR keyword in its definition. You must name the dialog box procedure in an EXPORTS statement in the application's module-definition file. As with a window procedure, a dialog box procedure must not be called directly from your application.

Unlike a window procedure, a dialog box procedure usually processes only user-input messages, such as WM_COMMAND, and must not send unprocessed messages to the DefWindowProc function. Generic's dialog box procedure, About, looks like this:

BOOL FAR PASCAL About(hDlg, message, wParam, lParam)
HWND hDlg;        /* handle of dialog box window               */
WORD message;     /* type of message                           */
WPARAM wParam;    /* message-specific information              */
LPARAM lParam;



{
    switch (message) {
        case WM_INITDIALOG: /* message: initialize dialog box  */
            return TRUE;

        case WM_COMMAND:                 /* received a command */
            if (wParam == IDOK           /* OK box selected?   */
                || wParam == IDCANCEL) { /* Close command?     */
                EndDialog(hDlg, TRUE);   /* exits dialog box   */
                return TRUE;
            }
            break;
    }
    return FALSE;                 /* did not process a message */
}

The About dialog box procedure processes two messages: WM_INITDIALOG and WM_COMMAND. Windows sends the WM_INITDIALOG message to a dialog box procedure to let the procedure initialize its controls before displaying the dialog box. In this case, WM_INITDIALOG returns TRUE so that the focus is passed to the first control in the dialog box that has the WS_TABSTOP bit set (this control will be the default push button). If WM_INITDIALOG had returned FALSE, Windows would not have set the focus to any control.

In contrast to WM_INITDIALOG messages, WM_COMMAND messages are a result of user input. The About procedure responds to input to the OK button or the System menu Close command by calling the EndDialog function, which directs Windows to remove the dialog box and continue running the application. The EndDialog function is used to terminate dialog boxes.