XBrowseForFolder - Wrapper for SHBrowseForFolder

• Download demo project - 47.2 KB

Introduction

Sometimes you need to allow the user to pick a folder. Beginning with Win95, the standard way to do this is to use the SHBrowseForFolder API, which you can find in MSDN here. If you read the Usenet news groups, you will find many complaints about how complex SHBrowseForFolder is to use, and how bad the documentation is.

But my biggest problem with SHBrowseForFolder is the appearance of the dialog. It looks half-finished, with huge margins at the top and bottom. I know there are optional controls that could be placed in these spaces, but I think it is ridiculous to add a control that tells the user what he has just clicked on. Also, the dialog itself is way too small. Finally, the dialog displays a context help button in the caption bar, which displays non-helpful text such as "Click the plus sign next to an item to display more choices."

Here is what the usual SHBrowseForFolder dialog looks like on XP:

On Vista the SHBrowseForFolder dialog hasn't changed:

One alternative to using SHBrowseForFolder is to roll your own API + dialog, which would give you complete control over the appearance. Unfortunately, this has one big drawback: by abandoning the "standard" SHBrowseForFolder, you cannot be completely sure that what you do will be compatible in the future.

A Usable Alternative

XBrowseForFolder provides a wrapper for SHBrowseForFolder that overcomes the problems mentioned above, while ensuring future compatibility by utilizing the SHBrowseForFolder API.

Here is what the XBrowseForFolder dialog looks like:

As you can see, the margins are evenly sized around the folder tree, the context help button is gone, and the folder tree control is 70% larger than in the standard SHBrowseForFolder dialog.

What's New in v1.2

	For XBrowseForFolder v1.2, there is completely new UI for demo app:
	You can now specify a caption for the folder dialog.
	You can now specify the root of the folder tree, which can be any valid CSIDL, real or virtual (virtual means there is no actual corresponding file system folder; example: CSIDL_NETWORK). VISTA NOTE In Vista and later, Microsoft is promoting the use of new Known Folders instead of CSIDLs. In my testing, existing CSIDLs seem to work correctly in Vista. However, there are some KNOWNFOLDERID constants that have no CSIDL equivalent. To use the new KNOWNFOLDERID constants, you will also need to use new-in-Vista functions such as SHGetKnownFolderPath(). Doing so will of course make your code non-functional on previous Windows OSs.
	You can now specify an initial folder, which can be either a fully-qualified folder path, or the CSIDL of an existing (real, not virtual) folder. To specify a CSIDL, simply cast it to LPCTSTR before calling XBrowseForFolder.
	You can now optionally display the edit box on the folder dialog.

XBrowseForFolder API

///////////////////////////////////////////////////////////////////////////////
//
// XBrowseForFolder()
//
// Purpose:     Invoke the SHBrowseForFolder API.  If lpszInitialFolder is
//              supplied, it will be the folder initially selected in the tree 
//              folder list.  Otherwise, the initial folder will be set to the 
//              current directory.  The selected folder will be returned in 
//              lpszBuf.
//
// Parameters:  hWnd              - handle to the owner window for the dialog
//              lpszInitialFolder - initial folder in tree;  if NULL, the initial
//                                  folder will be the current directory;
//                                  if this is a CSIDL, must be a real folder.
//              nRootFolder       - optional CSIDL of root folder for tree;
//                                  -1 = use default.
//              lpszCaption       - optional caption for folder dialog
//              lpszBuf           - buffer for the returned folder path
//              dwBufSize         - size of lpszBuf in TCHARs
//              bEditBox          - TRUE = include edit box in dialog
//
// Returns:     BOOL - TRUE = success;  FALSE = user hit Cancel
//
BOOL XBrowseForFolder(HWND hWnd,
                      LPCTSTR lpszInitialFolder,
                      int nRootFolder,
                      LPCTSTR lpszCaption,
                      LPTSTR lpszBuf,
                      DWORD dwBufSize,
                      BOOL bEditBox /*= FALSE*/)

The XBrowseForFolder API is documented in the source code, and there is an example in XBrowseForFolderTestDlg.cpp.

Implementation Notes

Most of the code for resizing, etc. occurs in the BrowseCallbackProc() function when the BFFM_INITIALIZED message is received. There is really nothing complicated to it — just moving and sizing the controls.

How To Use

To integrate XBrowseForFolder into your app, you first need to add following files to your project:

• XBrowseForFolder.cpp
• XBrowseForFolder.h

XBrowseForFolder does not use MFC internally, so it can be used in non-MFC projects by commenting out the #include "stdafx.h" line.

Revision History

Version 1.2 - 2008 February 29

• Changed API to allow for initial CSIDL.
• Added option to set dialog caption, suggested by SimpleDivX.
• Added option to set root, suggested by Jean-Michel Reghem.
• Added VS2005 project.

Version 1.1 - 2003 September 29 (not released)

• Added option for edit box

Version 1.0 - 2003 September 25

• Initial public release.

Usage

This software is released into the public domain. You are free to use it in any way you like, except that you may not sell this source code. If you modify it or extend it, please to consider posting new code here for everyone to share. This software is provided "as is" with no expressed or implied warranty. I accept no liability for any damage or loss of business that this software may cause.