Introduction
As I mentioned in my other article "CIconDialog - Selecting Icons", while developing a wizard application, I needed a dialog to select an icon from executables and another one for selecting folders on multiple ones, but did not find anything about in MFC. So, CFolderDialog
was written. It wraps the ::SHBrowseForFolder
API.
Sample Usage
The CFolderDialog
is derived from CCommonDialog
and acts like any common dialog. See sample usage:
#ifndef __FOLDERDLG_H__
#include "FolderDlg.h"
#endif
void CSomeDialog::OnSomeHandler( void )
{
m_strFolderPath = _T( "d:\\Windows" );
m_strDisplayName.Empty();
CFolderDialog dlg( _T( "Dialog Title" ), m_strFolderPath, this );
if( dlg.DoModal() == IDOK )
{
m_strFolderPath = dlg.GetFolderPath();
m_strDisplayName = dlg.GetFolderDisplayName();
}
}
See demo project source for more.
Setting the Root Folder
You can also set the root folder of the dialog, specifying the location of the root folder from which to start browsing. Only the specified folder and any subfolders that are beneath it in the namespace hierarchy will appear in the dialog box.
See sample usage:
#ifndef __FOLDERDLG_H__
#include "FolderDlg.h"
#endif
void CSomeDialog::OnSomeHandler( void )
{
CFolderDialog dlg( _T( "Root folder is C:\" ), NULL, this );
dlg.SetRootFolder( _T( "C:\\" );
if( dlg.DoModal() == IDOK )
{
// ...
}
}
//
Thanks to Eckhard Schwabe and Jose Insa for that sample.
Custom Filtering
Under Microsoft� Windows� XP/2003 or later, you can do custom filtering on the contents of the dialog box.
To create a custom filter, follow these steps:
- Set the
BIF_NEWDIALOGSTYLE
flag in the uFlags
member of the CFolderDialog
constructor. Override the OnIUnknown
virtual member function in the derived class. On OnIUnknown
, the function's pIUnknown
parameter will contain a pointer to an instance of IUnknown
. Call QueryInterface
on that IUnknown
to obtain a pointer to an IFolderFilterSite
.
- Create an object that implements
IFolderFilter
- derive a class from it that implements all basic pure virtual member functions of IUnknown
, and implement IFolderFilterSite::ShouldShow
and IFolderFilterSite::GetEnumFlags
functions, that do filtering.
- Call
IFolderFilterSite::SetFilter
(pointer to which you obtained in step 1), passing it a pointer to your custom IFolderFilter
derived class. IFolderFilterSite::ShouldShow
and IFolderFilterSite::GetEnumFlags
methods can then be used to include and exclude items from the tree.
- Once the filter is created, the
IFolderFilterSite
interface is no longer needed. Call IFolderFilterSite::Release
if you have no further use for it.
I have added a sample custom filtering (look at the picture, the dialog shows only "JPG/GIF/BMP" files in the tree). Thanks to Arik Poznanski for his article "C# does Shell, Part 1". For more information, please see the source code.
Class Members
Base Class
Data Members
m_bi
- The Windows BROWSEINFO
structure. Provides access to basic folder dialog box parameters.
m_szFolPath
- Contains the path of the folder selected with the dialog.
m_szSelPath
- Contains the folder path to be initially selected when the the dialog opens.
Construction
Constructs a CFolderDialog
object:
CFolderDialog( IN LPCTSTR pszTitle = NULL, IN LPCTSTR pszSelPath =
NULL, IN CWnd* pWndParent = NULL, IN UINT uFlags = BIF_RETURNONLYFSDIRS )
pszTitle
- Title to display in the top of the dialog.
pszSelPath
- The folder path to be initially selected when the the dialog opens.
pWndParent
- A pointer to the file dialog-box object's parent or owner window.
uFlags
- A combination of one or more flags that allows you to customize the dialog box. For more information, see BROWSEINFO
structure in the Platform SDK.
Operations
DoModal( void )
Displays the browse for folder dialog box and allows the user to make a selection.
SetSelectedFolder( IN LPCTSTR pszPath )
- Sets the folder path to be initially selected when the the dialog opens.
SetRootFolder( IN LPCTSTR pszPath )
- Sets the root folder path to show. If pszPath
is NULL
, the root folder is removed.
GetRootFolder( IN OUT LPTSTR pszPath )
- Gets the root folder of the dialog. The pszPath
buffer must be at least MAX_PATH
characters in size.
GetSelectedFolder( void ) const
- Gets the folder path to be initially selected when the the dialog opens.
GetFolderPath( void )const
- Retrieves the path of the open folder.
GetFolderDisplayName( void )const
- Retrieves the display name of the currently open folder.
GetFolderImageIndex( void )const
- Gets the image associated with the selected folder. The image is specified as an index to the system image list.
GetBI( void )
- Retrieves the BROWSEINFO
structure of the CFolderDialog
object.
GetBI( void )const
- Retrieves the BROWSEINFO
structure of the CFolderDialog
object.
Overridables
OnInitialized( void )
- Called when browse dialog box has finished initializing.
OnSelChanged( IN LPITEMIDLIST pItemIDList )
- Called when browse dialog box selection is changed.
OnValidateFailed( IN LPCTSTR pszPath )
- Called when the user typed an invalid name into the edit box (if any) of the browse dialog box. Return zero to allow the dialog to be dismissed or nonzero to keep the dialog open.
Microsoft� Windows� XP/2003 or later:
OnIUnknown( IN IUnknown* pIUnknown )
- Provides an IUnknown
interface to the client for custom filtering of the contents of the dialog box, using IFolderFilterSite
and IFolderFilter
.
Functions, that are valid to be called only from Overridables:
EnableOK( IN BOOL bEnable = TRUE )
- Enables or disables the browse dialog box's OK button.
SetSelection( IN LPITEMIDLIST pItemIDList )
- Selects the specified folder.
SetSelection( IN LPCTSTR pszPath )
- Selects the specified folder.
SetStatusText( IN LPCTSTR pszText )
- Sets the dialog box status text.
Shell version 5.0 or later:
SetExpanded( IN LPITEMIDLIST pItemIDList )
- Specifies a path to expand in the dialog box.
SetExpanded( IN LPCTSTR pszPath )
- Specifies a path to expand in the dialog box.
SetOKText( IN LPCTSTR pszText )
- Sets the dialog box "OK" button text.
Notes
If you convert this project to VC 7.0 or later, do not forget to add shlwapi.dll to the list of delay loaded DLLs because it uses ::StrRetToStr
function of shlwapi.dll 5.0. Go to "[Project Properties]>[Configuration Properties]>[Linker]>[Input]" and add "shlwapi.dll;" to the list of "[Delay Loaded DLLs]". VC 6.0 project does this using "/DelayLoad" linker option, not supported under VC 7.0 or later.
Version History
- 27 Mar 2002
- 30 Mar 2003
- Some code changes.
- Added missing in old Platform SDK new flag definitions.
- Added support for both MFC 6.0 and 7.0.
- Added
OnIUnknown
handler for Microsoft� Windows� XP folder filtration.
- Added
SetExpanded
, SetOKText
and GetSelectedFolder
functions.
- 30 May 2003
- Added
OnSelChanged
default implementation.
- 14 Jul 2003
- Added custom filtering sample for Microsoft� Windows� XP/2003 or later.
- Set
SetExpanded
and SetOKText
to noinline
.
- 07 Jan 2004
- Added
SetRootFolder
and GetRootFolder
functions.
- Changed
IFolderFilter
implementation.
- 15 Feb 2005
- Small bug fix in
DoModal
, thanks to WindSeven.