HOWTO: Add a Custom Template to a Common Dialog Box

ID: Q86720

The information in this article applies to:

Microsoft Windows Software Development Kit (SDK)
Microsoft Win32 Software Development Kit (SDK) on the following platforms:
```
    - Microsoft Windows NT version 3.5, 3.51
```

SUMMARY

Many applications developed for the Microsoft Windows environment using dialog boxes from the common dialogs library (COMMDLG.DLL) require custom dialog templates. An application generally uses a custom dialog box template to add controls to a standard common dialog box. The text below discusses the steps required to implement a custom dialog box template with a common dialog box.

A custom dialog box template is most often used in conjunction with a hook function. For details on using a hook function with one of the common dialog boxes, query on the following words in the Microsoft Knowledge Base:

   steps adding hook function

MORE INFORMATION

CDDEMO, one of the advanced sample applications provided with version 3.1 of the Microsoft Windows Software Development Kit (SDK), demonstrates adding a hook function to the File Open dialog box. The five steps required to modify the CDDEMO application to use a custom dialog box template in its File Open dialog box are as follows:

 1. Edit the FILEOPEN.DLG template in the Windows SDK advanced sample
    applications directory (by default, C:\WINDEV\SAMPLES\COMMDLG). All
    existing controls must remain in the dialog template; add
    additional controls, if desired. To demonstrate the process, make a
    copy of the FILEOPEN.DLG template and include it in the CDDEMO.RC
    file. Modify the title of the "Cancel" button to "CANCEL." Renaming
    the button minimizes the potential for error while demonstrating
    that the application loaded the custom dialog box template.

 2. In the application, modify the Flags member of the OPENFILENAME
    data structure to include the OFN_ENABLETEMPLATE initialization
    flag.

 3. Specify MAKEINTRESOURCE(FILEOPENORD) as the value of the
    lpTemplateName member of the OPENFILENAME data structure.

 4. Specify ghInst as the value of the hInstance member of the
    OPENFILENAME data structure.

 5. Use the #include directive to include DLGS.H in the CDDEMO.RC file.

If an application adds a hook function to a common dialog box, the hook receives all messages addressed to the dialog box. With the exception of the WM_INITDIALOG message, the hook function receives messages before its associated common dialog box does. If the hook function processes a message completely, it returns TRUE. If the common dialog box must provide default processing for a message, the hook function returns FALSE.

In the hook function, the application should process messages for any new controls added through the custom dialog box template. If the standard common dialog box template contains a control that is unnecessary in a particular application, hide the control when the hook function processes the WM_INITDIALOG message. Use the ShowWindow() API to hide a control; do not delete any controls from the common dialog box template. To indicate that the common dialog boxes DLL does not function properly if any controls are missing, the debug version of Windows displays FatalExit 0x0007.

Additional query words:

Keywords          : kbCmnDlg kbNTOS350 kbNTOS351 kbGrpUser kbWinOS310 
Issue type        : kbhowto

Last Reviewed: December 18, 1998