CListCtrl Class

Article
01/08/2013

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
CListCtrl::CListCtrl	Constructs a CListCtrl object.

Public Methods

Name	Description
CListCtrl::ApproximateViewRect	Determines the width and height required to display the items of a list view control.
CListCtrl::Arrange	Aligns items on a grid.
CListCtrl::CancelEditLabel	Cancels item text editing operation.
CListCtrl::Create	Creates a list control and attaches it to a CListCtrl object.
CListCtrl::CreateDragImage	Creates a drag image list for a specified item.
CListCtrl::CreateEx	Creates a list control with the specified Windows extended styles and attaches it to a CListCtrl object.
CListCtrl::DeleteAllItems	Deletes all items from the control.
CListCtrl::DeleteColumn	Deletes a column from the list view control.
CListCtrl::DeleteItem	Deletes an item from the control.
CListCtrl::DrawItem	Called when a visual aspect of an owner-draw control changes.
CListCtrl::EditLabel	Begins in-place editing of an item's text.
CListCtrl::EnableGroupView	Enables or disables whether the items in a list view control display as a group.
CListCtrl::EnsureVisible	Ensures that an item is visible.
CListCtrl::FindItem	Searches for a list view item having specified characteristics.
CListCtrl::GetBkColor	Retrieves the background color of a list view control.
CListCtrl::GetBkImage	Retrieves the current background image of a list view control.
CListCtrl::GetCallbackMask	Retrieves the callback mask for a list view control.
CListCtrl::GetCheck	Retrieves the current display status of the state image associated with an item.
CListCtrl::GetColumn	Retrieves the attributes of a control's column.
CListCtrl::GetColumnOrderArray	Retrieves the column order (left to right) of a list view control.
CListCtrl::GetColumnWidth	Retrieves the width of a column in report view or list view.
CListCtrl::GetCountPerPage	Calculates the number of items that can fit vertically in a list view control.
CListCtrl::GetEditControl	Retrieves the handle of the edit control used to edit an item's text.
CListCtrl::GetEmptyText	Retrieves the string to display if the current list-view control is empty.
CListCtrl::GetExtendedStyle	Retrieves the current extended styles of a list view control.
CListCtrl::GetFirstSelectedItemPosition	Retrieves the position of the first selected list view item in a list view control.
CListCtrl::GetFocusedGroup	Retrieves the group that has the keyboard focus in the current list-view control.
CListCtrl::GetGroupCount	Retrieves the number of groups in the current list-view control.
CListCtrl::GetGroupInfo	Gets the information for a specified group of the list view control.
CListCtrl::GetGroupInfoByIndex	Retrieves information about a specified group in the current list-view control.
CListCtrl::GetGroupMetrics	Retrieves the metrics of a group.
CListCtrl::GetGroupRect	Retrieves the bounding rectangle for a specified group in the current list-view control.
CListCtrl::GetGroupState	Retrieves the state for a specified group in the current list-view control.
CListCtrl::GetHeaderCtrl	Retrieves the header control of a list view control.
CListCtrl::GetHotCursor	Retrieves the cursor used when hot tracking is enabled for a list view control.
CListCtrl::GetHotItem	Retrieves the list view item currently under the cursor.
CListCtrl::GetHoverTime	Retrieves the current hover time of a list view control.
CListCtrl::GetImageList	Retrieves the handle of an image list used for drawing list view items.
CListCtrl::GetInsertMark	Retrieves the current position of the insertion mark.
CListCtrl::GetInsertMarkColor	Retrieves the current color of the insertion mark.
CListCtrl::GetInsertMarkRect	Retrieves the rectangle that bounds the insertion point.
CListCtrl::GetItem	Retrieves a list view item's attributes.
CListCtrl::GetItemCount	Retrieves the number of items in a list view control.
CListCtrl::GetItemData	Retrieves the application-specific value associated with an item.
CListCtrl::GetItemIndexRect	Retrieves the bounding rectangle for all or part of a subitem in the current list-view control.
CListCtrl::GetItemPosition	Retrieves the position of a list view item.
CListCtrl::GetItemRect	Retrieves the bounding rectangle for an item.
CListCtrl::GetItemSpacing	Calculates the spacing between items in the current list-view control.
CListCtrl::GetItemState	Retrieves the state of a list view item.
CListCtrl::GetItemText	Retrieves the text of a list view item or subitem.
CListCtrl::GetNextItem	Searches for a list view item with specified properties and with specified relationship to a given item.
CListCtrl::GetNextItemIndex	Retrieves the index of the item in the current list-view control that has a specified set of properties.
CListCtrl::GetNextSelectedItem	Retrieves the index of a list view item position, and the position of the next selected list view item for iterating.
CListCtrl::GetNumberOfWorkAreas	Retrieves the current number of working areas for a list view control.
CListCtrl::GetOrigin	Retrieves the current view origin for a list view control.
CListCtrl::GetOutlineColor	Retrieves the color of the border of a list view control.
CListCtrl::GetSelectedColumn	Retrieves the index of the currently selected column in the list control.
CListCtrl::GetSelectedCount	Retrieves the number of selected items in the list view control.
CListCtrl::GetSelectionMark	Retrieves the selection mark of a list view control.
CListCtrl::GetStringWidth	Determines the minimum column width necessary to display all of a given string.
CListCtrl::GetSubItemRect	Retrieves the bounding rectangle of an item in a list view control.
CListCtrl::GetTextBkColor	Retrieves the text background color of a list view control.
CListCtrl::GetTextColor	Retrieves the text color of a list view control.
CListCtrl::GetTileInfo	Retrieves information about a tile in a list view control.
CListCtrl::GetTileViewInfo	Retrieves information about a list view control in tile view.
CListCtrl::GetToolTips	Retrieves the tooltip control that the list view control uses to display tooltips.
CListCtrl::GetTopIndex	Retrieves the index of the topmost visible item.
CListCtrl::GetView	Gets the view of the list view control.
CListCtrl::GetViewRect	Retrieves the bounding rectangle of all items in the list view control.
CListCtrl::GetWorkAreas	Retrieves the current working areas of a list view control.
CListCtrl::HasGroup	Determines if the list view control has the specified group.
CListCtrl::HitTest	Determines which list view item is at a specified position.
CListCtrl::InsertColumn	Inserts a new column in a list view control.
CListCtrl::InsertGroup	Inserts a group into the list view control.
CListCtrl::InsertGroupSorted	Inserts the specified group into an ordered list of groups.
CListCtrl::InsertItem	Inserts a new item in a list view control.
CListCtrl::InsertMarkHitTest	Retrieves the insertion point closest to a specified point.
CListCtrl::IsGroupViewEnabled	Determines whether group view is enabled for a list view control.
CListCtrl::IsItemVisible	Indicates whether a specified item in the current list-view control is visible.
CListCtrl::MapIDToIndex	Maps the unique ID of an item in the current list-view control to an index.
CListCtrl::MapIndexToID	Maps the index of an item in the current list-view control to a unique ID.
CListCtrl::MoveGroup	Moves the specified group.
CListCtrl::MoveItemToGroup	Moves the specified group to the specified zero based index of the list view control.
CListCtrl::RedrawItems	Forces a list view control to repaint a range of items.
CListCtrl::RemoveAllGroups	Removes all groups from a list view control.
CListCtrl::RemoveGroup	Removes the specified group from the list view control.
CListCtrl::Scroll	Scrolls the content of a list view control.
CListCtrl::SetBkColor	Sets the background color of the list view control.
CListCtrl::SetBkImage	Sets the current background image of a list view control.
CListCtrl::SetCallbackMask	Sets the callback mask for a list view control.
CListCtrl::SetCheck	Sets the current display status of the state image associated with an item.
CListCtrl::SetColumn	Sets the attributes of a list view column.
CListCtrl::SetColumnOrderArray	Sets the column order (left to right) of a list view control.
CListCtrl::SetColumnWidth	Changes the width of a column in report view or list view.
CListCtrl::SetExtendedStyle	Sets the current extended styles of a list view control.
CListCtrl::SetGroupInfo	Sets the information for the specified group of a list view control.
CListCtrl::SetGroupMetrics	Sets the group metrics of a list view control.
CListCtrl::SetHotCursor	Sets the cursor used when hot tracking is enabled for a list view control.
CListCtrl::SetHotItem	Sets the current hot item of a list view control.
CListCtrl::SetHoverTime	Sets the current hover time of a list view control.
CListCtrl::SetIconSpacing	Sets the spacing between icons in a list view control.
CListCtrl::SetImageList	Assigns an image list to a list view control.
CListCtrl::SetInfoTip	Sets the tooltip text.
CListCtrl::SetInsertMark	Sets the insertion point to the defined position.
CListCtrl::SetInsertMarkColor	Sets the color of the insertion point.
CListCtrl::SetItem	Sets some or all of a list view item's attributes.
CListCtrl::SetItemCount	Prepares a list view control for adding a large number of items.
CListCtrl::SetItemCountEx	Sets the item count for a virtual list view control.
CListCtrl::SetItemData	Sets the item's application-specific value.
CListCtrl::SetItemIndexState	Sets the state of an item in the current list-view control.
CListCtrl::SetItemPosition	Moves an item to a specified position in a list view control.
CListCtrl::SetItemState	Changes the state of an item in a list view control.
CListCtrl::SetItemText	Changes the text of a list view item or subitem.
CListCtrl::SetOutlineColor	Sets the color of the border of a list view control.
CListCtrl::SetSelectedColumn	Sets the selected column of the list view control.
CListCtrl::SetSelectionMark	Sets the selection mark of a list view control.
CListCtrl::SetTextBkColor	Sets the background color of text in a list view control.
CListCtrl::SetTextColor	Sets the text color of a list view control.
CListCtrl::SetTileInfo	Sets the information for a tile of the list view control.
CListCtrl::SetTileViewInfo	Sets information that a list view control uses in tile view.
CListCtrl::SetToolTips	Sets the tooltip control that the list view control will use to display tooltips.
CListCtrl::SetView	Sets the view of the list view control.
CListCtrl::SetWorkAreas	Sets the area where icons can be displayed in a list view control.
CListCtrl::SortGroups	Sorts the groups of a list view control with a user-defined function.
CListCtrl::SortItems	Sorts list view items using an application-defined comparison function.
CListCtrl::SortItemsEx	Sorts list view items using an application-defined comparison function.
CListCtrl::SubItemHitTest	Determines which list view item, if any, is at a given position.
CListCtrl::Update	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

CObject

CCmdTarget

CWnd

CListCtrl

Requirements

Header: afxcmn.h

Share via