This documentation is archived and is not being maintained.


Updated: July 2010

Call this function to construct a standard Windows file dialog box.

explicit CFileDialog(
   BOOL bOpenFileDialog,
   LPCTSTR lpszDefExt = NULL,
   LPCTSTR lpszFileName = NULL,
   LPCTSTR lpszFilter = NULL,
   CWnd* pParentWnd = NULL,
   DWORD dwSize = 0,
   BOOL bVistaStyle = TRUE

[in] bOpenFileDialog

The parameter that specifies what type of dialog box to create. Set it to TRUE to construct a File Open dialog box. Set it to FALSE to construct a File Save As dialog box.

[in] lpszDefExt

The default file name extension. If the user does not include a known extension (one that has an association on the user’s computer) in the Filename box, the extension specified by lpszDefExt is automatically appended to the file name. If this parameter is NULL, no extension is appended.

[in] lpszFileName

The initial file name that appears in the Filename box. If NULL, no initial file name appears.

[in] dwFlags

A combination of one or more flags that you can use to customize the dialog box. For a description of these flags, see the OPENFILENAME structure in the Windows SDK. If you modify the m_ofn.Flags structure member, use a bitwise-OR operator in your changes to keep the default behavior intact.

[in] lpszFilter

A series of string pairs that specify filters you can apply to the file. If you specify file filters, only files that match filter criteria will appear in the Files list. See the Remarks section for more information about how to work with file filters.

[in] pParentWnd

A pointer to the parent or owner window of the file dialog box.

[in] dwSize

The size of the OPENFILENAME structure. This value depends on the operating system version. MFC used this parameter to determine the appropriate kind of dialog box to create (for example, new Windows 2000 dialog boxes instead of NT4 dialog boxes). The default size of 0 means that the MFC code will determine the correct dialog box size to use based on the operating system version on which the program is run.

[in] bVistaStyle

Note   This parameter is available in Visual Studio 2008 and later and has effect only when the application is running under Windows Vista or later.

The parameter that specifies the style of the file dialog. Set it to TRUE to use the new Vista style file dialogs. Otherwise, the old style of dialog boxes will be used. See the Remarks section for more information.

Either a File Open or File Save As dialog box is constructed, depending on the value of bOpenFileDialog.

Specifying a default extension using lpszDefExt may not produce the behavior that you expect, because it is seldom predictable what extensions have file associations on the user’s computer. If you need more control over the appending of a default extension, you can derive your own class from CFileDialog, and override the CFileDialog::OnFileNameOK method to perform your own extension handling.

To enable the user to select multiple files, set the OFN_ALLOWMULTISELECT flag before you call DoModal. You must supply your own file name buffer to store the returned list of multiple file names. Do this by replacing m_ofn.lpstrFile with a pointer to a buffer you have allocated, after you construct the CFileDialog, but before you call 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. For example:

// 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);
// Release file names buffer. 
delete[] filenamesBuffer;

To enable the user to resize an Explorer-style dialog box by using either the mouse or keyboard, set the OFN_ENABLESIZING flag. Setting this flag is necessary only if you provide a hook procedure or custom template. The flag works only with an Explorer-style dialog box; old-style dialog boxes cannot be resized.

The lpszFilter parameter is used to determine the type of file name a file must have to be displayed in the file list. The first string in the string pair describes the filter; the second string indicates the file name extension to use. Multiple extensions may be specified by using a semicolon (the ';' character) as the delimiter. The string ends with two '|' characters, followed by a NULL character. You can also use a CString object for this parameter.

For example, Microsoft Excel allows users to open files that have extensions .xlc (chart) or .xls (worksheet), among others. The filter for Excel could be written as:

static TCHAR BASED_CODE szFilter[] = _T("Chart Files (*.xlc)|*.xlc|")
_T("Worksheet Files (*.xls)|*.xls|Data Files (*.xlc;*.xls)|")
_T("*.xlc; *.xls|All Files (*.*)|*.*||");

However, if you plan to use this string to directly update the OPENFILENAME structure, you should delimit your strings with the null character, '\0', instead of the vertical bars ('|').

The bVistaStyle parameter is applicable only if the application is compiled in Visual Studio 2008 or later and running under Windows Vista or later. Under earlier versions of Windows, this parameter is ignored. If bVistaStyle is set to TRUE, the new Vista style File Dialog will be used. Otherwise, the previous MFC style File Dialog will be used. See CFileDialog Class for more information.

Dialog templates are not supported on dialogs that have the bVistaStyle.

See the example for CFileDialog::DoModal.

Header: afxdlgs.h




July 2010

Changed “compiling under Vista” to “running under Vista”.

Customer feedback.