ListBox Class

A list box control displays a list of items from which the user can select one or more items. If the number of items exceeds the number that can be displayed, a vertical scroll bar is automatically added to the list box.

If no item is selected, the listIndex property value is -1. The first item in the list has a listIndex of 1, and the listCount method returns the number of items in the list. The text property returns the text for the currently selected item.

When multiple items are currently selected, the value of the listIndex property is the last of the items selected. One or more items can be selected, with the value of the listIndex property being none of those items (for example, when you select an item, press the Shift key and select another item, then press the Ctrl key and remove the selection of one of the previously selected items).

It is much more efficient to copy a GUI value into a local variable for reuse rather than request the value again. For example, listBox.listCount requires the calling of a list box method to retrieve the value. Storing the value in a local property for reuse avoids a significant overhead for the second and subsequent requests for that value when it will not change. The first of the following examples is much more expensive than the second of these examples.

while count <= listBox.listCount do  // inefficient use of the variable

vars                                 // recommended use of the variable
    listBoxCount : Integer;
begin
    listBoxCount := listBox.listCount;
    while count <= listBoxCount do
        ...
    endwhile;
end;

If the width of any displayed item exceeds the width of the list box and the scrollHorizontal property is set to 1 (automatic), a horizontal scroll bar is added to the list box. The scroll ranges for the list box are set automatically and cannot be changed. For details about the support of mouse wheel requests to scroll up, down, or across a list box control, see "Window Class", earlier in this document. A list box can have a maximum of 32,000 items.

Press Ctrl+Home to move a list box with an associated collection to the first entry in the collection. Conversely, press Ctrl+End to move the display to the last entry in the collection.

Pressing the Home key on a list box moves the display to the first entry that has been loaded in the control. Pressing the End key moves the display to the last entry currently loaded in the control. Using the Ctrl key for a list box that does not have a collection attached has the same result as pressing the Home or End key without the Ctrl key. For details about dragging the scroll bar thumb of a list box when an Array, Dictionary, or Set collection is attached to the list box, see the displayCollection method.

If the list item entry in a list box is too long to fit in the list, bubble help showing the complete text is automatically displayed over the text portion of the entry when the mouse is moved over that entry. Bubble help is no longer displayed if the mouse is moved off that entry or after approximately three seconds.

Clicking on the bubble help generates a click event for that list entry.

The automatic display of bubble help does not occur if the list box already has bubble help defined (by using the Window::bubbleHelp property).

To disable the automatic bubble help for a list box, set the bubbleHelp property of that control to a space.

For the arrays associated with list boxes (for example, itemBackColor), the only methods that are implemented are at, atPut (which enables you to use the square brackets notation to access the elements), createIterator (which allows logic to do a foreach over the array), size, and size64.