Home

VCL Controls: The Directory List Box

   

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 Directory List Box. In the VCL, this control is represented by a class of the same name.

 

Practical LearningPractical Learning: Introducing the Directory List Box

  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 Drive Combo Box 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

 

Practical LearningPractical Learning: Adding a Directory List Box

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

Using a Directory List Box

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

Directory List Box

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:

Directory List 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};

Practical LearningPractical Learning: Adding a Directory List Box

  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

The Drive of a Directory List Box

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

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;

Opening the Current Directory

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();
}
//---------------------------------------------------------------------------

The Current Directory

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

Showing the Selected 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";
}
//---------------------------------------------------------------------------

Practical LearningPractical Learning: Adding a Label

  1. On the Tool Palette, click Standard
  2. Click the TLabel control Directory List Box and click inside the frame under the directory list box
     
    File Viewer
  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
 
 
 

Home Copyright © 2010-2011 FunctionX, Inc.