Introduction

To help you visually get a list of directories of a drive and/or a list of sub-directories, the VCL provides the directory list box. In the Win 3.1 section of the Toolbox, the directory list box is represented by the TDirectoryListBox control . In the VCL, this control is represented by a class of the same name.

1. Start Embarcadero RAD Studio
2. To create a new project, on the main menu, click File -> New -> VCL Forms Application - C++Builder
3. Change the Caption of the form to File Viewer
4. On the main menu, click File -> New -> Other
5. On the main menu, click File -> New -> Other
6. In the right list of the New Items dialog box, double-click Frame
7. Notice the name on the tab of the new frame
8. In the top section of the Code Edirtor, click Unit1.cpp
9. In the Standard section of the Tool Palette, click Frame and click the form
10. In the Select Frame to Insert dialog box, select the name of the new frame (it should be the last in the list) and click OK
11. In the top section of the Code Editor, click the UnitX.cpp of the last frame
12. In the Tool Palette, click Win 3.1
13. Click the TDriveComboBox button and click inside the frame
14. Press F9 to execute
15. Click the down-point button of the drive combo box
16. Close the form and return to your programming environment

1. In the Win 3.1 section of the Tool Palette, click the TDirectoryListBox control and click inside the frame
2. Adjust the design as follows:
    
   

A directory list box appears as a list with folders based on a parent directory:

To use a directory list box, a user should first select or identify a drive. The directory list box itself doesn't provide a means of changing a drive. To provide this functionality, you can add a drive combo box:

If you have both a drive combo box and a directory list box, you should "connect" them so that, when a drive is selected in the drive combo box, its contents would display in the directory list box. To support this, the TDriveComboBox class is equipped with a property named DirList and that is of type TDirectoryListBox::

__property Filectrl::TDirectoryListBox * DirList =
                   {read=FDirList,write=SetDirListBox};

1. In the frame, click the drive combo box to select it
2. In the Object Inspector, click DirList and select DirectoryListBox1
3. Press F9 to execute
4. Change a drive in the combo box
5. Close the form and return to your programming environment

To visually connect these controls, in the Object Inspector of the drive combo box, select the directory list box in the DirList field. After doing this, before using the directory list box, the user can first select a drive in the drive combo box. To help you identify the drive that is currently selected, the TDirectoryListBox class is equipped with a Drive property:

__property wchar_t Drive = {read=GetDrive,write=SetDrive};

This property produces a character that represents the selected drive. As opposed to the user selecting a drive, you too can programmatically select one. To do this, assign its character to this property. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnSelectDriveClick(TObject *Sender)
{
	DirectoryListBox1->Drive = L'E:\\';
}
//---------------------------------------------------------------------------

If you use this property in its write version, make sure the drive you specify exists. Otherwise, you may receive an EInOutError exception (Invalid File Name):

To use a directory list box, the user can click a directory to select it. When this is done, the control fires an OnChange event:

__property TNotifyEvent OnChange;

To show the contents of a directory, the user can double-click it. This causes the control to call its OpenCurrent() method. Its syntax is:

void __fastcall OpenCurrent(void);

Because this is a public method, you too can call it at any time to open a directory from the directory list box. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnOpenDirectoryClick(TObject *Sender)
{
	DirectoryListBox1->OpenCurrent();
}
//---------------------------------------------------------------------------

When a user double-click a directory to open, the directory that was selected in stored in the Directory property:

__property System::UnicodeString Directory =
  		{read=GetDirectory,write=SetDirectory};

Here is an example of getting the value of this property:

//---------------------------------------------------------------------------
void __fastcall TForm1::DirectoryListBox1Change(TObject *Sender)
{
	ShowMessage(DirectoryListBox1->Directory);
}
//---------------------------------------------------------------------------

If you want to show the complete path of the directory that is currently selected, you can add a label to your form. To make this label display the directory, the TDirectoryListBox class is equipped with a property named DirLabel:

__property Stdctrls::TLabel * DirLabel = {read=FDirLabel,write=SetDirLabel};

At design time, add a TLabel control to your form and in the Object Inspector of the directory list box, select the name of the label in the DirLabel field.

On the other hand, to programmatically select a directory, assign the desired path to the TDirectoryListBox::Directory property. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnChangeDirectoryClick(TObject *Sender)
{
	DirectoryListBox1->Directory = L"C:\\Exercise1\\App_Data";
}
//---------------------------------------------------------------------------

1. On the Tool Palette, click Standard
2. Click the TLabel control and click inside the frame under the directory list box
    
   
3. In the frame, click the directory list box to select it
4. In the Object Inspector, click DirLabel and select Label1
5. Press F9 to execute
6. Change a drive in the combo box
7. Close the form and return to your programming environment