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);

This function takes three arguments. The Directory specifies the starting point from where to starting listing the folders. This Directory argument is required and it 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. The Options argument specifies some effects you want on the dialog box. If you don't have any, you can pass this argument as TSelectDirOpts(). The HelpCtx is an index from a help file. If you don't have a help file, you can pass this argument as 0. Here is an example:

//---------------------------------------------------------------------------
#include <vcl.h>
#include <FileCtrl.hpp>

#pragma hdrstop

#include "Unit1.h"
//---------------------------------------------------------------------------
#pragma package(smart_init)
#pragma resource "*.dfm"
TForm1 *Form1;

//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
	: TForm(Owner)
{
}
//---------------------------------------------------------------------------
void __fastcall TForm1::mnuFileOpenClick(TObject *Sender)
{
    String strDirectory = "C:\\cic";

    SelectDirectory(strDirectory, TSelectDirOpts(), 0);
}
//---------------------------------------------------------------------------

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

NoNotice 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.

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;

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

//---------------------------------------------------------------------------
void __fastcall TForm1::mnuFileOpenClick(TObject *Sender)
{
	String strDirectory = "C:\\Program Files";

	SelectDirectory(strDirectory,
			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::mnuFileOpenClick(TObject *Sender)
{
	AnsiString Directory = L"C:\\Program Files (x86)";
	const int HelpMe = 12;
	SelectDirectory(Directory,
		        TSelectDirOpts() << sdAllowCreate
			                 << sdPerformCreate
					 << sdPrompt,
			HelpMe);
}
//---------------------------------------------------------------------------