Click here to Skip to main content
Click here to Skip to main content

XBrowseForFolder - Wrapper for SHBrowseForFolder

, 7 Mar 2008 CPOL
Rate this:
Please Sign up or sign in to vote.
XBrowseForFolder wraps the SHBrowseForFolder API, provides a way to specify an initial directory, and cleans up the SHBrowseForFolder dialog.

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:

screenshot

On Vista the SHBrowseForFolder dialog hasn't changed:

screenshot

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:

screenshot

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

screenshot
screenshot For XBrowseForFolder v1.2, there is completely new UI for demo app:

screenshot

screenshot You can now specify a caption for the folder dialog.
screenshot 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.

screenshot 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.
screenshot 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.

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.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Hans Dietrich
Software Developer (Senior) Hans Dietrich Software
United States United States
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.






Comments and Discussions

 
Questionset default directory in SHBrowseForFolder Pinmembershashankacharya27-Jun-11 19:02 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web03 | 2.8.141015.1 | Last Updated 7 Mar 2008
Article Copyright 2003 by Hans Dietrich
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid