CListCtrl Class
Encapsulates the functionality of a "list view control," which displays a collection of items each consisting of an icon (from an image list) and a label.
class CListCtrl : public CWnd
Members
Public Constructors
Name |
Description |
---|---|
Constructs a CListCtrl object. |
Public Methods
Name |
Description |
---|---|
Determines the width and height required to display the items of a list view control. |
|
Aligns items on a grid. |
|
Cancels item text editing operation. |
|
Creates a list control and attaches it to a CListCtrl object. |
|
Creates a drag image list for a specified item. |
|
Creates a list control with the specified Windows extended styles and attaches it to a CListCtrl object. |
|
Deletes all items from the control. |
|
Deletes a column from the list view control. |
|
Deletes an item from the control. |
|
Called when a visual aspect of an owner-draw control changes. |
|
Begins in-place editing of an item's text. |
|
Enables or disables whether the items in a list view control display as a group. |
|
Ensures that an item is visible. |
|
Searches for a list view item having specified characteristics. |
|
Retrieves the background color of a list view control. |
|
Retrieves the current background image of a list view control. |
|
Retrieves the callback mask for a list view control. |
|
Retrieves the current display status of the state image associated with an item. |
|
Retrieves the attributes of a control's column. |
|
Retrieves the column order (left to right) of a list view control. |
|
Retrieves the width of a column in report view or list view. |
|
Calculates the number of items that can fit vertically in a list view control. |
|
Retrieves the handle of the edit control used to edit an item's text. |
|
Retrieves the string to display if the current list-view control is empty. |
|
Retrieves the current extended styles of a list view control. |
|
Retrieves the position of the first selected list view item in a list view control. |
|
Retrieves the group that has the keyboard focus in the current list-view control. |
|
Retrieves the number of groups in the current list-view control. |
|
Gets the information for a specified group of the list view control. |
|
Retrieves information about a specified group in the current list-view control. |
|
Retrieves the metrics of a group. |
|
Retrieves the bounding rectangle for a specified group in the current list-view control. |
|
Retrieves the state for a specified group in the current list-view control. |
|
Retrieves the header control of a list view control. |
|
Retrieves the cursor used when hot tracking is enabled for a list view control. |
|
Retrieves the list view item currently under the cursor. |
|
Retrieves the current hover time of a list view control. |
|
Retrieves the handle of an image list used for drawing list view items. |
|
Retrieves the current position of the insertion mark. |
|
Retrieves the current color of the insertion mark. |
|
Retrieves the rectangle that bounds the insertion point. |
|
Retrieves a list view item's attributes. |
|
Retrieves the number of items in a list view control. |
|
Retrieves the application-specific value associated with an item. |
|
Retrieves the bounding rectangle for all or part of a subitem in the current list-view control. |
|
Retrieves the position of a list view item. |
|
Retrieves the bounding rectangle for an item. |
|
Calculates the spacing between items in the current list-view control. |
|
Retrieves the state of a list view item. |
|
Retrieves the text of a list view item or subitem. |
|
Searches for a list view item with specified properties and with specified relationship to a given item. |
|
Retrieves the index of the item in the current list-view control that has a specified set of properties. |
|
Retrieves the index of a list view item position, and the position of the next selected list view item for iterating. |
|
Retrieves the current number of working areas for a list view control. |
|
Retrieves the current view origin for a list view control. |
|
Retrieves the color of the border of a list view control. |
|
Retrieves the index of the currently selected column in the list control. |
|
Retrieves the number of selected items in the list view control. |
|
Retrieves the selection mark of a list view control. |
|
Determines the minimum column width necessary to display all of a given string. |
|
Retrieves the bounding rectangle of an item in a list view control. |
|
Retrieves the text background color of a list view control. |
|
Retrieves the text color of a list view control. |
|
Retrieves information about a tile in a list view control. |
|
Retrieves information about a list view control in tile view. |
|
Retrieves the tooltip control that the list view control uses to display tooltips. |
|
Retrieves the index of the topmost visible item. |
|
Gets the view of the list view control. |
|
Retrieves the bounding rectangle of all items in the list view control. |
|
Retrieves the current working areas of a list view control. |
|
Determines if the list view control has the specified group. |
|
Determines which list view item is at a specified position. |
|
Inserts a new column in a list view control. |
|
Inserts a group into the list view control. |
|
Inserts the specified group into an ordered list of groups. |
|
Inserts a new item in a list view control. |
|
Retrieves the insertion point closest to a specified point. |
|
Determines whether group view is enabled for a list view control. |
|
Indicates whether a specified item in the current list-view control is visible. |
|
Maps the unique ID of an item in the current list-view control to an index. |
|
Maps the index of an item in the current list-view control to a unique ID. |
|
Moves the specified group. |
|
Moves the specified group to the specified zero based index of the list view control. |
|
Forces a list view control to repaint a range of items. |
|
Removes all groups from a list view control. |
|
Removes the specified group from the list view control. |
|
Scrolls the content of a list view control. |
|
Sets the background color of the list view control. |
|
Sets the current background image of a list view control. |
|
Sets the callback mask for a list view control. |
|
Sets the current display status of the state image associated with an item. |
|
Sets the attributes of a list view column. |
|
Sets the column order (left to right) of a list view control. |
|
Changes the width of a column in report view or list view. |
|
Sets the current extended styles of a list view control. |
|
Sets the information for the specified group of a list view control. |
|
Sets the group metrics of a list view control. |
|
Sets the cursor used when hot tracking is enabled for a list view control. |
|
Sets the current hot item of a list view control. |
|
Sets the current hover time of a list view control. |
|
Sets the spacing between icons in a list view control. |
|
Assigns an image list to a list view control. |
|
Sets the tooltip text. |
|
Sets the insertion point to the defined position. |
|
Sets the color of the insertion point. |
|
Sets some or all of a list view item's attributes. |
|
Prepares a list view control for adding a large number of items. |
|
Sets the item count for a virtual list view control. |
|
Sets the item's application-specific value. |
|
Sets the state of an item in the current list-view control. |
|
Moves an item to a specified position in a list view control. |
|
Changes the state of an item in a list view control. |
|
Changes the text of a list view item or subitem. |
|
Sets the color of the border of a list view control. |
|
Sets the selected column of the list view control. |
|
Sets the selection mark of a list view control. |
|
Sets the background color of text in a list view control. |
|
Sets the text color of a list view control. |
|
Sets the information for a tile of the list view control. |
|
Sets information that a list view control uses in tile view. |
|
Sets the tooltip control that the list view control will use to display tooltips. |
|
Sets the view of the list view control. |
|
Sets the area where icons can be displayed in a list view control. |
|
Sorts the groups of a list view control with a user-defined function. |
|
Sorts list view items using an application-defined comparison function. |
|
Sorts list view items using an application-defined comparison function. |
|
Determines which list view item, if any, is at a given position. |
|
Forces the control to repaint a specified item. |
Remarks
In addition to an icon and label, each item can have information displayed in columns to the right of the icon and label. This control (and therefore the CListCtrl class) is available only to programs running under Windows 95/98 and Windows NT version 3.51 and later.
The following is a brief overview of the CListCtrl class. For a detailed, conceptual discussion, see Using CListCtrl and Controls.
Views
List view controls can display their contents in four different ways, called "views."
Icon view
Each item appears as a full-sized icon (32 x 32 pixels) with a label below it. The user can drag the items to any location in the list view window.
Small icon view
Each item appears as a small icon (16 x 16 pixels) with the label to the right of it. The user can drag the items to any location in the list view window.
List view
Each item appears as a small icon with a label to the right of it. Items are arranged in columns and cannot be dragged to any location in the list view window.
Report view
Each item appears on its own line, with additional information arranged in columns to the right. The leftmost column contains the small icon and label, and subsequent columns contain subitems as specified by the application. An embedded header control (class CHeaderCtrl) implements these columns. For more information on the header control and columns in a report view, see Using CListCtrl: Adding Columns to the Control (Report View).
Also see:
Knowledge Base article Q250614: HOWTO: Sort Items in a CListCtrl in Report View
Knowledge Base article Q200054: PRB: OnTimer() Is Not Called Repeatedly for a List Control
The style of the control's current list view determines the current view. For more information on these styles and their usage, see Using CListCtrl: Changing List Control Styles.
Extended Styles
In addition to the standard list styles, class CListCtrl supports a large set of extended styles, providing enriched functionality. Some examples of this functionality include:
Hover selection
When enabled, allows automatic selection of an item when the cursor remains over the item for a certain period of time.
Virtual list views
When enabled, allows the control to support up to DWORD items. This is possible by placing the overhead of managing item data on the application. Except for the item selection and focus information, all item information must be managed by the application. For more information, see Using CListCtrl: Virtual List Controls.
One– and two– click activation
When enabled, allows hot tracking (automatic highlighting of the item text) and one– or two– click activation of the highlighted item.
Drag and drop column ordering
When enabled, allows drag-and-drop reordering of columns in a list view control. Only available in report view.
For information on using these new extended styles, see Using CListCtrl: Changing List Control Styles.
Items and Subitems
Each item in a list view control consists of an icon (from an image list), a label, a current state, and an application-defined value (referred to as "item data"). One or more subitems can also be associated with each item. A "subitem" is a string that, in report view, can be displayed in a column to the right of an item's icon and label. All items in a list view control must have the same number of subitems.
Class CListCtrl provides several functions for inserting, deleting, finding, and modifying these items. For more information, see CListCtrl::GetItem, CListCtrl::InsertItem, and CListCtrl::FindItem, Using CListCtrl: Adding Items to the Control, and Using CListCtrl: Scrolling, Arranging, Sorting, and Finding in List Controls.
By default, the list view control is responsible for storing an item's icon and text attributes. However, in addition to these item types, class CListCtrl supports "callback items." A "callback item" is a list view item for which the application — rather than the control — stores the text, icon, or both. A callback mask is used to specify which item attributes (text and/or icon) are supplied by the application. If an application uses callback items, it must be able to supply the text and/or icon attributes on demand. Callback items are helpful when your application already maintains some of this information. For more information, see Using CListCtrl: Callback Items and the Callback Mask.
Image Lists
The icons, header item images, and application– defined states for list view items are contained in several image lists (implemented by class CImageList), which you create and assign to the list view control. Each list view control can have up to four different types of image lists:
Large icon
Used in the icon view for full-sized icons.
Small icon
Used in the small icon, list, and report views for smaller versions of the icons used in the icon view.
Application-defined state
Contains state images, which are displayed next to an item's icon to indicate an application-defined state.
Header item
Used in the report view for small images that appear in each header control item.
By default, a list view control destroys the image lists assigned to it when it is destroyed; however, the developer can customize this behavior by destroying each image list when it is no longer used, as determined by the application. For more information, see Using CListCtrl: List Items and Image Lists.
Inheritance Hierarchy
CListCtrl
Requirements
Header: afxcmn.h