Function name: SHBrowseForFolder

Defined in : Shell32

Requirements : Windows NT 4.0 or later; Windows 95 or later

Declaration:

Declare Function SHBrowseForFolder Lib "shell32" (lpbi As BrowseInfo) As Long

Parameters:

* lpbi Pointer to a BROWSEINFO structure that contains information used to display the dialog box. The BROWSEINFO structure contains the following members : * hwndOwner Handle to the owner window for the dialog box. * pidlRoot Pointer to an item identifier list (PIDL) specifying the location of the root folder from which to start browsing. Only the specified folder and any subfolders that are beneath it in the namespace hierarchy will appear in the dialog box. This member can be NULL; in that case, the namespace root (the desktop folder) is used. * pszDisplayName Address of a buffer to receive the display name of the folder selected by the user. The size of this buffer is assumed to be MAX_PATH characters. * lpszTitle Address of a null-terminated string that is displayed above the tree view control in the dialog box. This string can be used to specify instructions to the user. * ulFlags Flags specifying the options for the dialog box. This member can include zero or a combination of the following values. - BIF_BROWSEFORCOMPUTER Only return computers. If the user selects anything other than a computer, the OK button is grayed. - BIF_BROWSEFORPRINTER Only allow the selection of printers. If the user selects anything other than a printer, the OK button is grayed. - In Microsoft Windows XP, the best practice is to use an XP-style dialog, setting the root of the dialog to the Printers and Faxes folder (CSIDL_PRINTERS). - BIF_BROWSEINCLUDEFILES Version 4.71. The browse dialog box will display files as well as folders. - BIF_BROWSEINCLUDEURLS Version 5.0. The browse dialog box can display URLs. The BIF_USENEWUI and BIF_BROWSEINCLUDEFILES flags must also be set. If these three flags are not set, the browser dialog box will reject URLs. Even when these flags are set, the browse dialog box will only display URLs if the folder that contains the selected item supports them. When the folder's IShellFolder::GetAttributesOf method is called to request the selected item's attributes, the folder must set the SFGAO_FOLDER attribute flag. Otherwise, the browse dialog box will not display the URL. - BIF_DONTGOBELOWDOMAIN Do not include network folders below the domain level in the dialog box's tree view control. - BIF_EDITBOX Version 4.71. Include an edit control in the browse dialog box that allows the user to type the name of an item. - BIF_NEWDIALOGSTYLE Version 5.0. Use the new user interface. Setting this flag provides the user with a larger dialog box that can be resized. The dialog box has several new capabilities including: drag-and-drop capability within the dialog box, reordering, shortcut menus, new folders, delete, and other shortcut menu commands. To use this flag, you must call OleInitialize or CoInitialize before calling SHBrowseForFolder. - BIF_NONEWFOLDERBUTTON Version 6.0. Do not include the New Folder button in the browse dialog box. - BIF_NOTRANSLATETARGETS Version 6.0. When the selected item is a shortcut, return the PIDL of the shortcut itself rather than its target. - BIF_RETURNFSANCESTORS Only return file system ancestors. An ancestor is a subfolder that is beneath the root folder in the namespace hierarchy. If the user selects an ancestor of the root folder that is not part of the file system, the OK button is grayed. - BIF_RETURNONLYFSDIRS Only return file system directories. If the user selects folders that are not part of the file system, the OK button is grayed. - BIF_SHAREABLE Version 5.0. The browse dialog box can display shareable resources on remote systems. It is intended for applications that want to expose remote shares on a local system. The BIF_NEWDIALOGSTYLE flag must also be set. - BIF_STATUSTEXT Include a status area in the dialog box. The callback function can set the status text by sending messages to the dialog box. This flag is not supported when BIF_NEWDIALOGSTYLE is specified. - BIF_UAHINT Version 6.0. When combined with BIF_NEWDIALOGSTYLE, adds a usage hint to the dialog box in place of the edit box. BIF_EDITBOX overrides this flag. - BIF_USENEWUI Version 5.0. Use the new user interface, including an edit box. This flag is equivalent to BIF_EDITBOX | BIF_NEWDIALOGSTYLE. To use BIF_USENEWUI, you must call OleInitialize or CoInitialize before calling SHBrowseForFolder. - BIF_VALIDATE Version 4.71. If the user types an invalid name into the edit box, the browse dialog box will call the application's BrowseCallbackProc with the BFFM_VALIDATEFAILED message. This flag is ignored if BIF_EDITBOX is not specified. * lpfn Address of an application-defined function that the dialog box calls when an event occurs. For more information, see the BrowseCallbackProc function. This member can be NULL. * lParam Application-defined value that the dialog box passes to the callback function, if one is specified. * iImage Variable to receive the image associated with the selected folder. The image is specified as an index to the system image list.

Returns:

Returns a pointer to an item identifier list that specifies the location of the selected folder relative to the root of the name space. If the user chooses the Cancel button in the dialog box, the return value is NULL. The calling application is responsible for freeing the returned item identifier list using the shell’s task allocator.

Related functions: SHFileOperation, SHGetPathFromIDList

Examples:

Browse For Folder