TListBox

Description

Displays a collection of items in a scrollable list.

Remarks

Use TListBox to display a scrollable list of items that users can select, add, or delete.

TListBox Properties

Property AutoComplete: Boolean (R/W)

Determines whether the user can give focus to items by typing in the list. Use AutoComplete to specify whether the list box automatically updates the ItemIndex property in response to user keystrokes. When AutoComplete is true, the item with focus changes to the first item that begins with the sequence of characters that the user typed. As the user types more characters, ItemIndex may change to a later item because the string to match becomes longer.

Property Columns: Integer (R/W)

Specifies the number of columns, in a multi-column list box, that are visible without having to scroll. Use Columns to specify the number of columns, in a multi-column list box, that are visible without having to use the horizontal scroll bar. Multi-column list boxes have a horizontal scroll bar that allows users to view multiple columns as they wrap. The default value for Columns is 0, meaning that the list box is not multi-column. That is, users can scroll only vertically and the list of items will not wrap. For Columns values greater than 0, multiple columns accommodate the items as they wrap beyond the bottom of the list box. The Columns property specifies the number of columns that are visible without having to horizontally scroll the list box. The width of each column depends upon both the Width property and the number of Columns.

Property Count: Integer (R)

Indicates the number of items in the list box. Use Count to determine the number of items in the list box.

Property ExtendedSelect: Boolean (R/W)

Determines if the user can select a sequential range of items in the list box.

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.

Property ItemIndex: Integer (R/W)

Specifies the ordinal number of the selected item in the list box's item list. 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.

Property Items: TStringList (R)

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

Property MultiSelect: Boolean (R/W)

Determines whether the user can select more than one element at a time. 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.

Property SelCount: Integer (R)

Indicates the number of items that are selected when multiple selections are allowed. 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.

Property Selected(Index: integer): Boolean (R/W)

Indicates whether a particular item is selected. Use Selected to query the state of a particular item in the list box. If the item specified by the Index parameter is selected in the list box, the value of the Selected property is true. If the specified item is not selected, Selected is false. Set Selected to change the currently selected item.

The Index parameter is the item referenced by its position in the list box, with the first item having an Index value of 0. An item is selected when the user highlights it. More than one item in the list box can be selected by setting the MultiSelect property to true. In this case, the Selected item is the one that has focus when the list box has input focus.

Property Sorted: Boolean (R/W)

Specifies whether the items in a list box are arranged alphabetically. Use Sorted to sort the items by setting its value to true. If Sorted is false, the items are unsorted. When Sorted is true, items are automatically added or inserted into the list box in alphabetical order.

Property TopIndex: Integer (R/W)

Specifies the index number of the item that appears at the top of the list box. Use TopIndex property to find or set the first item displayed at the top of the list box. TopIndex can be used, for example, to change the topmost item to a different item in the list.

TListBox Methods

Method Clear

Deletes all items from the list box. Use Clear to delete all of the items in the list box at once.

Method ClearSelection

Deselects all selected items in the list box, if possible. Use ClearSelection to deselect all the currently selected items in the list box. When the list box receives focus, after ClearSelection is called, the last item that was selected is the item that receives the current focus in the list box. Although this item receives focus, the item itself is not selected.

Method DeleteSelected

Deletes the selected items from the list box. Call DeleteSelected to delete the selected items from the list box.

Method SelectAll

Selects the entire block of text in the list box. Use SelectAll to select the entire block of text in the list box. To select only part of the text, use the SelStart and SelLength properties.