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

# TCustomListView

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

TCustomListView is the base class for TListView.

## Declaration

Source position: comctrls.pp line 1396

`type TCustomListView = class(TWinControl)`
`protected`
`procedure ItemDeleted();` |  | Called when the specified list item is removed from the list.
`procedure ItemInserted();` |  | Performs actions when a list item has been inserted in the Items collection.
`class procedure WSRegisterClass; override;` |  | Registers this component class with the current WidgetSet.
`class function GetControlClassDefaultSize; override;` |  | Gets the default size for new instances of the class.
`procedure InitializeWnd; override;` |  | Calls the inherited method, and sets default values in properties.
`procedure FinalizeWnd; override;` |  | Frees the window handle and other resources for the control.
`procedure DestroyWnd; override;` |  | Destroys the interface object (widget).
`procedure BeginAutoDrag; override;` |  | For internal use: user has started dragging the control.
`function CreateListItem; virtual;` |  | Signals the OnCreateItemClass event handler to get the class type used for new list items, and creates a new list item.
`function CreateListItems; virtual;` |  | Creates a new TListItems instance used in the Items property.
`function CanEdit(); virtual;` |  | Determines if the specified list Item can be edited in the control.
`procedure Change(); virtual;` |  | Change - Internal procedure to simulate the OnChange event.
`function CanChange();` |  | Indicates whether a change notification can be applied for an item on the list view control.
`procedure ColClick(); virtual;` |  | Performs actions to handle a mouse click on a Report view column header.
`procedure Delete(); virtual;` |  | Deletes the specified list item.
`procedure DoDeletion(); virtual;` |  | Performs actions needed to delete the specified list item.
`procedure DoInsert(); virtual;` |  | Performs actions needed to insert the specified list item.
`procedure InsertItem(); virtual;` |  | Inserts an Item into the List.
`procedure DoItemChecked();` |  | Synchronizes the checked state for an item with the widgetset class.
`procedure DoSelectItem(); virtual;` |  | Signals the OnSelectItem event handler when the current selection is changed.
`procedure DoAutoAdjustLayout(); override;` |  | Adjusts the layout for the list view using the specified arguments.
`procedure DoSetBounds(); override;` |  | Set the bounds for the control to the specified values.
`procedure DoEndEdit(); virtual;` |  | Performs actions when editing has been completed for a list item.
`procedure Edit(); virtual;` |  | Signals OnEdited to validate the editor text, and updates the caption for the specified list item.
`procedure ImageChanged();` |  | Implements the event handler signalled when an image on the control is changed.
`procedure Loaded; override;` |  | Performs actions when LCL component streaming is completed for the component.
`procedure Notification(); override;` |  | Handles the notification when a component is added to or removed from the class instance.
`function IsCustomDrawn(); virtual;` |  | Returns True if a target is custom-drawn in the control.
`function CustomDraw(); virtual;` |  | Performs custom drawing in the specified rectangle and returns True on success.
`function CustomDrawItem(); virtual;` |  | Custom draws the specified item and returns True on success.
`function CustomDrawSubItem(); virtual;` |  | Performs custom drawing for the specified sub-item using the event handlers for the control.
`function IntfCustomDraw();` |  | IntfCustomDraw - uses the interface to perform custom drawing
`function GetUpdateCount;` |  | Gets the value for the internal update counter.
`procedure DrawItem();` |  | Draws the specified list item with a given state.
`procedure DoGetOwnerData(); virtual;` |  | Performs actions needed to get list item data when OwnerData is True.
`function DoOwnerDataHint(); virtual;` |  | Signals the OnDataHint event handler (when assigned).
`function DoOwnerDataStateChange(); virtual;` |  | Signals the OnDataStateChange event handler (when assigned).
`function DoOwnerDataFind(); virtual;` |  | Implements incremental search in list items when OwnerData has been enabled.
`FMultiSelList: TIntegerList;` |  | Member used to store the multi-selection list in the class instance.
`function GetFirstSelected;` |  | Gets the first item in the list view with its Selected property set to True.
`procedure InitMultiSelList();` |  | Enables or disables the internal multi-selection list in the control.
`procedure UpdateMultiSelList();` |  | Updates the specified list item in the multi-selection list for the control.
`procedure DblClick; override;` |  | Performs actions needed when the control is double clicked.
`procedure KeyDown(); override;` |  | Handles key down messages for the control.
`property AllocBy: Integer; [rw]` |  | Reduces allocation overhead in the widgetset class by increasing the internal buffer capacity by this block size.
`property AutoSort: Boolean; [rw]` |  | Controls automatic updates to the sort column and order indicator for the control.
`property AutoSortIndicator: Boolean; [rw]` |  | Indicates if the control automatically changes the column and/or order indicator when a column is clicked.
`property AutoWidthLastColumn: Boolean; [rw]` |  | Resizes the last visible column to fill the remaining display area for the control.
`property ColumnClick: Boolean; [rw]` |  | Enables or disables OnColumnClick events for column headers on the control.
`property Columns: TListColumns; [rw]` |  | Collection with the column definitions for the list view control (size, alignment, image index, etc.).
`property DefaultItemHeight: Integer; [rw]` |  | Default height for items displayed on the list view control.
`property HideSelection: Boolean; [rw]` |  | If control looses focus, don't paint selection background for selected item(s).
`property HoverTime: Integer; [rw]` |  | Time (in milliseconds) that the mouse cursor must hover over an item before its tool tip is shown.
`property LargeImages: TCustomImageList; [rw]` |  | Image list which contains "big" icons displayed for view styles on the control.
`property LargeImagesWidth: Integer; [rw]` |  | Contains the Width for the large images used in the list view.
`property OwnerDraw: Boolean; [rw]` |  | Indicates if owner-draw mode is used for the control.
`property ScrollBars: TScrollStyle; [rw]` |  | Specifies the scroll bars visible for the control.
`property ShowColumnHeaders: Boolean; [rw]` |  | Show header area in ListView, which shows captions of columns.
`property ShowWorkAreas: Boolean; [rw]` |  | Indicates if work area captions and highlights are enabled for the control.
`property SmallImages: TCustomImageList; [rw]` |  | Image list which contains "small" icons used for view styles.
`property SmallImagesWidth: Integer; [rw]` |  | Width for the images in the SmallImages property.
`property SortType: TSortType; [rw]` |  | Specifies the sorting mechanism used for the current SortColumn.
`property SortColumn: Integer; [rw]` |  | Ordinal position for the column used to sort the list items, or -1 when not assigned.
`property SortDirection: TSortDirection; [rw]` |  | Sorting direction (order) for the current SortColumn.
`property StateImages: TCustomImageList; [rw]` |  | Image list with the state images for the items on the control.
`property StateImagesWidth: Integer; [rw]` |  | Width of the images in the StateImages property.
`property ToolTips: Boolean; [rw]` |  | Indicates if a hint (tool tip) is automatically displayed for the list item under the mouse cursor.
`property ViewStyle: TViewStyle; [rw]` |  | Sets one of ListView layouts: List (simple column), Report (few columns with full width), Icon (big icons), Small Icon (small icons, 16x16).
`property OnChange: TLVChangeEvent; [rw]` |  | Event handler signalled when the content for a list item is changed.
`property OnChanging: TLVChangingEvent; [rw]` |  | Event handler signalled when a change notification is received for a list item.
`property OnColumnClick: TLVColumnClickEvent; [rw]` |  | Event handler signalled when a column header for the control is clicked.
`property OnCompare: TLVCompareEvent; [rw]` |  | Event handler signalled to compare list items in the CustomSort method.
`property OnCreateItemClass: TLVCreateItemClassEvent; [rw]` |  | Event handler signalled to get the class reference used to create new list view items.
`property OnData: TLVDataEvent; [rw]` |  | Event handler signalled to the value(s) for a list item when OwnerData (virtual mode) has been enabled.
`property OnDataFind: TLVDataFindEvent; [rw]` |  | Event handler signalled to locate list item data when OwnerData (virtual) mode is enabled.
`property OnDataHint: TLVDataHintEvent; [rw]` |  | Event handler signalled to load a range of cached list items in the virtual storage for the control.
`property OnDataStateChange: TLVDataStateChangeEvent; [rw]` |  | Not used in the current LCL version.
`property OnDeletion: TLVDeletedEvent; [rw]` |  | Event handler signalled when a list item is deleted from the Items container.
`property OnEdited: TLVEditedEvent; [rw]` |  | Event handler signalled prior to updating a list item caption when it has been edited in the control.
`property OnEditing: TLVEditingEvent; [rw]` |  | Event handler signalled to determine if editing can be performed for a list item in the control.
`property OnInsert: TLVInsertEvent; [rw]` |  | Event handler signalled when a list item is added to or inserted in the Items for the control.
`property OnItemChecked: TLVCheckedItemEvent; [rw]` |  | Event handler signalled when the Checked property for a list item has been changed.
`property OnSelectItem: TLVSelectItemEvent; [rw]` |  | Event handler signalled when the selected list item for the control is changed.
`property OnCustomDraw: TLVCustomDrawEvent; [rw]` |  | Event handler signalled to perform custom drawing for the list view control.
`property OnCustomDrawItem: TLVCustomDrawItemEvent; [rw]` |  | Event handler signalled to perform custom drawing for list items on the control.
`property OnCustomDrawSubItem: TLVCustomDrawSubItemEvent; [rw]` |  | Event handler signalled to perform custom drawing for list sub-item on the control.
`property OnDrawItem: TLVDrawItemEvent; [rw]` |  | Event handler signalled to render an owner drawn item.
`property OnAdvancedCustomDraw: TLVAdvancedCustomDrawEvent; [rw]` |  | Event handler signalled to custom draw the grid control when the draw state is not cdPrePaint.
`property OnAdvancedCustomDrawItem: TLVAdvancedCustomDrawItemEvent; [rw]` |  | Event handler signalled to custom draw a list item on the grid control when the draw state is not cdPrePaint.
`property OnAdvancedCustomDrawSubItem: TLVAdvancedCustomDrawSubItemEvent; [rw]` |  | Event handler signalled to custom draw list sub-items when the draw stage is not cdPrePaint.
`public`
`constructor Create(); override;` |  | Constructor for the class instance.
`destructor Destroy; override;` |  | Destructor for the class instance.
`procedure AddItem();` |  | Adds a list item with the specified caption and optional object.
`function AlphaSort;` |  | Sorts the first column for the list view control in ascending alphabetic order.
`procedure Sort;` |  | Sorts the values in Items using the SortType, SortColumn, and SortDirection for the control.
`function CustomSort();` |  | Sorts the Items for the list view control using the specified procedure or the OnCompare event handler.
`procedure BeginUpdate;` |  | Starts an update process for the list view control.
`procedure Clear;` |  | Clears the Items for the list view.
`procedure EndUpdate;` |  | Finishes an active update for the list view control.
`procedure Repaint; override;` |  | Immediately redraws the control.
`function FindCaption();` |  | FindCaption- search for and return the list item that contains the nominated caption.
`function FindData();` |  | Locates a list item with a given value starting from the specified position in Items.
`function GetHitTestInfoAt();` |  | Gets hit test information from the widgetset class when its Handle has been assigned.
`function GetItemAt();` |  | Finds and return the list item at the specified coordinates.
`function GetNearestItem();` |  | Locates the list item closest to the specified position.
`function GetNextItem();` |  | Gets the next list item in the given direction from the starting item.
`function GetNextSelected();` |  | Indicates whether a list item following the list item at the specified position can be authoritatively selected for the list view control.
`procedure ClearSelection;` |  | Clears the selected items for the list view control.
`procedure SelectAll;` |  | Selects all Items in the control when MultiSelect has been enabled.
`function IsEditing;` |  | Indicates if the editor is active in the list view control.
`property BoundingRect: TRect; [r]` |  | Coordinates for the rectangle containing the list view control.
`property BorderStyle: TBorderStyle;` |  | Line style drawn as a border around the control.
`property Canvas: TCanvas; [r]` |  | TCanvas instance used to draw the control.
`property Checkboxes: Boolean; [rw]` |  | Displays a check box column for the list items on the control.
`property Column []: TListColumn; [r]` |  | Provides indexed access to the columns defined for the control.
`property ColumnCount: Integer; [r]` |  | The number of defined Columns for the control.
`property DropTarget: TListItem; [rw]` |  | The list item that is the drop target on the control.
`property FlatScrollBars: Boolean; [rw]` |  | Enables scroll bars using a "flat" display style when available for the widgetset.
`property FullDrag: Boolean; [rw]` |  | Indicates whether column headers are redrawn during a column drag or resizing operation.
`property GridLines: Boolean; [rw]` |  | Enables or disables grid lines between rows and columns on the control.
`property HotTrack: Boolean; [rw]` |  | Enables or disables hot tracking selection when the mouse is hovered over an item.
`property HotTrackStyles: TListHotTrackStyles; [rw]` |  | Hot tracking styles enabled for the control.
`property IconOptions: TIconOptions; [rw]` |  | Options for layouts, which show icons. Sets arrangement of icons, text-wrapping state.
`property ItemFocused: TListItem; [rw]` |  | The list item which has focus on the control.
`property ItemIndex: Integer; [rw]` |  | Ordinal position for the selected list item on the control.
`property Items: TListItems; [rw]` |  | Collection of list items displayed on the list view control.
`property MultiSelect: Boolean; [rw]` |  | Allows simultaneous selection of one or more list items using Ctrl+Click, Shift+Click, Ctrl+Shift+Click, or using program code.
`property OwnerData: Boolean; [rw]` |  | Enables or disables owner data (virtual) mode for the list view control.
`property ReadOnly: Boolean; [rw]` |  | Disables editing of list items on the control when set to True.
`property RowSelect: Boolean; [rw]` |  | Indicates if the entire row is highlighted when selected on the list view control.
`property SelCount: Integer; [r]` |  | Number of currently selected Items when MultiSelect is enabled.
`property Selected: TListItem; [rw]` |  | Contains the selected list item in the list view control.
`property LastSelected: TListItem; [r]` |  | Contains the list item that was the most recently selected item on the control.
`property TabStop: Boolean;` |  | Allows navigation to and from the control by pressing the Tab or Shift+Tab keys.
`property TopItem: TListItem; [r]` |  | The list item which is displayed at the top of the list view control.
`property ViewOrigin: TPoint; [rw]` |  | Coordinate with the left/top visible point for the list items on the control.
`property VisibleRowCount: Integer; [r]` |  | Number of visible rows using the size, position, and layout for the list view control.
`end;`

## Inheritance

`TCustomListView` |  | TCustomListView is the base class for TListView.
`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

TCustomListView is the base class for TListView. It provides a multi-platform implementation of the List View control from the Windows API. TCustomListView allows a collection of items to be displayed using different view styles. For instance:

Icon View
  Each list item has an large icon with a caption.
Small Icon View
  Each list item has a small icon with a caption.
List View
  Each list item has a small icon with a caption, and is displayed in a single column in the control.
Report View
  Each list item is displayed on a single line, with sub-items displayed as additional columns. The first column has a small icon and a caption. Other columns contain the text for the sub-items.

Remark: | TCustomListView does not implement some features available for Windows version 6 or higher, including: the Tile View style, List View Item Grouping, and List View Work Areas.