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.

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.

XBrowseForFolder is based on the old-style dialog — using BIF_NEWDIALOGSTYLE creates a dialog with a totally different structure, and XBrowseForFolder will not work.

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.

Share

About the Author

I attended St. Michael's College of the University of Toronto, with the intention of becoming a priest. A friend in the University's Computer Science Department got me interested in programming, and I have been hooked ever since.

Recently, I have moved to Los Angeles where I am doing consulting and development work.

For consulting and custom software development, please see www.hdsoft.org.