ComboBox Class

A combo box control combines the features of a TextBox control and a ListBox control. Use a combo box to give the user the choice of typing in the text box portion or selecting an item from the list portion of the control. As the ComboBox class is a subclass of the Control class, it inherits all of the properties and methods defined in the Control class and Window class.

If the ComboBox class with a style other than Style_Simple or Style_DropDown accepts text, the entry that is alphabetically less than or equal to the entered text is selected, without issuing an event. The user then has only to enter as much as required to uniquely identify a specific entry. (You can enter text in Style_Simple or Style_DropDown combo boxes that does not relate to the entries in the list. For more details, see the style property.)

If the combo box list is open, the Esc key closes the combo box list. In addition, the Alt+UpArrow shortcut keys action closes the combo box list when it has focus and the Alt+DownArrow shortcut keys action opens the combo box list when it has focus.

If the form has a Button control with the cancel property set to true and the open combo box has focus, the Esc key is processed by the combo box; not by the Cancel button. The Cancel button action occurs only if the combo box list is not open.

The alternatingRowBackColor and alternatingRowBackColorCount properties are available only for the ListBox control and the JadeTableSheet class, and they do not exist for a ComboBox control. However, you can achieve the alternating style on a combo box by using a skin. If a ComboBox skin references a ListBox skin that has the alternatingRowBackColorCount property value set (that is, it is greater than zero (0)) for the list box, the value of the alternatingRowBackColor list box skin property is used to draw the alternating background colors of the displayed combo box list.

A combo box, which is case‑insensitive, can have a maximum of 32,000 items, although the maximum number of entries displayed in the list portion of the control is 20.

It is much more efficient to copy a GUI value into a local variable for reuse rather than request the value again; for example, comboBox.listCount requires the calling of a combo 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 <= comboBox.listCount do  // inefficient use of the variable

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

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 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.)

For a combo box, the click event is not normally implemented. The selection action is performed on the closeup event so that nothing happens until the user completes the selection action.

If the list item entry in a combo box is too long to fit in the list box portion of the control, 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 combo box already has bubble help defined (by using the Window class bubbleHelp property).

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

Keystrokes that are entered while the list box area of a combo box has focus are concatenated into a string for searching the contents of the list box. For example, when you entering the letter T followed by the letter O, focus goes to the entry whose text began with T and then to an entry beginning with TO, provided that you enter the letter O within one second of the letter T. If the gap between the entry of the letters T and O is more than one second, focus goes to an entry whose text begins with T and then to an entry beginning with O. However, if the first character of the sequence is repeated (that is, the letter T in this example), the search finds the next entry that starts with that character (which is treated like two T characters separated by more than one second). For example, if you have list items 6001, 6002, 6601, and 6602 and you quickly enter 66, 6001 is first selected and then 6002, so that you can access each list item rather than going directly from 6001 to 6601.

The resulting search string for a series of keystrokes can be of any length, provided there is less than one second gap between each keystroke.

To implement the handling of a ComboBox control to achieve the same functionality as the default Table class InputType_ComboBox value, only the following is required when the combo box entries are already loaded:

In the click event for the combo box:
```
table1.text := combo1.text
```
In the cellInputReady event for the table:
```
combo1.text := table1.text
```

For the arrays associated with combo 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.

For more details, see the Table class inputType and cellControl properties. See also the Control class automaticCellControl property.

As the combo box can have the functionality of a ListBox control, see also "Setting Properties for Individual Items in a List Box" and "Using a List Box to Display a Hierarchy or Tree", later in this document.

From Jade release 2022.0.03, scroll bars and spin‑style (Style_SpinBox) combo boxes support accessibility by exposing each of their child elements including names, locations, and values.

For a summary of the constants, properties, methods, and events defined in the ComboBox class, see "ComboBox Class Constants", "ComboBox Properties", "ComboBox Methods", and "ComboBox Events", in the following subsections.

For details about the support of mouse wheel requests to scroll up, down, or across a combo box control, see "Window Class", earlier in this document.