Click here to Skip to main content
11,805,035 members (66,932 online)
Click here to Skip to main content

XBrowseForFolder - Wrapper for SHBrowseForFolder

, 7 Mar 2008 CPOL 177.9K 4.6K 77
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.


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

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


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


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.


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.


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


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

You may also be interested in...

Comments and Discussions

GeneralMy vote of 5 Pin
zhrh22-Mar-12 23:24
memberzhrh22-Mar-12 23:24 
Questionset default directory in SHBrowseForFolder Pin
shashankacharya27-Jun-11 19:02
membershashankacharya27-Jun-11 19:02 
Generalworks great on Win 7 Pin
sumicus2-Jun-10 3:23
membersumicus2-Jun-10 3:23 
GeneralBorland C++ Version Pin
JeffBilkey2-Mar-09 21:28
memberJeffBilkey2-Mar-09 21:28 
GeneralRe: Borland C++ Version Pin
JeffBilkey3-Mar-09 13:10
memberJeffBilkey3-Mar-09 13:10 
QuestionHow to include the directory shortcuts in Browse for folder dialog (using Win32 API) Pin
nileshkhemkar11-Feb-09 19:06
membernileshkhemkar11-Feb-09 19:06 
QuestionWhat happened to "create new folder"? Pin
jackbowman23-Jan-09 15:50
memberjackbowman23-Jan-09 15:50 
AnswerRe: What happened to "create new folder"? Pin
Hans Dietrich24-Jan-09 2:08
mvpHans Dietrich24-Jan-09 2:08 
QuestionProblem When You Set Initial Directory to be a UNC Pin
Robert Cowan15-Dec-08 0:39
memberRobert Cowan15-Dec-08 0:39 
I have a much cruder wrapper for ShBrowseForFolder() that I coded as a DLL years ago so I could call it from VBA code in MS Office applications (callback functions being something of a challenge in VBA). However both my implementation and yours seem to suffer from the same problem if you specify a UNC as the initial directory (in that it seems to be ignored).

So for instance if drive H: is mapped to "\\Server1\Users\Robert" and that folder contains a sub-folder called "Data" then although both of our implementations work correctly if the initial directory is specified as "H:\Data", neither work if the initial directory is specified as "\\Server1\Users\Robert\Data". In the second case I was expecting/hoping it would expand the "Microsoft Windows Network" pseudo object, through the domain object, down to the machine called "Server1" etc. One last thing to add to the confusion... if I use your test app to browse all the way through to the UNC noted above and click OK, further launches of the folder dialogue DO display with the correct initial folder.

Any ideas anyone?

Robert Cowan

AnswerRe: Problem When You Set Initial Directory to be a UNC Pin
Hans Dietrich15-Dec-08 3:40
mvpHans Dietrich15-Dec-08 3:40 
GeneralRe: Problem When You Set Initial Directory to be a UNC Pin
Robert Cowan15-Dec-08 6:33
memberRobert Cowan15-Dec-08 6:33 
GeneralRe: Problem When You Set Initial Directory to be a UNC Pin
Hans Dietrich15-Dec-08 6:53
mvpHans Dietrich15-Dec-08 6:53 
GeneralRe: Problem When You Set Initial Directory to be a UNC Pin
Robert Cowan16-Dec-08 4:40
memberRobert Cowan16-Dec-08 4:40 
GeneralRe: Problem When You Set Initial Directory to be a UNC Pin
Robert Cowan16-Dec-08 5:06
memberRobert Cowan16-Dec-08 5:06 
QuestionHow to set focus still on the tree control when edit box option is selected? Pin
Z Gao19-Apr-08 13:48
memberZ Gao19-Apr-08 13:48 
Questioncan't find afxres.rc Pin
dave keller10-Dec-07 1:27
memberdave keller10-Dec-07 1:27 
GeneralRe: can't find afxres.rc Pin
Herbert Yu19-Feb-08 18:58
memberHerbert Yu19-Feb-08 18:58 
Kontza11-Jun-07 1:18
memberKontza11-Jun-07 1:18 
Herbert Yu26-Feb-08 13:34
memberHerbert Yu26-Feb-08 13:34 
Hans Dietrich28-Feb-08 21:58
mvpHans Dietrich28-Feb-08 21:58 
GeneralBug Pin
sdfkfggh14-Dec-06 2:54
membersdfkfggh14-Dec-06 2:54 
GeneralRe: Bug Pin
Hans Dietrich28-Feb-08 21:52
mvpHans Dietrich28-Feb-08 21:52 
QuestionDialog with a check for Sub folder Pin
ishusakshi15-May-06 2:34
memberishusakshi15-May-06 2:34 
AnswerRe: Dialog with a check for Sub folder Pin
jmcc2k13-Nov-08 23:28
memberjmcc2k13-Nov-08 23:28 
GeneralExcellent! Pin
DanRR4-Apr-06 19:44
memberDanRR4-Apr-06 19:44 

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 | Terms of Use | Mobile
Web04 | 2.8.151002.1 | Last Updated 7 Mar 2008
Article Copyright 2003 by Hans Dietrich
Everything else Copyright © CodeProject, 1999-2015
Layout: fixed | fluid