INFO: Default/Private Dialog Classes, Procedures, DefDlgProc

ID: Q68566

The information in this article applies to:

Microsoft Windows Software Development Kit (SDK)
Microsoft Win32 Software Development Kit (SDK)
Microsoft Windows 2000

SUMMARY

The information below explains the differences between default and private dialog classes, their associated dialog procedures, and using the DefDlgProc() function.

This information is organized as a comparison between private and default dialog classes, covering class registration, dialog templates, dialog creation, and message processing.

Note that the source to the DefDlgProc() function is provided with the Windows Software Development Kit (SDK) version 3.0. The code is supplied on the Sample Source 2 disk in the DEFDLG.C file. By default, DEFDLG.C is placed into the \SAMPLES\DEFPROCS directory if the SDK installation program copies the sample source code.

There are many functions and macros used in DefDlgProc() that are internal to Windows and cannot be used by applications. No additional information is available on these functions and macros.

MORE INFORMATION

All dialog classes are window classes, just as all dialog boxes are windows. All dialog classes must declare at least DLGWINDOWEXTRA in the cbWndExtra field of the WNDCLASS structure before the dialog class is registered. The Windows Dialog Manager uses this area to store special information for dialog boxes.

The default dialog class is registered by Windows at startup. The window procedure for this class is known as DefDlgProc(), which is located in Windows's USER module. DefDlgProc() calls the application- provided dialog function, which returns TRUE if it processes a message completely or FALSE if DefDlgProc should process the message further.

If an application registers a private dialog class, it provides a window procedure for the dialog box. The window procedure is the same as that for any other application window and returns a LONG value. Messages that are not processed by this window function are passed to DefDlgProc().

Dialog Class Registration

Windows registers the default dialog class, which is represented by the value 0x8002. Windows uses this class when an application creates a dialog box using the DialogBox() or CreateDialog() functions, but specifies no class in the dialog resource template.

To use a private dialog class, the application must specify the fields of a WNDCLASS structure and call RegisterClass(). This is the same procedure that Windows uses to register the default dialog class.

In either case, the value in the cbWndExtra field of the WNDCLASS structure must contain a value of at least DLGWINDOWEXTRA. These bytes are used as storage space for dialog-box specific information, such as which control has the focus and which button is the default.

When a dialog class is registered, the lpfnWndProc field of the WNDCLASS structure must contain a function pointer. For the default dialog class, this field points to DefDlgProc(). For a private class, the field points to application-supplied procedure that returns a LONG (as does a normal window procedure) and passes all unprocessed messages to DefDlgProc().

Dialog Templates

Resource scripts are almost identical whether used with a default or a private dialog class. Dialog boxes using a private class must use the CLASS statement in the dialog template. The name given in the CLASS statement must match the name of class that exists (is registered) when the dialog box is created.

Dialog Creation and the lpfnDlgFunc Parameter

Applications create dialog boxes using the function DialogBox(), CreateDialog(), or one of the variant functions such as DialogBoxIndirect(). The complete list of functions is found on page 1- 43 of the "Microsoft Windows Software Development Kit Reference Volume 1."

All dialog box creation calls take a parameter called lpfnDlgFunc, which can either be NULL or the procedure instance address of the dialog box function returned from MakeProcInstance(). When the application specifies a private dialog class and sets lpfnDlgFunc to a procedure instance address, the application processes each message for the dialog box twice. The message processing proceeds as follows:

Windows calls the dialog class procedure to process the message. To process a message in the default manner, this procedure calls DefDlgProc().

DefDlgProc() calls the procedure specified in the dialog box creation call.

The procedure specified in lpfnDlgFunc must be designed very carefully. When it processes a message, it returns TRUE or FALSE and does not call DefDlgProc(). These requirements are the same as for any other dialog procedure.

Using a dialog procedure in conjunction with a private dialog class can be very useful. Processing for the private dialog class can be generic and apply to a number of dialog boxes. Code in the dialog procedure is specific to the particular instance of the private dialog class.

Dialog Message Processing

In dialog boxes with the default class, the application provides a callback dialog function that returns TRUE or FALSE, depending on whether or not the message was processed. As mentioned above, DefDlgProc(), which is the window procedure for the default dialog class, calls the application's dialog function and uses the return value to determine whether it should continue processing the message.

In dialog boxes of a private class, Windows sends all messages to the application-provided window procedure. The procedure either processes the message like any other window procedure or passes it to DefDlgProc(). DefDlgProc() processes dialog-specific functions and passes any other messages to DefWindowProc() for processing.

Some messages are sent only to the application-supplied procedure specified in the call to CreateDialog() or DialogBox(). Two examples of functions that Windows does not send to the private dialog class function are WM_INITDIALOG and WM_SETFONT.

Additional query words:

Keywords : kbDlg kbNTOS kbWinOS2000 kbSDKWin32 kbGrpUser kbWinOS
Version : WINDOWS:
Platform : WINDOWS
Issue type : kbinfo