The Value List Editor

 

Introduction

The value list editor is list-based control that is used to create an ini list. An ini list is a group of strings in the form Name=Value. Although you can create an ini list manually, the VCL provides a visual mechanism of creating and managing such a list.

The TVisualListEditor Control

To create a list of items of the form Name=Value, you can use a special control, VisualListEditor, which is available from the Additional tab of the Component Palette.

After adding the control to a form or to another container such as a frame or a panel, you can create the actual list using the Strings property. To edit the list, type a string under the Key column and type another string under the Value column.

You can also edit the list in an event as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    // Fill out the Value List Editor with a few strings
    ValueListEditor1->Strings->Add("Maryland=MD");
    ValueListEditor1->Strings->Add("Virginia=VA");
    ValueListEditor1->Strings->Add("District of Columbia=DC");
    ValueListEditor1->Strings->Add("West Virginia=WV");
    ValueListEditor1->Strings->Add("Delaware=DE");
}
//---------------------------------------------------------------------------

Combo Boxes on a Value List Editor

The reason for using the Value List Editor is to allow the user to create or edit the list of items. The user does this by typing the desired strings in the Key and the Value columns. Alternatively, instead of typing the values, you can let the user select the desired value. To do this, you can provide either a combo box or an external dialog box.

To provide a combo box on a Values cell, first create a list, and then assign it to the PickList property of the ItemProps member variable of the TValueListEditor class. When doing this, you must specify on the ItemProps which value will use the combo box. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    // Fill out the Value List Editor with a few strings
    ValueListEditor1->Strings->Add("Maryland=MD");
    ValueListEditor1->Strings->Add("Virginia=VA");
    ValueListEditor1->Strings->Add("District of Columbia=DC");
    ValueListEditor1->Strings->Add("West Virginia=WV");
    ValueListEditor1->Strings->Add("Delaware=DE");

    // Before creating a combo box, create a list of items
    TStringList *ListOfStates = new TStringList;

    ListOfStates->Add("SD");
    ListOfStates->Add("ND");
    ListOfStates->Add("NV");
    ListOfStates->Add("VA");
    ListOfStates->Add("WV");
    ListOfStates->Add("WA");
    ListOfStates->Add("SC");
    ListOfStates->Add("NC");
    ListOfStates->Add("PA");
    ListOfStates->Add("IL");
    ListOfStates->Add("LA");
    ListOfStates->Add("TX");
    ListOfStates->Add("MD");
    ListOfStates->Add("DC");
    ListOfStates->Add("TN");
    ListOfStates->Add("MI");

    // Put a combo box in the second item
    ValueListEditor1->ItemProps[1]->PickList = ListOfStates;
}
//---------------------------------------------------------------------------

Using this approach, you can create different lists or different combo boxes for various Value cells. To do this, you should use the OnGetPickList event. In fact, instead of creating the list of items of a combo box in the OnCreate event of the form, which makes you specify which cell would have the combo box, if you want all Value cells to have a combo box, you can create the list in the OnGetPickList event as follows

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    // Fill out the Value List Editor with a few strings
    ValueListEditor1->Strings->Add("Maryland=MD");
    ValueListEditor1->Strings->Add("Virginia=VA");
    ValueListEditor1->Strings->Add("District of Columbia=DC");
    ValueListEditor1->Strings->Add("West Virginia=WV");
    ValueListEditor1->Strings->Add("Delaware=DE");
}
//---------------------------------------------------------------------------
void __fastcall TForm1::ValueListEditor1GetPickList(TObject *Sender,
      const AnsiString KeyName, TStrings *Values)
{
    Values->Add("SD");
    Values->Add("ND");
    Values->Add("NV");
    Values->Add("VA");
    Values->Add("WV");
    Values->Add("WA");
    Values->Add("SC");
    Values->Add("NC");
    Values->Add("PA");
    Values->Add("IL");
    Values->Add("LA");
    Values->Add("TX");
    Values->Add("MD");
    Values->Add("DC");
    Values->Add("TN");
    Values->Add("MI");
}
//---------------------------------------------------------------------------

In the same way, you can display a list that depends on the string of the Key cell. This allows you to display a combo box only if the Key cell is not empty. This can be done as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::ValueListEditor1GetPickList(TObject *Sender,
      const AnsiString KeyName, TStrings *Values)
{
    if( KeyName == "CAF" )
    {
        Values->Add("Cameroon");
        Values->Add("Senegal");
        Values->Add("Lybia");
        Values->Add("Ghana");
        Values->Add("Tunisia");
    }
    else if( KeyName == "CONCACAF" )
    {
        Values->Add("USA");
        Values->Add("Costa Rica");
        Values->Add("Canada");
        Values->Add("Colombia");
        Values->Add("Nicaragua");
        Values->Add("Jamaica");
    }
    else if( KeyName == "UEFA" )
    {
        Values->Add("Portugal");
        Values->Add("Spain");
        Values->Add("Italy");
        Values->Add("Holland");
    }
    else
    {
        Values->Add("New Zealand");
        Values->Add("Greece");
        Values->Add("Gabon");
    }
}
//---------------------------------------------------------------------------

Ellipsis Buttons on a Value List Editor

To create an ellipsis button, you assign the appropriate style to the EditStyle property of the ItemProps member variable. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    // Fill out the Value List Editor with a few strings
    ValueListEditor1->Strings->Add("Maryland=MD");
    ValueListEditor1->Strings->Add("Virginia=VA");
    ValueListEditor1->Strings->Add("District of Columbia=DC");
    ValueListEditor1->Strings->Add("West Virginia=WV");
    ValueListEditor1->Strings->Add("Delaware=DE");

    // Put an ellipsis button in the 4th item
    ValueListEditor1->ItemProps[3]->EditStyle = esEllipsis;
}
//---------------------------------------------------------------------------

After adding a button to a Value cell, it is your responsibility to specify what would happen when the user clicks it. For example, imagine you want the user to select a file and provide its path as the value of a cell, you can implement this behavior in the TValueListEditor::OnEditButtonClick() event as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::ValueListEditor1EditButtonClick(TObject *Sender)
{
    if( OpenDialog1->Execute() )
        ValueListEditor1->Values["West Virginia"] = "Result=" +
                                                    OpenDialog1->FileName;
}
//---------------------------------------------------------------------------

 


Copyright 2003-2007 FunctionX, Inc.