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

# TCustomListBox

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

The base class for TListBox.

## Declaration

Source position: stdctrls.pp line 537

`type TCustomListBox = class(TWinControl)`
`protected`
`class procedure WSRegisterClass; override;` |  | Registers this component class with the current WidgetSet.
`procedure AssignItemDataToCache(); virtual;` |  | Copies selected state for an item to the cache.
`procedure AssignCacheToItemData(); virtual;` |  | Sends the cached selection state to the widget.
`procedure BeforeDragStart; override;` |  | Notifies the widgetset class that a Drag operation is starting.
`procedure BeginAutoDrag; override;` |  | Starts a non-immediate drag / dock operation for the control.
`function CalculateStandardItemHeight; virtual;` |  | Determines the standard Height of the items, when the widget has yet been created.
`procedure CreateParams(); override;` |  | Initializes the creation parameters for the class instance.
`procedure InitializeWnd; override;` |  | Updates Items from the widgetset class and invalidates the item cache.
`procedure DestroyWnd; override;` |  | Frees the handle for the window and its canvas.
`procedure FinalizeWnd; override;` |  | Caches the Items stored in the widgetset class.
`class function GetControlClassDefaultSize; override;` |  | Returns the default dimensions for new instances of the class.
`procedure CheckIndex();` |  | Ensures that the Item index is within the bounds for the Items in the control.
`function GetItemHeight;` |  | Gets the value for the ItemHeight property.
`function GetItemIndex; virtual;` |  | Gets the value for the ItemIndex property.
`function GetSelCount;` |  | Gets the value for the SelCount property.
`function GetSelected();` |  | Gets the value for the Selected property.
`function GetCachedDataSize; virtual;` |  | Returns the size for cached item data in the control.
`function GetCachedData();` |  | Returns a pointer to the cached item data.
`procedure SetExtendedSelect(); virtual;` |  | Sets the value for the ExtendedSelect property.
`procedure SetItemIndex(); virtual;` |  | Sets the value for the ItemIndex property.
`procedure SetItems(); virtual;` |  | Sets the value for the Items property.
`procedure SetItemHeight();` |  | Sets the value for the ItemHeight property.
`procedure SetMultiSelect(); virtual;` |  | Sets the value for the MultiSelect property.
`procedure SetSelected();` |  | Sets the value for the Selected property.
`procedure SetSorted(); virtual;` |  | Sets the value for the Sorted property.
`procedure SetStyle(); virtual;` |  | Sets the value for the Style property.
`procedure DrawItem(); virtual;` |  | Paints an item in owner-draw mode.
`procedure DoAutoAdjustLayout(); override;` |  | Performs actions needed to auto-adjust the control using the specified layout policy.
`procedure DoSelectionChange(); virtual;` |  | Signals the OnSelectionChange handler.
`procedure SendItemIndex;` |  | Sends the value in ItemIndex to the widgetset class instance.
`procedure WMGetDlgCode(); message;` |  | Handles Tab, Return, Cursor keys, and Escape characters in control messages.
`public`
`constructor Create(); override;` |  | Constructor for the class instance.
`destructor Destroy; override;` |  | Destructor for the class instance.
`procedure AddItem();` |  | Adds an item to the list.
`procedure Click; override;` |  | Performs the Changed method when the control is clicked.
`procedure Clear; virtual;` |  | Removes all items from the list box control.
`procedure ClearSelection;` |  | Unselects all items in the control.
`function GetIndexAtXY();` |  | Gets the index for the item at the given client coordinates.
`function GetIndexAtY();` |  | Gets the index position for the item at the specified vertical coordinate.
`function GetSelectedText;` |  | Get the text for all selected items as a string value.
`function ItemAtPos();` |  | Get the item index for the given client coordinates.
`function ItemRect();` |  | Returns the client rectangle for an item (including scrollbar area).
`function ItemVisible();` |  | Returns True if the item is at least partially visible in the scrollable list.
`function ItemFullyVisible();` |  | Returns True if the item is fully visible in the scrollable list.
`procedure LockSelectionChange;` |  | Blocks selection changes during update to the widgetset class.
`procedure MakeCurrentVisible;` |  | Makes the item at ItemIndex visible, possibly scrolling the list.
`procedure MeasureItem(); virtual;` |  | Gets the height for an item in the list.
`procedure SelectAll; virtual;` |  | Selects all items in the list (in ExtendedSelect mode).
`procedure SelectRange(); virtual;` |  | Changes the selection state for a range of Items in the control.
`procedure DeleteSelected; virtual;` |  | Removes one or more selected entries from the Items property.
`procedure UnlockSelectionChange;` |  | Removes a previous selection change lock.
`property Align: TAlign;` |  | Specifies the placement of the control on its Parent control.
`property Anchors: TAnchors;` |  | The set of anchor definitions for this control.
`property BorderStyle: TBorderStyle;` |  | Line style used for the border on the control.
`property Canvas: TCanvas; [r]` |  | Drawing surface where the control is drawn.
`property ClickOnSelChange: Boolean; [rw]` |  | Allows selection changes to generate a Click event.
`property Columns: Integer; [rw]` |  | The number of visible columns displayed on the control.
`property Constraints: TSizeConstraints;` |  | Contains the minimum and maximum Width and Height for the control.
`property Count: Integer; [r]` |  | The number of items defined in the scrollable list box.
`property ExtendedSelect: Boolean; [rw]` |  | True when a contiguous range of items can be selected using Shift+Click. The default value is True.
`property Font: TFont;` |  | The font to be used for text display in this control.
`property IntegralHeight: Boolean; [rw]` |  | Not implemented: shrink the Height of the widget, so that it only shows fully visible rows.
`property ItemHeight: Integer; [rw]` |  | The default height for an item displayed in the list.
`property ItemIndex: Integer; [rw]` |  | Ordinal position for the currently selected item, -1 if none.
`property Items: TStrings; [rw]` |  | The list of all items defined in the control.
`property MultiSelect: Boolean; [rw]` |  | Allows selection of more than one item from the list.
`property OnChangeBounds: TNotifyEvent;` |  | Event handler signalled when the Bounds for the control have been changed.
`property OnClick: TNotifyEvent;` |  | Notification handler for mouse clicks.
`property OnDblClick: TNotifyEvent;` |  | Event handler signalled when a mouse double click occurs in the control.
`property OnDrawItem: TDrawItemEvent; [rw]` |  | Handler for painting of a list item in owner-draw mode.
`property OnEnter: TNotifyEvent;` |  | Event handler signalled when the control receives focus.
`property OnExit: TNotifyEvent;` |  | Event handler signalled when the control loses focus.
`property OnKeyDown: TKeyEvent;` |  | Event handler signalled for key down keyboard events.
`property OnKeyPress: TKeyPressEvent;` |  | Event handler signalled for character data entered by the user.
`property OnKeyUp: TKeyEvent;` |  | Event handler signalled when a key up event has occurred for the control.
`property OnMeasureItem: TMeasureItemEvent; [rw]` |  | Handler invoked when the height for an item is needed.
`property OnMouseDown: TMouseEvent;` |  | Event handler signalled when a mouse down event is handled for the control.
`property OnMouseEnter: TNotifyEvent;` |  | Event handler signalled when the mouse pointer has entered the control.
`property OnMouseLeave: TNotifyEvent;` |  | Event handler signalled when the mouse pointer has left the control.
`property OnMouseMove: TMouseMoveEvent;` |  | Event handler signalled when the mouse pointer is moved in the control.
`property OnMouseUp: TMouseEvent;` |  | Event handler signalled when a mouse up event is handled for the control.
`property OnMouseWheel: TMouseWheelEvent;` |  | Event handler for mouse wheel turned.
`property OnMouseWheelDown: TMouseWheelUpDownEvent;` |  | Event handler signalled for a downward movement of the mouse wheel.
`property OnMouseWheelUp: TMouseWheelUpDownEvent;` |  | Event handler signalled for an upward movement of the mouse wheel.
`property OnResize: TNotifyEvent;` |  | Notification handler for a resize of the control.
`property OnSelectionChange: TSelectionChangeEvent; [rw]` |  | Handler invoked when an item is selected in the control.
`property OnUTF8KeyPress: TUTF8KeyPressEvent;` |  | Handler for a character entered by the user.
`property Options: TListBoxOptions; [rw]` |  | Contains options enabled for the list box control.
`property ParentColor: Boolean;` |  | Use the Color from the Parent control, when enabled.
`property ParentFont: Boolean;` |  | Indicates if the Font from the Parent control is used in the control.
`property ParentShowHint: Boolean;` |  | If True, the value of ShowHint for the control will be the same as the one from the Parent. Default is True.
`property PopupMenu: TPopupMenu;` |  | A context-sensitive menu that pops up when the right mouse button is clicked over this control.
`property ScrollWidth: Integer; [rw]` |  | The virtual width of the list box, in pixels.
`property SelCount: Integer; [r]` |  | The number of selected items in the list box control.
`property Selected []: Boolean; [rw]` |  | The Selected state for an item in the control.
`property ShowHint: Boolean;` |  | Enables Hint display for the control.
`property Sorted: Boolean; [rw]` |  | Determines whether the list entries are sorted in alphanumeric order.
`property Style: TListBoxStyle; [rw]` |  | Appearance of the list box (standard, owner-draw fixed, or owner-draw variable).
`property TabOrder: TTabOrder;` |  | Indicates the navigation order for the control when the user presses the Tab or Shift+Tab key.
`property TabStop: Boolean;` |  | Enables keyboard navigation using the Tab or Shift+Tab keys.
`property TopIndex: Integer; [rw]` |  | Index of the first visible (or top-most) item.
`property Visible: Boolean;` |  | Allows the control, and all of its children, to be displayed or hidden.
`end;`

## Inheritance

`TCustomListBox` |  | The base class for TListBox.
`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

TCustomListBox is a TWinControl descendant which specifies the base class used for a list box control. A list box displays a scrollable list which allows selection of one or more of the item values.

TCustomListBox provides methods, properties, and events used to display, order, and select item values. The Items for the control can be assigned at design-time in the Lazarus IDE, or stored at run-time. Owner-drawn styles are available to render icons or bitmaps along with the text for the items, or using a variable height for list items. A Canvas property is provided for owner-drawn usage. Items in the list box can be display in one or more columns.

Do not create instances of TCustomListBox; use the TListBox descendant.

## See also

TListBox |  | Control which displays a scrollable list of strings.
TWinControl |  | Implements a windowed control which can contain other child controls.