CFileDialog Class
Encapsulates the common dialog box that is used for file open or file save operations.
class CFileDialog : public CCommonDialog
Name | Description |
---|---|
CFileDialog::CFileDialog | Constructs a CFileDialog object. |
Name | Description |
---|---|
CFileDialog::AddCheckButton | Adds a check button to the dialog. |
CFileDialog::AddComboBox | Adds a combo box to the dialog. |
CFileDialog::AddControlItem | Adds an item to a container control in the dialog. |
CFileDialog::AddEditBox | Adds an edit box to the dialog. |
CFileDialog::AddMenu | Adds a menu to the dialog. |
CFileDialog::AddPlace | Overloaded. Adds a folder to the list of places available for the user to open or save items. |
CFileDialog::AddPushButton | Adds a button to the dialog. |
CFileDialog::AddRadioButtonList | Adds an option button (also known as radio button) group to the dialog. |
CFileDialog::AddSeparator | Adds a separator to the dialog. |
CFileDialog::AddText | Adds text content to the dialog. |
CFileDialog::ApplyOFNToShellDialog | Updates the state of the CFileDialog to match the parameters and flags stored in the m_ofn member variable. |
CFileDialog::DoModal | Displays the dialog box and enables the user to make a selection. |
CFileDialog::EnableOpenDropDown | Enables a drop-down list on the Open or Save button in the dialog. |
CFileDialog::EndVisualGroup | Stops the addition of elements to a visual group in the dialog. |
CFileDialog::GetCheckButtonState | Gets the current state of a check button (check box) in the dialog. |
CFileDialog::GetControlItemState | Gets the current state of an item in a container control found in the dialog. |
CFileDialog::GetControlState | Gets the current visibility and enabled states of a given control. |
CFileDialog::GetEditBoxText | Gets the current text in an edit box control. |
CFileDialog::GetFileExt | Returns the extension of the selected file. |
CFileDialog::GetFileName | Returns the file name of the selected file. |
CFileDialog::GetFileTitle | Returns the title of the selected file. |
CFileDialog::GetFolderPath | Retrieves the path of the currently open folder or directory for an Explorer-style Open or Save As common dialog box. |
CFileDialog::GetIFileDialogCustomize | Retrieves the internal COM object for a customized CFileDialog object. |
CFileDialog::GetIFileOpenDialog | Retrieves the internal COM object for a CFileDialog that is used as an Open file dialog box. |
CFileDialog::GetIFileSaveDialog | Retrieves the internal COM object for a CFileDialog that is used as a Save file dialog box. |
CFileDialog::GetNextPathName | Returns the full path of the next selected file. |
CFileDialog::GetOFN | Retrieves the OPENFILENAME structure of the CFileDialog object. |
CFileDialog::GetPathName | Returns the full path of the selected file. |
CFileDialog::GetReadOnlyPref | Returns the read-only status of the selected file. |
CFileDialog::GetResult | Gets the choice that the user made in the dialog. |
CFileDialog::GetResults | Gets the user's choices in a dialog that allows multiple selection. |
CFileDialog::GetSelectedControlItem | Gets a particular item from specified container controls in the dialog. |
CFileDialog::GetStartPosition | Returns the position of the first element of the file name list. |
CFileDialog::HideControl | Hides the specified control in an Explorer-style Open or Save As common dialog box. |
CFileDialog::IsPickFoldersMode | Determines if the current dialog in folder picker mode. |
CFileDialog::MakeProminent | Places a control in the dialog so that it stands out compared to other added controls. |
CFileDialog::RemoveControlItem | Removes an item from a container control in the dialog. |
CFileDialog::SetCheckButtonState | Sets the current state of a check button (check box) in the dialog. |
CFileDialog::SetControlItemState | Sets the current state of an item in a container control found in the dialog. |
CFileDialog::SetControlItemText | Sets the text of a control item. For example, the text that accompanies a radio button or an item in a menu. |
CFileDialog::SetControlLabel | Sets the text associated with a control, such as button text or an edit box label. |
CFileDialog::SetControlState | Sets the current visibility and enabled states of a given control. |
CFileDialog::SetControlText | Sets the text for the specified control in an Explorer-style Open or Save As common dialog box. |
CFileDialog::SetDefExt | Sets the default file name extension for an Explorer-style Open or Save As common dialog box. |
CFileDialog::SetEditBoxText | Sets the current text in an edit box control. |
CFileDialog::SetProperties | Provides a property store that defines the default values to be used for the item being saved. |
CFileDialog::SetSelectedControlItem | Sets the selected state of a particular item in an option button group or a combo box found in the dialog. |
CFileDialog::SetTemplate | Sets the dialog box template for the CFileDialog object. |
CFileDialog::StartVisualGroup | Declares a visual group in the dialog. Subsequent calls to any "add" method add those elements to this group. |
CFileDialog::UpdateOFNFromShellDialog | Updates the data stored in the m_ofn member variable to match the current state of the file dialog box. |
Name | Description |
---|---|
CFileDialog::OnButtonClicked | Called when the button is clicked. |
CFileDialog::OnCheckButtonToggled | Called when the check box is checked/unchecked. |
CFileDialog::OnControlActivating | Called when the control is being active. |
CFileDialog::OnFileNameChange | Handles the WM_NOTIFY CDN_SELCHANGE message. |
CFileDialog::OnFileNameOK | Validates the file name entered in the dialog box. |
CFileDialog::OnFolderChange | Handles the WM_NOTIFY CDN_FOLDERCHANGE message. |
CFileDialog::OnInitDone | Handles the WM_NOTIFY CDN_INITDONE message. |
CFileDialog::OnItemSelected | Called when the container item is being selected. |
CFileDialog::OnLBSelChangedNotify | Allows you to perform custom actions when the file selection changes. |
CFileDialog::OnShareViolation | Handles share violations. |
CFileDialog::OnTypeChange | Handles the WM_NOTIFY CDN_TYPECHANGE message. |
Name | Description |
---|---|
CFileDialog::m_ofn | The Windows OPENFILENAME structure. Provides access to basic file dialog box parameters. |
Common file dialog boxes let you implement file-selection dialog boxes, for example, Open File and Save As, in a manner that is consistent with Windows standards.
You can use CFileDialog
as is with the constructor provided, or you can derive your own dialog box 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 is included in Windows.
Both the appearance and the functionality of the CFileDialog
with Windows Vista or later differ from the earlier versions of Windows. The default CFileDialog
automatically uses the new Windows Vista or later style without code changes if a program is compiled and run under Windows Vista or later. 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 or later 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 or later. Check the individual method topic for information about whether the method is supported. In addition, the following inherited functions are not supported under Windows Vista or later:
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 and later operating systems do 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 controls. The m_ofn
structure is of type OPENFILENAME
. For more information, see the OPENFILENAME structure in the Windows SDK.
After you initialize the dialog box controls, call the CFileDialog::DoModal method to display the dialog box so that the user can type the path and file name. DoModal
returns whether the user clicked the OK (IDOK) or the Cancel (IDCANCEL) button. If DoModal
returns IDOK, you can use one of the CFileDialog
public member functions to retrieve the information put in by the user.
Note
Under Windows Vista or later, 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 or later. 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 let you 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 have to use because default handling is performed automatically. Message-map entries for these functions are not required 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. You do not have to call CDialog::EndDialog.
To let the user select multiple files, set the OFN_ALLOWMULTISELECT flag before you call 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 you construct the CFileDialog
, but before you call DoModal
.
Additionally, you must set m_ofn.nMaxFile
by using 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 required buffer size is n * (_MAX_PATH + 1) + 1
. The first item returned in the buffer is the path to the folder where the files were selected. For Windows Vista or later-style dialog boxes, the directory and file name strings are null-terminated, with an extra null character after the last file name. This format enables the Explorer-style dialog boxes to return long file names that include spaces. For old-style dialog boxes, the directory and file name strings are separated by spaces and the function uses short file names for file names with spaces.
The following example demonstrates how to use a buffer to retrieve and list multiple file names.
#define MAX_CFileDialog_FILE_COUNT 99
#define FILE_LIST_BUFFER_SIZE ((MAX_CFileDialog_FILE_COUNT * (MAX_PATH + 1)) + 1)
CString fileName;
wchar_t* p = fileName.GetBuffer( FILE_LIST_BUFFER_SIZE );
CFileDialog dlgFile(TRUE);
OPENFILENAME& ofn = dlgFile.GetOFN( );
ofn.Flags |= OFN_ALLOWMULTISELECT;
ofn.lpstrFile = p;
ofn.nMaxFile = FILE_LIST_BUFFER_SIZE;
dlgFile.DoModal();
fileName.ReleaseBuffer();
wchar_t* pBufEnd = p + FILE_LIST_BUFFER_SIZE - 2;
wchar_t* start = p;
while( ( p < pBufEnd ) && ( *p ) )
p++;
if( p > start )
{
_tprintf(_T("Path to folder where files were selected: %s\r\n\r\n"), start );
p++;
int fileCount = 1;
while( ( p < pBufEnd ) && ( *p ) )
{
start = p;
while( ( p < pBufEnd ) && ( *p ) )
p++;
if( p > start )
_tprintf(_T("%2d. %s\r\n"), fileCount, start );
p++;
fileCount++;
}
}
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 have to provide a hook function to customize the dialog box.
To customize the dialog box, derive a class from CFileDialog
, provide a custom dialog box template, and add a message map to process the notification messages from the extended controls. Pass any unprocessed messages to the base class. You do not have to customize the hook function.
When you are using the Windows Vista or later style of the CFileDialog
, you cannot use message maps and dialog box templates. Instead, you must use the COM interfaces for similar functionality.
For more information about how to use CFileDialog
, see Common Dialog Classes.
CFileDialog
Header: afxdlgs.h
Adds a check button to the dialog.
HRESULT AddCheckButton(
DWORD dwIDCtl,
const CString& strLabel,
BOOL bChecked);
dwIDCtl
The ID of the check button to add.
strLabel
The check button name.
bChecked
A Boolean indicating the current state of the check button. TRUE if checked; FALSE otherwise
Adds a combo box to the dialog.
HRESULT AddComboBox(DWORD dwIDCtl);
dwIDCtl
The ID of the combo box to add.
Adds an item to a container control in the dialog.
HRESULT AddControlItem(
DWORD dwIDCtl,
DWORD dwIDItem,
const CString& strLabel);
dwIDCtl
The ID of the container control to add the item to.
dwIDItem
The ID of the item.
strLabel
Item's text.
Adds an edit box to the dialog.
HRESULT AddEditBox(
DWORD dwIDCtl,
const CString& strText);
dwIDCtl
The ID of the edit box to add.
strText
The edit box name.
Adds a menu to the dialog.
HRESULT AddMenu(
DWORD dwIDCtl,
const CString& strLabel);
dwIDCtl
The ID of the menu to add.
strLabel
The menu name.
Adds a folder to the list of places available for the user to open or save items.
void AddPlace(
LPCWSTR lpszFolder,
FDAP fdap = FDAP_TOP) throw();
void AddPlace(
IShellItem* psi,
FDAP fdap = FDAP_TOP) throw();
lpszFolder
A path to the folder to be made available to the user. This can only be a folder.
fdap
Specifies where the folder is placed within the list.
psi
A pointer to an IShellItem that represents the folder to be made available to the user. This can only be a folder.
Adds a button to the dialog.
HRESULT AddPushButton(
DWORD dwIDCtl,
const CString& strLabel);
dwIDCtl
The ID of the button to add.
strLabel
The button name.
Adds an option button (also known as radio button) group to the dialog.
HRESULT AddRadioButtonList(DWORD dwIDCtl);
dwIDCtl
The ID of the option button group to add.
Adds a separator to the dialog.
HRESULT AddSeparator(DWORD dwIDCtl);
dwIDCtl
The ID of the separator add.
Adds text to the dialog.
HRESULT AddText(
DWORD dwIDCtl,
const CString& strText);
dwIDCtl
The ID of the text to add.
strText
The text name.
Updates the current state of the CFileDialog based on the values stored in the m_ofn
data structure.
void ApplyOFNToShellDialog();
In versions of Windows before Windows Vista, the member OPENFILENAME data structure was continuously synchronized with the state of the CFileDialog
. Any changes to the m_ofn member variable were immediately reflected in the state of the dialog box. Also, any changes to the state of the dialog box immediately update the m_ofn
member variable.
In Windows Vista or later, the values in the m_ofn
member variable and state of the CFileDialog
are not guaranteed to be synchronized. This function forces the state of the CFileDialog
to be updated to match the m_ofn
structure. Windows calls this function automatically during CFileDialog::DoModal.
For more information about how to use the CFileDialog
class under Windows Vista or later, see CFileDialog Class.
See the example for CFileDialog::UpdateOFNFromShellDialog.
Call this function to construct a standard Windows file dialog box.
explicit CFileDialog(
BOOL bOpenFileDialog,
LPCTSTR lpszDefExt = NULL,
LPCTSTR lpszFileName = NULL,
DWORD dwFlags = OFN_HIDEREADONLY | OFN_OVERWRITEPROMPT,
LPCTSTR lpszFilter = NULL,
CWnd* pParentWnd = NULL,
DWORD dwSize = 0,
BOOL bVistaStyle = TRUE);
bOpenFileDialog
[in] 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.
lpszDefExt
[in] 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.
lpszFileName
[in] The initial file name that appears in the Filename box. If NULL, no initial file name appears.
dwFlags
[in] 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.
lpszFilter
[in] 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.
pParentWnd
[in] A pointer to the parent or owner window of the file dialog box.
dwSize
[in] 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. 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.
bVistaStyle
[in] Note This parameter is available in Visual Studio 2008 and later and causes the new-style dialog to be used only if you are running in 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 about running under Vista.
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:
#define MAX_CFileDialog_FILE_COUNT 99
#define FILE_LIST_BUFFER_SIZE ((MAX_CFileDialog_FILE_COUNT * (MAX_PATH + 1)) + 1)
CString fileName;
wchar_t* p = fileName.GetBuffer( FILE_LIST_BUFFER_SIZE );
CFileDialog dlgFile(TRUE);
OPENFILENAME& ofn = dlgFile.GetOFN( );
ofn.Flags |= OFN_ALLOWMULTISELECT;
ofn.lpstrFile = p;
ofn.nMaxFile = FILE_LIST_BUFFER_SIZE;
dlgFile.DoModal();
fileName.ReleaseBuffer();
wchar_t* pBufEnd = p + FILE_LIST_BUFFER_SIZE - 2;
wchar_t* start = p;
while( ( p < pBufEnd ) && ( *p ) )
p++;
if( p > start )
{
_tprintf(_T("Path to folder where files were selected: %s\r\n\r\n"), start );
p++;
int fileCount = 1;
while( ( p < pBufEnd ) && ( *p ) )
{
start = p;
while( ( p < pBufEnd ) && ( *p ) )
p++;
if( p > start )
_tprintf(_T("%2d. %s\r\n"), fileCount, start );
p++;
fileCount++;
}
}
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 vertical bar 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 when running under Windows Vista or later. Under earlier versions of Windows, this parameter is ignored. If bVistaStyle is set to TRUE, when you compile a program with Visual Studio 2008 or later, the new Vista style File Dialog will be used. Otherwise, the previous MFC style File Dialog will be used.
Dialog templates are not supported on dialogs based on bVistaStyle
See the example for CFileDialog::DoModal.
Call this function to display the Windows common file dialog box and allow the user to browse files and directories and enter a filename.
virtual INT_PTR DoModal();
IDOK or IDCANCEL. If IDCANCEL is returned, call the Windows CommDlgExtendedError function to determine whether an error occurred.
IDOK and IDCANCEL are constants that indicate whether the user selected the OK or Cancel button.
If you want to initialize the various file dialog-box options by setting members of the m_ofn
structure, you should do this before calling DoModal
, but after the dialog object is constructed.
For example, if you want to allow the user to select multiple files, set the OFN_ALLOWMULTISELECT flag before calling DoModal
, as shown in the code example in this topic.
When the user clicks the dialog box's OK or Cancel buttons, or selects the Close option from the dialog box's control menu, control is returned to your application. You can then call other member functions to retrieve the settings or information the user inputs into the dialog box.
DoModal
is a virtual function overridden from class CDialog
.
void CMyClass::OnFileOpen()
{
// szFilters is a text string that includes two file name filters:
// "*.my" for "MyType Files" and "*.*' for "All Files."
TCHAR szFilters[]= _T("MyType Files (*.my)|*.my|All Files (*.*)|*.*||");
// Create an Open dialog; the default file name extension is ".my".
CFileDialog fileDlg(TRUE, _T("my"), _T("*.my"),
OFN_FILEMUSTEXIST | OFN_HIDEREADONLY, szFilters);
// Display the file dialog. When user clicks OK, fileDlg.DoModal()
// returns IDOK.
if(fileDlg.DoModal() == IDOK)
{
CString pathName = fileDlg.GetPathName();
// Implement opening and reading file in here.
//Change the window's title to the opened file's title.
CString fileName = fileDlg.GetFileTitle();
SetWindowText(fileName);
}
}
Enables a drop-down list on the Open or Save button in the dialog.
HRESULT EnableOpenDropDown(DWORD dwIDCtl);
dwIDCtl
The ID of the drop-down list.
Stops the addition of elements to a visual group in the dialog.
HRESULT EndVisualGroup();
Returns S_OK if successful; an error value otherwise.
Retrieves the current state of a check button (check box) in the dialog.
HRESULT GetCheckButtonState(
DWORD dwIDCtl,
BOOL& bChecked);
dwIDCtl
The ID of the check box.
bChecked
The state of the check box. TRUE indicates checked; FALSE indicates unchecked.
Retrieves the current state of an item in a container control found in the dialog.
HRESULT GetControlItemState(
DWORD dwIDCtl,
DWORD dwIDItem,
CDCONTROLSTATEF& dwState);
dwIDCtl
The ID of the container control.
dwIDItem
The ID of the item.
dwState
A reference to a variable that receives one of more values from the CDCONTROLSTATE enumeration that indicates the current state of the control.
Retrieves the current visibility and enabled states of a given control.
HRESULT GetControlState(
DWORD dwIDCtl,
CDCONTROLSTATEF& dwState);
dwIDCtl
The ID of the control.
dwState
A reference to a variable that receives one or more values from the CDCONTROLSTATE enumeration that indicates the current state of the control.
Retrieves the current text in an edit box control.
HRESULT GetEditBoxText(
DWORD dwIDCtl,
CString& strText);
dwIDCtl
The ID of the edit box.
strText
The text value.
Call this function to retrieve the extension of the filename entered into the dialog box.
CString GetFileExt() const;
The extension of the filename.
For example, if the name of the file entered is DATA.TXT, GetFileExt
returns "TXT".
If m_ofn.Flags
has the OFN_ALLOWMULTISELECT flag set, this string contains a sequence of null-terminated strings, with the first string being the directory path of the file group selected, followed by the names of all files selected by the user. To retrieve file pathnames, use the GetStartPosition and GetNextPathName member functions.
Call this function to retrieve the name of the filename entered in the dialog box.
CString GetFileName() const;
The name of the file.
The name of the file includes both the prefix and the extension. For example, GetFileName
will return "TEXT.DAT" for the file C:\FILES\TEXT.DAT.
If m_ofn.Flags
has the OFN_ALLOWMULTISELECT
flag set, you should call GetStartPosition and GetNextPathName to retrieve a file pathname.
Call this function to retrieve the title of the file entered in the dialog box.
CString GetFileTitle() const;
The title of the file.
The title of the file includes only its prefix, without the path or the extension. For example, GetFileTitle
will return "TEXT" for the file C:\FILES\TEXT.DAT.
If m_ofn.Flags
has the OFN_ALLOWMULTISELECT flag set, this string contains a sequence of null-terminated strings, with the first string being the directory path of the file group selected, followed by the names of all files selected by the user. For this reason, use the GetStartPosition and GetNextPathName member functions to retrieve the next file name in the list.
See the example for CFileDialog::DoModal.
Call this member function to retrieve the path of the currently open folder or directory for an Explorer-style Open or Save As common dialog box.
CString GetFolderPath() const;
A CString object containing the currently open folder or directory.
The dialog box must have been created with the OFN_EXPLORER style; otherwise, the method will fail with an assertion.
You can call this method only while the dialog box is being displayed. After the dialog box has been closed, this function will no longer work, and the method will fail with an assertion.
Retrieves a pointer to the internal COM object for a given CFileDialog.
IFileDialogCustomize* GetIFileDialogCustomize();
The pointer to the internal COM object for the CFileDialog
. It is your responsibility to release this pointer appropriately.
Use this function only under Windows Vista or later with an object that has bVistaStyle set to TRUE. If you use this function when bVistaStyle is FALSE, it will return NULL in release mode and throw an assertion in debug mode.
For more information about the IFileDialogCustomize
interface, see IFileDialogCustomize.
This example retrieves the internal COM object. To run this code example, you must compile it under Windows Vista or later.
// Get the interface pointer
IFileDialogCustomize *customDlgPtr = m_myFileDialogPtr->GetIFileDialogCustomize();
// Make sure that it is not null
if (customDlgPtr != NULL)
{
//
// Perform any interface functionality here
//
// Release the pointer
customDlgPtr->Release();
}
Retrieves a pointer to the internal COM object for a given CFileDialog
.
IFileOpenDialog* GetIFileOpenDialog();
The pointer to the internal COM object for the CFileDialog
. It is your responsibility to release this pointer appropriately.
Use this function only under Windows Vista or later with an object that has bVistaStyle set to TRUE. This function returns NULL if the CFileDialog
is not an Open dialog box or if bVistaStyle is set to FALSE. In this final case, the function only returns NULL in release mode - in debug mode it will throw an assertion.
For more information about the IFileOpenDialog
interface, see IFileOpenDialog.
This example retrieves the internal COM object. To run this code, you must compile it under Windows Vista or later.
// Get the interface pointer
IFileOpenDialog * openDlgPtr = m_myFileDialogPtr->GetIFileOpenDialog();
// Make sure that it is not null
if ( openDlgPtr != NULL )
{
//
// Perform any interface functionality here
//
// Release the pointer
openDlgPtr->Release();
}
Retrieves a pointer to the internal COM object for a given CFileDialog
.
IFileSaveDialog* GetIFileSaveDialog();
The pointer to the internal COM object for the CFileDialog
. It is your responsibility to release this pointer appropriately.
Use this function only under Windows Vista or later with an object that has bVistaStyle set to TRUE. This function will return NULL if the CFileDialog
is not a Save dialog box or if bVistaStyle is set to FALSE. In this final case, the function only returns NULL in release mode - in debug mode it will throw an assertion.
For more information about the IFileSaveDialog
interface, see IFileSaveDialog.
This example retrieves the internal COM object. To run this code example, you must compile it under Windows Vista or later.
// Get the interface pointer
IFileSaveDialog *saveDlgPtr = m_myFileDialogPtr->GetIFileSaveDialog();
// Make sure that it is not null
if (saveDlgPtr != NULL)
{
//
// Perform any interface functionality here
//
// Release the pointer
saveDlgPtr->Release();
}
Call this function to retrieve the next filename from the group selected in the dialog box.
CString GetNextPathName(POSITION& pos) const;
pos
A reference to a POSITION value returned by a previous GetNextPathName
or GetStartPosition
function call. NULL if the end of the list has been reached.
The full path of the file.
The path of the filename includes the file's title plus the entire directory path. For example, GetNextPathName
will return "C:\FILES\TEXT.DAT" for the file C:\FILES\TEXT.DAT. You can use GetNextPathName
in a forward iteration loop if you establish the initial position with a call to GetStartPosition
.
If the selection consists of only one file, that file name will be returned.
Retrieves the associated OPENFILENAME
structure.
const OPENFILENAME& GetOFN() const;
OPENFILENAME& GetOFN();
An OPENFILENAME structure.
Use the second version of this function to initialize the appearance of a File Open or File Save As dialog box after it is constructed but before it is displayed with the DoModal
member function. For example, you can set the lpstrTitle
member of m_ofn
to the caption you want the dialog box to have.
Call this function to retrieve the full path of the file entered in the dialog box.
CString GetPathName() const;
The full path of the file.
The path of the filename includes the file's title plus the entire directory path. For example, GetPathName
will return "C:\FILES\TEXT.DAT" for the file C:\FILES\TEXT.DAT.
If m_ofn.Flags
has the OFN_ALLOWMULTISELECT flag set, this string contains a sequence of null-teminated strings, with the first string being the directory path of the file group selected, followed by the names of all files selected by the user. For this reason, use the GetStartPosition and GetNextPathName member functions to retrieve the next file name in the list.
See the example for CFileDialog::DoModal.
Call this function to determine whether the Read Only check box has been selected in the Windows standard File Open and File Save As dialog boxes.
BOOL GetReadOnlyPref() const;
Non-zero if the Read Only check box in the dialog box is selected; otherwise 0.
You can hide the Read Only check box by setting the OFN_HIDEREADONLY style in the CFileDialog
constructor.
Note
Windows Vista or later style CFileDialog
objects do not support this function. Attempting to use this function on a Windows Vista or later style CFileDialog
will throw CNotSupportedException.
Retrieves the choice that the user made in the dialog.
IShellItem* GetResult() throw();
A pointer to an IShellItem that represents the user's choice.
Retrieves the user's choices in a dialog that allows multiple selection.
IShellItemArray* GetResults() throw();
A pointer to an IShellItemArray through which the items selected in the dialog can be accessed.
Retrieves a particular item from the specified container control in the dialog.
HRESULT GetSelectedControlItem(
DWORD dwIDCtl,
DWORD& dwIDItem);
dwIDCtl
The ID of the container control.
dwIDItem
The ID of the item that the user selected in the control.
Call this member function to retrieve the position of the first file pathname in the list, if m_ofn.Flags
has the OFN_ALLOWMULTISELECT flag set.
POSITION GetStartPosition() const;
A POSITION value that can be used for iteration; NULL if the list is empty.
Call this member function to hide the specified control in an Explorer-style Open or Save As common dialog box.
void HideControl(int nID);
nID
The ID of the control to hide.
The dialog box must have been created with the OFN_EXPLORER style; otherwise, the function will fail with an assertion.
Determines if the current dialog is in folder picker mode.
BOOL IsPickFoldersMode() const;
TRUE if the dialog is in folder picker mode; otherwise FALSE.
m_ofn
is a structure of type OPENFILENAME
. The data in this structure represents the current state of the CFileDialog
.
Use this structure to initialize the appearance of a File Open or File Save As dialog box after you construct it but before you display it with the DoModal method. For example, you can set the lpstrTitle member of m_ofn
to the caption you want the dialog box to have.
With the Windows Vista or later style of CFileDialog, m_ofn
is not guaranteed to always match the state of the dialog box. It is synchronized with the dialog box in earlier versions of Windows. See CFileDialog::ApplyOFNToShellDialog and CFileDialog::UpdateOFNFromShellDialog for more information about synchronizing the m_ofn
structure and the CFileDialog
state under Windows Vista or later.
Windows Vista or later style file dialogs do not support certain members and flags of the CFileDialog
. As a result, these will have no effect.
The following is a list of the members that are not supported by Windows Vista or later:
lpstrCustomFilter
lpstrInitialDir
lCustData
lpfnHook
lpTemplateName
The following flags are not supported and therefore have no effect when you use the Windows Vista or later style of CFileDialog
:
OFN_ENABLEHOOK
OFN_ENABLEINCLUDENOTIFY
OFN_ENABLETEMPLATE
OFN_ENABLETEMPLATEHANDLE
OFN_EXPLORER
OFN_EXTENSIONDIFFERENT
OFN_HIDEREADONLY
OFN_LONGNAMES - effectively always on in Windows Vista or later
OFN_NOLONGNAMES - effectively always off in Windows Vista or later
OFN_NONETWORKBUTTON - effectively always on in Windows Vista or later
OFN_READONLY
OFN_SHOWHELP
For more information about this structure, see the OPENFILENAME structure in the Windows SDK.
Places a control in the dialog so that it stands out compared to other controls.
HRESULT MakeProminent(DWORD dwIDCtl);
dwIDCtl
The ID of the control.
Called when the button is clicked.
virtual void OnButtonClicked(DWORD dwIDCtl);
dwIDCtl
The ID of the button.
Called when the check box is checked or unchecked.
virtual void OnCheckButtonToggled(
DWORD dwIDCtl,
BOOL bChecked);
dwIDCtl
The ID of the check box.
bChecked
Checked or unchecked.
Called when the control is activated.
virtual void OnControlActivating(DWORD dwIDCtl);
dwIDCtl
The ID of the control.
Override this method if you want to handle the WM_NOTIFY CDN_SELCHANGE message.
virtual void OnFileNameChange();
The system sends the CDN_SELCHANGE message when the user selects a new file or folder in the file list of the Open or Save As dialog box. Override this method if you want to perform any actions in response to this message.
The system sends this message only if the dialog box was created with the OFN_EXPLORER flag turned on. For more information about the notification, see CDN_SELCHANGE. For information about the OFN_EXPLORER flag, see the OPENFILENAME structure and Open and Save As Dialog Boxes.
Override this function only if you want to provide custom validation of filenames that are entered into a common file dialog box.
virtual BOOL OnFileNameOK();
1 if the filename is not a valid filename; otherwise 0.
This function allows you to reject a filename for any application-specific reason. Normally, you do not need to use this function because the framework provides default validation of filenames and displays a message box if an invalid filename is entered.
If 1 is returned, the dialog box will remain displayed for the user to enter another filename. The dialog procedure dismisses the dialog if the return is 0. Other nonzero return values are currently reserved and should not be used.
Override this function to handle the WM_NOTIFYCDN_FOLDERCHANGE message.
virtual void OnFolderChange();
The notification message is sent when a new folder is opened in the Open or Save As dialog box.
Notification is sent only if the dialog box was created with the OFN_EXPLORER style. For more information about the notification, see CDN_FOLDERCHANGE. For information about the OFN_EXPLORER style, see the OPENFILENAME structure and Open and Save As Dialog Boxes.
Override this function to handle the WM_NOTIFY CDN_INITDONE message.
virtual void OnInitDone();
The system sends this notification message when the system has finished arranging controls in the Open or Save As dialog box to make room for the controls of the child dialog box.
The system sends this only if the dialog box was created with the OFN_EXPLORER style. For more information about the notification, see CDN_INITDONE. For information about the OFN_EXPLORER style, see the OPENFILENAME structure and Open and Save As Dialog Boxes.
Note
Windows Vista or later style file dialogs do not support this function. Attempting to use this function on a Windows Vista or later style file dialog will throw CNotSupportedException.
Called when the container item is selected.
virtual void OnItemSelected(
DWORD dwIDCtl,
DWORD dwIDItem);
dwIDCtl
The ID of the container control.
dwIDItem
The ID of the item.
This function is called whenever the current selection in a list box is about to change.
virtual void OnLBSelChangedNotify(
UINT nIDBox,
UINT iCurSel,
UINT nCode);
nIDBox
The ID of the list box or combo box in which the selection occurred.
iCurSel
The index of the current selection.
nCode
The control notification code. This parameter must have one of the following values:
CD_LBSELCHANGE Specifies iCurSel is the selected item in a single-selection list box.
CD_LBSELSUB Specifies that iCurSel is no longer selected in a multiselection list box.
CD_LBSELADD Specifies that iCurSel is selected in a multiselection list box.
CD_LBSELNOITEMS Specifies that no selection exists in a multiselection list box.
Override this function to provide custom handling of selection changes in the list box. For example, you can use this function to display the access rights or date-last-modified of each file the user selects.
Override this function to provide custom handling of share violations.
virtual UINT OnShareViolation(LPCTSTR lpszPathName);
lpszPathName
The path of the file on which the share violation occurred.
One of the following values:
OFN_SHAREFALLTHROUGH The filename is returned from the dialog box.
OFN_SHARENOWARN No further action needs to be taken.
OFN_SHAREWARN The user receives the standard warning message for this error.
Normally, you do not need to use this function because the framework provides default checking of share violations and displays a message box if a share violation occurs.
If you want to disable share violation checking, use the bitwise OR operator to combine the flag OFN_SHAREAWARE with m_ofn.Flags
.
Override this function to handle the WM_NOTIFYCDN_TYPECHANGE message.
virtual void OnTypeChange();
The notification message is sent when the user selects a new file type from the list of file types in the Open or Save As dialog box.
Notification is sent only if the dialog box was created with the OFN_EXPLORER style. For more information about the notification, see CDN_TYPECHANGE. For information about the OFN_EXPLORER style, see the OPENFILENAME structure and Open and Save As Dialog Boxes.
Removes an item from a container control in the dialog.
HRESULT RemoveControlItem(
DWORD dwIDCtl,
DWORD dwIDItem);
dwIDCtl
The ID of the container control to remove the item from.
dwIDItem
The ID of the item.
Sets the current state of a check button (check box) in the dialog.
HRESULT SetCheckButtonState(
DWORD dwIDCtl,
BOOL bChecked);
dwIDCtl
The ID of the check box.
bChecked
The state of the check box. TRUE indicates checked; FALSE indicates Unchecked.
Sets the current state of an item in a container control found in the dialog.
HRESULT SetControlItemState(
DWORD dwIDCtl,
DWORD dwIDItem,
CDCONTROLSTATEF dwState);
dwIDCtl
The ID of the container control.
dwIDItem
The ID of the item.
dwState
One or more values from the CDCONTROLSTATE enumeration that indicate the new state of the control.
Sets the text of a control item. For example, the text that accompanies a radio button or an item in a menu.
HRESULT SetControlItemText(
DWORD dwIDCtl,
DWORD dwIDItem,
const CString& strLabel);
dwIDCtl
The ID of the container control.
dwIDItem
The ID of the item.
strLabel
Item's text.
Sets the text associated with a control, such as button text or an edit box label.
HRESULT SetControlLabel(
DWORD dwIDCtl,
const CString& strLabel);
dwIDCtl
The ID of the control.
strLabel
The control name.
Sets the current visibility and enabled states of a given control.
HRESULT SetControlState(
DWORD dwIDCtl,
CDCONTROLSTATEF dwState);
dwIDCtl
The ID of the control.
dwState
One or more values from the CDCONTROLSTATE enumeration that indicate the current state of the control.
Call this method to set the text for the specified control in an Explorer-style Open or Save As dialog box.
void SetControlText(
int nID,
LPCSTR lpsz);
void SetControlText(
int nID,
const wchar_t *lpsz);
nID
[in] The ID of the control for which to set the text.
lpsz
[in] A pointer to the string that contains the text to set for the control.
Both versions of this function are valid for applications that use Unicode. However, only the version with the LPCSTR type is valid for applications that use ANSI.
To use this method, you must create the dialog box with the OFN_EXPLORER style. Otherwise, the function will fail with an assertion.
Call this function to set the default file name extension for an Explorer-style Open or Save As common dialog box.
void SetDefExt(LPCSTR lpsz);
lpsz
A pointer to a string containing the default extension to use for the dialog box object. This string must not contain a period (.).
The dialog box must have been created with the OFN_EXPLORER style; otherwise, the function will fail with an assertion.
Sets the current text in an edit box control.
HRESULT SetEditBoxText(
DWORD dwIDCtl,
const CString& strText);
dwIDCtl
The ID of the edit box.
strText
The text value.
Provides a property store that defines the default values to be used for the item being saved.
BOOL SetProperties(LPCWSTR lpszPropList);
lpszPropList
A list of predefined properties separated by ";". For a list of the flags, see the Flags section of OPENFILENAME.
Sets the selected state of a particular item in an option button group or a combo box found in the dialog.
HRESULT SetSelectedControlItem(
DWORD dwIDCtl,
DWORD dwIDItem);
dwIDCtl
The ID of the container control.
dwIDItem
The ID of the item that the user selected in the control.
Sets the dialog box template for the CFileDialog object.
void SetTemplate(
UINT nWin3ID,
UINT nWin4ID);
void SetTemplate(
LPCTSTR lpWin3ID,
LPCTSTR lpWin4ID);
nWin3ID
[in] Contains the ID number of the template resource for the non-Explorer CFileDialog
object. This template is only used on Windows NT 3.51 or when the OFN_EXPLORER style is not present.
nWin4ID
[in] Contains the ID number of the template resource for the Explorer CFileDialog
object. This template is used only on Windows NT 4.0 and later versions, Windows 95 and later versions, or when the OFN_EXPLORER style is present.
lpWin3ID
[in] Contains the name of the template resource for the non-Explorer CFileDialog
object. This template is only used on Windows NT 3.51 or when the OFN_EXPLORER style is not present.
lpWin4ID
[in] Contains the name of the template resource of the Explorer CFileDialog
object. This template is used only on Windows NT 4.0 and later versions, Windows 95 and later versions, or when the OFN_EXPLORER style is present.
The system will use only one of the specified templates. The system determines which template to use based on the presence of the OFN_EXPLORER style and the operating system that the application is running on. By specifying both a non-Explorer and Explorer-style template, it is easy to support Windows NT 3.51, Windows NT 4.0 and later versions, and Windows 95 and later versions.
Note
Windows Vista or later style file dialog boxes do not support this function. Attempting to use this function on a Windows Vista or later style file dialog box will throw CNotSupportedException. An alternative is to use a customized dialog. For more information about using a custom CFileDialog
, see IFileDialogCustomize.
Declares a visual group in the dialog. Subsequent calls to any "add" method add those elements to this group.
HRESULT StartVisualGroup(
DWORD dwIDCtl,
const CString& strLabel);
dwIDCtl
The ID of the visual group.
strLabel
The group name.
Updates the m_ofn
data structure of the CFileDialog based on the current state of the internal object.
void UpdateOFNFromShellDialog();
In versions of Windows before Windows Vista, the member OPENFILENAME data structure was continuously synchronized with the state of the CFileDialog
. Any changes to the m_ofn member variable directly affected the state of the dialog box. Also, any changes to the state of the dialog immediately updated the m_ofn member variable.
In Windows Vista or later, the m_ofn
data structure is not automatically updated. To guarantee the accuracy of the data in the m_ofn
member variable, you should call the UpdateOFNFromShellDialog
function before accessing the data. Windows calls this function automatically during the processing of IFileDialog::OnFileOK.
For more information about how to use the CFileDialog
class under Windows Vista or later, see CFileDialog Class.
This example updates the CFileDialog
before displaying it. Before updating the m_ofn
member variable, we need to synchronize it to the current state of the dialog box.
// Update the m_ofn variable
m_myFileDialogPtr->UpdateOFNFromShellDialog();
// Change the title
m_myFileDialogPtr->m_ofn.lpstrTitle = L"New Dialog Title";
// Apply the changes
m_myFileDialogPtr->ApplyOFNToShellDialog();
// Show the window
LRESULT result = m_myFileDialogPtr->DoModal();