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.

To add an item to a list

Use the addItem or addItemAt method.

To delete an item from a list

Use the removeItem method.

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.

You can implement filtering of combo box and list box entries to enable users to locate a required list item more quickly, using standard combo box and list box facilities to achieve this filtering. (For details, see "Filtering Entries in Combo Box and List Box Text", in Chapter 2 of the Development Environment User's Guide.) You can achieve the filtering of entries in your own Jade systems, as follows.

Set the value of the style property for the ComboBox control class to ComboBox.Style_DropDown (0).
Set the value of the ListBox control hasPictures, hasTreeLines, and hasPlusMinus properties to false.
The value of the sorted property must be set to false after the list is loaded.
A disabled description list item is added as the first entry in the list (after sorting is turned off).
The change event on the combo box or associated text box calls a filtering routine to hide or show the entries based on the new text entered. Setting the level of the item to 2 hides the entries, which is why there has to be an entry at item position 1 that is always at level 1. (A child item must have a parent.)

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.

From Jade release 2022.0.03, you can enable or disable Microsoft UI Automation accessibility features for ListBox and Table controls by using the AccessibilityUIAEnabled parameter in the [Jade] section of the Jade initialization file.

For a summary of the constants, properties, methods, and events defined in the ListBox class, see "ListBox Class Constants", "ListBox Properties", "ListBox Methods", and "ListBox Events", later in this section. See also "Setting Properties for Individual Items in a List Box", "Using a List Box to Display a Hierarchy or Tree", and "Copying Text from a List Box", in the following subsections.