TCustomListBox class

In unit StdCtrls

The base class for TListBox.

Declaration

pascal

TCustomListBox = class(TWinControl)

Inheritance

Descends from it: TCustomCheckListBox TCustomColorListBox TCustomDBListBox TCustomFileListBox TListBox

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.

At design time, a click on the ellipsis character (...) next to the Items entry in the Object Inspector opens a string-list editor in which the individual text-strings for the list items can be entered or edited. The editor also allows the entries to be sorted alphabetically in normal or reverse order.

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 displayed in one or more columns.

Use the Styles property to enable owner-drawn styles (with either fixed or variable height list items) or the "virtual mode" where the items displayed on the control are provided by event handlers. Use the OnMeasureItem and OnDrawItem event handlers to measure and render the owner-drawn list items. Use the Canvas property when needed to implement an owner-drawn style.

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

Properties

`Align`	public	Specifies the placement of the control on its Parent control.
`Anchors`	public	The set of anchor definitions for this control.
`BorderStyle`	public	Line style used for the border on the control.
`Canvas`	public	Drawing surface where the control is drawn.
`ClickOnSelChange`	public	Allows selection changes to generate a Click event.
`Columns`	public	The number of visible columns displayed on the control.
`Constraints`	public	Contains the minimum and maximum Width and Height for the control.
`Count`	public	The number of list items defined for the scrollable list box.
`ExtendedSelect`	public	True when a contiguous range of items can be selected using Shift+Click. The default value is True.
`Font`	public	The font to be used for text display in this control.
`IntegralHeight`	public	Not implemented: shrink the Height of the widget, so that it only shows fully visible rows.
`ItemHeight`	public	The default height for an item displayed in the list.
`ItemIndex`	public	Ordinal position for the currently selected item, -1 if none.
`Items`	public	The list of items defined for the control.
`MultiSelect`	public	Allows selection of more than one item from the list.
`Options`	public	Contains options enabled for the list box control.
`ParentColor`	public	Use the Color from the Parent control, when enabled.
`ParentFont`	public	Indicates if the Font from the Parent control is used in the control.
`ParentShowHint`	public	If True, the value of ShowHint for the control will be the same as the one from the Parent. Default is True.
`PopupMenu`	public	A context-sensitive menu that pops up when the right mouse button is clicked over this control.
`ScrollWidth`	public	The virtual width of the list box, in pixels.
`SelCount`	public	The number of selected items in the list box control.
`Selected`	public	The Selected state for an item in the control.
`ShowHint`	public	Enables Hint display for the control.
`Sorted`	public	Determines whether the list entries are sorted in alphanumeric order.
`Style`	public	Controls the appearance of items on the list box control and indicates whether the control uses "virtual mode".
`TabOrder`	public	Indicates the navigation order for the control when the user presses the Tab or Shift+Tab key.
`TabStop`	public	Enables keyboard navigation using the Tab or Shift+Tab keys.
`TopIndex`	public	Index of the first visible (or top-most) item.
`Visible`	public	Allows the control, and all of its children, to be displayed or hidden.

Methods

`WSRegisterClass`	protected	Registers this component class with the current WidgetSet.
`AssignItemDataToCache`	protected	Copies selected state for an item to the cache.
`AssignCacheToItemData`	protected	Sends the cached selection state to the widget.
`BeforeDragStart`	protected	Notifies the widgetset class that a Drag operation is starting.
`BeginAutoDrag`	protected	Starts a non-immediate drag / dock operation for the control.
`CalculateStandardItemHeight`	protected	Determines the standard Height of the items, when the widget has yet been created.
`CreateParams`	protected	Initializes the creation parameters for the class instance.
`InitializeWnd`	protected	Updates Items from the widgetset class and invalidates the item cache.
`DestroyWnd`	protected	Frees the handle for the window and its canvas.
`FinalizeWnd`	protected	Caches the Items stored in the widgetset class.
`GetControlClassDefaultSize`	protected	Returns the default dimensions for new instances of the class.
`CheckIndex`	protected	Ensures that the Item index is within the bounds for the Items in the control.
`GetItemHeight`	protected	Gets the value for the ItemHeight property.
`GetItemIndex`	protected	Gets the value for the ItemIndex property.
`GetSelCount`	protected	Gets the value for the SelCount property.
`GetSelected`	protected	Gets the value for the Selected property.
`GetCachedDataSize`	protected	Returns the size for cached item data in the control.
`GetCachedData`	protected	Returns a pointer to the cached item data.
`SetExtendedSelect`	protected	Sets the value for the ExtendedSelect property.
`SetItemIndex`	protected	Sets the value for the ItemIndex property.
`SetItems`	protected	Sets the value for the Items property.
`SetItemHeight`	protected	Sets the value for the ItemHeight property.
`SetMultiSelect`	protected	Sets the value for the MultiSelect property.
`SetSelected`	protected	Sets the value for the Selected property.
`SetSorted`	protected	Sets the value for the Sorted property.
`SetStyle`	protected	Sets the value for the Style property.
`DrawItem`	protected	Paints an item in owner-draw mode.
`DoAutoAdjustLayout`	protected	Performs actions needed to auto-adjust the control using the specified layout policy.
`DoSelectionChange`	protected	Signals the OnSelectionChange handler.
`SendItemIndex`	protected	Sends the value in ItemIndex to the widgetset class instance.
`WMGetDlgCode`	protected	Handles Tab, Return, Cursor keys, and Escape characters in control messages.
`Create`	public	Constructor for the class instance.
`Destroy`	public	Destructor for the class instance.
`AddItem`	public	Adds an item to the list.
`Click`	public	Performs the Changed method when the control is clicked.
`Clear`	public	Removes all items from the list box control.
`ClearSelection`	public	Unselects all items in the control.
`GetIndexAtXY`	public	Gets the index for the item at the given client coordinates.
`GetIndexAtY`	public	Gets the index position for the item at the specified vertical coordinate.
`GetSelectedText`	public	Get the text for all selected items as a string value.
`ItemAtPos`	public	Get the item index for the given client coordinates.
`ItemRect`	public	Returns the client rectangle for an item (including scrollbar area).
`ItemVisible`	public	Returns True if the item is at least partially visible in the scrollable list.
`ItemFullyVisible`	public	Returns True if the item is fully visible in the scrollable list.
`LockSelectionChange`	public	Blocks selection changes during update to the widgetset class.
`MakeCurrentVisible`	public	Makes the item at ItemIndex visible, possibly scrolling the list.
`MeasureItem`	public	Gets the height for an item in the list.
`SelectAll`	public	Selects all items in the list (in ExtendedSelect mode).
`SelectRange`	public	Changes the selection state for a range of Items in the control.
`DeleteSelected`	public	Removes one or more selected entries from the Items property.
`UnlockSelectionChange`	public	Removes a previous selection change lock.

Events

`OnData`	public	Event handler signalled to provide the data for a "virtual" item on the list box control.
`OnDataObject`	public	Event handler signalled to get the TObject instance with the data for a "virtual" item on the list box control. Not used in the current LCL version.
`OnDataFind`	public	Event handler signalled to get the ordinal position for a virtual list item with the specified string value. Not used in the current LCL version.
`OnChangeBounds`	public	Event handler signalled when the Bounds for the control have been changed.
`OnClick`	public	Notification handler for mouse clicks.
`OnDblClick`	public	Event handler signalled when a mouse double click occurs in the control.
`OnDrawItem`	public	Handler for painting of a list item in owner-draw mode.
`OnEnter`	public	Event handler signalled when the control receives focus.
`OnExit`	public	Event handler signalled when the control loses focus.
`OnKeyDown`	public	Event handler signalled for key down keyboard events.
`OnKeyPress`	public	Event handler signalled for character data entered by the user.
`OnKeyUp`	public	Event handler signalled when a key up event has occurred for the control.
`OnMeasureItem`	public	Handler invoked when the height for an item is needed.
`OnMouseDown`	public	Event handler signalled when a mouse down event is handled for the control.
`OnMouseEnter`	public	Event handler signalled when the mouse pointer has entered the control.
`OnMouseLeave`	public	Event handler signalled when the mouse pointer has left the control.
`OnMouseMove`	public	Event handler signalled when the mouse pointer is moved in the control.
`OnMouseUp`	public	Event handler signalled when a mouse up event is handled for the control.
`OnMouseWheel`	public	Event handler for mouse wheel turned.
`OnMouseWheelDown`	public	Event handler signalled for a downward movement of the mouse wheel.
`OnMouseWheelUp`	public	Event handler signalled for an upward movement of the mouse wheel.
`OnResize`	public	Notification handler for a resize of the control.
`OnSelectionChange`	public	Handler invoked when an item is selected in the control.
`OnUTF8KeyPress`	public	Handler for a character entered by the user.