Share via


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

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

See Also

Reference

CWnd Class

Hierarchy Chart

CImageList Class

Concepts

MFC Sample ROWLIST