9.2.1 Creating a Dialog Box Procedure

A dialog box procedure has the following form:

BOOL FAR PASCAL DlgProc(hDlg, message, wParam, lParam)
HWND hDlg;
UINT message;
WPARAM wParam;
LPARAM lParam;
{
    switch (message) {

        /* Place message cases here. */

        default:
            return FALSE;
    }
}

This is basically a window procedure, except that the DefWindowProc function is not called. The dialog box procedure should not call DefWindowProc, because default processing of dialog box messages is handled internally when the dialog box procedure returns FALSE. If the procedure returns TRUE, no further processing takes place. (The WM_INITDIALOG message is an exception to this rule about how TRUE and FALSE affect the processing in a dialog box procedure.)

The dialog box procedure must be defined as a FAR PASCAL function and must have the specified parameters. BOOL is the required type for the return value.

Just as it does with window procedures, Windows sends messages to a dialog box procedure when it has information to give the procedure or requires the procedure to carry out some action. Unlike a window procedure, a dialog box procedure responds to a message by returning a Boolean value. If the procedure processes the message, it returns TRUE. Otherwise, it returns FALSE.

In this dialog box procedure, the hDlg variable receives the handle of the dialog box. The other parameters serve the same purpose as in a window procedure. The switch statement is used as a filter for different messages. Most dialog box procedures process the WM_INITDIALOG and WM_COMMAND messages, but little else.

The dialog box procedure can, if necessary, give the input focus to any control in the dialog box by processing the WM_INITDIALOG message. After setting the focus to the desired control, the procedure should return FALSE; otherwise, Windows sets the input focus to the control of its choosing.

The WM_COMMAND message is sent to the dialog box procedure by the controls in the dialog box. If there are controls in the dialog box, they send notification messages when the user carries out some action within them. For example, a dialog box procedure with a push button can check WM_COMMAND messages for the control identifier of the push button. When it finds this identifier (which is in the message's wParam parameter), the procedure can carry out the corresponding task.

If you specify the WS_SYSMENU style when creating the dialog box, you should include a WM_COMMAND switch statement for the IDCANCEL control identifier, which is sent when the user chooses the Close command in the dialog box's System menu. The statement should include a call to the EndDialog function.