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.

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;

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:

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