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

Public Methods

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

See Also

Reference

CWnd Class

Hierarchy Chart

CImageList Class

Concepts

MFC Sample ROWLIST