TCustomComboBox class

In unit StdCtrls

The base class for combo-box components.

Declaration

pascal

TCustomComboBox = class(TWinControl)

Inheritance

Descends from it: TComboBox TCustomCheckCombo TCustomColorBox TCustomComboBoxEx TCustomDBComboBox TCustomFilterComboBox TPickListCellEditor

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

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.

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.

Properties

`ItemHeight`	protected	The default height of an item in the drop-down for the control.
`ItemWidth`	protected	The minimum width of the items in the drop-down list.
`MaxLength`	protected	The maximum length for text entered in the edit box for the control.
`ParentColor`	protected	Uses the Color from the Parent control, when enabled.
`Sorted`	protected	Determines whether the list entries are sorted in alphanumeric order.
`CharCase`	public	Indicates the case conversion applied to the value entered in the edit box for the control.
`DroppedDown`	public	Indicates whether the drop-down list has been displayed.
`AutoComplete`	public	Positions the list box using partial text matching.
`AutoCompleteText`	public	Options for the behavior of the Auto-Complete feature.
`AutoDropDown`	public	Makes the drop-down list appear as soon as the user starts entering text.
`AutoSelect`	public	Selects the entire content of the edit box when the control receives the focus.
`AutoSelected`	public	True indicates that the selection was marked automatically by the control.
`AutoSize`	public	Allows automatic adjustment of the size for the control, according to its content.
`ArrowKeysTraverseList`	public	Indicates if keyboard Arrow (or cursor) keys can be used to move through the list.
`Canvas`	public	Provides access to the drawing surface for the control.
`DropDownCount`	public	The maximum number of Items visible in the drop-down list for the control.
`EmulatedTextHintStatus`	public	Status for the emulated TextHint in the control.
`Items`	public	The list of items displayed in the combo-box control.
`ItemIndex`	public	The index of the currently selected item, or -1 if no item is selected.
`ReadOnly`	public	Disallows free-form entry of Text into the combo-box edit field.
`SelLength`	public	The number of selected UTF-8 characters in the edit box.
`SelStart`	public	zero-based index to the UTF-8 character at the beginning of the selected text in the edit box.
`SelText`	public	The selected text in the edit box for the control.
`Style`	public	Controls the appearance and behavior for the combo-box.
`TabStop`	public	Enables or disables keyboard navigation using the Tab or Shift+Tab keys.
`Text`	public	The value in the edit box for the control.
`TextHint`	public	Default hint text shown when the Text property is empty for the control.

Methods

`WSRegisterClass`	protected	Registers this component class with the current WidgetSet.
`CanShowEmulatedTextHint`	protected	Indicates whether an emulated TextHint can be displayed for the control.
`CreateParams`	protected	Updates the specified creation parameters to include additional flags for the control.
`InitializeWnd`	protected	Synchronizes the control and its widgetset class instance when the handle is created.
`DestroyWnd`	protected	Destroys the handle for the control (and its children).
`DoAutoCompleteSelect`	protected	Selects an item in the control when auto-complete is enabled and activated by a key event.
`DoEnter`	protected	Updates the control when the Enter key is applied.
`DoExit`	protected	Updates the control when the CM_EXIT control message is handled.
`DrawItem`	protected	Draws a list item, using the OnDrawItem handler (when assigned).
`KeyUpAfterInterface`	protected	Handles key up events forwarded from the LCL interface.
`MeasureItem`	protected	Gets the height for an item in the drop-down list.
`GetControlClassDefaultSize`	protected	Returns the default dimensions for new instances of the class.
`LMChanged`	protected	Handles the LM_CHANGED message for the control.
`CMWantSpecialKey`	protected	Handles the CM_WANTSPECIALKEY control message for the control.
`Change`	protected	Signals the OnChange event handler when the value for the control is changed.
`Select`	protected	Signals the OnSelect event handler when ItemIndex is changed.
`DropDown`	protected	Signals the OnDropDown event handler.
`GetItems`	protected	Signals the OnGetItems event handler.
`SetItems`	protected	Sets the value for the Items property.
`CloseUp`	protected	Called when the drop-down list is closed.
`AdjustDropDown`	protected	Adjusts the extent for the drop-down list.
`DoAutoAdjustLayout`	protected	Performs actions needed to auto-adjust the control using the specified layout policy.
`GetItemCount`	protected	Returns the number of items defined in the drop-down list.
`GetItemHeight`	protected	Gets the value for the ItemHeight property.
`GetSelLength`	protected	Gets the value for the SelLength property.
`GetSelStart`	protected	Gets the value for the SelStart property.
`GetSelText`	protected	Gets the value for the SelText property.
`GetItemIndex`	protected	Gets the value for the ItemIndex property.
`GetMaxLength`	protected	Gets the value for the MaxLength property.
`SetDropDownCount`	protected	Sets the value for the DropDownCount property.
`SetDroppedDown`	protected	Sets the value for the DroppedDown property.
`SetItemHeight`	protected	Sets the value for the ItemHeight property.
`SetItemIndex`	protected	Sets the value for the ItemIndex property.
`SetMaxLength`	protected	Sets the value for the MaxLength property.
`SetSelLength`	protected	Sets the value for the SelLength property.
`SetSelStart`	protected	Sets the value for the SelStart property.
`SetSelText`	protected	Sets the value for the SelText property.
`SetSorted`	protected	Sets the value for the Sorted property.
`SetStyle`	protected	Sets the value for the Style property.
`RealGetText`	protected	Gets the text/caption for the control.
`RealSetText`	protected	Updates ItemIndex when the new value for the control is updated.
`KeyDown`	protected	Filters keys used to traverse the list.
`KeyUp`	protected	Handles AutoComplete and AutoSelect for the control.
`UTF8KeyPress`	protected	UTF8KeyPress converts character case if required then calls the inherited method.
`MouseUp`	protected	Highlights the selected text in the control when the left mouse button is released.
`SelectItem`	protected	Selects the list item with the specified text.
`ShouldAutoAdjust`	protected	Indicates if the width and/or height for the control can be adjusted by a layout policy.
`Create`	public	Constructor for the class instance.
`Destroy`	public	Destructor for the class instance.
`IntfGetItems`	public	Gets the values in the Items property for the widgetset class.
`AddItem`	public	Adds the specified string (and optional object) to the Items displayed in the control.
`MatchListItem`	public	Gets the position for the specified value in Items using the AutoCompleteText settings for the control.
`AddHistoryItem`	public	Add an item as the first entry in the history list for the control.
`Clear`	public	Removes all items from the list, and clears the edit box.
`ClearSelection`	public	Removes the item selection in the list box for the control.
`SelectAll`	public	Selects the text content in the edit box for the control.

Events

`OnChange`	protected	Event handler signalled for user changes to the text in the edit box.
`OnCloseUp`	protected	Handler invoked when the drop-down list closes.
`OnDrawItem`	protected	Handler for special painting of an item (in owner-draw mode).
`OnDropDown`	protected	Handler invoked when the list has dropped down.
`OnGetItems`	protected	Handler invoked when widgetset items list can be populated.
`OnMeasureItem`	protected	Handler invoked when the height for an item is needed.
`OnSelect`	protected	Handler invoked when an item is selected.