|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
Encapsulates the Windows common file dialog box.
Common file dialog boxes provide an easy way to implement File Open and File Save As dialog boxes (as well as other file-selection dialog boxes) in a manner consistent with Windows standards.
You can use CFileDialog "as is" with the constructor provided, or you can derive your own dialog class from CFileDialog and write a constructor to suit your needs. In either case, these dialog boxes will behave like standard Microsoft Foundation class dialog boxes because they are derived from the CCommonDialog class.
To use a CFileDialog object, first create the object using the CFileDialog constructor. After the dialog box has been constructed, you can set or modify any values in the m_ofn structure to initialize the values or states of the dialog box's controls. The m_ofn structure is of type OPENFILENAME. For more information, see the OPENFILENAME structure in the Platform SDK.
After initializing the dialog box's controls, call the DoModal member function to display the dialog box and allow the user to enter the path and file. DoModal returns whether the user selected the OK (IDOK) or the Cancel (IDCANCEL) button.
If DoModal returns IDOK, you can use one of CFileDialog's public member functions to retrieve the information input by the user.
CFileDialog includes several protected members that enable you to do custom handling of share violations, filename validation, and list-box change notification. These protected members are callback functions that most applications do not need to use, since default handling is done automatically. Message-map entries for these functions are not necessary because they are standard virtual functions.
You can use the Windows CommDlgExtendedError function to determine whether an error occurred during initialization of the dialog box and to learn more about the error.
The destruction of CFileDialog objects is handled automatically. It is not necessary to call CDialog::EndDialog.
To allow the user to select multiple files, set the OFN_ALLOWMULTISELECT flag before calling DoModal. You need to supply your own filename buffer to accommodate the returned list of multiple filenames. Do this by replacing m_ofn.lpstrFile with a pointer to a buffer you have allocated, after constructing the CFileDialog, but before calling DoModal.
When the user allocates their own buffer to accommodate OFN_ALLOWMULTISELECT, the buffer can't be larger than 2048 or else everything gets corrupted (2048 is the maximum size).
Additionally, you must set m_ofn.nMaxFile with the number of characters in the buffer pointed to by m_ofn.lpstrFile. If you set the maximum number of files to be selected to n, the necessary buffer size is n*(_MAX_PATH + 1) + 1. For example:
CFileDialog dlgFile(...); ... CString fileName; dlgFile.GetOFN().lpstrFile = fileName.GetBuffer(<very large number>); dlgFile.GetOFN().nMaxFile = <very large number>; INT_PTR nResult = dlgFile.DoModal(); fileName.ReleaseBuffer();
CFileDialog relies on the COMMDLG.DLL file that ships with Windows versions 3.1 and later.
If you derive a new class from CFileDialog, you can use a message map to handle any messages. To extend the default message handling, derive a class from CWnd, add a message map to the new class, and provide member functions for the new messages. You do not need to provide a hook function to customize the dialog box.
To customize the dialog box, derive a class from CFileDialog, provide a custom dialog template, and add a message map to process the notification messages from the extended controls. Any unprocessed messages should be passed to the base class.
Customizing the hook function is not required.
For more information on using CFileDialog, see Common Dialog Classes.