CListCtrl

The 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. In addition to an icon and label, each item can have information displayed in colums to the right of the icon and label. This control (and therefore the CListCtrl class) is available only to programs running under Windows 95 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 Control Topics in the Visual C++ Programmer’s Guide.

Views

List view controls can display their contents in four different ways, called “views.”

The style of the control’s current list view determines the current view. For more information on these 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:

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 CListCtrl::GetCallBackMask and 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:

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 and Using CListCtrl: List Items and Image Lists.

#include <afxcmn.h>

Class MembersBase ClassHierarchy Chart

Samples   MFC Sample DAOTABLEMFC Sample HTTPSVRMFC Sample LISTHDRMFC Sample ROWLISTMFC Sample DBVLIST

See Also   CImageList