HOWTO: Customize Common Dialog Box Parameter Blocks

Last reviewed: January 15, 1998
Article ID: Q99097

The information in this article applies to:

The Microsoft Foundation Classes (MFC) included with: - Microsoft C/C++ version 7.0 - Microsoft Visual C++ for Windows, versions 1.0, 1.5, 1.51, 1.52 - Microsoft Visual C++ 32-bit Edition, versions 2.0, 2.1, 4.0, 4.1,
```
     4.2, 5.0
```

SUMMARY

The Microsoft Foundation Classes (MFC) Standard Dialog Classes provide convenient C++ wrappers for the Microsoft Windows Common Dialog Boxes dynamic-link library (DLL), COMMDLG.DLL. To customize one of these classes, you may need to modify some of the default parameter block members. The wrapper functions use the same parameter blocks as the corresponding common dialog functions because, ultimately, the code calls the Windows functions.

   Microsoft
   Foundation Classes   Windows Common Dialog   Parameter Block
   -------------------------------------------------------------------
   CFileDialog          GetOpenFileName and     OPENFILENAME
                          GetSaveFileName
   CFontDialog          ChooseFont              CHOOSEFONT
   CColorDialog         ChooseColor             CHOOSECOLOR
   CPrintDialog         PrintDlg                PRINTDLG
   CFindReplaceDialog   FindText and            FINDREPLACE
                          ReplaceText

For Microsoft Foundation Classes version 1.0, distributed with Microsoft C/C++ version 7.0, Technical Note #13 provides additional information about these classes and how to use them. Technical Note #13 is in the TN013.TXT file in the MFC\DOC directory (by default, C:\C700\MFC\DOC). For Microsoft Foundation Classes library versions 2.x, 3.x, and 4.x, each of these functions is listed in the online documentation and in the "Class Library Reference" manual by its class name.

Even though the parameter block defaults that the Microsoft Foundation Classes library provides are generally adequate, there are times it may be necessary to customize a dialog box. For example, it may be helpful to specify the OFN_ALLOWMULTISELECT flag with the CFileDialog to allow the user to select more than one file in the GetOpenFileName dialog box.

If you add a flag, however, you must be careful to provide any additional information as appropriate. For example, CFileDialog provides a default buffer m_szFileName that is _MAX_PATH characters in length. If you allow the user to select more than one file, this buffer capacity can be exhausted quickly.

Even though the CFileDialog class was designed with a buffer to support only one file, it is an easy matter to provide your own buffer by setting the m_ofn.lpstrFile and m_ofn.nMax members of the OPENFILENAME parameter block yourself after constructing your CFileDialog, but before calling DoModal().

The text below demonstrates this method of replacing the default CFileDialog buffer. However, similar techniques apply to any of the standard dialog box classes. In general, when you change any of the default flags, you should examine the Microsoft Foundation Classes library source code to determine the effects of the change, if any, and to take appropriate action.

MORE INFORMATION

The following code fragment demonstrates using CFileDialog to select multiple files by adding the OFN_ALLOWMULTISELECT flag and using an application-supplied buffer:

   char bigBuff[2048] = "";  // maximum common dialog buffer size
   char szFilter[] =
      "All Files (*.*)|*.*|Text Files (*.txt)|*.txt||";
   CFileDialog dlg(bOpen, NULL, NULL,
      OFN_HIDEREADONLY | OFN_ALLOWMULTISELECT, szFilter);

   // Modify OPENFILENAME members directly to point to bigBuff
   dlg.m_ofn.lpstrFile = bigBuff;
   dlg.m_ofn.nMaxFile = sizeof(bigBuff);

   dlg.DoModal();

There are a number of circumstances in which it is desirable to add a custom template and/or a hook function to the Windows common dialog boxes. To do so, modify fields in the appropriate common dialog box parameter block. When the application uses the Microsoft Foundation Classes library, modify these fields after creating the dialog object but before calling DoModal(), as illustrated above.

For more information on using a custom template or a hook function with one of the common dialog boxes, please query in the Microsoft Knowledge Base on the following words:

steps add hook function

-or-

steps add custom template

Keywords          : MfcUI
Technology        : kbMfc
Version           : 1.0 1.5 1.51 1.52 2.0 4.0 4.2
Platform          : MS-DOS NT WINDOWS
Issue type        : kbhowto

================================================================================

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: January 15, 1998
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.