Browse for Folder
| Function Syntax | (LM:BrowseForFolder <msg> [dir] <bit>) |
| Current Version | 1.3 |
| Download | BrowseForFolderV1-3.lsp |
| View HTML Version | BrowseForFolderV1-3.html |
| Donate |
| Arguments | ||
|---|---|---|
| Symbol | Type | Description |
| msg | String | Message to display at the top of the dialog (may be an empty string) |
| dir | String | (Optional) Root Directory, user cannot navigate above this level |
| bit | Integer | Bit-coded integer controlling the behaviour of the dialog interface (detailed below) |
| Returns | ||
| Type | Description | |
| String | Selected directory, else nil if user presses Cancel | |
Program Description
This function utilises the BrowseForFolder method of the Windows Shell Object to provide a dialog interface through which the user may select a directory. The appearance and behaviour of the dialog displayed to the user may be controlled using the bit-coded third parameter, supplied with values from the table shown below.
Given a valid response, this function will return the full path of the selected directory, with backslash path delimiters and no trailing path delimiter.
If the user presses 'Cancel' when prompted, this function will return nil.
Example Function Call
The following function call will display the dialog as shown in the graphic below, and will return the value shown if the user clicks OK to accept the current selection. If the user clicks Cancel, the function would return nil.
_$ (LM:browseforfolder "Select a folder" "C:\\Test" 0) "C:\\Test\\Test 2"
Values for bit Parameter
The following table lists the bit codes valid for use with the third bit parameter required by the function.
These enumerations may also be found on the MSDN website here.
| Bit | Result |
|---|---|
| 0 | Standard behaviour (Default) |
| 1 | Only file system folders can be selected. If this bit is set, the OK button is disabled if the user selects a folder that doesn't belong to the file system. |
| 2 | The user is prohibited from browsing below the domain within a network |
| 4 | Room for status text is provided under the dialog box |
| 8 | Returns file system ancestors only. An ancestor is a subfolder that is beneath the root folder. If the user selects an ancestor of the root folder that is not part of the file system, the OK button is greyed. |
| 16 | Shows an edit box in the dialog box for the user to type the name of an item. |
| 32 | Validate the name typed in the edit box. |
| 64 | Enable drag-and-drop capability within the dialog box, reordering, shortcut menus, new folders, delete, and other shortcut menu commands. |
| 128 | The browse dialog box can display URLs. |
| 256 | When combined with flag 64, adds a usage hint to the dialog box, in place of the edit box. |
| 512 | Suppresses display of the New Folder button |
| 1024 | When the selected item is a shortcut, return the PIDL of the shortcut itself rather than its target. |
| 4096 | Enables the user to browse the network branch for computer names. If the user selects anything other than a computer, the OK button is greyed. |
| 8192 | Enables the user to browse the network branch for printer names. If the user selects anything other than a printer, the OK button is greyed. |
| 16384 | Allows browsing for everything: the browse dialog box displays files as well as folders. |
| 32768 | If combined with flag 64, the browse dialog box can display shareable resources on remote systems. |
| 65536 | Windows 7 & later: Allow folder junctions such as a library or a compressed file with a .zip file name extension to be browsed. |