CFileDialog Class

Άρθρο
10/17/2022

Encapsulates the common dialog box that is used for file open or file save operations.

Syntax

class CFileDialog : public CCommonDialog

Members

Public Constructors

Name	Description
CFileDialog::CFileDialog	Constructs a `CFileDialog` object.

Public Methods

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.

Protected Methods

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.

Public Data Members

Name	Description
CFileDialog::m_ofn	The Windows `OPENFILENAME` structure. Provides access to basic file dialog box parameters.

Remarks

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.

Inheritance Hierarchy

CFileDialog

Requirements

Header: afxdlgs.h

CFileDialog::AddCheckButton

Adds a check button to the dialog.

HRESULT AddCheckButton(
    DWORD dwIDCtl,
    const CString& strLabel,
    BOOL bChecked);

Parameters

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

Remarks

CFileDialog::AddComboBox

Adds a combo box to the dialog.

HRESULT AddComboBox(DWORD dwIDCtl);

Parameters

dwIDCtl
The ID of the combo box to add.

Remarks

CFileDialog::AddControlItem

Adds an item to a container control in the dialog.

HRESULT AddControlItem(
    DWORD dwIDCtl,
    DWORD dwIDItem,
    const CString& strLabel);

Parameters

dwIDCtl
The ID of the container control to add the item to.

dwIDItem
The ID of the item.

strLabel
Item's text.

Remarks

CFileDialog::AddEditBox

Adds an edit box to the dialog.

HRESULT AddEditBox(
    DWORD dwIDCtl,
    const CString& strText);

Parameters

dwIDCtl
The ID of the edit box to add.

strText
The edit box name.

Remarks

CFileDialog::AddMenu

Adds a menu to the dialog.

HRESULT AddMenu(
    DWORD dwIDCtl,
    const CString& strLabel);

Parameters

dwIDCtl
The ID of the menu to add.

strLabel
The menu name.

Remarks

CFileDialog::AddPlace

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();

Parameters

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.

Remarks

CFileDialog::AddPushButton

Adds a button to the dialog.

HRESULT AddPushButton(
    DWORD dwIDCtl,
    const CString& strLabel);

Parameters

dwIDCtl
The ID of the button to add.

strLabel
The button name.

Remarks

CFileDialog::AddRadioButtonList

Adds an option button (also known as radio button) group to the dialog.

HRESULT AddRadioButtonList(DWORD dwIDCtl);

Parameters

dwIDCtl
The ID of the option button group to add.

Remarks

CFileDialog::AddSeparator

Adds a separator to the dialog.

HRESULT AddSeparator(DWORD dwIDCtl);

Parameters

dwIDCtl
The ID of the separator add.

Remarks

CFileDialog::AddText

Adds text to the dialog.

HRESULT AddText(
    DWORD dwIDCtl,
    const CString& strText);

Parameters

dwIDCtl
The ID of the text to add.

strText
The text name.

Remarks

CFileDialog::ApplyOFNToShellDialog

Updates the current state of the CFileDialog based on the values stored in the m_ofn data structure.

void ApplyOFNToShellDialog();

Remarks

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.

Example

See the example for CFileDialog::UpdateOFNFromShellDialog.

CFileDialog::CFileDialog

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);

Parameters

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.

Remarks

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

Example

See the example for CFileDialog::DoModal.

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();

Return Value

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.

Remarks

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.

Example

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);
   }
}

CFileDialog::EnableOpenDropDown

Enables a drop-down list on the Open or Save button in the dialog.

HRESULT EnableOpenDropDown(DWORD dwIDCtl);

Parameters

dwIDCtl
The ID of the drop-down list.

Remarks

CFileDialog::EndVisualGroup

Stops the addition of elements to a visual group in the dialog.

HRESULT EndVisualGroup();

Return Value

Returns S_OK if successful; an error value otherwise.

Remarks

CFileDialog::GetCheckButtonState

Retrieves the current state of a check button (check box) in the dialog.

HRESULT GetCheckButtonState(
    DWORD dwIDCtl,
    BOOL& bChecked);

Parameters

dwIDCtl
The ID of the check box.

bChecked
The state of the check box. TRUE indicates checked; FALSE indicates unchecked.

Remarks

CFileDialog::GetControlItemState

Retrieves the current state of an item in a container control found in the dialog.

HRESULT GetControlItemState(
    DWORD dwIDCtl,
    DWORD dwIDItem,
    CDCONTROLSTATEF& dwState);

Parameters

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.

Remarks

CFileDialog::GetControlState

Retrieves the current visibility and enabled states of a given control.

HRESULT GetControlState(
    DWORD dwIDCtl,
    CDCONTROLSTATEF& dwState);

Parameters

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.

Remarks

CFileDialog::GetEditBoxText

Retrieves the current text in an edit box control.

HRESULT GetEditBoxText(
    DWORD dwIDCtl,
    CString& strText);

Parameters

dwIDCtl
The ID of the edit box.

strText
The text value.

Remarks

CFileDialog::GetFileExt

Call this function to retrieve the extension of the filename entered into the dialog box.

CString GetFileExt() const;

Return Value

The extension of the filename.

Remarks

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.

CFileDialog::GetFileName

Call this function to retrieve the name of the filename entered in the dialog box.

CString GetFileName() const;

Return Value

The name of the file.

Remarks

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.

CFileDialog::GetFileTitle

Call this function to retrieve the title of the file entered in the dialog box.

CString GetFileTitle() const;

Return Value

The title of the file.

Remarks

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.

Example

See the example for CFileDialog::DoModal.

CFileDialog::GetFolderPath

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;

Return Value

A CString object containing the currently open folder or directory.

Remarks

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.

CFileDialog::GetIFileDialogCustomize

Retrieves a pointer to the internal COM object for a given CFileDialog.

IFileDialogCustomize* GetIFileDialogCustomize();

Return Value

The pointer to the internal COM object for the CFileDialog. It is your responsibility to release this pointer appropriately.

Remarks

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.

Example

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();
}

CFileDialog::GetIFileOpenDialog

Retrieves a pointer to the internal COM object for a given CFileDialog.

IFileOpenDialog* GetIFileOpenDialog();

Return Value

The pointer to the internal COM object for the CFileDialog. It is your responsibility to release this pointer appropriately.

Remarks

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.

Example

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();
}

CFileDialog::GetIFileSaveDialog

Retrieves a pointer to the internal COM object for a given CFileDialog.

IFileSaveDialog* GetIFileSaveDialog();

Return Value

The pointer to the internal COM object for the CFileDialog. It is your responsibility to release this pointer appropriately.

Remarks

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.

Example

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();
}

CFileDialog::GetNextPathName

Call this function to retrieve the next filename from the group selected in the dialog box.

CString GetNextPathName(POSITION& pos) const;

Parameters

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.

Return Value

The full path of the file.

Remarks

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.

CFileDialog::GetOFN

Retrieves the associated OPENFILENAME structure.

const OPENFILENAME& GetOFN() const;

OPENFILENAME& GetOFN();

Return Value

An OPENFILENAME structure.

Remarks

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.

CFileDialog::GetPathName

Call this function to retrieve the full path of the file entered in the dialog box.

CString GetPathName() const;

Return Value

The full path of the file.

Remarks

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.

Example

See the example for CFileDialog::DoModal.

CFileDialog::GetReadOnlyPref

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;

Return Value

Non-zero if the Read Only check box in the dialog box is selected; otherwise 0.

Remarks

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.

CFileDialog::GetResult

Retrieves the choice that the user made in the dialog.

IShellItem* GetResult() throw();

Return Value

A pointer to an IShellItem that represents the user's choice.

Remarks

CFileDialog::GetResults

Retrieves the user's choices in a dialog that allows multiple selection.

IShellItemArray* GetResults() throw();

Return Value

A pointer to an IShellItemArray through which the items selected in the dialog can be accessed.

Remarks

CFileDialog::GetSelectedControlItem

Retrieves a particular item from the specified container control in the dialog.

HRESULT GetSelectedControlItem(
    DWORD dwIDCtl,
    DWORD& dwIDItem);

Parameters

dwIDCtl
The ID of the container control.

dwIDItem
The ID of the item that the user selected in the control.

Remarks

CFileDialog::GetStartPosition

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;

Return Value

A POSITION value that can be used for iteration; NULL if the list is empty.

CFileDialog::HideControl

Call this member function to hide the specified control in an Explorer-style Open or Save As common dialog box.

void HideControl(int nID);

Parameters

nID
The ID of the control to hide.

Remarks

The dialog box must have been created with the OFN_EXPLORER style; otherwise, the function will fail with an assertion.

CFileDialog::IsPickFoldersMode

Determines if the current dialog is in folder picker mode.

BOOL IsPickFoldersMode() const;

Return Value

TRUE if the dialog is in folder picker mode; otherwise FALSE.

Remarks

CFileDialog::m_ofn

m_ofn is a structure of type OPENFILENAME. The data in this structure represents the current state of the CFileDialog.

Remarks

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.

CFileDialog::MakeProminent

Places a control in the dialog so that it stands out compared to other controls.

HRESULT MakeProminent(DWORD dwIDCtl);

Parameters

dwIDCtl
The ID of the control.

Remarks

CFileDialog::OnButtonClicked

Called when the button is clicked.

virtual void OnButtonClicked(DWORD dwIDCtl);

Parameters

dwIDCtl
The ID of the button.

Remarks

CFileDialog::OnCheckButtonToggled

Called when the check box is checked or unchecked.

virtual void OnCheckButtonToggled(
    DWORD dwIDCtl,
    BOOL bChecked);

Parameters

dwIDCtl
The ID of the check box.

bChecked
Checked or unchecked.

Remarks

CFileDialog::OnControlActivating

Called when the control is activated.

virtual void OnControlActivating(DWORD dwIDCtl);

Parameters

dwIDCtl
The ID of the control.

Remarks

CFileDialog::OnFileNameChange

Override this method if you want to handle the WM_NOTIFY CDN_SELCHANGE message.

virtual void OnFileNameChange();

Remarks

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.

CFileDialog::OnFileNameOK

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();

Return Value

1 if the filename is not a valid filename; otherwise 0.

Remarks

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.

CFileDialog::OnFolderChange

Override this function to handle the WM_NOTIFYCDN_FOLDERCHANGE message.

virtual void OnFolderChange();

Remarks

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.

CFileDialog::OnInitDone

Override this function to handle the WM_NOTIFY CDN_INITDONE message.

virtual void OnInitDone();

Remarks

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.

CFileDialog::OnItemSelected

Called when the container item is selected.

virtual void OnItemSelected(
    DWORD dwIDCtl,
    DWORD dwIDItem);

Parameters

dwIDCtl
The ID of the container control.

dwIDItem
The ID of the item.

Remarks

CFileDialog::OnLBSelChangedNotify

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);

Parameters

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.

Remarks

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.

CFileDialog::OnShareViolation

Override this function to provide custom handling of share violations.

virtual UINT OnShareViolation(LPCTSTR lpszPathName);

Parameters

lpszPathName
The path of the file on which the share violation occurred.

Return Value

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.

Remarks

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.

CFileDialog::OnTypeChange

Override this function to handle the WM_NOTIFYCDN_TYPECHANGE message.

virtual void OnTypeChange();

Remarks

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.

CFileDialog::RemoveControlItem

Removes an item from a container control in the dialog.

HRESULT RemoveControlItem(
    DWORD dwIDCtl,
    DWORD dwIDItem);

Parameters

dwIDCtl
The ID of the container control to remove the item from.

dwIDItem
The ID of the item.

Remarks

CFileDialog::SetCheckButtonState

Sets the current state of a check button (check box) in the dialog.

HRESULT SetCheckButtonState(
    DWORD dwIDCtl,
    BOOL bChecked);

Parameters

dwIDCtl
The ID of the check box.

bChecked
The state of the check box. TRUE indicates checked; FALSE indicates Unchecked.

Remarks

CFileDialog::SetControlItemState

Sets the current state of an item in a container control found in the dialog.

HRESULT SetControlItemState(
    DWORD dwIDCtl,
    DWORD dwIDItem,
    CDCONTROLSTATEF dwState);

Parameters

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.

Remarks

CFileDialog::SetControlItemText

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);

Parameters

dwIDCtl
The ID of the container control.

dwIDItem
The ID of the item.

strLabel
Item's text.

Remarks

CFileDialog::SetControlLabel

Sets the text associated with a control, such as button text or an edit box label.

HRESULT SetControlLabel(
    DWORD dwIDCtl,
    const CString& strLabel);

Parameters

dwIDCtl
The ID of the control.

strLabel
The control name.

Remarks

CFileDialog::SetControlState

Sets the current visibility and enabled states of a given control.

HRESULT SetControlState(
    DWORD dwIDCtl,
    CDCONTROLSTATEF dwState);

Parameters

dwIDCtl
The ID of the control.

dwState
One or more values from the CDCONTROLSTATE enumeration that indicate the current state of the control.

Remarks

CFileDialog::SetControlText

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);

Parameters

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.

Remarks

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.

CFileDialog::SetDefExt

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);

Parameters

lpsz
A pointer to a string containing the default extension to use for the dialog box object. This string must not contain a period (.).

Remarks

The dialog box must have been created with the OFN_EXPLORER style; otherwise, the function will fail with an assertion.

CFileDialog::SetEditBoxText

Sets the current text in an edit box control.

HRESULT SetEditBoxText(
    DWORD dwIDCtl,
    const CString& strText);

Parameters

dwIDCtl
The ID of the edit box.

strText
The text value.

Remarks

CFileDialog::SetProperties

Provides a property store that defines the default values to be used for the item being saved.

BOOL SetProperties(LPCWSTR lpszPropList);

Parameters

lpszPropList
A list of predefined properties separated by ";". For a list of the flags, see the Flags section of OPENFILENAME.

Remarks

CFileDialog::SetSelectedControlItem

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);

Parameters

dwIDCtl
The ID of the container control.

dwIDItem
The ID of the item that the user selected in the control.

Remarks

CFileDialog::SetTemplate

Sets the dialog box template for the CFileDialog object.

void SetTemplate(
    UINT nWin3ID,
    UINT nWin4ID);

void SetTemplate(
    LPCTSTR lpWin3ID,
    LPCTSTR lpWin4ID);

Parameters

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.

Remarks

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.

CFileDialog::StartVisualGroup

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);

Parameters

dwIDCtl
The ID of the visual group.

strLabel
The group name.

Remarks

CFileDialog::UpdateOFNFromShellDialog

Updates the m_ofn data structure of the CFileDialog based on the current state of the internal object.

void UpdateOFNFromShellDialog();

Remarks

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.

Example

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();

Κοινή χρήση μέσω

CFileDialog Class

Syntax

Members

Public Constructors

Public Methods

Protected Methods

Public Data Members

Remarks

Inheritance Hierarchy

Requirements

CFileDialog::AddCheckButton

Parameters

Remarks

CFileDialog::AddComboBox

Parameters

Remarks

CFileDialog::AddControlItem

Parameters

Remarks

CFileDialog::AddEditBox

Parameters

Remarks

CFileDialog::AddMenu

Parameters

Remarks

CFileDialog::AddPlace

Parameters

Remarks

CFileDialog::AddPushButton

Parameters

Remarks

CFileDialog::AddRadioButtonList

Parameters

Remarks

CFileDialog::AddSeparator

Parameters

Remarks

CFileDialog::AddText

Parameters

Remarks

CFileDialog::ApplyOFNToShellDialog

Remarks

Example

CFileDialog::CFileDialog

Parameters

Remarks

Example

CFileDialog::DoModal

Return Value

Remarks

Example

CFileDialog::EnableOpenDropDown

Parameters

Remarks

CFileDialog::EndVisualGroup

Return Value

Remarks

CFileDialog::GetCheckButtonState

Parameters

Remarks

CFileDialog::GetControlItemState

Parameters

Remarks

CFileDialog::GetControlState

Parameters

Remarks

CFileDialog::GetEditBoxText

Parameters

Remarks

CFileDialog::GetFileExt

Return Value

Remarks

CFileDialog::GetFileName

Return Value

Remarks

CFileDialog::GetFileTitle

Return Value

Remarks

Example