Adding a Custom Template to a Common Dialog Box

 Last reviewed: November 2, 1995
Article ID: Q86720
The information in this article applies to:
  • Microsoft Windows Software Development Kit (SDK) versions 3.1
  • Microsoft Win32 Application Programming Interface (API) included with: 

        - Microsoft Windows NT version 3.5

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 reference words: 3.10 3.50
KBCategory: kbui
KBSubcategory: UsrCmnDlg

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: November 2, 1995
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.