Share via


CFileDialog Class

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

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 differ from the earlier versions of Windows. The default CFileDialog automatically uses the new Windows Vista style without code changes if a program is compiled and run under Windows Vista. Use the bVistaStyle parameter in the constructor to manually override this automatic update. The exception to the automatic update is customized dialog boxes. They will not be converted to the new style. For more information about the constructor, see CFileDialog::CFileDialog.

Note

The control ID system differs in Windows Vista from earlier versions of Windows when you use a CFileDialog. You must update all references to CFileDialog controls in code before you can port your project from an earlier version of Windows.

Some CFileDialog methods are not supported under Windows Vista. Check the individual method topic for information about whether the method is supported. In addition, the following inherited functions are not supported under Windows Vista:

The windows messages for the CFileDialog class vary based on what operating system you are using. For example, Windows XP does not support CDialog::OnCancel and CDialog::OnOK for the CFileDialog class. However, Windows Vista does support them. For more information about the different messages that are generated and the order in which they are received, see CFileDialog Sample: Logging Event Order.

To use a CFileDialog object, first create the object by using the CFileDialog constructor. After the dialog box has been constructed, you can set or modify any values in the CFileDialog::m_ofn structure to initialize the values or states of the dialog box 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, multiple calls to IFileDialog::SetFileTypes causes an error. The second call to SetFileTypes for any instance of a CFileDialog will return E_UNEXPECTED in Windows Vista. Some CFileDialog method functions call SetFileTypes. For example, two calls to CFileDialog::DoModal for the same instance of a CFileDialog generates ASSERT.

CFileDialog includes several protected members that 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-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 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

CObject

CCmdTarget

CWnd

CDialog

CCommonDialog

CFileDialog

Requirements

**Header:**afxdlgs.h

See Also

Reference

CCommonDialog Class

Hierarchy Chart