TComboBox

Description

Combines an edit box with a scrollable list.

Remarks

A TComboBox control is an edit box with a scrollable drop-down list attached to it. Users can select an item from the list or type directly into the edit box.

TComboBox Properties

Property AutoCloseUp: Boolean (R/W)

Specifies whether the drop-down closes up automatically when the user selects an item. When AutoCloseUp is true, the drop-down closes up automatically when the user selects an item.

Property AutoComplete: Boolean (R/W)

Specifies whether the combo box automatically completes words that the user types by selecting the first item that begins with the currently typed string. When AutoComplete is true, the combo box responds to user keystrokes by searching the Items property array for the first item that matches the string entered so far. If it finds an item that begins with the prefix typed so far, the combo box selects that item, "completing" the user's typing. If the user continues to type, selection may move to another, later, item, as the currently typed prefix no longer matches the initial AutoComplete selection. If the user types a string that is not the prefix of a string in the combo box, the string is taken as a unique entry and none of the items in the list are selected. When AutoComplete is false, this feature is disabled. Strings that the user types are taken literally, with no attempt to match them to a string in the combo box. Setting AutoComplete to false is necessary if you want to allow the user to enter a value that is not in the Items list but that is a prefix on one of the items.

Property AutoDropDown: Boolean (R/W)

Specifies whether the drop-down list drops down automatically in response to user keystrokes. When AutoDropDown is true, the combo box automatically drops down its list when the user starts typing a string while the combo box has focus. When AutoDropDown is false, the user must explicitly use the drop-down button to drop down the combo box list.

Property CharCase: Enumerated (ecNormal, ecUpperCase, ecLowerCase) (R/W)

Determines the case of the text in the combo box. Use CharCase to force the contents of the combo box into upper or lower case. When CharCase is set to ecLowerCase or ecUpperCase, the case of characters is converted as the user types into the combo box. Changing the CharCase property changes the actual text, not just its appearance; case information is lost and cannot be recaptured by changing CharCase back to ecNormal.

Property ItemHeight: Integer (R/W)

Specifies the height, in pixels, of the items in the drop-down list. Use ItemHeight to specify the height needed to draw the items in the list when Style is set to csOwnerDrawFixed.

Property Items: TStringList (R)

Provides access to the list of items (strings) in the list portion of the combo box. Read Items to access the list of items that appears in the combo box. Use the methods of Items to add, insert and delete items.

Property MaxLength: Integer (R/W)

Specifies the maximum number of characters the user can type into the edit portion of the combo box. Use MaxLength to limit the number of characters that the user can enter into the edit portion of the combo box. A value of 0 indicates that there is no application-defined limit on the length.

Note: Setting MaxLength will not truncate the existing text, it merely prevents the user from adding more text after reaching the limit of MaxLength characters. Even when MaxLength is 0, there may be limitations imposed by the operating system on the number of characters that may be entered into an edit control.

Property SelLength: Integer (R/W)

Specifies the length, in characters, of the selected text in the edit portion of the combo box. The selected portion of the text in the edit region of the combo box is the string of SelLength characters that starts at the character specified by the SelStart property. The selected text appears highlighted in the edit region of the combo box. To select a section of text in the edit region, first set the SelStart property to position the cursor, and then set SelLength to the number of characters that should be selected. The SelText property is the substring that is selected.

Note: The SelLength property is only valid when the combo box has focus. When the combo box does not have focus, reading SelLength always yields a value of 0, and setting it has no effect.

Property SelLength: String (R/W)

Represents the selected text in the edit region. Read SelText to obtain the text that is selected in the edit region of the combo box. When the combo box is the active control, SelText appears highlighted. Set SelText to replace the current selection with a different substring. If no text is selected when a value is assigned to SelText, the SelText string is inserted in the text at the cursor.

Note: The SelText property is only valid when the combo box has focus. When the combo box does not have focus, reading SelText always yields an empty string and setting it inserts the text at the cursor rather than replacing the selected text.

Property SelStart: Integer (R/W)

Specifies the position of the first selected character in the edit portion of the combo box. Read SelStart to determine where the selection starts in the Text property. The first character is designated with 0, the second with 1, and so on. When SelLength is 0, SelStart is the position of the cursor. Set SelStart to position the cursor in the edit region of the combo box. Setting SelStart to 0 positions the cursor before the first character, setting SelStart to 1 positions the cursor before the second character, and so on.

Note: Setting SelStart changes the SelLength property to 0. When using SelStart and SelLength to programmatically select a portion of the text in the edit region, set SelStart before setting SelLength. The SelStart property is only valid when the combo box has focus. When the combo box does not have focus, reading SelStart always yields a value of 0, and setting it has no effect.

Property Sorted: Boolean (R/W)

Determines whether the list portion of the combo box is alphabetized. Set Sorted to true to sort the items in the Items list alphabetically. New items added to the list while Sorted is true are inserted in the correct alphabetical position. When Sorted is changed from false to true, the original order of the items is lost. Setting Sorted back to false does not restore the original order.

Property Style:eEnumerated (csDropDown, csSimple, csDropDownList) (R/W)

Determines the display style of the combo box. Set Style to specify how the list and edit region of the combo box should appear.

Property DropDownCount: Integer (R/W)

Specifies the maximum number of items displayed in the drop-down list. By default, the drop-down list is long enough to contain eight items without requiring the user to scroll to see them all. To make the drop-down list smaller or larger, specify a number larger or smaller than eight as the DropDownCount value. If the DropDownCount value is larger than the number of items in the Items property, the drop-down list will be just large enough to hold all the possible choices and no more. If the DropDownCount value is smaller then the number of item in the Items property, the drop down list will display a scroll bar.

Property DropedDown: Booelan (R/W)

Indicates whether the drop-down list is currently displayed. Read DroppedDown to determine whether the drop-down list is visible. Set DropDown to drop the list down or close it up. DroppedDown is true when the drop-down list is open, and false when it is closed.

Property ItemIndex: Integer (R/W)

Indicates which item in the drop-down list is selected. Read ItemIndex to determine which item in the list is the selected value in the combo box. This value appears in the edit box portion of the combo box. The first item in the list has index 0, the second item has index 1, and so on. If no item is selected, the value of ItemIndex is -1. Write to ItemIndex to programmatically select an item from the list by passing in the index value.

TComboBox Methods

Method Clear

Deletes all text from the edit box and all items from the Items list. Call Clear to empty the combo box at runtime.

Method ClearSelection

Deselects any selected items in the drop-down list. ClearSelection checks whether an item in the drop-down list is currently selected. If so, it deselects the item (sets ItemIndex to -1), and changes the Text property to an empty string.

Method DeleteSelected

Deletes the selected item from the drop-down list. DeleteSelected deletes the item specified by the ItemIndex property from the drop-down list.

Method SelectAll

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

TComboBox Events

Event OnChange

Occurs when the user changes the text displayed in the edit region. Write an OnChange event handler to take specific action immediately after the user edits the text in the edit region or selects an item from the list. The Text property gives the new value in the edit region.

Note: OnChange only occurs in response to user actions. Changing the Text property programmatically does not trigger an OnChange event.

Event OnCloseUp

Occurs when the drop-down list closes up due to some user action. Write an OnCloseUp event handler to implement special processing that needs to occur when the drop-down list closes up. For example, an OnCloseUp event handler can check whether the user changed the selected item while the list was dropped down and respond accordingly.

Event OnDropDown

Occurs when the user opens the drop-down list. Write an OnDropDown event handler to implement special processing that needs to occur only when the drop-down list is activated.

Event OnSelect

Occurs when the user selects a string in the drop-down list. Write an OnSelect event handler to respond when the user changes the selected item in the drop-down list. OnSelect occurs after the selection has changed and the Text property reflects the new item.