VCL Controls:
The Select Directory Dialog Box

Introduction

An overloaded version of the SelectDirectory() function allows performing a different type of folder selection:

To make available a Select Directory dialog box to your application, you can call the SelectDirectory() function using the following syntax:

bool __fastcall SelectDirectory(AnsiString &Directory,
				TSelectDirOpts Options,
				int HelpCtx);

Like the other SelectDirectory() function, this version returns two values: a Boolean type and a string. Once again, the Directory argument is required, although it is used as a sample that the user can change. Since the root drive is not a directory, you cannot set its value as “C:”, “C:\””, “A:”, “A:\”” or the likes. The Directory value must be a valid path of an existing folder. When the dialog displays, the string of the Directory is selected, which enables the OK and the Cancel buttons. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button2Click(TObject *Sender)
{
	AnsiString Directory = "F:\\Corel\\WordPerfect Office 2002\\Graphics";
	SelectDirectory(Directory, TSelectDirOpts(), 0);
}
//---------------------------------------------------------------------------

On the computer used for this exercise, the function produced:

Notice the absence of a Directory Name edit box.

Once again, the user can change the displaying folder. This time, to proceed, the user would double-click a folder in the Directories tree view to expand the folder. Once the user has located the desired folder, he must click it to highlight it. After selecting a folder, the user would click OK. In this case the function would return true and the path of the folder. Two options not available on the first CreateDirectory() version can be used here. If you want to display the Directory Name edit box, set the TSelectDirOpts option set to at least:

TSelectDirOpts() << sdAllowCreate

If the user wants to use a directory that does not exist, if the directory can be created, add the sdPerformCreate option to the set as follows:

TSelectDirOpts() << sdAllowCreate << sdPerformCreate;

If the user types a directory that does not exist, it would be created transparently. If you want the user to confirm that he wants to create a new folder, add the sdPrompt option to the set. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button2Click(TObject *Sender)
{
	AnsiString Directory = "C:\\Program Files\\Borland\\Delphi4\\Projects";
	SelectDirectory(Directory, TSelectDirOpts() << sdAllowCreate
			<< sdPerformCreate << sdPrompt, 0);
}
//---------------------------------------------------------------------------

The last option allows you to specify a help file to provide context sensitive help to the user. To use it, associate an integer that is mapped to the appropriate identifier in the Help file. Once you set this argument and the application has a help file, a Help button would appear on the dialog box. Here is an example of using the help argument:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button2Click(TObject *Sender)
{
	AnsiString Directory = "C:\\Program Files\\Borland\\Delphi4\\Projects";
	const int HelpMe = 12;
	SelectDirectory(Directory, TSelectDirOpts() << sdAllowCreate
			<< sdPerformCreate << sdPrompt, HelpMe);
}
//---------------------------------------------------------------------------