Click here to Skip to main content
15,112,645 members
Articles / Desktop Programming / MFC
Posted 24 Sep 2003


77 bookmarked

XBrowseForFolder - Wrapper for SHBrowseForFolder

Rate me:
Please Sign up or sign in to vote.
4.89/5 (62 votes)
7 Mar 2008CPOL4 min read
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

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


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

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

Comments and Discussions

GeneralMy vote of 5 Pin
zhrh23-Mar-12 0:24
Memberzhrh23-Mar-12 0:24 
Questionset default directory in SHBrowseForFolder Pin
shashankacharya27-Jun-11 20:02
Membershashankacharya27-Jun-11 20:02 
Generalworks great on Win 7 Pin
sumicus2-Jun-10 4:23
Membersumicus2-Jun-10 4:23 
GeneralBorland C++ Version Pin
JeffBilkey2-Mar-09 22:28
MemberJeffBilkey2-Mar-09 22:28 
GeneralRe: Borland C++ Version Pin
JeffBilkey3-Mar-09 14:10
MemberJeffBilkey3-Mar-09 14:10 
QuestionHow to include the directory shortcuts in Browse for folder dialog (using Win32 API) Pin
nileshkhemkar11-Feb-09 20:06
Membernileshkhemkar11-Feb-09 20:06 
Is there any way to shows the directory shortcuts when we use Win32 API (Browse for folder's (SHBrowseForFolder)).

Currently my application use BIF_NEWDIALOGSTYLE + BIF_RETURNONLYFSDIRS flags.

I tried using flag "BIF_BROWSEINCLUDEFILES" , but it no use as it shows both(files as well as folders). where I need to display/include shortcuts of a directory when user select browse for folder dialog.
QuestionWhat happened to "create new folder"? Pin
jackbowman23-Jan-09 16:50
Memberjackbowman23-Jan-09 16:50 
AnswerRe: What happened to "create new folder"? Pin
Hans Dietrich24-Jan-09 3:08
mentorHans Dietrich24-Jan-09 3:08 
QuestionProblem When You Set Initial Directory to be a UNC Pin
Robert Cowan15-Dec-08 1:39
MemberRobert Cowan15-Dec-08 1:39 
AnswerRe: Problem When You Set Initial Directory to be a UNC Pin
Hans Dietrich15-Dec-08 4:40
mentorHans Dietrich15-Dec-08 4:40 
GeneralRe: Problem When You Set Initial Directory to be a UNC Pin
Robert Cowan15-Dec-08 7:33
MemberRobert Cowan15-Dec-08 7:33 
GeneralRe: Problem When You Set Initial Directory to be a UNC Pin
Hans Dietrich15-Dec-08 7:53
mentorHans Dietrich15-Dec-08 7:53 
GeneralRe: Problem When You Set Initial Directory to be a UNC Pin
Robert Cowan16-Dec-08 5:40
MemberRobert Cowan16-Dec-08 5:40 
GeneralRe: Problem When You Set Initial Directory to be a UNC Pin
Robert Cowan16-Dec-08 6:06
MemberRobert Cowan16-Dec-08 6:06 
QuestionHow to set focus still on the tree control when edit box option is selected? Pin
Z Gao19-Apr-08 14:48
MemberZ Gao19-Apr-08 14:48 
Questioncan't find afxres.rc Pin
dave keller10-Dec-07 2:27
Memberdave keller10-Dec-07 2:27 
GeneralRe: can't find afxres.rc Pin
Herbert Yu19-Feb-08 19:58
MemberHerbert Yu19-Feb-08 19:58 
Kontza11-Jun-07 2:18
MemberKontza11-Jun-07 2:18 
Herbert Yu26-Feb-08 14:34
MemberHerbert Yu26-Feb-08 14:34 
Hans Dietrich28-Feb-08 22:58
mentorHans Dietrich28-Feb-08 22:58 
GeneralBug Pin
sdfkfggh14-Dec-06 3:54
Membersdfkfggh14-Dec-06 3:54 
GeneralRe: Bug Pin
Hans Dietrich28-Feb-08 22:52
mentorHans Dietrich28-Feb-08 22:52 
QuestionDialog with a check for Sub folder Pin
ishusakshi15-May-06 3:34
Memberishusakshi15-May-06 3:34 
AnswerRe: Dialog with a check for Sub folder Pin
jmcc2k14-Nov-08 0:28
Memberjmcc2k14-Nov-08 0:28 
GeneralExcellent! Pin
DanRR4-Apr-06 20:44
MemberDanRR4-Apr-06 20:44 

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

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