CFileDialog Class
Encapsulates the common dialog box that is used for file open or file save operations.
class CFileDialog : public CCommonDialog
Remarks
Common file dialog boxes provide an easy way to implement File Open and File Save As dialog boxes (and 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 MFC dialog boxes because they are derived from the CCommonDialog Class. CFileDialog relies on the COMMDLG.DLL file that ships with Windows.
Both the appearance and the functionality of the CFileDialog with Windows Vista differ from the earlier versions of Windows. The default CFileDialog automatically uses the new Windows Vista style without code changes if a program is compiled and run under Windows Vista. Use the bVistaStyle parameter in the constructor to manually override this automatic update. The exception to the automatic update is customized dialog boxes. They will not be converted to the new style. For more information about the constructor, see CFileDialog::CFileDialog.
Note
The control ID system differs in Windows Vista from earlier versions of Windows when you use a CFileDialog. You must update all references to CFileDialog controls in code before you can port your project from an earlier version of Windows.
Some CFileDialog methods are not supported under Windows Vista. Check the individual method topic for information about whether it is supported. In addition, the following inherited functions are not supported under Windows Vista:
The windows messages for the CFileDialog class vary based on what operating system you are using. For example, Windows XP does not support CDialog::OnCancel and CDialog::OnOK for the CFileDialog class. However, Windows Vista does support them. For more information about the different messages that are generated and the order in which they are received, see CFileDialog Sample: Logging Event Order.
To use a CFileDialog object, first create the object by using the CFileDialog constructor. After the dialog box has been constructed, you can set or modify any values in the CFileDialog::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 Windows SDK.
After initializing the dialog box's controls, call the CFileDialog::DoModal method to display the dialog box for 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.
Note
Under Windows Vista, multiple calls to IFileDialog::SetFileTypes causes an error. The second call to SetFileTypes for any instance of a CFileDialog will return E_UNEXPECTED in Windows Vista. Some CFileDialog method functions call SetFileTypes. For example, two calls to CFileDialog::DoModal for the same instance of a CFileDialog generates ASSERT.
CFileDialog includes several protected members that enable you to do custom handling of share violations, file name validation, and list-box change notification. These protected members are callback functions that most applications do not need to use because 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 must supply your own file name buffer to accommodate the returned list of multiple file names. Do this by replacing m_ofn.lpstrFile with a pointer to a buffer you have allocated, after constructing the CFileDialog, but before calling DoModal.
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.
The following example demonstrates how to use a buffer to retrieve multiple file names.
// Create dialog to open multiple files.
CFileDialog dlg(TRUE, _T("txt"), _T("*.txt"), OFN_ALLOWMULTISELECT);
// Create buffer for file names.
const DWORD numberOfFileNames = 100;
const DWORD fileNameMaxLength = MAX_PATH + 1;
const DWORD bufferSize = (numberOfFileNames * fileNameMaxLength) + 1;
TCHAR* filenamesBuffer = new TCHAR[bufferSize];
// Initialize beginning and end of buffer.
filenamesBuffer[0] = NULL;
filenamesBuffer[bufferSize-1] = NULL;
// Attach buffer to OPENFILENAME member.
dlg.m_ofn.lpstrFile = filenamesBuffer;
dlg.m_ofn.nMaxFile = bufferSize;
// Create array for file names.
CString fileNameArray[numberOfFileNames];
if(dlg.DoModal() == IDOK)
{
// Retrieve file name(s).
POSITION fileNamesPosition = dlg.GetStartPosition();
int iCtr = 0;
while(fileNamesPosition != NULL)
{
fileNameArray[iCtr] = dlg.GetNextPathName(fileNamesPosition);
iCtr++;
}
}
// Release file names buffer.
delete[] filenamesBuffer;
To change the buffer size in response to the user selecting multiple file names, you must derive a new class from CFileDialog and override the CFileDialog::OnFileNameChange method.
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 CFileDialog, 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.
When you are using the Windows Vista style of the CFileDialog, you cannot use message maps and dialog templates. Instead, you will need to use the COM interfaces for similar functionality.
For more information about using CFileDialog, see Common Dialog Classes.
Requirements
**Header:**afxdlgs.h
See Also
Reference
Other Resources
Change History
Date |
History |
Reason |
|---|---|---|
October 2008 |
Updated example code and related text. |
Information enhancement. |
September 2009 |
Added note about behavior under Windows Vista. |
Information enhancement. |