Opening a dialog to browse for a folder ¶

browse_for_folder()

Open a dialog to browse for a folder or filename

Contents

Opening a dialog to browse for a folder
- Illustration
- Flags

SYNTAX

browse_for_folder(window_id, parameter_record )

Opens a dialog enabling the user to browse for a folder. The dialog uses a tree view control and returns the name of the selected folder. It can also be used to browse for a filename. The dialog is terminated when the user either makes a selection or cancels the operation.

The function returns the name of the folder or file selected. This is blank if the dialog was cancelled without anything being chosen.

A sample program, browse_for_folder.r, is provided in the directory $SCULPTOR\examples. This program can be used to test all combinations of flags and root pathnames.

window_id

The identifier of the window that is to be the parent of the dialog window. This must be provided. In practice the main task window wintask can always be used. The only effect of using a different window is to change the position of the dialog.

parameter_record

The identifier of a !record structure to be used to provide parameters for the function call. The record should be defined as follows:

!record record_id {
    Title,,a80
    DisplayName,,a80
    Flags,,i4
    RootIDL,,i4
    RootPath,,a255
}

Fields that are not required can be omitted. In this case their value, if required by the function, is taken to be zero or blank.

Title	A text string that is displayed above the tree in the dialog window. This feature can be used to provide instructions such as “Please select a folder in which to save this document”. The a80 size is arbitrary; the field can be larger or smaller.
DisplayName	This field receives the name of the selected file or folder, without path information. It is blank if the user cancels the dialog. The a80 size is arbitrary; the field can be larger or smaller. It should however be large enough to receive the name of any object that can be selected.
Flags	Option flags. If this field is missing or set to zero, the default options are used. See Flags below.
RootIDL	The root folder for the dialog. This is an integer type field. If it is zero or missing, the folder specified in RootPath is used. Otherwise RootIDL should be set to one of the values defined in files.h with the prefix CSIDL_. These define standard Windows folders. If the standard folder requested does not exist on the system, the default root path (the desktop) is used. Note the special flag CSIDL_FLAG_CREATE, which is used with another value to force folder creation. Values are combined by use of the “\|” operator.
RootPath	If RootIDL is zero or missing, this field provides the path of the folder to be used as the root folder. Either “/” or “\” can be used as a directory separator, but note that in a string constant the “\” character must be escaped by entering it as “\\”.

Illustration ¶

The illustration shows the function running with all flags off. The text “Please select a folder.” has been assigned to the Title, and the RootIDL is CSIDL_DESKTOP.

Flags ¶

Any non-default options that are required should be specified in the Flags field. These options are listed in the include file $SCULPTOR/include/files.h, and have the prefix BIF_. If more than one option flag is required, the flags should be separated by the | character, e.g.

BIF_NEWDIALOGSTYLE | BIF_UAHINT

If none of the available options is required, the Flags field, if present in the parameter_record, should be set to zero.

All flags are off by default.

The options are listed below with a brief description. For more information, refer to the Microsoft SHBrowseForFolder function,

BIF_BROWSEFORCOMPUTER	Browse for a computer. Only a computer can be returned. If the user selects anything other than a computer, the OK button is greyed.
BIF_BROWSEFORPRINTER	Browse for a printer. If the user selects anything other than a printer, the OK button is greyed.
BIF_BROWSEINCLUDEFILES	Browse for files and folders. Unless this flag is set, only folders are included in the listing. If it is set, the program must determine the type of the returned object. The Sculptor function fileinfo() can be used for this purpose.
BIF_BROWSEINCLUDEURLS	The browse dialog box can display URLs. If this flag is set, the new dialog style is used automatically. BIF_BROWSEINCLUDEFILES must also be set, or the browser dialog box will reject URLS. Note that URLs will only be displayed if the folder that contains the selected item supports them.
BIF_DONTGOBELOWDOMAIN	Do not include network folders below the domain level in the tree view control (for example, My Computer and My Networks).
BIF_EDITBOX	Include an edit box that allows the user to type the name of an item.
BIF_NEWDIALOGSTYLE	Use the new user interface. The dialog window is larger and can be resized. The dialog box also has several new capabilities, including drag and drop within the dialog, reordering and shortcut menus. A “Make New Folder” button is included by default on platforms that support it. See BIF_NONEWFOLDERBUTTON below.
BIF_NONEWFOLDERBUTTON	Exclude the “Make New Folder” button. Valid only with BIF_NEWDIALOGSTYLE. See the note below about variation between platforms.
BIF_NOTRANSLATETARGETS	When the selected item is a shortcut, return the PIDL of the shortcut itself rather than its target.
BIF_RETURNFSANCESTORS	Return file system ancestors only. 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 greyed.
BIF_RETURNONLYFSDIRS	Return file system directories only (physical locations), not pseudo-folders like My Network Place. If the user selects folders that are not part of the file system, the OK button is greyed.
BIF_UAHINT	When combined with BIF_NEWDIALOGSTYLE, adds a usage hint to the dialog box in place of the edit box. BIF_EDITBOX overrides this flag.

NOTES

The browse_for_folder() function is a direct interface to a Windows control than can behave differently depending on the version of Windows and, in some cases, on the version of Internet Explorer that is installed. In general, simple browsing for a file or directory with the default flags works in the same way on all systems. For more complex folder browsing, refer to the Microsoft documentation for the SHBrowseForFolder() function and test on all the platforms that are to be supported.

Note in particular that the BIF_NEWDIALOGSTYLE flag creates a “New Folder” button on platforms that support it, but the BIF_NONEWFOLDERBUTTON flag, which causes this button to be omitted, is not supported on some platforms that support BIF_NEWDIALOGSTYLE.

EXAMPLE

Browse for a folder, starting in My Computer, using the new dialog style without a “Make New Folder” button:

!record BFFParams {
     Title,,a8
     DisplayName,,a80
     Flags,,i4
     RootIDL,,i4
     RootPath,,a255
}

!temp SelectedPath,,a255

     ...
     BFFParams.Flags = BIF_NEWDIALOGSTYLE | BIF_NONEWFOLDERBUTTON
     BFFParams.RootIDL = CSIDL_DRIVES
     BFFParams.Title = "Please select a folder."
     tmp.SelectedPath = browse_for_folder(wintask, BFFParams)