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 useListBox1->Clear();
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The following examples illustrate the use of some of these methods and properties.