# Function Reference

# _WinAPI_BrowseForFolderDlg

Displays a dialog box that enables the user to select a Shell folder

#include <WinAPIDlg.au3>
_WinAPI_BrowseForFolderDlg ( [$sRoot = '' [, $sText = '' [, $iFlags = 0 [, $pBrowseProc = 0 [, $lParam = 0 [, $hParent = 0]]]]]] )

## Parameters

$sRoot | [optional] The root folder from which to start browsing. Only the specified folder and its subfolders in the namespace hierarchy appear in the dialog box. If this parameter is 0, the namespace root (the Desktop folder) is used.
$sText | [optional] The string that is displayed above the tree view control in the dialog box.
$iFlags | [optional] Flags that specify the options for the dialog box. This parameter can be a combination of the following values: $BIF_BROWSEFORCOMPUTER $BIF_BROWSEFORPRINTER $BIF_BROWSEINCLUDEFILES $BIF_BROWSEINCLUDEURLS $BIF_DONTGOBELOWDOMAIN $BIF_EDITBOX $BIF_NEWDIALOGSTYLE $BIF_NONEWFOLDERBUTTON $BIF_NOTRANSLATETARGETS $BIF_RETURNFSANCESTORS $BIF_RETURNONLYFSDIRS $BIF_SHAREABLE $BIF_STATUSTEXT $BIF_USENEWUI $BIF_UAHINT $BIF_VALIDATE Windows 7 or later $BIF_BROWSEFILEJUNCTIONS
$pBrowseProc | [optional] Pointer to a callback function that the dialog box calls when an event occurs. This function will receive one of the following event messages: $BFFM_INITIALIZED $BFFM_IUNKNOWN $BFFM_SELCHANGED $BFFM_VALIDATEFAILED (See MSDN for more information)
$lParam | [optional] The value that the dialog box passes to the callback function.
$hParent | [optional] Handle to the parent window for the dialog box.

## Return Value

Success: | The full path for chosen folder, or an empty string if user cancels/closes the dialog.
Failure: | Empty string.

## See Also

Search SHBrowseForFolder in MSDN Library.

## Example

    #include <MsgBoxConstants.au3>
    #include <SendMessage.au3>
    #include <WinAPIDlg.au3>
    #include <WinAPIMem.au3>
    #include <WinAPIMisc.au3>
    #include <WinAPIShellEx.au3>
    #include <WinAPIShPath.au3>
    #include <WinAPISysWin.au3>

    Local Const $sInitDir = @ProgramFilesDir

    Local $hBrowseProc = DllCallbackRegister('_BrowseProc', 'int', 'hwnd;uint;lparam;ptr')
    Local $pBrowseProc = DllCallbackGetPtr($hBrowseProc)

    Local $pText = _WinAPI_CreateString($sInitDir)
    Local $sPath = _WinAPI_BrowseForFolderDlg(_WinAPI_PathStripToRoot($sInitDir), 'Select a folder from the list below.', BitOR($BIF_RETURNONLYFSDIRS, $BIF_EDITBOX, $BIF_VALIDATE), $pBrowseProc, $pText)
    _WinAPI_FreeMemory($pText)

    If $sPath Then
        ConsoleWrite('--------------------------------------------------' & @CRLF)
        ConsoleWrite($sPath & @CRLF)
    EndIf

    DllCallbackFree($hBrowseProc)

    Func _BrowseProc($hWnd, $iMsg, $wParam, $lParam)
        Local $sPath

        Switch $iMsg
            Case $BFFM_INITIALIZED
                _WinAPI_SetWindowText($hWnd, 'MyTitle')
                _SendMessage($hWnd, $BFFM_SETSELECTIONW, 1, $lParam)
            Case $BFFM_SELCHANGED
                $sPath = _WinAPI_ShellGetPathFromIDList($wParam)
                If Not @error Then
                    ConsoleWrite($sPath & @CRLF)
                EndIf
            Case $BFFM_VALIDATEFAILED
                MsgBox(($MB_ICONERROR + $MB_SYSTEMMODAL), 'Error', _WinAPI_GetString($wParam) & ' is invalid.', 0, $hWnd)
                Return 1
        EndSwitch
        Return 0
    EndFunc   ;==>_BrowseProc