The GetFolder() function defined in COA2's Coafuncs.pas module uses the SHBrowseForFolder() API function to display the familiar folder-selection tree dialog. Using SHBrowseForFolder() isn't as simple as arranging for file selection with a TOpenDialog component, but there are many opportunities to customize the dialog to work exactly as you wish.
SHBrowseForFolder() takes a data structure of the Windows-defined type TBrowseInfo as its only argument, and returns a PIDL (pronounced piddle)-a pointer to an Item ID List. Like a pathname, a PIDL identifies a folder or other object within the Windows shell's name space. But where a pathname can refer only to an existing file or folder, a PIDL also can identify a virtual object, such as Control Panel. COA2 deals only with existing files or folders but has to reference them through a PIDL.
GetFolder() defines a variable of type TBrowseInfo and initializes its data fields to control the behavior of the folder-selection tree. GetFolder() requests a folder tree rooted at My Computer, specifies the dialog title and starting folder, and identifies a callback procedure that will be used for communication between the dialog and COA2.
The ulFlags field of the TBrowseInfo structure holds a large number of bit flags that define specific behaviors for the dialog, some of which are only available under a particular version of the Windows shell. GetFolder() starts with three basic flags that are valid in all shell versions: BIF_RETURNONLYFSDIRS forces the dialog to return only file-system folders, not virtual folders.BIF_DONTGOBELOWDOMAIN prevents the dialog from including network folders below the domain level.BIF_STATUSTEXT provides the dialog with a status line.
Version 4.71 of the Windows shell, introduced with IE4, adds the option to include an edit box in the dialog, allowing users to enter full pathnames directly ( Figure 6 ). If the shell version is 4.71 or later, GetFolders() includes the flags BIF_EDITBOX, which adds the edit box, and BIF_VALIDATE, which prevents the dialog from accepting an invalid folder name in the edit box. Version 5.0 of the shell, provided with Windows 2000, Windows Me, and IE5, changes the user interface for the dialog substantially. The new dialog style, invoked using the BIF_NEWDIALOGSTYLE flag, is resizable and supports a number of context-menu commands ( Figure 7 ).
The SHBrowseForFolder() function doesn't return until the user clicks OK or Cancel. If the returned PIDL is non-nil, GetFolder() calls the API function SHGetPathFromIDList() to convert the PIDL into a path. Note that both the returned PIDL and the My Computer PIDL obtained earlier must be freed by calling the API function CoTaskMemFree().