[Overview][Constants][Types][Classes][Procedures and functions][Index] | Reference for unit 'StdCtrls' (#lcl)

# TCustomComboBox

[Properties (by Name)] [Methods (by Name)] [Events (by Name)]

The base class for combo-box components.

## Declaration

Source position: stdctrls.pp line 289

`type TCustomComboBox = class(TWinControl)`
`protected`
`class procedure WSRegisterClass; override;` |  | Registers this component class with the current WidgetSet.
`function CanShowEmulatedTextHint; virtual;` |  | Indicates whether an emulated TextHint can be displayed for the control.
`procedure CreateParams(); override;` |  | Updates the specified creation parameters to include additional flags for the control.
`procedure InitializeWnd; override;` |  | Synchronizes the control and its widgetset class instance when the handle is created.
`procedure DestroyWnd; override;` |  | Destroys the handle for the control (and its children).
`procedure DoAutoCompleteSelect; virtual;` |  | Selects an item in the control when auto-complete is enabled and activated by a key event.
`procedure DoEnter; override;` |  | Updates the control when the Enter key is applied.
`procedure DoExit; override;` |  | Updates the control when the CM_EXIT control message is handled.
`procedure DrawItem(); virtual;` |  | Draws a list item, using the OnDrawItem handler (when assigned).
`procedure KeyUpAfterInterface(); override;` |  | Handles key up events forwarded from the LCL interface.
`procedure MeasureItem(); virtual;` |  | Gets the height for an item in the drop-down list.
`class function GetControlClassDefaultSize; override;` |  | Returns the default dimensions for new instances of the class.
`procedure LMChanged(); message;` |  | Handles the LM_CHANGED message for the control.
`procedure CMWantSpecialKey(); message;` |  | Handles the CM_WANTSPECIALKEY control message for the control.
`procedure Change; virtual;` |  | Signals the OnChange event handler when the value for the control is changed.
`procedure Select; virtual;` |  | Signals the OnSelect event handler when ItemIndex is changed.
`procedure DropDown; virtual;` |  | Signals the OnDropDown event handler.
`procedure GetItems; virtual;` |  | Signals the OnGetItems event handler.
`procedure SetItems(); virtual;` |  | Sets the value for the Items property.
`procedure CloseUp; virtual;` |  | Called when the drop-down list is closed.
`procedure AdjustDropDown; virtual;` |  | Adjusts the extent for the drop-down list.
`procedure DoAutoAdjustLayout(); override;` |  | Performs actions needed to auto-adjust the control using the specified layout policy.
`function GetItemCount;` |  | Returns the number of items defined in the drop-down list.
`function GetItemHeight; virtual;` |  | Gets the value for the ItemHeight property.
`function GetSelLength; virtual;` |  | Gets the value for the SelLength property.
`function GetSelStart; virtual;` |  | Gets the value for the SelStart property.
`function GetSelText; virtual;` |  | Gets the value for the SelText property.
`function GetItemIndex; virtual;` |  | Gets the value for the ItemIndex property.
`function GetMaxLength; virtual;` |  | Gets the value for the MaxLength property.
`procedure SetDropDownCount(); virtual;` |  | Sets the value for the DropDownCount property.
`procedure SetDroppedDown(); virtual;` |  | Sets the value for the DroppedDown property.
`procedure SetItemHeight(); virtual;` |  | Sets the value for the ItemHeight property.
`procedure SetItemIndex(); virtual;` |  | Sets the value for the ItemIndex property.
`procedure SetMaxLength(); virtual;` |  | Sets the value for the MaxLength property.
`procedure SetSelLength(); virtual;` |  | Sets the value for the SelLength property.
`procedure SetSelStart(); virtual;` |  | Sets the value for the SelStart property.
`procedure SetSelText(); virtual;` |  | Sets the value for the SelText property.
`procedure SetSorted(); virtual;` |  | Sets the value for the Sorted property.
`procedure SetStyle(); virtual;` |  | Sets the value for the Style property.
`function RealGetText; override;` |  | Gets the text/caption for the control.
`procedure RealSetText(); override;` |  | Updates ItemIndex when the new value for the control is updated.
`procedure KeyDown(); override;` |  | Filters keys used to traverse the list.
`procedure KeyUp(); override;` |  | Handles AutoComplete and AutoSelect for the control.
`procedure UTF8KeyPress(); override;` |  | UTF8KeyPress converts character case if required then calls the inherited method.
`procedure MouseUp(); override;` |  | Highlights the selected text in the control when the left mouse button is released.
`function SelectItem();` |  | Selects the list item with the specified text.
`procedure ShouldAutoAdjust(); override;` |  | Indicates if the width and/or height for the control can be adjusted by a layout policy.
`property ItemHeight: Integer; [rw]` |  | The default height of an item in the drop-down for the control.
`property ItemWidth: Integer; [rw]` |  | The minimum width of the items in the drop-down list.
`property MaxLength: Integer; [rw]` |  | The maximum length for text entered in the edit box for the control.
`property OnChange: TNotifyEvent; [rw]` |  | Event handler signalled for user changes to the text in the edit box.
`property OnCloseUp: TNotifyEvent; [rw]` |  | Handler invoked when the drop-down list closes.
`property OnDrawItem: TDrawItemEvent; [rw]` |  | Handler for special painting of an item (in owner-draw mode).
`property OnDropDown: TNotifyEvent; [rw]` |  | Handler invoked when the list has dropped down.
`property OnGetItems: TNotifyEvent; [rw]` |  | Handler invoked when widgetset items list can be populated.
`property OnMeasureItem: TMeasureItemEvent; [rw]` |  | Handler invoked when the height for an item is needed.
`property OnSelect: TNotifyEvent; [rw]` |  | Handler invoked when an item is selected.
`property ParentColor: Boolean;` |  | Uses the Color from the Parent control, when enabled.
`property Sorted: Boolean; [rw]` |  | Determines whether the list entries are sorted in alphanumeric order.
`public`
`constructor Create(); override;` |  | Constructor for the class instance.
`destructor Destroy; override;` |  | Destructor for the class instance.
`procedure IntfGetItems;` |  | Gets the values in the Items property for the widgetset class.
`procedure AddItem(); virtual;` |  | Adds the specified string (and optional object) to the Items displayed in the control.
`function MatchListItem();` |  | Gets the position for the specified value in Items using the AutoCompleteText settings for the control.
`procedure AddHistoryItem();` |  | Add an item as the first entry in the history list for the control.
`procedure Clear; virtual;` |  | Removes all items from the list, and clears the edit box.
`procedure ClearSelection;` |  | Removes the item selection in the list box for the control.
`property CharCase: TEditCharCase; [rw]` |  | Indicates the case conversion applied to the value entered in the edit box for the control.
`property DroppedDown: Boolean; [rw]` |  | Indicates whether the drop-down list has been displayed.
`procedure SelectAll;` |  | Selects the text content in the edit box for the control.
`property AutoComplete: Boolean; [rw]` |  | Positions the list box using partial text matching.
`property AutoCompleteText: TComboBoxAutoCompleteText; [rw]` |  | Options for the behavior of the Auto-Complete feature.
`property AutoDropDown: Boolean; [rw]` |  | Makes the drop-down list appear as soon as the user starts entering text.
`property AutoSelect: Boolean; [rw]` |  | Selects the entire content of the edit box when the control receives the focus.
`property AutoSelected: Boolean; [rw]` |  | True indicates that the selection was marked automatically by the control.
`property AutoSize: Boolean;` |  | Allows automatic adjustment of the size for the control, according to its content.
`property ArrowKeysTraverseList: Boolean; [rw]` |  | Indicates if keyboard Arrow (or cursor) keys can be used to move through the list.
`property Canvas: TCanvas; [r]` |  | Provides access to the drawing surface for the control.
`property DropDownCount: Integer; [rw]` |  | The maximum number of Items visible in the drop-down list for the control.
`property EmulatedTextHintStatus: TEmulatedTextHintStatus; [r]` |  | Status for the emulated TextHint in the control.
`property Items: TStrings; [rw]` |  | The list of items displayed in the combo-box control.
`property ItemIndex: Integer; [rw]` |  | The index of the currently selected item, or -1 if no item is selected.
`property ReadOnly: Boolean; [rw]` |  | Disallows free-form entry of Text into the combo-box edit field.
`property SelLength: Integer; [rw]` |  | The number of selected UTF-8 characters in the edit box.
`property SelStart: Integer; [rw]` |  | zero-based index to the UTF-8 character at the beginning of the selected text in the edit box.
`property SelText: string; [rw]` |  | The selected text in the edit box for the control.
`property Style: TComboBoxStyle; [rw]` |  | Controls the appearance and behavior for the combo-box.
`property TabStop: Boolean;` |  | Enables or disables keyboard navigation using the Tab or Shift+Tab keys.
`property Text: TCaption;` |  | The value in the edit box for the control.
`property TextHint: TTranslateString; [rw]` |  | Default hint text shown when the Text property is empty for the control.
`end;`

## Inheritance

`TCustomComboBox` |  | The base class for combo-box components.
`TWinControl` |  | Implements a windowed control which can contain other child controls.
`TControl` |  | The base class for visible controls.
`TLCLComponent` |  | The base class for LCL components which have an associated widget.
`TComponent`
?
`TObject`

## Description

TCustomComboBox is a TWinControl descendant which implements the base class for combo-box components in the LCL (Lazarus Component Library).

A combo-box is visually represented as an edit control and a scrollable list of items which can be selected. The list can always be visible, or opened when needed using a drop-down indicator. In addition, the items displayed on the control be drawn using using the built-in mechanisms for the widgetset class or using an owner-drawn style.

Despite similarities in appearance to TCustomEdit and TCustomList, the class inherits no properties from these classes (Delphi compatible).

Use Items to access the entries displayed in the drop-down list. Use AddItem or AddHistoryItem to add entries to the list of items. Use OnGetItems to dynamically populate the Items in the control when the drop-down list is displayed.

The selectable values in Items can be maintained at design-time by clicking on the ellipsis character (...) displayed next to Items in the Object Inspector.

The Text property reflects the text entered directly into the edit box, or selected either manually or by auto-completion from the Items in the list. At run-time, the entry selected from the list replaces the text in the edit box, and ItemIndex holds the (zero-based) index number of the selected item. If no value is selected from the drop-down list, the default text (if any) remains for any information typed directly into the control Text, and ItemIndex takes the value of -1.

Use Style to control the display style and drawing mechanism enabled for the drop-down list on the control.

Use AutoDropDown, AutoComplete, AutoCompleteText, and AutoDropDown to control the behavior of the edit box and its interaction with the drop-down list on the control.

Use ItemHeight and ItemWidth to control the appearance for the Items displayed on the drop-down list.

Do not create instances of TCustomComboBox. Use one of the descendent classes, like TComboBox or TComboBoxEx.

Remark: | The Height property in TCustomComboBox / TComboBox cannot be changed for some platforms, including Windows and macOS. It is best to set AutoSize to True to ensure consistent size handling on the supported platforms.

Remark: | Changing the value in BorderStyle to bsNone has no effect for the Windows widgetset. It is not possible to remove the border on the Windows platform.

## See also

TComboBox |  | Implements a control with an edit box and a drop-down list allowing one of several options to be chosen.
TWinControl
TComboBoxEx |  | Implements an extended combo-box component.