Main List Box Functions and Properties

Important Functions

void __fastcall Clear(void);

Use Clear to delete all of the items in the list box at once. Although the items in a standard list box are of type TStrings, use the Clear method of the list box rather than calling the Clear method of the Items property. This allows descendants of TCustomListBox to perform any other necessary clean-up in the Clear method, in addition to deleting the items from the Items property. Thus, applications should use

ListBox1->Clear();
rather than
ListBox1->Items->Clear();
int __fastcall ItemAtPos(const tagPOINT &Pos, bool Existing);

Use ItemAtPos to detect if an item exists at a particular point in the control.

The Pos parameter is the point in the control in window coordinates. If Pos is beyond the last item in the list box, the value of the Existing variable determines the returned value. If Existing is set to true, ItemAtPos returns -1, indicating that no item exists at that point. If Existing is set to false, ItemAtPos returns the index of the last item in the list box plus one.

DYNAMIC void __fastcall DeleteString(int Index);
DeleteString deletes the string specified by the Index parameter from list box control.
DYNAMIC int __fastcall GetItemData(int Index);
Use GetItemData to retrieve the data associated with a particular item in a list box. This value can be displayed as that list box item, or can be a value (such as a pointer) associated with the list box item.
DYNAMIC void __fastcall SetItemData(int Index, int AData);
Use SetItemData to set the data associated with a particular item in a list box. This value can be displayed as that list box item, or it can be a value (such as a pointer) represented by the list box item.

Important Properties

int ItemIndex

Use ItemIndex to select an item at runtime. Set the value of ItemIndex to the index of the item to be selected. The ItemIndex of the first item in the list box is 0. If no item is selected, the value is -1, which is the default value unless MultiSelect is true.

If the value of the MultiSelect property is true the user can select more than one item in the list box. In this case, the ItemIndex value is the index of the selected item that has focus. If MultiSelect is true, ItemIndex defaults to 0.

bool MultiSelect

Set MultiSelect to true to allow the user to select multiple items. If MultiSelect if false, multiple items cannot be selected in the list box at the same time.

MultiSelect allows users to select multiple non-sequential items. It does not allow users to select a range of items in one operation, as does the ExtendedSelect property.

When MultiSelect is true and multiple items are selected, the value of the ItemIndex property, which indicates the index of the Selected item, is the index of the selected item that has focus.

bool ExtendedSelect

ExtendedSelect works with the MultiSelect property. If ExtendedSelect is true and MultiSelect is true, the user can select an item then hold down the Shift key and select another and all the items in between the two selected items also become selected.

If the user doesn’t hold down the Shift or Ctrl key while selecting a second item, the first selected item becomes unselected—in other words, the user must use the Ctrl key to select multiple noncontiguous items, or the Shift key to select a range of items.

If ExtendedSelect is false and MultiSelect is true, the user can select multiple items without using the Shift or Ctrl key, but they can’t select a range of items in one operation.

If MultiSelect is false, the setting of ExtendedSelect has no effect as the user will not be able to select more than one item at a time in the list box.

int SelCount

SelCount is read-only. Use SelCount to find the number of selected items in the list box when the MultiSelect property is true.

When the MultiSelect property is false, SelCount is always -1.

TStrings* Items

Use Items to add, insert, delete and move items. By default, the items in a list box are of type TStrings. Use this item type to access its methods or properties to manipulate the items in the list.

TStrings Methods

virtual int __fastcall Add(const System::AnsiString S);
Call Add to add a string to the end of the list. Add returns the index of the new string.
virtual int __fastcall AddObject(const System::AnsiString S, System::TObject* AObject);
Call AddObject to add a string and its associated object to the list. AddObject returns the index of the new string and object.
virtual void __fastcall Insert(int Index, const System::AnsiString S) = 0;

Descendants of TStrings implement an Insert method to add the string S to the list at the position specified by Index. If Index is 0, the string is inserted at the beginning of the list. If Index is 1, the string is put in the second position of the list, and so on.

All methods that add strings to the list use the Insert method to add the string.

If the string has an associated object, use the InsertObject method instead.

void __fastcall InsertObject(int Index, const System::AnsiString S, System:: TObject* AObject);
Call InsertObject to insert the string S into the list at the position identified by Index, and associate it with the object AObject. If Index is 0, the string is inserted at the beginning of the list. If Index is 1, the string is put in the second position of the list, and so on.
virtual void __fastcall Move(int CurIndex, int NewIndex);

Use Move to move the string at position CurIndex so that it occupies the position NewIndex. The positions are specified as 0-based indexes. For example, the following line of code moves the string in the first position to the last position.

MyStringsObject->Move(0, MyStringsObject->Count - 1);

If the string has an associated object, the object remains associated with the string in its new position.

TSrings Properties

int Count

Descendants of TStrings implement a Count property to indicate the number of strings in the list.

Use the Count property when iterating over all the strings in the list, or when trying to locate the position of a string relative to the last string in the list.

System::AnsiString Strings[int Index]

Descendants of TStrings must implement an accessor function for the Strings property to return the string at the position indicated by Index. Index gives the position of the string, where 0 is the first string, 1 is the second string, and so on.

Use the Strings property to get or set the string at a particular position.

System::AnsiString Text

Use Text to get or set all the strings in the TStrings object in a single string delimited by carriage return, line feed pairs.

When reading Text, the strings in the list will be separated by carriage return, line feed pairs. If any of the strings in the list contain a carriage return and line feed pair, the resulting value of Text will appear to contain more strings than is indicated by the Count property.

When setting Text, the value will be parsed by separating into substrings whenever a carriage return or linefeed is encountered. (The two do not need to form pairs).

If the strings in the list contain carriage return or linefeed characters, a less ambiguous format for the strings is available through the CommaText property.

Examples

The following examples illustrate the use of some of these methods and properties.