clistctrl-class.md

---
description: "Learn more about: CListCtrl Class"
title: "CListCtrl Class"
ms.date: "06/13/2019"
f1_keywords: ["CListCtrl", "AFXCMN/CListCtrl", "AFXCMN/CListCtrl::CListCtrl", "AFXCMN/CListCtrl::ApproximateViewRect", "AFXCMN/CListCtrl::Arrange", "AFXCMN/CListCtrl::CancelEditLabel", "AFXCMN/CListCtrl::Create", "AFXCMN/CListCtrl::CreateDragImage", "AFXCMN/CListCtrl::CreateEx", "AFXCMN/CListCtrl::DeleteAllItems", "AFXCMN/CListCtrl::DeleteColumn", "AFXCMN/CListCtrl::DeleteItem", "AFXCMN/CListCtrl::DrawItem", "AFXCMN/CListCtrl::EditLabel", "AFXCMN/CListCtrl::EnableGroupView", "AFXCMN/CListCtrl::EnsureVisible", "AFXCMN/CListCtrl::FindItem", "AFXCMN/CListCtrl::GetBkColor", "AFXCMN/CListCtrl::GetBkImage", "AFXCMN/CListCtrl::GetCallbackMask", "AFXCMN/CListCtrl::GetCheck", "AFXCMN/CListCtrl::GetColumn", "AFXCMN/CListCtrl::GetColumnOrderArray", "AFXCMN/CListCtrl::GetColumnWidth", "AFXCMN/CListCtrl::GetCountPerPage", "AFXCMN/CListCtrl::GetEditControl", "AFXCMN/CListCtrl::GetEmptyText", "AFXCMN/CListCtrl::GetExtendedStyle", "AFXCMN/CListCtrl::GetFirstSelectedItemPosition", "AFXCMN/CListCtrl::GetFocusedGroup", "AFXCMN/CListCtrl::GetGroupCount", "AFXCMN/CListCtrl::GetGroupInfo", "AFXCMN/CListCtrl::GetGroupInfoByIndex", "AFXCMN/CListCtrl::GetGroupMetrics", "AFXCMN/CListCtrl::GetGroupRect", "AFXCMN/CListCtrl::GetGroupState", "AFXCMN/CListCtrl::GetHeaderCtrl", "AFXCMN/CListCtrl::GetHotCursor", "AFXCMN/CListCtrl::GetHotItem", "AFXCMN/CListCtrl::GetHoverTime", "AFXCMN/CListCtrl::GetImageList", "AFXCMN/CListCtrl::GetInsertMark", "AFXCMN/CListCtrl::GetInsertMarkColor", "AFXCMN/CListCtrl::GetInsertMarkRect", "AFXCMN/CListCtrl::GetItem", "AFXCMN/CListCtrl::GetItemCount", "AFXCMN/CListCtrl::GetItemData", "AFXCMN/CListCtrl::GetItemIndexRect", "AFXCMN/CListCtrl::GetItemPosition", "AFXCMN/CListCtrl::GetItemRect", "AFXCMN/CListCtrl::GetItemSpacing", "AFXCMN/CListCtrl::GetItemState", "AFXCMN/CListCtrl::GetItemText", "AFXCMN/CListCtrl::GetNextItem", "AFXCMN/CListCtrl::GetNextItemIndex", "AFXCMN/CListCtrl::GetNextSelectedItem", "AFXCMN/CListCtrl::GetNumberOfWorkAreas", "AFXCMN/CListCtrl::GetOrigin", "AFXCMN/CListCtrl::GetOutlineColor", "AFXCMN/CListCtrl::GetSelectedColumn", "AFXCMN/CListCtrl::GetSelectedCount", "AFXCMN/CListCtrl::GetSelectionMark", "AFXCMN/CListCtrl::GetStringWidth", "AFXCMN/CListCtrl::GetSubItemRect", "AFXCMN/CListCtrl::GetTextBkColor", "AFXCMN/CListCtrl::GetTextColor", "AFXCMN/CListCtrl::GetTileInfo", "AFXCMN/CListCtrl::GetTileViewInfo", "AFXCMN/CListCtrl::GetToolTips", "AFXCMN/CListCtrl::GetTopIndex", "AFXCMN/CListCtrl::GetView", "AFXCMN/CListCtrl::GetViewRect", "AFXCMN/CListCtrl::GetWorkAreas", "AFXCMN/CListCtrl::HasGroup", "AFXCMN/CListCtrl::HitTest", "AFXCMN/CListCtrl::InsertColumn", "AFXCMN/CListCtrl::InsertGroup", "AFXCMN/CListCtrl::InsertGroupSorted", "AFXCMN/CListCtrl::InsertItem", "AFXCMN/CListCtrl::InsertMarkHitTest", "AFXCMN/CListCtrl::IsGroupViewEnabled", "AFXCMN/CListCtrl::IsItemVisible", "AFXCMN/CListCtrl::MapIDToIndex", "AFXCMN/CListCtrl::MapIndexToID", "AFXCMN/CListCtrl::MoveGroup", "AFXCMN/CListCtrl::MoveItemToGroup", "AFXCMN/CListCtrl::RedrawItems", "AFXCMN/CListCtrl::RemoveAllGroups", "AFXCMN/CListCtrl::RemoveGroup", "AFXCMN/CListCtrl::Scroll", "AFXCMN/CListCtrl::SetBkColor", "AFXCMN/CListCtrl::SetBkImage", "AFXCMN/CListCtrl::SetCallbackMask", "AFXCMN/CListCtrl::SetCheck", "AFXCMN/CListCtrl::SetColumn", "AFXCMN/CListCtrl::SetColumnOrderArray", "AFXCMN/CListCtrl::SetColumnWidth", "AFXCMN/CListCtrl::SetExtendedStyle", "AFXCMN/CListCtrl::SetGroupInfo", "AFXCMN/CListCtrl::SetGroupMetrics", "AFXCMN/CListCtrl::SetHotCursor", "AFXCMN/CListCtrl::SetHotItem", "AFXCMN/CListCtrl::SetHoverTime", "AFXCMN/CListCtrl::SetIconSpacing", "AFXCMN/CListCtrl::SetImageList", "AFXCMN/CListCtrl::SetInfoTip", "AFXCMN/CListCtrl::SetInsertMark", "AFXCMN/CListCtrl::SetInsertMarkColor", "AFXCMN/CListCtrl::SetItem", "AFXCMN/CListCtrl::SetItemCount", "AFXCMN/CListCtrl::SetItemCountEx", "AFXCMN/CListCtrl::SetItemData", "AFXCMN/CListCtrl::SetItemIndexState", "AFXCMN/CListCtrl::SetItemPosition", "AFXCMN/CListCtrl::SetItemState", "AFXCMN/CListCtrl::SetItemText", "AFXCMN/CListCtrl::SetOutlineColor", "AFXCMN/CListCtrl::SetSelectedColumn", "AFXCMN/CListCtrl::SetSelectionMark", "AFXCMN/CListCtrl::SetTextBkColor", "AFXCMN/CListCtrl::SetTextColor", "AFXCMN/CListCtrl::SetTileInfo", "AFXCMN/CListCtrl::SetTileViewInfo", "AFXCMN/CListCtrl::SetToolTips", "AFXCMN/CListCtrl::SetView", "AFXCMN/CListCtrl::SetWorkAreas", "AFXCMN/CListCtrl::SortGroups", "AFXCMN/CListCtrl::SortItems", "AFXCMN/CListCtrl::SortItemsEx", "AFXCMN/CListCtrl::SubItemHitTest", "AFXCMN/CListCtrl::Update"]
helpviewer_keywords: ["CListCtrl [MFC], CListCtrl", "CListCtrl [MFC], ApproximateViewRect", "CListCtrl [MFC], Arrange", "CListCtrl [MFC], CancelEditLabel", "CListCtrl [MFC], Create", "CListCtrl [MFC], CreateDragImage", "CListCtrl [MFC], CreateEx", "CListCtrl [MFC], DeleteAllItems", "CListCtrl [MFC], DeleteColumn", "CListCtrl [MFC], DeleteItem", "CListCtrl [MFC], DrawItem", "CListCtrl [MFC], EditLabel", "CListCtrl [MFC], EnableGroupView", "CListCtrl [MFC], EnsureVisible", "CListCtrl [MFC], FindItem", "CListCtrl [MFC], GetBkColor", "CListCtrl [MFC], GetBkImage", "CListCtrl [MFC], GetCallbackMask", "CListCtrl [MFC], GetCheck", "CListCtrl [MFC], GetColumn", "CListCtrl [MFC], GetColumnOrderArray", "CListCtrl [MFC], GetColumnWidth", "CListCtrl [MFC], GetCountPerPage", "CListCtrl [MFC], GetEditControl", "CListCtrl [MFC], GetEmptyText", "CListCtrl [MFC], GetExtendedStyle", "CListCtrl [MFC], GetFirstSelectedItemPosition", "CListCtrl [MFC], GetFocusedGroup", "CListCtrl [MFC], GetGroupCount", "CListCtrl [MFC], GetGroupInfo", "CListCtrl [MFC], GetGroupInfoByIndex", "CListCtrl [MFC], GetGroupMetrics", "CListCtrl [MFC], GetGroupRect", "CListCtrl [MFC], GetGroupState", "CListCtrl [MFC], GetHeaderCtrl", "CListCtrl [MFC], GetHotCursor", "CListCtrl [MFC], GetHotItem", "CListCtrl [MFC], GetHoverTime", "CListCtrl [MFC], GetImageList", "CListCtrl [MFC], GetInsertMark", "CListCtrl [MFC], GetInsertMarkColor", "CListCtrl [MFC], GetInsertMarkRect", "CListCtrl [MFC], GetItem", "CListCtrl [MFC], GetItemCount", "CListCtrl [MFC], GetItemData", "CListCtrl [MFC], GetItemIndexRect", "CListCtrl [MFC], GetItemPosition", "CListCtrl [MFC], GetItemRect", "CListCtrl [MFC], GetItemSpacing", "CListCtrl [MFC], GetItemState", "CListCtrl [MFC], GetItemText", "CListCtrl [MFC], GetNextItem", "CListCtrl [MFC], GetNextItemIndex", "CListCtrl [MFC], GetNextSelectedItem", "CListCtrl [MFC], GetNumberOfWorkAreas", "CListCtrl [MFC], GetOrigin", "CListCtrl [MFC], GetOutlineColor", "CListCtrl [MFC], GetSelectedColumn", "CListCtrl [MFC], GetSelectedCount", "CListCtrl [MFC], GetSelectionMark", "CListCtrl [MFC], GetStringWidth", "CListCtrl [MFC], GetSubItemRect", "CListCtrl [MFC], GetTextBkColor", "CListCtrl [MFC], GetTextColor", "CListCtrl [MFC], GetTileInfo", "CListCtrl [MFC], GetTileViewInfo", "CListCtrl [MFC], GetToolTips", "CListCtrl [MFC], GetTopIndex", "CListCtrl [MFC], GetView", "CListCtrl [MFC], GetViewRect", "CListCtrl [MFC], GetWorkAreas", "CListCtrl [MFC], HasGroup", "CListCtrl [MFC], HitTest", "CListCtrl [MFC], InsertColumn", "CListCtrl [MFC], InsertGroup", "CListCtrl [MFC], InsertGroupSorted", "CListCtrl [MFC], InsertItem", "CListCtrl [MFC], InsertMarkHitTest", "CListCtrl [MFC], IsGroupViewEnabled", "CListCtrl [MFC], IsItemVisible", "CListCtrl [MFC], MapIDToIndex", "CListCtrl [MFC], MapIndexToID", "CListCtrl [MFC], MoveGroup", "CListCtrl [MFC], MoveItemToGroup", "CListCtrl [MFC], RedrawItems", "CListCtrl [MFC], RemoveAllGroups", "CListCtrl [MFC], RemoveGroup", "CListCtrl [MFC], Scroll", "CListCtrl [MFC], SetBkColor", "CListCtrl [MFC], SetBkImage", "CListCtrl [MFC], SetCallbackMask", "CListCtrl [MFC], SetCheck", "CListCtrl [MFC], SetColumn", "CListCtrl [MFC], SetColumnOrderArray", "CListCtrl [MFC], SetColumnWidth", "CListCtrl [MFC], SetExtendedStyle", "CListCtrl [MFC], SetGroupInfo", "CListCtrl [MFC], SetGroupMetrics", "CListCtrl [MFC], SetHotCursor", "CListCtrl [MFC], SetHotItem", "CListCtrl [MFC], SetHoverTime", "CListCtrl [MFC], SetIconSpacing", "CListCtrl [MFC], SetImageList", "CListCtrl [MFC], SetInfoTip", "CListCtrl [MFC], SetInsertMark", "CListCtrl [MFC], SetInsertMarkColor", "CListCtrl [MFC], SetItem", "CListCtrl [MFC], SetItemCount", "CListCtrl [MFC], SetItemCountEx", "CListCtrl [MFC], SetItemData", "CListCtrl [MFC], SetItemIndexState", "CListCtrl [MFC], SetItemPosition", "CListCtrl [MFC], SetItemState", "CListCtrl [MFC], SetItemText", "CListCtrl [MFC], SetOutlineColor", "CListCtrl [MFC], SetSelectedColumn", "CListCtrl [MFC], SetSelectionMark", "CListCtrl [MFC], SetTextBkColor", "CListCtrl [MFC], SetTextColor", "CListCtrl [MFC], SetTileInfo", "CListCtrl [MFC], SetTileViewInfo", "CListCtrl [MFC], SetToolTips", "CListCtrl [MFC], SetView", "CListCtrl [MFC], SetWorkAreas", "CListCtrl [MFC], SortGroups", "CListCtrl [MFC], SortItems", "CListCtrl [MFC], SortItemsEx", "CListCtrl [MFC], SubItemHitTest", "CListCtrl [MFC], Update"]
ms.assetid: fe08a1ca-4b05-4ff7-a12a-ee4c765a2197
---
# 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.

## Syntax

```
class CListCtrl : public CWnd
```

## Members

### Public Constructors

|Name|Description|
|----------|-----------------|
|[CListCtrl::CListCtrl](#clistctrl)|Constructs a `CListCtrl` object.|

### Public Methods

|Name|Description|
|----------|-----------------|
|[CListCtrl::ApproximateViewRect](#approximateviewrect)|Determines the width and height required to display the items of a list view control.|
|[CListCtrl::Arrange](#arrange)|Aligns items on a grid.|
|[CListCtrl::CancelEditLabel](#canceleditlabel)|Cancels item text editing operation.|
|[CListCtrl::Create](#create)|Creates a list control and attaches it to a `CListCtrl` object.|
|[CListCtrl::CreateDragImage](#createdragimage)|Creates a drag image list for a specified item.|
|[CListCtrl::CreateEx](#createex)|Creates a list control with the specified Windows extended styles and attaches it to a `CListCtrl` object.|
|[CListCtrl::DeleteAllItems](#deleteallitems)|Deletes all items from the control.|
|[CListCtrl::DeleteColumn](#deletecolumn)|Deletes a column from the list view control.|
|[CListCtrl::DeleteItem](#deleteitem)|Deletes an item from the control.|
|[CListCtrl::DrawItem](#drawitem)|Called when a visual aspect of an owner-draw control changes.|
|[CListCtrl::EditLabel](#editlabel)|Begins in-place editing of an item's text.|
|[CListCtrl::EnableGroupView](#enablegroupview)|Enables or disables whether the items in a list view control display as a group.|
|[CListCtrl::EnsureVisible](#ensurevisible)|Ensures that an item is visible.|
|[CListCtrl::FindItem](#finditem)|Searches for a list view item having specified characteristics.|
|[CListCtrl::GetBkColor](#getbkcolor)|Retrieves the background color of a list view control.|
|[CListCtrl::GetBkImage](#getbkimage)|Retrieves the current background image of a list view control.|
|[CListCtrl::GetCallbackMask](#getcallbackmask)|Retrieves the callback mask for a list view control.|
|[CListCtrl::GetCheck](#getcheck)|Retrieves the current display status of the state image associated with an item.|
|[CListCtrl::GetColumn](#getcolumn)|Retrieves the attributes of a control's column.|
|[CListCtrl::GetColumnOrderArray](#getcolumnorderarray)|Retrieves the column order (left to right) of a list view control.|
|[CListCtrl::GetColumnWidth](#getcolumnwidth)|Retrieves the width of a column in report view or list view.|
|[CListCtrl::GetCountPerPage](#getcountperpage)|Calculates the number of items that can fit vertically in a list view control.|
|[CListCtrl::GetEditControl](#geteditcontrol)|Retrieves the handle of the edit control used to edit an item's text.|
|[CListCtrl::GetEmptyText](#getemptytext)|Retrieves the string to display if the current list-view control is empty.|
|[CListCtrl::GetExtendedStyle](#getextendedstyle)|Retrieves the current extended styles of a list view control.|
|[CListCtrl::GetFirstSelectedItemPosition](#getfirstselecteditemposition)|Retrieves the position of the first selected list view item in a list view control.|
|[CListCtrl::GetFocusedGroup](#getfocusedgroup)|Retrieves the group that has the keyboard focus in the current list-view control.|
|[CListCtrl::GetGroupCount](#getgroupcount)|Retrieves the number of groups in the current list-view control.|
|[CListCtrl::GetGroupInfo](#getgroupinfo)|Gets the information for a specified group of the list view control.|
|[CListCtrl::GetGroupInfoByIndex](#getgroupinfobyindex)|Retrieves information about a specified group in the current list-view control.|
|[CListCtrl::GetGroupMetrics](#getgroupmetrics)|Retrieves the metrics of a group.|
|[CListCtrl::GetGroupRect](#getgrouprect)|Retrieves the bounding rectangle for a specified group in the current list-view control.|
|[CListCtrl::GetGroupState](#getgroupstate)|Retrieves the state for a specified group in the current list-view control.|
|[CListCtrl::GetHeaderCtrl](#getheaderctrl)|Retrieves the header control of a list view control.|
|[CListCtrl::GetHotCursor](#gethotcursor)|Retrieves the cursor used when hot tracking is enabled for a list view control.|
|[CListCtrl::GetHotItem](#gethotitem)|Retrieves the list view item currently under the cursor.|
|[CListCtrl::GetHoverTime](#gethovertime)|Retrieves the current hover time of a list view control.|
|[CListCtrl::GetImageList](#getimagelist)|Retrieves the handle of an image list used for drawing list view items.|
|[CListCtrl::GetInsertMark](#getinsertmark)|Retrieves the current position of the insertion mark.|
|[CListCtrl::GetInsertMarkColor](#getinsertmarkcolor)|Retrieves the current color of the insertion mark.|
|[CListCtrl::GetInsertMarkRect](#getinsertmarkrect)|Retrieves the rectangle that bounds the insertion point.|
|[CListCtrl::GetItem](#getitem)|Retrieves a list view item's attributes.|
|[CListCtrl::GetItemCount](#getitemcount)|Retrieves the number of items in a list view control.|
|[CListCtrl::GetItemData](#getitemdata)|Retrieves the application-specific value associated with an item.|
|[CListCtrl::GetItemIndexRect](#getitemindexrect)|Retrieves the bounding rectangle for all or part of a subitem in the current list-view control.|
|[CListCtrl::GetItemPosition](#getitemposition)|Retrieves the position of a list view item.|
|[CListCtrl::GetItemRect](#getitemrect)|Retrieves the bounding rectangle for an item.|
|[CListCtrl::GetItemSpacing](#getitemspacing)|Calculates the spacing between items in the current list-view control.|
|[CListCtrl::GetItemState](#getitemstate)|Retrieves the state of a list view item.|
|[CListCtrl::GetItemText](#getitemtext)|Retrieves the text of a list view item or subitem.|
|[CListCtrl::GetNextItem](#getnextitem)|Searches for a list view item with specified properties and with specified relationship to a given item.|
|[CListCtrl::GetNextItemIndex](#getnextitemindex)|Retrieves the index of the item in the current list-view control that has a specified set of properties.|
|[CListCtrl::GetNextSelectedItem](#getnextselecteditem)|Retrieves the index of a list view item position, and the position of the next selected list view item for iterating.|
|[CListCtrl::GetNumberOfWorkAreas](#getnumberofworkareas)|Retrieves the current number of working areas for a list view control.|
|[CListCtrl::GetOrigin](#getorigin)|Retrieves the current view origin for a list view control.|
|[CListCtrl::GetOutlineColor](#getoutlinecolor)|Retrieves the color of the border of a list view control.|
|[CListCtrl::GetSelectedColumn](#getselectedcolumn)|Retrieves the index of the currently selected column in the list control.|
|[CListCtrl::GetSelectedCount](#getselectedcount)|Retrieves the number of selected items in the list view control.|
|[CListCtrl::GetSelectionMark](#getselectionmark)|Retrieves the selection mark of a list view control.|
|[CListCtrl::GetStringWidth](#getstringwidth)|Determines the minimum column width necessary to display all of a given string.|
|[CListCtrl::GetSubItemRect](#getsubitemrect)|Retrieves the bounding rectangle of an item in a list view control.|
|[CListCtrl::GetTextBkColor](#gettextbkcolor)|Retrieves the text background color of a list view control.|
|[CListCtrl::GetTextColor](#gettextcolor)|Retrieves the text color of a list view control.|
|[CListCtrl::GetTileInfo](#gettileinfo)|Retrieves information about a tile in a list view control.|
|[CListCtrl::GetTileViewInfo](#gettileviewinfo)|Retrieves information about a list view control in tile view.|
|[CListCtrl::GetToolTips](#gettooltips)|Retrieves the tooltip control that the list view control uses to display tooltips.|
|[CListCtrl::GetTopIndex](#gettopindex)|Retrieves the index of the topmost visible item.|
|[CListCtrl::GetView](#getview)|Gets the view of the list view control.|
|[CListCtrl::GetViewRect](#getviewrect)|Retrieves the bounding rectangle of all items in the list view control.|
|[CListCtrl::GetWorkAreas](#getworkareas)|Retrieves the current working areas of a list view control.|
|[CListCtrl::HasGroup](#hasgroup)|Determines if the list view control has the specified group.|
|[CListCtrl::HitTest](#hittest)|Determines which list view item is at a specified position.|
|[CListCtrl::InsertColumn](#insertcolumn)|Inserts a new column in a list view control.|
|[CListCtrl::InsertGroup](#insertgroup)|Inserts a group into the list view control.|
|[CListCtrl::InsertGroupSorted](#insertgroupsorted)|Inserts the specified group into an ordered list of groups.|
|[CListCtrl::InsertItem](#insertitem)|Inserts a new item in a list view control.|
|[CListCtrl::InsertMarkHitTest](#insertmarkhittest)|Retrieves the insertion point closest to a specified point.|
|[CListCtrl::IsGroupViewEnabled](#isgroupviewenabled)|Determines whether group view is enabled for a list view control.|
|[CListCtrl::IsItemVisible](#isitemvisible)|Indicates whether a specified item in the current list-view control is visible.|
|[CListCtrl::MapIDToIndex](#mapidtoindex)|Maps the unique ID of an item in the current list-view control to an index.|
|[CListCtrl::MapIndexToID](#mapindextoid)|Maps the index of an item in the current list-view control to a unique ID.|
|[CListCtrl::MoveGroup](#movegroup)|Moves the specified group.|
|[CListCtrl::MoveItemToGroup](#moveitemtogroup)|Moves the specified group to the specified zero based index of the list view control.|
|[CListCtrl::RedrawItems](#redrawitems)|Forces a list view control to repaint a range of items.|
|[CListCtrl::RemoveAllGroups](#removeallgroups)|Removes all groups from a list view control.|
|[CListCtrl::RemoveGroup](#removegroup)|Removes the specified group from the list view control.|
|[CListCtrl::Scroll](#scroll)|Scrolls the content of a list view control.|
|[CListCtrl::SetBkColor](#setbkcolor)|Sets the background color of the list view control.|
|[CListCtrl::SetBkImage](#setbkimage)|Sets the current background image of a list view control.|
|[CListCtrl::SetCallbackMask](#setcallbackmask)|Sets the callback mask for a list view control.|
|[CListCtrl::SetCheck](#setcheck)|Sets the current display status of the state image associated with an item.|
|[CListCtrl::SetColumn](#setcolumn)|Sets the attributes of a list view column.|
|[CListCtrl::SetColumnOrderArray](#setcolumnorderarray)|Sets the column order (left to right) of a list view control.|
|[CListCtrl::SetColumnWidth](#setcolumnwidth)|Changes the width of a column in report view or list view.|
|[CListCtrl::SetExtendedStyle](#setextendedstyle)|Sets the current extended styles of a list view control.|
|[CListCtrl::SetGroupInfo](#setgroupinfo)|Sets the information for the specified group of a list view control.|
|[CListCtrl::SetGroupMetrics](#setgroupmetrics)|Sets the group metrics of a list view control.|
|[CListCtrl::SetHotCursor](#sethotcursor)|Sets the cursor used when hot tracking is enabled for a list view control.|
|[CListCtrl::SetHotItem](#sethotitem)|Sets the current hot item of a list view control.|
|[CListCtrl::SetHoverTime](#sethovertime)|Sets the current hover time of a list view control.|
|[CListCtrl::SetIconSpacing](#seticonspacing)|Sets the spacing between icons in a list view control.|
|[CListCtrl::SetImageList](#setimagelist)|Assigns an image list to a list view control.|
|[CListCtrl::SetInfoTip](#setinfotip)|Sets the tooltip text.|
|[CListCtrl::SetInsertMark](#setinsertmark)|Sets the insertion point to the defined position.|
|[CListCtrl::SetInsertMarkColor](#setinsertmarkcolor)|Sets the color of the insertion point.|
|[CListCtrl::SetItem](#setitem)|Sets some or all of a list view item's attributes.|
|[CListCtrl::SetItemCount](#setitemcount)|Prepares a list view control for adding a large number of items.|
|[CListCtrl::SetItemCountEx](#setitemcountex)|Sets the item count for a virtual list view control.|
|[CListCtrl::SetItemData](#setitemdata)|Sets the item's application-specific value.|
|[CListCtrl::SetItemIndexState](#setitemindexstate)|Sets the state of an item in the current list-view control.|
|[CListCtrl::SetItemPosition](#setitemposition)|Moves an item to a specified position in a list view control.|
|[CListCtrl::SetItemState](#setitemstate)|Changes the state of an item in a list view control.|
|[CListCtrl::SetItemText](#setitemtext)|Changes the text of a list view item or subitem.|
|[CListCtrl::SetOutlineColor](#setoutlinecolor)|Sets the color of the border of a list view control.|
|[CListCtrl::SetSelectedColumn](#setselectedcolumn)|Sets the selected column of the list view control.|
|[CListCtrl::SetSelectionMark](#setselectionmark)|Sets the selection mark of a list view control.|
|[CListCtrl::SetTextBkColor](#settextbkcolor)|Sets the background color of text in a list view control.|
|[CListCtrl::SetTextColor](#settextcolor)|Sets the text color of a list view control.|
|[CListCtrl::SetTileInfo](#settileinfo)|Sets the information for a tile of the list view control.|
|[CListCtrl::SetTileViewInfo](#settileviewinfo)|Sets information that a list view control uses in tile view.|
|[CListCtrl::SetToolTips](#settooltips)|Sets the tooltip control that the list view control will use to display tooltips.|
|[CListCtrl::SetView](#setview)|Sets the view of the list view control.|
|[CListCtrl::SetWorkAreas](#setworkareas)|Sets the area where icons can be displayed in a list view control.|
|[CListCtrl::SortGroups](#sortgroups)|Sorts the groups of a list view control with a user-defined function.|
|[CListCtrl::SortItems](#sortitems)|Sorts list view items using an application-defined comparison function.|
|[CListCtrl::SortItemsEx](#sortitemsex)|Sorts list view items using an application-defined comparison function.|
|[CListCtrl::SubItemHitTest](#subitemhittest)|Determines which list view item, if any, is at a given position.|
|[CListCtrl::Update](#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](../../mfc/using-clistctrl.md) and [Controls](../../mfc/controls-mfc.md).

## 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](../../mfc/reference/cheaderctrl-class.md)) 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)](../../mfc/adding-columns-to-the-control-report-view.md).

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](../../mfc/changing-list-control-styles.md).

## 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](../../mfc/virtual-list-controls.md).

- 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](../../mfc/changing-list-control-styles.md).

## 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](#getitem), [CListCtrl::InsertItem](#insertitem), and [CListCtrl::FindItem](#finditem), [Adding Items to the Control](../adding-items-to-the-control.md), and [Scrolling, Arranging, Sorting, and Finding in list controls](../scrolling-arranging-sorting-and-finding-in-list-controls.md).

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](../callback-items-and-the-callback-mask.md).

## 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](cimagelist-class.md)), 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](../list-items-and-image-lists.md).

## Inheritance Hierarchy

[CObject](cobject-class.md)

[CCmdTarget](ccmdtarget-class.md)

[CWnd](cwnd-class.md)

`CListCtrl`

## Requirements

**Header:** afxcmn.h

## <a name="approximateviewrect"></a> CListCtrl::ApproximateViewRect

Determines the width and height required to display the items of a list view control.

```
CSize ApproximateViewRect(
    CSize sz = CSize(-1, -1),
    int iCount = -1) const;
```

### Parameters

*sz*<br/>
The proposed dimensions of the control, in pixels. If dimensions are not specified, the framework uses the current width or height values of the control.

*iCount*<br/>
Number of items to be displayed in the control. Pass -1 to use the total number of items currently in the control.

### Return Value

A `CSize` object that contains the approximate width and height needed to display the items, in pixels.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_ApproximateViewRect](/windows/win32/api/commctrl/nf-commctrl-listview_approximateviewrect), as described in the Windows SDK.

## <a name="arrange"></a> CListCtrl::Arrange

Repositions items in an icon view so that they align on a grid.

```
BOOL Arrange(UINT nCode);
```

### Parameters

*nCode*<br/>
Specifies the alignment style for the items. It can be one of the following values:

- LVA_ALIGNLEFT Aligns items along the left edge of the window.

- LVA_ALIGNTOP Aligns items along the top edge of the window.

- LVA_DEFAULT Aligns items according to the list view's current alignment styles (the default value).

- LVA_SNAPTOGRID Snaps all icons to the nearest grid position.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

The *nCode* parameter specifies the alignment style.

### Example

```cpp
    // Align all of the list view control items along the top
    // of the window (the list view control must be in icon or
    // small icon mode).
    m_myListCtrl.Arrange(LVA_ALIGNTOP);
```

## <a name="canceleditlabel"></a> CListCtrl::CancelEditLabel

Cancels item text editing operation.

```cpp
void CancelEditLabel();
```

### Remarks

This member function emulates the functionality of the [LVM_CANCELEDITLABEL](/windows/win32/Controls/lvm-canceleditlabel) message, as described in the Windows SDK.

## <a name="clistctrl"></a> CListCtrl::CListCtrl

Constructs a `CListCtrl` object.

```
CListCtrl();
```

## <a name="create"></a> CListCtrl::Create

Creates a list control and attaches it to a `CListCtrl` object.

```
virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);
```

### Parameters

*dwStyle*<br/>
Specifies the list control's style. Apply any combination of list control styles to the control. See [List view window styles](/windows/win32/Controls/list-view-window-styles) in the Windows SDK for a complete list of these styles. Set extended styles specific to a control using [SetExtendedStyle](#setextendedstyle).

*rect*<br/>
Specifies the list control's size and position. It can be either a `CRect` object or a [RECT](/windows/win32/api/windef/ns-windef-rect) structure.

*pParentWnd*<br/>
Specifies the list control's parent window, usually a `CDialog`. It must not be NULL.

*nID*<br/>
Specifies the list control's ID.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

You construct a `CListCtrl` in two steps. First, call the constructor and then call `Create`, which creates the list view control and attaches it to the `CListCtrl` object.

To apply extended Windows styles to the list control object, call [CreateEx](#createex) instead of `Create`.

### Example

```cpp
    m_myListCtrl.Create(
        WS_CHILD|WS_VISIBLE|WS_BORDER|LVS_REPORT|LVS_EDITLABELS,
        CRect(10,10,400,200), pParentWnd, IDD_MYLISTCTRL);
```

## <a name="createex"></a> CListCtrl::CreateEx

Creates a control (a child window) and associates it with the `CListCtrl` object.

```
virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);
```

### Parameters

*dwExStyle*<br/>
Specifies the extended style of the control being created. For a list of extended Windows styles, see the *dwExStyle* parameter for [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK.

*dwStyle*<br/>
Specifies the list control's style. Apply any combination of list control styles to the control. For a complete list of these styles, see [List view window styles](/windows/win32/Controls/list-view-window-styles) in the Windows SDK.

*rect*<br/>
A reference to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure describing the size and position of the window to be created, in client coordinates of *pParentWnd*.

*pParentWnd*<br/>
A pointer to the window that is the control's parent.

*nID*<br/>
The control's child-window ID.

### Return Value

Nonzero if successful; otherwise 0.

### Remarks

Use `CreateEx` instead of [Create](#create) to apply extended Windows styles, specified by the Windows extended style preface **WS_EX_**.

`CreateEx` creates the control with the extended Windows styles specified by *dwExStyle*. To set extended styles specific to a control, call [SetExtendedStyle](#setextendedstyle). For example, use `CreateEx` to set such styles as WS_EX_CONTEXTHELP, but use `SetExtendedStyle` to set such styles as LVS_EX_FULLROWSELECT. For more information, see the styles described in the article [Extended List View Styles](/windows/win32/Controls/extended-list-view-styles) in the Windows SDK.

## <a name="createdragimage"></a> CListCtrl::CreateDragImage

Creates a drag image list for the item specified by *nItem*.

```
CImageList* CreateDragImage(
    int nItem,
    LPPOINT lpPoint);
```

### Parameters

*nItem*<br/>
Index of the item whose drag image list is to be created.

*lpPoint*<br/>
Address of a [POINT](/windows/win32/api/windef/ns-windef-point) structure that receives the initial location of the upper-left corner of the image, in view coordinates.

### Return Value

A pointer to the drag image list if successful; otherwise NULL.

### Remarks

The `CImageList` object is permanent, and you must delete it when finished. For example:

```cpp
        CImageList* pImageList = m_myListCtrl.CreateDragImage(nItem, &point);

        // do something

        delete pImageList;
```

## <a name="deleteallitems"></a> CListCtrl::DeleteAllItems

Deletes all items from the list view control.

```
BOOL DeleteAllItems();
```

### Return Value

Nonzero if successful; otherwise zero.

### Example

```cpp
    // Delete all of the items from the list view control.
    m_myListCtrl.DeleteAllItems();
    ASSERT(m_myListCtrl.GetItemCount() == 0);
```

## <a name="deletecolumn"></a> CListCtrl::DeleteColumn

Deletes a column from the list view control.

```
BOOL DeleteColumn(int nCol);
```

### Parameters

*nCol*<br/>
Index of the column to be deleted.

### Return Value

Nonzero if successful; otherwise zero.

### Example

```cpp
        int nColumnCount = m_myListCtrl.GetHeaderCtrl()->GetItemCount();

        // Delete all of the columns.
        for (int i=0; i < nColumnCount; i++)
        {
            m_myListCtrl.DeleteColumn(0);
        }
```

## <a name="deleteitem"></a> CListCtrl::DeleteItem

Deletes an item from a list view control.

```
BOOL DeleteItem(int nItem);
```

### Parameters

*nItem*<br/>
Specifies the index of the item to be deleted.

### Return Value

Nonzero if successful; otherwise zero.

### Example

```cpp
        int nCount = m_myListCtrl.GetItemCount();

        // Delete all of the items from the list view control.
        for (int i=0; i < nCount; i++)
        {
            m_myListCtrl.DeleteItem(0);
        }
```

## <a name="drawitem"></a> CListCtrl::DrawItem

Called by the framework when a visual aspect of an owner-draw list view control changes.

```
virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);
```

### Parameters

*lpDrawItemStruct*<br/>
A long pointer to a `DRAWITEMSTRUCT` structure that contains information about the type of drawing required.

### Remarks

The `itemAction` member of the [DRAWITEMSTRUCT](/windows/win32/api/winuser/ns-winuser-drawitemstruct) structure defines the drawing action that is to be performed.

By default, this member function does nothing. Override this member function to implement drawing for an owner-draw `CListCtrl` object.

The application should restore all graphics device interface (GDI) objects selected for the display context supplied in *lpDrawItemStruct* before this member function terminates.

## <a name="editlabel"></a> CListCtrl::EditLabel

Begins in-place editing of an item's text.

```
CEdit* EditLabel(int nItem);
```

### Parameters

*nItem*<br/>
Index of the list view item that is to be edited.

### Return Value

If successful, a pointer to the `CEdit` object that is used to edit the item text; otherwise NULL.

### Remarks

A list view control that has the LVS_EDITLABELS window style enables a user to edit item labels in place. The user begins editing by clicking the label of an item that has the focus.

Use this function to begin in-place editing of the specified list view item's text.

### Example

```cpp
        // Make sure the focus is set to the list view control.
        m_myListCtrl.SetFocus();

        // Show the edit control on the label of the first
        // item in the list view control.
        CEdit* pmyEdit = m_myListCtrl.EditLabel(1);
        ASSERT(pmyEdit != NULL);
```

## <a name="enablegroupview"></a> CListCtrl::EnableGroupView

Enables or disables whether the items in a list view control display as a group.

```
LRESULT EnableGroupView(BOOL fEnable);
```

### Parameters

*fEnable*<br/>
Indicates whether to enable a listview control to group displayed items. TRUE to enable grouping; FALSE to disable it.

### Return Value

Returns one of the following values:

- **0** The ability to display list view items as a group is already enabled or disabled.

- **1** The state of the control was successfully changed.

- **-1** The operation failed.

### Remarks

This member function emulates the functionality of the [LVM_ENABLEGROUPVIEW](/windows/win32/Controls/lvm-enablegroupview) message, as described in the Windows SDK.

## <a name="ensurevisible"></a> CListCtrl::EnsureVisible

Ensures that a list view item is at least partially visible.

```
BOOL EnsureVisible(
    int nItem,
    BOOL bPartialOK);
```

### Parameters

*nItem*<br/>
Index of the list view item that is to be visible.

*bPartialOK*<br/>
Specifies whether partial visibility is acceptable.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

The list view control is scrolled if necessary. If the *bPartialOK* parameter is nonzero, no scrolling occurs if the item is partially visible.

### Example

```cpp
        // Ensure that the last item is visible.
        int nCount = m_myListCtrl.GetItemCount();
        if (nCount > 0)
            m_myListCtrl.EnsureVisible(nCount-1, FALSE);
```

## <a name="finditem"></a> CListCtrl::FindItem

Searches for a list view item having specified characteristics.

```
int FindItem(
    LVFINDINFO* pFindInfo,
    int nStart = -1) const;
```

### Parameters

*pFindInfo*<br/>
A pointer to an [LVFINDINFO](/windows/win32/api/commctrl/ns-commctrl-lvfindinfow) structure containing information about the item to be searched for.

*nStart*<br/>
Index of the item to begin the search with, or -1 to start from the beginning. The item at *nStart* is excluded from the search if *nStart* is not equal to -1.

### Return Value

The index of the item if successful or -1 otherwise.

### Remarks

The *pFindInfo* parameter points to an `LVFINDINFO` structure, which contains information used to search for a list view item.

### Example

```cpp
        LVFINDINFO info;
        int nIndex;

        info.flags = LVFI_PARTIAL|LVFI_STRING;
        info.psz = _T("item");

        // Delete all of the items that begin with the string.
        while ((nIndex = m_myListCtrl.FindItem(&info)) != -1)
        {
            m_myListCtrl.DeleteItem(nIndex);
        }
```

## <a name="getbkcolor"></a> CListCtrl::GetBkColor

Retrieves the background color of a list view control.

```
COLORREF GetBkColor() const;
```

### Return Value

A 32-bit value used to specify an RGB color.

### Example

See the example for [CListCtrl::SetBkColor](#setbkcolor).

## <a name="getbkimage"></a> CListCtrl::GetBkImage

Retrieves the current background image of a list view control.

```
BOOL GetBkImage(LVBKIMAGE* plvbkImage) const;
```

### Parameters

*plvbkImage*<br/>
A pointer to an `LVBKIMAGE` structure containing the current background image of the list view.

### Return Value

Returns nonzero if successful, or zero otherwise.

### Remarks

This method implements the behavior of the Win32 macro, [ListView_GetBkImage](/windows/win32/api/commctrl/nf-commctrl-listview_getbkimage), as described in the Windows SDK.

### Example

```cpp
        LVBKIMAGE bki;

        // If no background image is set for the list view control use
        // the Microsoft homepage image as the background image.
        if (m_myListCtrl.GetBkImage(&bki) && (bki.ulFlags == LVBKIF_SOURCE_NONE))
        {
            m_myListCtrl.SetBkImage(
                _T("https://www.microsoft.com/library/images/gifs/homepage/microsoft.gif"),
                TRUE);
        }
```

## <a name="getcallbackmask"></a> CListCtrl::GetCallbackMask

Retrieves the callback mask for a list view control.

```
UINT GetCallbackMask() const;
```

### Return Value

The list view control's callback mask.

### Remarks

A "callback item" is a list view item for which the application — rather than the control — stores the text, icon, or both. Although a list view control can store these attributes for you, you may want to use callback items if your application already maintains some of this information. The callback mask specifies which item state bits are maintained by the application, and it applies to the whole control rather than to a specific item. The callback mask is zero by default, meaning that the control tracks all item states. If an application uses callback items or specifies a nonzero callback mask, it must be able to supply list view item attributes on demand.

### Example

See the example for [CListCtrl::SetCallbackMask](#setcallbackmask).

## <a name="getcheck"></a> CListCtrl::GetCheck

Retrieves the current display status of the state image that is associated with an item.

```
BOOL GetCheck(int nItem) const;
```

### Parameters

*nItem*<br/>
The zero-based index of a list control item.

### Return Value

Nonzero if the item is selected, otherwise 0.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_GetCheckState](/windows/win32/api/commctrl/nf-commctrl-listview_getcheckstate), as described in the Windows SDK.

### Example

See the example for [CListCtrl::SetCheck](#setcheck).

## <a name="getcolumn"></a> CListCtrl::GetColumn

Retrieves the attributes of a list view control's column.

```
BOOL GetColumn(
    int nCol,
    LVCOLUMN* pColumn) const;
```

### Parameters

*nCol*<br/>
Index of the column whose attributes are to be retrieved.

*pColumn*<br/>
Address of an [LVCOLUMN](/windows/win32/api/commctrl/ns-commctrl-lvcolumnw) structure that specifies the information to retrieve and receives information about the column. The `mask` member specifies which column attributes to retrieve. If the `mask` member specifies the LVCF_TEXT value, the `pszText` member must contain the address of the buffer that receives the item text and the `cchTextMax` member must specify the size of the buffer.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

The `LVCOLUMN` structure contains information about a column in report view.

### Example

```cpp
        LVCOLUMN col;

        col.mask = LVCF_WIDTH;

        // Double the column width of the first column.
        if (m_myListCtrl.GetColumn(0, &col))
        {
            col.cx *= 2;
            m_myListCtrl.SetColumn(0, &col);
        }
```

## <a name="getcolumnorderarray"></a> CListCtrl::GetColumnOrderArray

Retrieves the column order (left to right) of a list view control.

```
BOOL GetColumnOrderArray(
    LPINT piArray,
    int iCount = -1);
```

### Parameters

*piArray*<br/>
A pointer to a buffer that will contain the index values of the columns in the list view control. The buffer must be large enough to contain the total number of columns in the list view control.

*iCount*<br/>
Number of columns in the list view control. If this parameter is -1, the number of columns is automatically retrieved by the framework.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_GetColumnOrderArray](/windows/win32/api/commctrl/nf-commctrl-listview_getcolumnorderarray), as described in the Windows SDK.

### Example

```cpp
        // Reverse the order of the columns in the list view control
        // (i.e. make the first column the last, the last column
        // the first, and so on...).
        CHeaderCtrl* pHeaderCtrl = m_myListCtrl.GetHeaderCtrl();

        if (pHeaderCtrl != NULL)
        {
            int  nColumnCount = pHeaderCtrl->GetItemCount();
            LPINT pnOrder = (LPINT) malloc(nColumnCount*sizeof(int));
            ASSERT(pnOrder != NULL);
            m_myListCtrl.GetColumnOrderArray(pnOrder, nColumnCount);

            int i, j, nTemp;
            for (i = 0, j = nColumnCount-1; i < j; i++, j--)
            {
                nTemp = pnOrder[i];
                pnOrder[i] = pnOrder[j];
                pnOrder[j] = nTemp;
            }

            m_myListCtrl.SetColumnOrderArray(nColumnCount, pnOrder);
            free(pnOrder);
        }
```

## <a name="getcolumnwidth"></a> CListCtrl::GetColumnWidth

Retrieves the width of a column in report view or list view.

```
int GetColumnWidth(int nCol) const;
```

### Parameters

*nCol*<br/>
Specifies the index of the column whose width is to be retrieved.

### Return Value

The width, in pixels, of the column specified by *nCol*.

### Example

```cpp
        // Increase the column width of the second column by 20.
        int nWidth = m_myListCtrl.GetColumnWidth(1);
        m_myListCtrl.SetColumnWidth(1, 20 + nWidth);
```

## <a name="getcountperpage"></a> CListCtrl::GetCountPerPage

Calculates the number of items that can fit vertically in the visible area of a list view control when in list view or report view.

```
int GetCountPerPage() const;
```

### Return Value

The number of items that can fit vertically in the visible area of a list view control when in list view or report view.

### Example

See the example for [CListCtrl::GetTopIndex](#gettopindex).

## <a name="geteditcontrol"></a> CListCtrl::GetEditControl

Retrieves the handle of the edit control used to edit a list view item's text.

```
CEdit* GetEditControl() const;
```

### Return Value

If successful, a pointer to the [CEdit](cedit-class.md) object that is used to edit the item text; otherwise NULL.

### Example

```cpp
        // The string replacing the text in the edit control.
        LPCTSTR lpszmyString = _T("custom label!");

        // If possible, replace the text in the label edit control.
        CEdit* pEdit = m_myListCtrl.GetEditControl();

        if (pEdit != NULL)
        {
            pEdit->SetWindowText(lpszmyString);
        }
```

## <a name="getemptytext"></a> CListCtrl::GetEmptyText

Retrieves the string to display if the current list-view control is empty.

```
CString GetEmptyText() const;
```

### Return Value

A [CString](../../atl-mfc-shared/reference/cstringt-class.md) that contains the text to display if the control is empty.

### Remarks

This method sends the [LVM_GETEMPTYTEXT](/windows/win32/Controls/lvm-getemptytext) message, which is described in the Windows SDK.

## <a name="getextendedstyle"></a> CListCtrl::GetExtendedStyle

Retrieves the current extended styles of a list view control.

```
DWORD GetExtendedStyle();
```

### Return Value

A combination of the extended styles currently in use by the list view control. For a descriptive list of these extended styles, see the [Extended List View Styles](/windows/win32/Controls/extended-list-view-styles) article in the Windows SDK.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_GetExtendedListViewStyle](/windows/win32/api/commctrl/nf-commctrl-listview_getextendedlistviewstyle), as described in the Windows SDK.

### Example

See the example for [CListCtrl::SetExtendedStyle](#setextendedstyle).

## <a name="getfirstselecteditemposition"></a> CListCtrl::GetFirstSelectedItemPosition

Gets the position of the first selected item in the list view control.

```
POSITION GetFirstSelectedItemPosition() const;
```

### Return Value

A POSITION value that can be used for iteration or object pointer retrieval; NULL if no items are selected.

### Example

The following code sample demonstrates the usage of this function.

```cpp
        POSITION pos = m_myListCtrl.GetFirstSelectedItemPosition();
        if (pos == NULL)
        {
            TRACE(_T("No items were selected!\n"));
        }
        else
        {
            while (pos)
            {
                int nItem = m_myListCtrl.GetNextSelectedItem(pos);
                TRACE(_T("Item %d was selected!\n"), nItem);
                // you could do your own processing on nItem here
            }
        }
```

## <a name="getfocusedgroup"></a> CListCtrl::GetFocusedGroup

Retrieves the group that has the keyboard focus in the current list-view control.

```
int GetFocusedGroup() const;
```

### Return Value

The index of the group whose state is LVGS_FOCUSED, if there is such a group; otherwise, -1.

### Remarks

This method sends the [LVM_GETFOCUSEDGROUP](/windows/win32/Controls/lvm-getfocusedgroup) message, which is described in the Windows SDK. For more information, see the LVGS_FOCUSED value of the `state` member of the [LVGROUP](/windows/win32/api/commctrl/ns-commctrl-lvgroup) structure.

## <a name="getgroupcount"></a> CListCtrl::GetGroupCount

Retrieves the number of groups in the current list-view control.

```
int GetGroupCount()const;
```

### Return Value

The number of groups in the list-view control.

### Remarks

This method sends the [LVM_GETGROUPCOUNT](/windows/win32/Controls/lvm-getgroupcount) message, which is described in the Windows SDK -->.

## <a name="getgroupinfo"></a> CListCtrl::GetGroupInfo

Gets the information for a specified group of the list view control.

```
int GetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp) const;
```

### Parameters

*iGroupId*<br/>
The identifier of the group whose information is to be retrieved.

*pgrp*<br/>
A pointer to the [LVGROUP](/windows/win32/api/commctrl/ns-commctrl-lvgroup) containing information on the group specified.

### Return Value

Returns the ID of the group if successful, or -1 otherwise.

### Remarks

This member function emulates the functionality of the [LVM_GETGROUPINFO](/windows/win32/Controls/lvm-getgroupinfo) message, as described in the Windows SDK.

## <a name="getgroupinfobyindex"></a> CListCtrl::GetGroupInfoByIndex

Retrieves information about a specified group in the current list-view control.

```
BOOL GetGroupInfoByIndex(
    int iIndex,
    PLVGROUP pGroup) const;
```

### Parameters

*iIndex*\
[in] Zero-based index of a group.

*pGroup*\
[out] Pointer to an [LVGROUP](/windows/win32/api/commctrl/ns-commctrl-lvgroup) structure that receives information about the group specified by the *iIndex* parameter. The caller is responsible for initializing the members of the [LVGROUP](/windows/win32/api/commctrl/ns-commctrl-lvgroup) structure. Set the `cbSize` member to the size of the structure, and the flags of the `mask` member to specify the information to retrieve.

### Return Value

TRUE if this method is successful; otherwise, FALSE.

### Remarks

This method sends the [LVM_GETGROUPINFOBYINDEX](/windows/win32/controls/lvm-getgroupinfobyindex) message, which is described in the Windows SDK -->.

### Example

The following code example defines a variable, `m_listCtrl`, that is used to access the current list-view control. This variable is used in the next example.

```cpp
public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;
```

### Example

The following code example demonstrates the `GetGroupInfoByIndex` method. In an earlier section of this code example, we created a list-view control that displays two columns titled "ClientID" and "Grade" in a report view. The following code example retrieves information about the group whose index is 0, if such a group exists.

```cpp
    // GetGroupInfoByIndex
    const int GROUP_HEADER_BUFFER_SIZE = 40;

// Initialize the structure
    LVGROUP gInfo = {0};
    gInfo.cbSize = sizeof(LVGROUP);
    wchar_t wstrHeadGet[GROUP_HEADER_BUFFER_SIZE] = {0};
    gInfo.cchHeader = GROUP_HEADER_BUFFER_SIZE;
    gInfo.pszHeader = wstrHeadGet;
    gInfo.mask = (LVGF_ALIGN | LVGF_STATE | LVGF_HEADER | LVGF_GROUPID);
    gInfo.state = LVGS_NORMAL;
    gInfo.uAlign  = LVGA_HEADER_LEFT;

    BOOL bRet = m_listCtrl.GetGroupInfoByIndex( 0, &gInfo );
    if (bRet == TRUE) {
        CString strHeader = CString( gInfo.pszHeader );
        CString str;
        str.Format(_T("Header: '%s'"), strHeader);
        AfxMessageBox(str, MB_ICONINFORMATION);
    }
    else
    {
        AfxMessageBox(_T("No group information was retrieved."));
    }
```

## <a name="getgroupmetrics"></a> CListCtrl::GetGroupMetrics

Retrieves the metrics of a group.

```cpp
void GetGroupMetrics(PLVGROUPMETRICS pGroupMetrics) const;
```

### Parameters

*pGroupMetrics*<br/>
A pointer to a [LVGROUPMETRICS](/windows/win32/api/commctrl/ns-commctrl-lvgroupmetrics) containing the group metrics information.

### Remarks

This member function emulates the functionality of the [LVM_GETGROUPMETRICS](/windows/win32/Controls/lvm-getgroupmetrics) message, as described in the Windows SDK.

## <a name="getgrouprect"></a> CListCtrl::GetGroupRect

Retrieves the bounding rectangle for a specified group in the current list-view control.

```
BOOL GetGroupRect(
    int iGroupId,
    LPRECT lpRect,
    int iCoords = LVGGR_GROUP) const;
```

### Parameters

*iGroupId*\
[in] Specifies a group.

*lpRect*\
[in, out] Pointer to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure. If this method is successful, the structure receives the rectangle coordinates of the group that is specified by *iGroupId*.

*iCoords*\
[in] Specifies the rectangle coordinates to retrieve. Use one of these values:

- LVGGR_GROUP - (Default) Coordinates of the entire expanded group.

- LVGGR_HEADER - Coordinates of only the header (collapsed group).

- LVGGR_SUBSETLINK - Coordinates of only the subset link (markup subset).

### Return Value

TRUE if this method is successful; otherwise, FALSE.

### Remarks

The caller is responsible for allocating the [RECT](/windows/win32/api/windef/ns-windef-rect) structure pointed to by the *pRect* parameter.

This method sends the [LVM_GETGROUPRECT](/windows/win32/Controls/lvm-getgrouprect) message, which is described in the Windows SDK.

### Example

The following code example defines a variable, `m_listCtrl`, that is used to access the current list-view control. This variable is used in the next example.

```cpp
public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;
```

### Example

The following code example demonstrates the `GetGroupRect` method. In an earlier section of this code example, we created a list-view control that displays two columns titled "ClientID" and "Grade" in a report view. The following code example draws a 3D rectangle around the group whose index is 0, if such a group exists.

```cpp
    // GetGroupRect

    // Get the graphics rectangle that surrounds group 0.
    CRect rect;
    BOOL bRet = m_listCtrl.GetGroupRect( 0, &rect, LVGGR_GROUP);
    // Draw a blue rectangle around group 0.
    if (bRet == TRUE) {
        m_listCtrl.GetDC()->Draw3dRect( &rect, RGB(0, 0, 255), RGB(0, 0, 255));
    }
    else {
        AfxMessageBox(_T("No group information was retrieved."), MB_ICONINFORMATION);
    }
```

## <a name="getgroupstate"></a> CListCtrl::GetGroupState

Retrieves the state for a specified group in the current list-view control.

```
UINT GetGroupState(
    int iGroupId,
    DWORD dwMask) const;
```

### Parameters

*iGroupId*\
[in] Zero-based index of a group.

*dwMask*\
[in] Mask that specifies the state value to retrieve for the specified group. For more information, see the `mask` member of the [LVGROUP](/windows/win32/api/commctrl/ns-commctrl-lvgroup) structure.

### Return Value

The requested state for the specified group, or 0 if the group cannot be found.

### Remarks

The return value is the result of a bitwise AND operation on the *dwMask* parameter and the value of the `state` member of an [LVGROUP](/windows/win32/api/commctrl/ns-commctrl-lvgroup) structure that represents the current list-view control.

This method sends the [LVM_GETGROUPSTATE](/windows/win32/Controls/lvm-getgroupstate) message, which is described in the Windows SDK. For more information, see the [ListView_GetGroupState](/windows/win32/api/commctrl/nf-commctrl-listview_getgroupstate) macro.

## <a name="getheaderctrl"></a> CListCtrl::GetHeaderCtrl

Retrieves the header control of a list view control.

```
CHeaderCtrl* GetHeaderCtrl();
```

### Return Value

A pointer to the header control, used by the list view control.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_GetHeader](/windows/win32/api/commctrl/nf-commctrl-listview_getheader), as described in the Windows SDK.

### Example

See the example for [CListCtrl::GetColumnOrderArray](#getcolumnorderarray).

## <a name="gethotcursor"></a> CListCtrl::GetHotCursor

Retrieves the cursor used when hot tracking is enabled for a list view control.

```
HCURSOR GetHotCursor();
```

### Return Value

The handle to the current hot cursor resource being used by the list view control.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_GetHotCursor](/windows/win32/api/commctrl/nf-commctrl-listview_gethotcursor), as described in the Windows SDK. The hot cursor, only visible when hover selection is enabled, appears when the cursor passes over any list view item. Hover selection is enabled by setting the LVS_EX_TRACKSELECT extended style.

### Example

```cpp
        // Set the hot cursor to be the system app starting cursor.
        HCURSOR hCursor = ::LoadCursor(NULL, IDC_APPSTARTING);
        m_myListCtrl.SetHotCursor(hCursor);
        ASSERT(m_myListCtrl.GetHotCursor() == hCursor);
```

## <a name="gethotitem"></a> CListCtrl::GetHotItem

Retrieves the list view item currently under the cursor.

```
int GetHotItem();
```

### Return Value

The index of the current hot item of the list view control.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_GetHotItem](/windows/win32/api/commctrl/nf-commctrl-listview_gethotitem), as described in the Windows SDK. The hot item is defined as the currently selected item when hot tracking (and hover selection) is enabled.

If hot tracking is enabled, when a user pauses over a list view item, the item label is automatically highlighted without the use of a mouse button.

### Example

```cpp
    // Set the hot item to the first item only if no other item is
    // highlighted.
    if (m_myListCtrl.GetHotItem() == -1)
        m_myListCtrl.SetHotItem(0);
```

## <a name="gethovertime"></a> CListCtrl::GetHoverTime

Retrieves the current hover time of a list view control.

```
DWORD GetHoverTime() const;
```

### Return Value

Returns the delay, in milliseconds, which the mouse cursor must hover over an item before it is selected. If the return value is -1, then the hover time is the default hover time.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_GetHoverTime](/windows/win32/api/commctrl/nf-commctrl-listview_gethovertime), as described in the Windows SDK.

### Example

```cpp
        // If the hover time is the default set to 1 sec.
        DWORD dwTime = m_myListCtrl.GetHoverTime();
        if (dwTime == -1)
            m_myListCtrl.SetHoverTime(1000);
```

## <a name="getimagelist"></a> CListCtrl::GetImageList

Retrieves the handle of an image list used for drawing list view items.

```
CImageList* GetImageList(int nImageList) const;
```

### Parameters

*nImageList*<br/>
Value specifying which image list to retrieve. It can be one of these values:

- LVSIL_NORMAL Image list with large icons.

- LVSIL_SMALL Image list with small icons.

- LVSIL_STATE Image list with state images.

### Return Value

A pointer to the image list used for drawing list view items.

### Example

```cpp
        ASSERT(m_myListCtrl.GetImageList(LVSIL_NORMAL) == NULL);
        m_myListCtrl.SetImageList(&m_lcImageList, LVSIL_NORMAL);
        ASSERT(m_myListCtrl.GetImageList(LVSIL_NORMAL) == &m_lcImageList);
```

## <a name="getinsertmark"></a> CListCtrl::GetInsertMark

Retrieves the current position of the insertion mark.

```
BOOL GetInsertMark(LPLVINSERTMARK plvim) const;
```

### Parameters

*plvim*<br/>
A pointer to an [LVINSERTMARK](/windows/win32/api/commctrl/ns-commctrl-lvinsertmark) structure containing the information for the insert mark.

### Return Value

Returns TRUE if successful, or FALSE otherwise. FALSE is returned if the size in the `cbSize` member of the `LVINSERTMARK` structure does not equal the actual size of the structure.

### Remarks

This member function emulates the functionality of the [LVM_GETINSERTMARK](/windows/win32/Controls/lvm-getinsertmark) message, as described in the Windows SDK.

## <a name="getinsertmarkcolor"></a> CListCtrl::GetInsertMarkColor

Retrieves the current color of the insertion mark.

```
COLORREF GetInsertMarkColor() const;
```

### Return Value

Returns a [COLORREF](/windows/win32/gdi/colorref) structure that contains the color of the insertion point.

### Remarks

This member function emulates the functionality of the [LVM_GETINSERTMARKCOLOR](/windows/win32/Controls/lvm-getinsertmarkcolor) message, as described in the Windows SDK.

## <a name="getinsertmarkrect"></a> CListCtrl::GetInsertMarkRect

Retrieves the rectangle that bounds the insertion point.

```
int GetInsertMarkRect(LPRECT pRect) const;
```

### Parameters

*pRect*<br/>
Pointer to a `RECT` structure that contains the coordinates of a rectangle that bounds the insertion point.

### Return Value

Returns one of the following values:

- **0** No insertion point found.

- **1** Insertion point found.

### Remarks

This member function emulates the functionality of the [LVM_GETINSERTMARKRECT](/windows/win32/Controls/lvm-getinsertmarkrect) message, as described in the Windows SDK.

## <a name="getitem"></a> CListCtrl::GetItem

Retrieves some or all of a list view item's attributes.

```
BOOL GetItem(LVITEM* pItem) const;
```

### Parameters

*pItem*<br/>
Pointer to an [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure that receives the item's attributes.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

The `LVITEM` structure specifies or receives the attributes of a list view item.

## <a name="getitemcount"></a> CListCtrl::GetItemCount

Retrieves the number of items in a list view control.

```
int GetItemCount() const;
```

### Return Value

The number of items in the list view control.

### Example

See the example for [CListCtrl::DeleteItem](#deleteitem).

## <a name="getitemdata"></a> CListCtrl::GetItemData

Retrieves the 32-bit application-specific value associated with the item specified by `nItem`.

```
DWORD_PTR GetItemData(int nItem) const;
```

### Parameters

*nItem*<br/>
Index of the list item whose data is to be retrieved.

### Return Value

A 32-bit application-specific value associated with the specified item.

### Remarks

This value is the `lParam` member of the [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure, as described in the Windows SDK

### Example

```cpp
    // If any item's data is equal to zero then reset it to -1.
    for (int i=0; i < m_myListCtrl.GetItemCount(); i++)
    {
        if (m_myListCtrl.GetItemData(i) == 0)
        {
            m_myListCtrl.SetItemData(i, (DWORD) -1);
        }
    }
```

## <a name="getitemindexrect"></a> CListCtrl::GetItemIndexRect

Retrieves the bounding rectangle for all or part of a subitem in the current list-view control.

```
BOOL GetItemIndexRect(
    PLVITEMINDEX pItemIndex,
    int iColumn,
    int rectType,
    LPRECT pRect) const;
```

### Parameters

*pItemIndex*\
[in] Pointer to an [LVITEMINDEX](/windows/win32/api/commctrl/ns-commctrl-lvitemindex) structure for the parent item of the subitem. The caller is responsible for allocating and setting the members of the [LVITEMINDEX](/windows/win32/api/commctrl/ns-commctrl-lvitemindex) structure. This parameter cannot be NULL.

*iColumn*\
[in] Zero-based index of a column in the control.

*rectType*\
[in] Portion of the list-view subitem for which the bounding rectangle is retrieved. Specify one of the following values:

- LVIR_BOUNDS - Returns the bounding rectangle of the entire subitem, including the icon and label.

- LVIR_ICON - Returns the bounding rectangle of the icon or small icon of the subitem.

- LVIR_LABEL - Returns the bounding rectangle of the subitem text.

*pRect*\
[out] Pointer to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure that receives information about the bounding rectangle of the subitem. The caller is responsible for allocating the [RECT](/windows/win32/api/windef/ns-windef-rect) structure. This parameter cannot be NULL.

### Return Value

TRUE if this method is successful; otherwise, FALSE.

### Remarks

This method sends the [LVM_GETITEMINDEXRECT](/windows/win32/Controls/lvm-getitemindexrect) message, which is described in the Windows SDK. For more information, see [ListView_GetItemIndexRect Macro](/windows/win32/api/commctrl/nf-commctrl-listview_getitemindexrect).

### Example

The following code example defines a variable, `m_listCtrl`, that is used to access the current list-view control. This variable is used in the next example.

```cpp
public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;
```

### Example

The following code example demonstrates the `GetGroupRect` method. Prior to entering this code example we created a list-view control that displays two columns titled "ClientID" and "Grade" in a report view. The following code example draws a 3D rectangle around the second subitem in both columns.

```cpp
    // GetItemIndexRect
    // Get the rectangle that bounds the second item in the first group.
    LVITEMINDEX lvItemIndex;
    lvItemIndex.iGroup = 0;
    lvItemIndex.iItem = 1;
    CRect rect;
    BOOL bRet = m_listCtrl.GetItemIndexRect(
        &lvItemIndex, 0, LVIR_BOUNDS, &rect);

    // Draw a red rectangle around the item.
    m_listCtrl.GetDC()->Draw3dRect( &rect, RGB(255, 0, 0), RGB(255, 0, 0) );
```

## <a name="getitemposition"></a> CListCtrl::GetItemPosition

Retrieves the position of a list view item.

```
BOOL GetItemPosition(
    int nItem,
    LPPOINT lpPoint) const;
```

### Parameters

*nItem*<br/>
The index of the item whose position is to be retrieved.

*lpPoint*<br/>
Address of a [POINT](/windows/win32/api/windef/ns-windef-point) structure that receives the position of the item's upper-left corner, in view coordinates.

### Return Value

Nonzero if successful; otherwise zero.

### Example

```cpp
        POINT pt;

        // Move all items in the list control 100 pixels to the right.
        UINT i, nCount = m_myListCtrl.GetItemCount();

        for (i=0; i < nCount; i++)
        {
            m_myListCtrl.GetItemPosition(i, &pt);
            pt.x += 100;
            m_myListCtrl.SetItemPosition(i, pt);
        }
```

## <a name="getitemrect"></a> CListCtrl::GetItemRect

Retrieves the bounding rectangle for all or part of an item in the current view.

```
BOOL GetItemRect(
    int nItem,
    LPRECT lpRect,
    UINT nCode) const;
```

### Parameters

*nItem*<br/>
The index of the item whose position is to be retrieved.

*lpRect*<br/>
Address of a [RECT](/windows/win32/api/windef/ns-windef-rect) structure that receives the bounding rectangle.

*nCode*<br/>
Portion of the list view item for which to retrieve the bounding rectangle. It can be one of these values:

- LVIR_BOUNDS Returns the bounding rectangle of the entire item, including the icon and label.

- LVIR_ICON Returns the bounding rectangle of the icon or small icon.

- LVIR_LABEL Returns the bounding rectangle of the item text.

### Return Value

Nonzero if successful; otherwise zero.

### Example

```cpp
// OnClick is the handler for the NM_CLICK notification
void CListCtrlDlg::OnClick(NMHDR* pNMHDR, LRESULT* pResult)
{
    UNREFERENCED_PARAMETER(pResult);
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;

    // Get the current mouse location and convert it to client
    // coordinates.
    CPoint pos( ::GetMessagePos() );
    ScreenToClient(&pos);

    // Get indexes of the first and last visible items in
    // the listview control.
    int index = m_myListCtrl.GetTopIndex();
    int last_visible_index = index + m_myListCtrl.GetCountPerPage();
    if (last_visible_index > m_myListCtrl.GetItemCount())
        last_visible_index = m_myListCtrl.GetItemCount();

    // Loop until number visible items has been reached.
    while (index <= last_visible_index)
    {
        // Get the bounding rectangle of an item. If the mouse
        // location is within the bounding rectangle of the item,
        // you know you have found the item that was being clicked.
        CRect r;
        m_myListCtrl.GetItemRect(index, &r, LVIR_BOUNDS);
        if (r.PtInRect(pia->ptAction))
        {
            UINT flag = LVIS_SELECTED | LVIS_FOCUSED;
            m_myListCtrl.SetItemState(index, flag, flag);
            break;
        }

        // Get the next item in listview control.
        index++;
    }
}
```

## <a name="getitemspacing"></a> CListCtrl::GetItemSpacing

Calculates the spacing between items in the current list-view control.

```
BOOL GetItemSpacing(
    BOOL fSmall,
    int* pnHorzSpacing,
    int* pnVertSpacing) const;
```

### Parameters

*fSmall*\
[in] View for which to retrieve the item spacing. Specify TRUE for small icon view, or FALSE for icon view.

*pnHorzSpacing*\
[out] Contains the horizontal spacing between items.

*pnVertSpacing*\
[out] Contains the vertical spacing between items.

### Return Value

TRUE if this method is successful; otherwise, FALSE.

### Remarks

This method sends the [LVM_GETITEMSPACING](/windows/win32/Controls/lvm-getitemspacing) message, which is described in the Windows SDK.

## <a name="getitemstate"></a> CListCtrl::GetItemState

Retrieves the state of a list view item.

```
UINT GetItemState(
    int nItem,
    UINT nMask) const;
```

### Parameters

*nItem*<br/>
The index of the item whose state is to be retrieved.

*nMask*<br/>
Mask specifying which of the item's state flags to return.

### Return Value

The state flags for the specified list view item.

### Remarks

An item's state is specified by the `state` member of the [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure, as described in the Windows SDK. When you specify or change an item's state, the `stateMask` member specifies which state bits you want to change.

### Example

See the example for [CListCtrl::GetTopIndex](#gettopindex).

## <a name="getitemtext"></a> CListCtrl::GetItemText

Retrieves the text of a list view item or subitem.

```
int GetItemText(
    int nItem,
    int nSubItem,
    LPTSTR lpszText,
    int nLen) const;

CString GetItemText(
    int nItem,
    int nSubItem) const;
```

### Parameters

*nItem*<br/>
The index of the item whose text is to be retrieved.

*nSubItem*<br/>
Specifies the subitem whose text is to be retrieved.

*lpszText*<br/>
Pointer to a string that is to receive the item text.

*nLen*<br/>
Length of the buffer pointed to by *lpszText*.

### Return Value

The version returning **`int`** returns the length of the retrieved string.

The version returning a `CString` returns the item text.

### Remarks

If *nSubItem* is zero, this function retrieves the item label; if *nSubItem* is nonzero, it retrieves the text of the subitem. For more information on the subitem argument, see the discussion of the [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure in the Windows SDK.

## <a name="getnextitem"></a> CListCtrl::GetNextItem

Searches for a list view item that has the specified properties and that bears the specified relationship to a given item.

```
int GetNextItem(
    int nItem,
    int nFlags) const;
```

### Parameters

*nItem*<br/>
Index of the item to begin the searching with, or -1 to find the first item that matches the specified flags. The specified item itself is excluded from the search.

*nFlags*<br/>
Geometric relation of the requested item to the specified item, and the state of the requested item. The geometric relation can be one of these values:

- LVNI_ABOVE Searches for an item that is above the specified item.

- LVNI_ALL Searches for a subsequent item by index (the default value).

- LVNI_BELOW Searches for an item that is below the specified item.

- LVNI_TOLEFT Searches for an item to the left of the specified item.

- LVNI_TORIGHT Searches for an item to the right of the specified item.

The state can be zero, or it can be one or more of these values:

- LVNI_DROPHILITED The item has the LVIS_DROPHILITED state flag set.

- LVNI_FOCUSED The item has the LVIS_FOCUSED state flag set.

- LVNI_SELECTED The item has the LVIS_SELECTED state flag set.

If an item does not have all of the specified state flags set, the search continues with the next item.

### Return Value

The index of the next item if successful, or -1 otherwise.

## <a name="getnextitemindex"></a> CListCtrl::GetNextItemIndex

Retrieves the index of the item in the current list-view control that has a specified set of properties.

```
BOOL GetNextItemIndex(
    PLVITEMINDEX pItemIndex,
    int nFlags) const;
```

### Parameters

*pItemIndex*\
[in, out] Pointer to the [LVITEMINDEX](/windows/win32/api/commctrl/ns-commctrl-lvitemindex) structure that describes the item where the search begins, or -1 to find the first item that matches the flags in the *nFlags* parameter. If this method is successful, the `LVITEMINDEX` structure describes the item found by the search.

*nFlags*\
[in] A bitwise combination (OR) of flags that specify how to perform the search. The search can depend on the index, state, or appearance of the target item, or the target item's physical position relative to the item specified by the *pItemIndex* parameter. For more information, see the *flags* parameter in the [LVM_GETNEXTITEMINDEX](/windows/win32/controls/lvm-getnextitemindex) message.

### Return Value

TRUE if this method is successful; otherwise, FALSE.

### Remarks

The caller is responsible for allocating and setting the members of the `LVITEMINDEX` structure pointed to by the *pItemIndex* parameter.

This method sends the [LVM_GETNEXTITEMINDEX](/windows/win32/controls/lvm-getnextitemindex) message, which is described in the Windows SDK.

## <a name="getnextselecteditem"></a> CListCtrl::GetNextSelectedItem

Gets the index of the list item identified by *pos*, then sets *pos* to the POSITION value.

```
int GetNextSelectedItem(POSITION& pos) const;
```

### Parameters

*pos*<br/>
A reference to a POSITION value returned by a previous call to `GetNextSelectedItem` or `GetFirstSelectedItemPosition`. The value is updated to the next position by this call.

### Return Value

The index of the list item identified by *pos*.

### Remarks

You can use `GetNextSelectedItem` in a forward iteration loop if you establish the initial position with a call to `GetFirstSelectedItemPosition`.

You must ensure that your POSITION value is valid. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts.

### Example

The following code sample demonstrates the usage of this function.

```cpp
        POSITION pos = m_myListCtrl.GetFirstSelectedItemPosition();
        if (pos == NULL)
        {
            TRACE(_T("No items were selected!\n"));
        }
        else
        {
            while (pos)
            {
                int nItem = m_myListCtrl.GetNextSelectedItem(pos);
                TRACE(_T("Item %d was selected!\n"), nItem);
                // you could do your own processing on nItem here
            }
        }
```

## <a name="getnumberofworkareas"></a> CListCtrl::GetNumberOfWorkAreas

Retrieves the current number of working areas for a list view control.

```
UINT GetNumberOfWorkAreas() const;
```

### Return Value

Not used at this time.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_GetNumberOfWorkAreas](/windows/win32/api/commctrl/nf-commctrl-listview_getnumberofworkareas), as described in the Windows SDK.

### Example

```cpp
        UINT i, uCount = m_myListCtrl.GetNumberOfWorkAreas();
        LPRECT lpRects = (LPRECT) malloc(uCount*sizeof(RECT));

        if (lpRects != NULL)
        {
            // Dump all of the work area dimensions.
            m_myListCtrl.GetWorkAreas(uCount, lpRects);

            for (i=0; i < uCount; i++)
            {
                TRACE(_T("Work area %d; left = %d, top = %d, right = %d, ")
                    _T("bottom = %d\r\n"),
                    i, lpRects[i].left, lpRects[i].top, lpRects[i].right,
                    lpRects[i].bottom);
            }

            free(lpRects);
        }
        else
        {
            TRACE(_T("Couldn't allocate enough memory!"));
        }
```

## <a name="getoutlinecolor"></a> CListCtrl::GetOutlineColor

Retrieves the color of the border of a list view control.

```
COLORREF GetOutlineColor() const;
```

### Return Value

Returns a [COLORREF](/windows/win32/gdi/colorref) structure containing the outline color.

### Remarks

This member function emulates the functionality of the [LVM_GETOUTLINECOLOR](/windows/win32/Controls/lvm-getoutlinecolor) message, as described in the Windows SDK.

## <a name="getorigin"></a> CListCtrl::GetOrigin

Retrieves the current view origin for a list view control.

```
BOOL GetOrigin(LPPOINT lpPoint) const;
```

### Parameters

*lpPoint*<br/>
Address of a [POINT](/windows/win32/api/windef/ns-windef-point) structure that receives the view origin.

### Return Value

Nonzero if successful; otherwise zero. However, if the control is in report view, the return value is always zero.

## <a name="getselectedcolumn"></a> CListCtrl::GetSelectedColumn

Retrieves the index of the currently selected column in the list control.

```
UINT GetSelectedColumn() const;
```

### Return Value

The index of the selected column.

### Remarks

This member function emulates the functionality of the [LVM_GETSELECTEDCOLUMN](/windows/win32/Controls/lvm-getselectedcolumn) message, as described in the Windows SDK.

## <a name="getselectedcount"></a> CListCtrl::GetSelectedCount

Retrieves the number of selected items in the list view control.

```
UINT GetSelectedCount() const;
```

### Return Value

The number of selected items in the list view control.

### Example

```cpp
        UINT i, uSelectedCount = m_myListCtrl.GetSelectedCount();
        int  nItem = -1;

        // Update all of the selected items.
        if (uSelectedCount > 0)
        {
            for (i=0; i < uSelectedCount; i++)
            {
                nItem = m_myListCtrl.GetNextItem(nItem, LVNI_SELECTED);
                ASSERT(nItem != -1);
                m_myListCtrl.Update(nItem);
            }
        }
```

## <a name="getselectionmark"></a> CListCtrl::GetSelectionMark

Retrieves the selection mark of a list view control.

```
int GetSelectionMark();
```

### Return Value

The zero-based selection mark, or -1 if there is no selection mark.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_GetSelectionMark](/windows/win32/api/commctrl/nf-commctrl-listview_getselectionmark), as described in the Windows SDK.

### Example

```cpp
    // Set the selection mark to the first item only if no other item is
    // selected.
    if (m_myListCtrl.GetSelectionMark() == -1)
        m_myListCtrl.SetSelectionMark(0);
```

## <a name="getstringwidth"></a> CListCtrl::GetStringWidth

Determines the minimum column width necessary to display all of a given string.

```
int GetStringWidth(LPCTSTR lpsz) const;
```

### Parameters

*lpsz*<br/>
Address of a null-terminated string whose width is to be determined.

### Return Value

The width, in pixels, of the string pointed to by *lpsz*.

### Remarks

The returned width takes into account the control's current font and column margins, but not the width of a small icon.

### Example

```cpp
        CString strColumn;
        int nWidth;

        // Insert six columns in the list view control. Make the width of
        // the column be the width of the column header plus 50%.
        for (int i = 0; i < 6; i++)
        {
            strColumn.Format(_T("column %d"), i);
            nWidth = 3*m_myListCtrl.GetStringWidth(strColumn)/2;
            m_myListCtrl.InsertColumn(i, strColumn, LVCFMT_LEFT, nWidth);
        }
```

## <a name="getsubitemrect"></a> CListCtrl::GetSubItemRect

Retrieves the bounding rectangle of an item in a list view control.

```
BOOL GetSubItemRect(
    int iItem,
    int iSubItem,
    int nArea,
    CRect& ref);
```

### Parameters

*iItem*<br/>
Index of the subitem's parent item.

*iSubItem*<br/>
The one-based index of the subitem.

*nArea*<br/>
Determines the portion of the bounding rectangle (of the list view subitem) to be retrieved. The portion (icon, label, or both) of the bounding rectangle is specified by applying the bitwise OR operator to one or more of the following values:

- LVIR_BOUNDS Returns the bounding rectangle of the entire item, including the icon and label.

- LVIR_ICON Returns the bounding rectangle of the icon or small icon.

- LVIR_LABEL Returns the bounding rectangle of the entire item, including the icon and label. This is identical to LVIR_BOUNDS.

*ref*<br/>
Reference to a [CRect](../../atl-mfc-shared/reference/crect-class.md) object that contains the coordinates of the subitem's bounding rectangle.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_GetSubItemRect](/windows/win32/api/commctrl/nf-commctrl-listview_getsubitemrect), as described in the Windows SDK.

## <a name="gettextbkcolor"></a> CListCtrl::GetTextBkColor

Retrieves the text background color of a list view control.

```
COLORREF GetTextBkColor() const;
```

### Return Value

A 32-bit value used to specify an RGB color.

### Example

See the example for [CListCtrl::SetTextBkColor](#settextbkcolor).

## <a name="gettextcolor"></a> CListCtrl::GetTextColor

Retrieves the text color of a list view control.

```
COLORREF GetTextColor() const;
```

### Return Value

A 32-bit value used to specify an RGB color.

### Example

See the example for [CListCtrl::SetTextColor](#settextcolor).

## <a name="gettileinfo"></a> CListCtrl::GetTileInfo

Retrieves information about a tile in a list view control.

```
BOOL GetTileInfo(PLVTILEINFO plvti) const;
```

### Parameters

*plvti*<br/>
A pointer to an [LVTILEINFO](/windows/win32/api/commctrl/ns-commctrl-lvtileinfo) structure that receives the tile information.

### Return Value

The return value is not used.

### Remarks

This member function emulates the functionality of the [LVM_GETTILEINFO](/windows/win32/Controls/lvm-gettileinfo) message, as described in the Windows SDK.

## <a name="gettileviewinfo"></a> CListCtrl::GetTileViewInfo

Retrieves information about a list view control in tile view.

```
BOOL GetTileViewInfo(PLVTILEVIEWINFO ptvi) const;
```

### Parameters

*ptvi*<br/>
A pointer to an [LVTILEVIEWINFO](/windows/win32/api/commctrl/ns-commctrl-lvtileviewinfo) structure that receives the retrieved information.

### Return Value

The return value is not used.

### Remarks

This member function emulates the functionality of the [LVM_GETTILEVIEWINFO](/windows/win32/Controls/lvm-gettileviewinfo) message, as described in the Windows SDK.

## <a name="gettooltips"></a> CListCtrl::GetToolTips

Retrieves the tooltip control that the list view control uses to display tooltips.

```
CToolTipCtrl* GetToolTips() const;
```

### Return Value

A pointer to a [CToolTipCtrl](ctooltipctrl-class.md) object to be used by the list control. If the [Create](#create) member function uses the style LVS_NOTOOLTIPS, no tooltips are used, and NULL is returned.

### Remarks

This member function implements the behavior of the Win32 message [LVM_GETTOOLTIPS](/windows/win32/Controls/lvm-gettooltips), as described in the Windows SDK. The MFC implementation of `GetToolTips` returns a `CToolTipCtrl` object, which is used by the list control, rather than a handle to a tooltip control.

### Example

```cpp
        CToolTipCtrl* pTip = m_myListCtrl.GetToolTips();
        if (NULL != pTip)
        {
            pTip->UpdateTipText(_T("I'm a list view!"), &m_myListCtrl,
                IDD_MYLISTCTRL);
        }
```

## <a name="gettopindex"></a> CListCtrl::GetTopIndex

Retrieves the index of the topmost visible item when in list view or report view.

```
int GetTopIndex() const;
```

### Return Value

The index of the topmost visible item.

### Example

```cpp
        // Make sure the focus is set to the list view control.
        m_myListCtrl.SetFocus();

        // Select all of the items that are completely visible.
        int n = m_myListCtrl.GetTopIndex();
        int nLast = n + m_myListCtrl.GetCountPerPage();

        for (; n < nLast; n++)
        {
            m_myListCtrl.SetItemState(n, LVIS_SELECTED, LVIS_SELECTED);
            ASSERT(m_myListCtrl.GetItemState(n, LVIS_SELECTED) == LVIS_SELECTED);
        }
```

## <a name="getview"></a> CListCtrl::GetView

Gets the view of the list view control.

```
DWORD GetView() const;
```

### Return Value

The current view of the list view control.

### Remarks

This member function emulates the functionality of the [LVM_GETVIEW](/windows/win32/Controls/lvm-getview) message, as described in the Windows SDK.

## <a name="getviewrect"></a> CListCtrl::GetViewRect

Retrieves the bounding rectangle of all items in the list view control.

```
BOOL GetViewRect(LPRECT lpRect) const;
```

### Parameters

*lpRect*<br/>
Address of a [RECT](/windows/win32/api/windef/ns-windef-rect) structure.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

The list view must be in icon view or small icon view.

## <a name="getworkareas"></a> CListCtrl::GetWorkAreas

Retrieves the current working areas of a list view control.

```cpp
void GetWorkAreas(
    int nWorkAreas,
    LPRECT pRect) const;
```

### Parameters

*nWorkAreas*<br/>
The number of `RECT` structures contained in the *pRect* array.

*pRect*<br/>
A pointer to an array of `RECT` structures (or [CRect](../../atl-mfc-shared/reference/crect-class.md) objects) that receive the working areas of the list view control. Values in these structures are in client coordinates.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_GetWorkAreas](/windows/win32/api/commctrl/nf-commctrl-listview_getworkareas), as described in the Windows SDK.

### Example

See the example for [CListCtrl::GetNumberOfWorkAreas](#getnumberofworkareas).

## <a name="hasgroup"></a> CListCtrl::HasGroup

Determines if the list view control has the specified group.

```
BOOL HasGroup(int iGroupId) const;
```

### Parameters

*iGroupId*<br/>
The identifier of the group being requested.

### Return Value

Returns TRUE on success, FALSE on failure.

### Remarks

This member function emulates the functionality of the [LVM_HASGROUP](/windows/win32/Controls/lvm-hasgroup) message, as described in the Windows SDK.

## <a name="hittest"></a> CListCtrl::HitTest

Determines which list view item, if any, is at a specified position.

```
int HitTest(LVHITTESTINFO* pHitTestInfo) const;

int HitTest(
    CPoint pt,
    UINT* pFlags = NULL) const;
```

### Parameters

*pHitTestInfo*<br/>
Address of an `LVHITTESTINFO` structure that contains the position to hit test and that receives information about the results of the hit test.

*pt*<br/>
Point to be tested.

*pFlags*<br/>
Pointer to an integer that receives information about the results of the test. See the explanation of the `flags` member of the [LVHITTESTINFO](/windows/win32/api/commctrl/ns-commctrl-lvhittestinfo) structure in the Windows SDK.

### Return Value

The index of the item at the position specified by *pHitTestInfo*, if any, or -1 otherwise.

### Remarks

You can use the LVHT_ABOVE, LVHT_BELOW, LVHT_TOLEFT, and LVHT_TORIGHT values of the structure's `flag` member to determine whether to scroll the contents of a list view control. Two of these flags can be combined, for example, if the position is above and to the left of the client area.

You can test for the LVHT_ONITEM value of the structure's `flag` member to determine whether a given position is over a list view item. This value is a bitwise-OR operation on the LVHT_ONITEMICON, LVHT_ONITEMLABEL, and LVHT_ONITEMSTATEICON values of the structure's `flag` member.

### Example

```cpp
void CListCtrlDlg::OnRClick(NMHDR* pNMHDR, LRESULT* pResult)
{
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;
    CPoint point(pia->ptAction);

    // Select the item the user clicked on.
    UINT uFlags;
    int nItem = m_myListCtrl.HitTest(point, &uFlags);

    if (uFlags & LVHT_ONITEMLABEL)
    {
        m_myListCtrl.SetItem(nItem, 0, LVIF_STATE, NULL, 0, LVIS_SELECTED,
            LVIS_SELECTED, 0);
    }

    *pResult = 0;
}
```

## <a name="insertcolumn"></a> CListCtrl::InsertColumn

Inserts a new column in a list view control.

```
int InsertColumn(
    int nCol,
    const LVCOLUMN* pColumn);

int InsertColumn(
    int nCol,
    LPCTSTR lpszColumnHeading,
    int nFormat = LVCFMT_LEFT,
    int nWidth = -1,
    int nSubItem = -1);
```

### Parameters

*nCol*<br/>
The index of the new column.

*pColumn*<br/>
Address of an `LVCOLUMN` structure that contains the attributes of the new column.

*lpszColumnHeading*<br/>
Address of a string containing the column's heading.

*nFormat*<br/>
Integer specifying the alignment of the column. It can be one of these values: LVCFMT_LEFT, LVCFMT_RIGHT, or LVCFMT_CENTER.

*nWidth*<br/>
Width of the column, in pixels. If this parameter is -1, the column width is not set.

*nSubItem*<br/>
Index of the subitem associated with the column. If this parameter is -1, no subitem is associated with the column.

### Return Value

The index of the new column if successful or -1 otherwise.

### Remarks

The leftmost column in a list view control must be left-aligned.

The [LVCOLUMN](/windows/win32/api/commctrl/ns-commctrl-lvcolumnw) structure contains the attributes of a column in report view. It is also used to receive information about a column. This structure is described in the Windows SDK.

## <a name="insertgroup"></a> CListCtrl::InsertGroup

Inserts a group into the list view control.

```
LRESULT InsertGroup(
    int index,
    PLVGROUP pgrp);
```

### Parameters

*index*<br/>
The index of the item where the group is to be inserted.

*pgrp*<br/>
A pointer to an [LVGROUP](/windows/win32/api/commctrl/ns-commctrl-lvgroup) structure containing the group to be added.

### Return Value

Returns the index of the item that the group was added to, or -1 if the operation failed.

### Remarks

This member function emulates the functionality of the [LVM_INSERTGROUP](/windows/win32/Controls/lvm-insertgroup) message, as described in the Windows SDK.

## <a name="insertgroupsorted"></a> CListCtrl::InsertGroupSorted

Inserts the specified group into an ordered list of groups.

```
LRESULT InsertGroupSorted(PLVINSERTGROUPSORTED pStructInsert);
```

### Parameters

*pStructInsert*<br/>
A pointer to an [LVINSERTGROUPSORTED](/windows/win32/api/commctrl/ns-commctrl-lvinsertgroupsorted) structure that contains the group to insert.

### Return Value

The return value is not used.

### Remarks

This member function emulates the functionality of the [LVM_INSERTGROUPSORTED](/windows/win32/Controls/lvm-insertgroupsorted) message, as described in the Windows SDK.

## <a name="insertitem"></a> CListCtrl::InsertItem

Inserts an item into the list view control.

```
int InsertItem(const LVITEM* pItem);

int InsertItem(
    int nItem,
    LPCTSTR lpszItem);

int InsertItem(
    int nItem,
    LPCTSTR lpszItem,
    int nImage);

int InsertItem(
    UINT nMask,
    int nItem,
    LPCTSTR lpszItem,
    UINT nState,
    UINT nStateMask,
    int nImage,
    LPARAM lParam);
```

### Parameters

*pItem*<br/>
Pointer to an [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure that specifies the item's attributes, as described in the Windows SDK.

*nItem*<br/>
Index of the item to be inserted.

*lpszItem*<br/>
Address of a string containing the item's label, or LPSTR_TEXTCALLBACK if the item is a callback item. For information on callback items, see [CListCtrl::GetCallbackMask](#getcallbackmask).

*nImage*<br/>
Index of the item's image, or I_IMAGECALLBACK if the item is a callback item. For information on callback items, see [CListCtrl::GetCallbackMask](#getcallbackmask).

*nMask*<br/>
The *nMask* parameter specifies which item attributes passed as parameters are valid. It can be one or more of the mask values described in [LVITEM Structure](/windows/win32/api/commctrl/ns-commctrl-lvitemw) in the Windows SDK. The valid values can be combined with the bitwise OR operator.

*nState*<br/>
Indicates the item's state, state image, and overlay image. For more information, see the Windows SDK topics [LVITEM Structure](/windows/win32/api/commctrl/ns-commctrl-lvitemw) and [List-View Item States](/windows/win32/Controls/list-view-item-states) for a list of valid flags.

*nStateMask*<br/>
Indicates which bits of the state member will be retrieved or modified. For more information, see [LVITEM Structure](/windows/win32/api/commctrl/ns-commctrl-lvitemw) in the Windows SDK.

*lParam*<br/>
A 32-bit application-specific value associated with the item. If this parameter is specified, you must set the *nMask* attribute LVIF_PARAM.

### Return Value

The index of the new item if successful or -1 otherwise.

### Remarks

Calling this method may cause the LVM_INSERTITEM message to be sent to your control window. The associated message handler for the control may fail to set the item text under certain conditions (such as using window styles such as LVS_OWNERDRAW). For more information on these conditions, see [LVM_INSERTITEM](/windows/win32/Controls/lvm-insertitem) in the Windows SDK.

### Example

```cpp
        CString strText;
        int nColumnCount = m_myListCtrl.GetHeaderCtrl()->GetItemCount();

        // Insert 10 items in the list view control.
        for (int i = 0; i < 10; i++)
        {
            strText.Format(TEXT("item %d"), i);

            // Insert the item, select every other item.
            m_myListCtrl.InsertItem(LVIF_TEXT | LVIF_STATE, i, strText,
                (i % 2) == 0 ? LVIS_SELECTED : 0, LVIS_SELECTED, 0, 0);

            // Initialize the text of the subitems.
            for (int j = 1; j < nColumnCount; j++)
            {
                strText.Format(TEXT("sub-item %d %d"), i, j);
                m_myListCtrl.SetItemText(i, j, strText);
            }
        }
```

## <a name="insertmarkhittest"></a> CListCtrl::InsertMarkHitTest

Retrieves the insertion point closest to a specified point.

```
int InsertMarkHitTest(
    LPPOINT pPoint,
    LPLVINSERTMARK plvim) const;
```

### Parameters

*pPoint*<br/>
A pointer to a [POINT](/windows/win32/api/windef/ns-windef-point) structure that contains the hit test coordinates, relative to the client area of the list control.

*plvim*<br/>
A pointer to an [LVINSERTMARK](/windows/win32/api/commctrl/ns-commctrl-lvinsertmark) structure that specifies the insertion point closest to the coordinates defined by the point parameter.

### Return Value

The insertion point closest to the specified point.

### Remarks

This member function emulates the functionality of the [LVM_INSERTMARKHITTEST](/windows/win32/Controls/lvm-insertmarkhittest) message, as described in the Windows SDK.

## <a name="isgroupviewenabled"></a> CListCtrl::IsGroupViewEnabled

Determines whether group view is enabled for a list view control.

```
BOOL IsGroupViewEnabled() const;
```

### Return Value

Returns TRUE if group view is enabled, or FALSE otherwise.

### Remarks

This member function emulates the functionality of the [LVM_ISGROUPVIEWENABLED](/windows/win32/Controls/lvm-isgroupviewenabled) message, as described in the Windows SDK.

## <a name="isitemvisible"></a> CListCtrl::IsItemVisible

Indicates whether a specified item in the current list-view control is visible.

```
BOOL IsItemVisible(int index) const;
```

### Parameters

*index*\
[in] Zero-based index of an item in the current list-view control.

### Return Value

TRUE if the specified item is visible; otherwise, FALSE.

### Remarks

This method sends the [LVM_ISITEMVISIBLE](/windows/win32/Controls/lvm-isitemvisible) message, which is described in the Windows SDK.

## <a name="mapidtoindex"></a> CListCtrl::MapIDToIndex

Maps the unique ID of an item in the current list-view control to an index.

```
UINT MapIDToIndex(UINT id) const;
```

### Parameters

*id*\
[in] The unique ID of an item.

### Return Value

The current index for the specified ID.

### Remarks

A list-view control internally tracks items by index. This can present problems because indexes can change during the control's lifetime. The list-view control can tag an item with an ID when the item is created and you can use this ID to guarantee uniqueness during the lifetime of the list-view control.

Note that in a multithreaded environment the index is guaranteed only on the thread that hosts the list-view control, not on background threads.

This method sends the [LVM_MAPIDTOINDEX](/windows/win32/controls/lvm-mapidtoindex) message, which is described in the Windows SDK.

## <a name="mapindextoid"></a> CListCtrl::MapIndexToID

Maps the index of an item in the current list-view control to a unique ID.

```
UINT MapIndexToID(UINT index) const;
```

### Parameters

*index*\
[in] The zero-based index of an item.

### Return Value

A unique ID for the specified item.

### Remarks

A list-view control internally tracks items by index. This can present problems because indexes can change during the control's lifetime. The list-view control can tag an item with an ID when the item is created. You can use this ID to access a specific item for the lifetime of the list-view control.

Note that in a multithreaded environment the index is guaranteed only on the thread that hosts the list-view control, not on background threads.

This method sends the [LVM_MAPINDEXTOID](/windows/win32/Controls/lvm-mapindextoid) message, which is described in the Windows SDK.

### Example

The following code example defines a variable, `m_listCtrl`, that is used to access the current list-view control. This variable is used in the next example.

```cpp
public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;
```

### Example

The following code example demonstrates the `MapIndexToID` method. In an earlier section of this code example, we created a list-view control that displays two columns titled "ClientID" and "Grade" in a report view. The following example maps the index of each list-view item to an identification number, and then retrieves the index for each identification number. Finally, the example reports whether the original indexes were retrieved.

```cpp
    // MapIndexToID
    int iCount = m_listCtrl.GetItemCount();
    UINT nId = 0;
    UINT nIndex = 0;
    for (int iIndexOriginal = 0; iIndexOriginal < iCount; iIndexOriginal++)
    {
        // Map index to ID.
        nId = m_listCtrl.MapIndexToID((UINT)iIndexOriginal);

        // Map ID to index.
        nIndex = m_listCtrl.MapIDToIndex(nId);

        if (nIndex != (UINT)(iIndexOriginal))
        {
            CString str;
            str.Format(_T("Mapped index (%d) is not equal to original index (%d)"),
                nIndex, (UINT)(iIndexOriginal));
            AfxMessageBox(str);
            return;
        }
    }
    AfxMessageBox(_T("The mapped indexes and original indexes are equal."),
        MB_ICONINFORMATION);
```

## <a name="movegroup"></a> CListCtrl::MoveGroup

Moves the specified group to the specified zero based index of the list view control.

```
LRESULT MoveGroup(
    int iGroupId,
    int toIndex);
```

### Parameters

*iGroupId*<br/>
The identifier of the group to be moved.

*toIndex*<br/>
The zero-based index where the group is to be moved.

### Return Value

The return value is not used.

### Remarks

This member function emulates the functionality of the [LVM_MOVEGROUP](/windows/win32/Controls/lvm-movegroup) message, as described in the Windows SDK.

## <a name="moveitemtogroup"></a> CListCtrl::MoveItemToGroup

Moves the specified item into the specified group.

```cpp
void MoveItemToGroup(
    int idItemFrom,
    int idGroupTo);
```

### Parameters

*idItemFrom*<br/>
[in] The index of the item to be moved.

*idGroupTo*<br/>
[in] The identifier of the group the item will be moved to.

### Remarks

> [!NOTE]
> This method currently is not implemented.

This method emulates the functionality of the [LVM_MOVEITEMTOGROUP](/windows/win32/Controls/lvm-moveitemtogroup) message, as described in the Windows SDK.

## <a name="redrawitems"></a> CListCtrl::RedrawItems

Forces a list view control to repaint a range of items.

```
BOOL RedrawItems(
    int nFirst,
    int nLast);
```

### Parameters

*nFirst*<br/>
Index of the first item to be repainted.

*nLast*<br/>
Index of the last item to be repainted.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

The specified items are not actually repainted until the list view window receives a WM_PAINT message. To repaint immediately, call the Windows [UpdateWindow](/windows/win32/api/winuser/nf-winuser-updatewindow) function after using this function.

## <a name="removeallgroups"></a> CListCtrl::RemoveAllGroups

Removes all groups from a list view control.

```cpp
void RemoveAllGroups();
```

### Remarks

This member function emulates the functionality of the [LVM_REMOVEALLGROUPS](/windows/win32/Controls/lvm-removeallgroups) message, as described in the Windows SDK.

## <a name="removegroup"></a> CListCtrl::RemoveGroup

Removes the specified group from the list view control.

```
LRESULT RemoveGroup(int iGroupId);
```

### Parameters

*iGroupId*<br/>
The identifier of the group to be removed.

### Return Value

Returns the index of the group if successful, or -1 otherwise.

### Remarks

This member function emulates the functionality of the [LVM_REMOVEGROUP](/windows/win32/Controls/lvm-removegroup) message, as described in the Windows SDK.

## <a name="scroll"></a> CListCtrl::Scroll

Scrolls the content of a list view control.

```
BOOL Scroll(CSize size);
```

### Parameters

*size*<br/>
A `CSize` object specifying the amount of horizontal and vertical scrolling, in pixels. The `y` member of *size* is divided by the height, in pixels, of the list view control's line, and the control is scrolled by the resulting number of lines.

### Return Value

Nonzero if successful; otherwise zero.

## <a name="setbkcolor"></a> CListCtrl::SetBkColor

Sets the background color of the list view control.

```
BOOL SetBkColor(COLORREF cr);
```

### Parameters

*cr*<br/>
Background color to set, or the CLR_NONE value for no background color. List view controls with background colors redraw themselves significantly faster than those without background colors. For information, see [COLORREF](/windows/win32/gdi/colorref) in the Windows SDK.

### Return Value

Nonzero if successful; otherwise zero.

### Example

```cpp
        // Use the 3D button face color for the background.
        COLORREF crBkColor = ::GetSysColor(COLOR_3DFACE);
        m_myListCtrl.SetBkColor(crBkColor);
        ASSERT(m_myListCtrl.GetBkColor() == crBkColor);
```

## <a name="setbkimage"></a> CListCtrl::SetBkImage

Sets the background image of a list view control.

```
BOOL SetBkImage(LVBKIMAGE* plvbkImage);

BOOL SetBkImage(
    HBITMAP hBitmap,
    BOOL fTile = TRUE,
    int xOffsetPercent = 0,
    int yOffsetPercent = 0);

BOOL SetBkImage(
    LPTSTR pszUrl,
    BOOL fTile = TRUE,
    int xOffsetPercent = 0,
    int yOffsetPercent = 0);
```

### Parameters

*plvbkImage*<br/>
Address of an `LVBKIMAGE` structure, containing the new background image information.

*hBitmap*<br/>
Handle to a bitmap.

*pszUrl*<br/>
A NULL-terminated string that contains the URL of the background image.

*fTile*<br/>
Nonzero if the image is to be tiled in the background of the list view control; otherwise 0.

*xOffsetPercent*<br/>
The offset, in pixels, of the image's left edge, from origin of the list view control.

*yOffsetPercent*<br/>
The offset, in pixels, of the image's top edge, from origin of the list view control.

### Return Value

Returns nonzero if successful, or zero otherwise.

### Remarks

> [!NOTE]
> Because `CListCtrl::SetBkImage` makes use of OLE COM functionality, the OLE libraries must be initialized before using `SetBkImage`. It is best to initialize the COM libraries when the application is initialized and uninitialize the libraries when the application terminates. This is automatically done in MFC applications that make use of ActiveX technology, OLE Automation, OLE Linking/Embedding, or ODBC/DAO operations.

### Example

See the example for [CListCtrl::GetBkImage](#getbkimage).

## <a name="setcallbackmask"></a> CListCtrl::SetCallbackMask

Sets the callback mask for a list view control.

```
BOOL SetCallbackMask(UINT nMask);
```

### Parameters

*nMask*<br/>
New value of the callback mask.

### Return Value

Nonzero if successful; otherwise zero.

### Example

```cpp
    // Set the callback mask so that only the selected and focused states
    // are stored for each item.
    m_myListCtrl.SetCallbackMask(LVIS_SELECTED|LVIS_FOCUSED);
    ASSERT(m_myListCtrl.GetCallbackMask() ==
        (LVIS_SELECTED|LVIS_FOCUSED));
```

## <a name="setcheck"></a> CListCtrl::SetCheck

Determines if the state image of a list control item is visible.

```
BOOL SetCheck(
    int nItem,
    BOOL fCheck = TRUE);
```

### Parameters

*nItem*<br/>
The zero-based index of a list control item.

*fCheck*<br/>
Specifies whether the state image of the item should be visible or not. By default, *fCheck* is TRUE and the state image is visible. If *fCheck* is FALSE, it is not visible.

### Return Value

Nonzero if the item is checked, otherwise 0.

### Example

```cpp
        int nCount = m_myListCtrl.GetItemCount();
        BOOL fCheck = FALSE;

        // Set the check state of every other item to TRUE and
        // all others to FALSE.
        for (int i = 0; i < nCount; i++)
        {
            m_myListCtrl.SetCheck(i, fCheck);
            ASSERT((m_myListCtrl.GetCheck(i) && fCheck) ||
                (!m_myListCtrl.GetCheck(i) && !fCheck));
            fCheck = !fCheck;
        }
```

## <a name="setcolumn"></a> CListCtrl::SetColumn

Sets the attributes of a list view column.

```
BOOL SetColumn(
    int nCol,
    const LVCOLUMN* pColumn);
```

### Parameters

*nCol*<br/>
Index of the column whose attributes are to be set.

*pColumn*<br/>
Address of an [LVCOLUMN](/windows/win32/api/commctrl/ns-commctrl-lvcolumnw) structure that contains the new column attributes, as described in the Windows SDK. The structure's `mask` member specifies which column attributes to set. If the `mask` member specifies the LVCF_TEXT value, the structure's `pszText` member is the address of a null-terminated string and the structure's `cchTextMax` member is ignored.

### Return Value

Nonzero if successful; otherwise zero.

### Example

See the example for [CListCtrl::GetColumn](#getcolumn).

## <a name="setcolumnorderarray"></a> CListCtrl::SetColumnOrderArray

Sets the column order (left to right) of a list view control.

```
BOOL SetColumnOrderArray(
    int iCount,
    LPINT piArray);
```

### Parameters

*piArray*<br/>
A pointer to a buffer containing the index values of the columns in the list view control (from left to right). The buffer must be large enough to contain the total number of columns in the list view control.

*iCount*<br/>
Number of columns in the list view control.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_SetColumnOrderArray](/windows/win32/api/commctrl/nf-commctrl-listview_setcolumnorderarray), as described in the Windows SDK.

### Example

See the example for [CListCtrl::GetColumnOrderArray](#getcolumnorderarray).

## <a name="setcolumnwidth"></a> CListCtrl::SetColumnWidth

Changes the width of a column in report view or list view.

```
BOOL SetColumnWidth(
    int nCol,
    int cx);
```

### Parameters

*nCol*<br/>
Index of the column for which the width is to be set. In list view, this parameter must be 0.

*cx*<br/>
The new width of the column. Can be either LVSCW_AUTOSIZE or LVSCW_AUTOSIZE_USEHEADER, as described in [LVM_SETCOLUMNWIDTH](/windows/win32/Controls/lvm-setcolumnwidth) in the Windows SDK.

### Return Value

Nonzero if successful; otherwise zero.

## <a name="setextendedstyle"></a> CListCtrl::SetExtendedStyle

Sets the current extended styles of a list view control.

```
DWORD SetExtendedStyle(DWORD dwNewStyle);
```

### Parameters

*dwNewStyle*<br/>
A combination of extended styles to be used by the list view control. For a descriptive list of these styles, see the [Extended List View Styles](/windows/win32/Controls/extended-list-view-styles) topic in the Windows SDK.

### Return Value

A combination of the previous extended styles used by the list view control.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_SetExtendedListViewStyle](/windows/win32/api/commctrl/nf-commctrl-listview_setextendedlistviewstyle), as described in the Windows SDK.

### Example

```cpp
    // Allow the header controls item to be movable by the user.
    m_myListCtrl.SetExtendedStyle
        (m_myListCtrl.GetExtendedStyle()|LVS_EX_HEADERDRAGDROP);
```

## <a name="setgroupinfo"></a> CListCtrl::SetGroupInfo

Sets the information that describes the specified group of the current list-view control.

```
int SetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp);
```

### Parameters

*iGroupId*<br/>
The identifier of the group whose information is set.

*pgrp*<br/>
Pointer to an [LVGROUP](/windows/win32/api/commctrl/ns-commctrl-lvgroup) structure that contains the information to set. The caller is responsible for allocating this structure and setting its members.

### Return Value

The ID of the group if the method is successful; otherwise, -1.

### Remarks

This method sends the [LVM_SETGROUPINFO](/windows/win32/Controls/lvm-setgroupinfo) message, which is described in the Windows SDK.

## <a name="setgroupmetrics"></a> CListCtrl::SetGroupMetrics

Sets the group metrics of a list view control.

```cpp
void SetGroupMetrics(PLVGROUPMETRICS pGroupMetrics);
```

### Parameters

*pGroupMetrics*<br/>
A pointer to an [LVGROUPMETRICS](/windows/win32/api/commctrl/ns-commctrl-lvgroupmetrics) structure containing the group metrics information to be set.

### Remarks

This member function emulates the functionality of the [LVM_SETGROUPMETRICS](/windows/win32/Controls/lvm-setgroupmetrics) message, as described in the Windows SDK.

## <a name="sethotcursor"></a> CListCtrl::SetHotCursor

Sets the cursor used when hot tracking is enabled for a list view control.

```
HCURSOR SetHotCursor(HCURSOR hc);
```

### Parameters

*hc*<br/>
A handle to a cursor resource, used to represent the hot cursor.

### Return Value

The handle to the previous hot cursor resource being used by the list view control.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_SetHotCursor](/windows/win32/api/commctrl/nf-commctrl-listview_sethotcursor), as described in the Windows SDK.

The hot cursor, only visible when hover selection is enabled, appears as the cursor passes over any list view item. Hover selection is enabled by setting the LVS_EX_TRACKSELECT extended style.

### Example

See the example for [CListCtrl::GetHotCursor](#gethotcursor).

## <a name="sethotitem"></a> CListCtrl::SetHotItem

Sets the current hot item of a list view control.

```
int SetHotItem(int iIndex);
```

### Parameters

*iIndex*<br/>
Zero-based index of the item to be set as the hot item.

### Return Value

The zero-based index of the previously hot item.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_SetHotItem](/windows/win32/api/commctrl/nf-commctrl-listview_sethotitem), as described in the Windows SDK.

### Example

See the example for [CListCtrl::GetHotItem](#gethotitem).

## <a name="sethovertime"></a> CListCtrl::SetHoverTime

Sets the current hover time of a list view control.

```
DWORD SetHoverTime(DWORD dwHoverTime = (DWORD)-1);
```

### Parameters

*dwHoverTime*<br/>
The new delay, in milliseconds, which the mouse cursor must hover over an item before it is selected. If the default value is passed, the time is set to the default hover time.

### Return Value

The previous hover time, in milliseconds.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_SetHoverTime](/windows/win32/api/commctrl/nf-commctrl-listview_sethovertime), as described in the Windows SDK.

### Example

See the example for [CListCtrl::GetHoverTime](#gethovertime).

## <a name="seticonspacing"></a> CListCtrl::SetIconSpacing

Sets the spacing between icons in a list view control.

```
CSize SetIconSpacing(
    int cx,
    int cy);

CSize SetIconSpacing(CSize size);
```

### Parameters

*cx*<br/>
The distance (in pixels) between icons on the x-axis.

*cy*<br/>
The distance (in pixels) between icons on the y-axis.

*size*<br/>
A `CSize` object specifying the distance (in pixels) between icons on the x- and y-axes.

### Return Value

A [CSize](../../atl-mfc-shared/reference/csize-class.md) object containing the previous values for icon spacing.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_SetIconSpacing](/windows/win32/api/commctrl/nf-commctrl-listview_seticonspacing), as described in the Windows SDK.

### Example

```cpp
    // Leave lots of space between icons.
    m_myListCtrl.SetIconSpacing(CSize(100, 100));
```

## <a name="setimagelist"></a> CListCtrl::SetImageList

Assigns an image list to a list view control.

```
CImageList* SetImageList(
    CImageList* pImageList,
    int nImageListType);
```

### Parameters

*pImageList*<br/>
Pointer to the image list to assign.

*nImageListType*<br/>
Type of image list. It can be one of these values:

- LVSIL_NORMAL Image list with large icons.

- LVSIL_SMALL Image list with small icons.

- LVSIL_STATE Image list with state images.

### Return Value

A pointer to the previous image list.

### Example

See the example for [CListCtrl::GetImageList](#getimagelist).

## <a name="setinfotip"></a> CListCtrl::SetInfoTip

Sets the tooltip text.

```
BOOL SetInfoTip(PLVSETINFOTIP plvInfoTip);
```

### Parameters

*plvInfoTip*<br/>
A pointer to an [LVFSETINFOTIP](/windows/win32/api/commctrl/ns-commctrl-lvsetinfotip) structure containing the information to be set.

### Return Value

Returns TRUE on success, FALSE on failure.

### Remarks

This member function emulates the functionality of the [LVM_SETINFOTIP](/windows/win32/Controls/lvm-setinfotip) message, as described in the Windows SDK.

## <a name="setinsertmark"></a> CListCtrl::SetInsertMark

Sets the insertion point to the defined position.

```
BOOL SetInsertMark(LPLVINSERTMARK plvim);
```

### Parameters

*plvim*<br/>
A pointer to an [LVINSERTMARK](/windows/win32/api/commctrl/ns-commctrl-lvinsertmark) structure specifying where to set the insertion point.

### Return Value

Returns TRUE if successful, or FALSE otherwise. FALSE is returned if the size in the `cbSize` member of the `LVINSERTMARK` structure does not equal the actual size of the structure, or when an insertion point does not apply in the current view.

### Remarks

This member function emulates the functionality of the [LVM_SETINSERTMARK](/windows/win32/Controls/lvm-setinsertmark) message, as described in the Windows SDK.

## <a name="setinsertmarkcolor"></a> CListCtrl::SetInsertMarkColor

Sets the color of the insertion point.

```
COLORREF SetInsertMarkColor(COLORREF color);
```

### Parameters

*color*<br/>
A [COLORREF](/windows/win32/gdi/colorref) structure specifying the color to set the insertion point.

### Return Value

Returns a `COLORREF` structure containing the previous color.

### Remarks

This member function emulates the functionality of the [LVM_SETINSERTMARKCOLOR](/windows/win32/Controls/lvm-setinsertmarkcolor) message, as described in the Windows SDK.

## <a name="setitem"></a> CListCtrl::SetItem

Sets some or all of a list view item's attributes.

```
BOOL SetItem(const LVITEM* pItem);

BOOL SetItem(
    int nItem,
    int nSubItem,
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam);

BOOL SetItem(
    int nItem,
    int nSubItem,
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam,
    int nIndent);
```

### Parameters

*pItem*<br/>
Address of an [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure that contains the new item attributes, as described in the Windows SDK. The structure's `iItem` and `iSubItem` members identify the item or subitem, and the structure's `mask` member specifies which attributes to set. For more information on the `mask` member, see the **Remarks**.

*nItem*<br/>
Index of the item whose attributes are to be set.

*nSubItem*<br/>
Index of the subitem whose attributes are to be set.

*nMask*<br/>
Specifies which attributes are to be set (see the Remarks).

*lpszItem*<br/>
Address of a null-terminated string specifying the item's label.

*nImage*<br/>
Index of the item's image within the image list.

*nState*<br/>
Specifies values for states to be changed (see the Remarks).

*nStateMask*<br/>
Specifies which states are to be changed (see the Remarks).

*lParam*<br/>
A 32-bit application-specific value to be associated with the item.

*nIndent*<br/>
Width, in pixels, of the indentation. If *nIndent* is less than the system-defined minimum width, the new width is set to the system-defined minimum

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

The `iItem` and `iSubItem` members of the `LVITEM` structure and the *nItem* and *nSubItem* parameters identify the item and subitem whose attributes are to be set.

The `mask` member of the `LVITEM` structure and the *nMask* parameter specify which item attributes are to be set:

- LVIF_TEXT The `pszText` member or the *lpszItem* parameter is the address of a null-terminated string; the `cchTextMax` member is ignored.

- LVIF_STATE The `stateMask` member or *nStateMask* parameter specifies which item states to change and the `state` member or *nState* parameter contains the values for those states.

### Example

See the example for [CListCtrl::HitTest](#hittest).

## <a name="setitemcount"></a> CListCtrl::SetItemCount

Prepares a list view control for adding a large number of items.

```cpp
void SetItemCount(int nItems);
```

### Parameters

*nItems*<br/>
Number of items that the control will ultimately contain.

### Remarks

To set the item count for a virtual list view control, see [CListCtrl::SetItemCountEx](#setitemcountex).

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_SetItemCount](/windows/win32/api/commctrl/nf-commctrl-listview_setitemcount), as described in the Windows SDK.

### Example

```cpp
        CString str;

        // Add 1024 items to the list view control.
        m_myListCtrl.SetItemCount(1024);

        for (int i = 0; i < 1024; i++)
        {
            str.Format(TEXT("item %d"), i);
            m_myListCtrl.InsertItem(i, str);
        }
```

## <a name="setitemcountex"></a> CListCtrl::SetItemCountEx

Sets the item count for a virtual list view control.

```
BOOL SetItemCountEx(
    int iCount,
    DWORD dwFlags = LVSICF_NOINVALIDATEALL);
```

### Parameters

*iCount*<br/>
Number of items that the control will ultimately contain.

*dwFlags*<br/>
Specifies the behavior of the list view control after resetting the item count. This value can be a combination of the following:

- LVSICF_NOINVALIDATEALL The list view control will not repaint unless affected items are currently in view. This is the default value.

- LVSICF_NOSCROLL The list view control will not change the scroll position when the item count changes.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_SetItemCountEx](/windows/win32/api/commctrl/nf-commctrl-listview_setitemcountex), as described in the Windows SDKand should only be called for virtual list views.

### Example

```cpp
        CString str;

        // Add 1024 items to the list view control.

        // Force my virtual list view control to allocate
        // enough memory for my 1024 items.
        m_myVirtualListCtrl.SetItemCountEx(1024, LVSICF_NOSCROLL|
            LVSICF_NOINVALIDATEALL);

        for (int i = 0; i < 1024; i++)
        {
            str.Format(TEXT("item %d"), i);
            m_myVirtualListCtrl.InsertItem(i, str);
        }
```

## <a name="setitemdata"></a> CListCtrl::SetItemData

Sets the 32-bit application-specific value associated with the item specified by *nItem*.

```
BOOL SetItemData(int nItem, DWORD_PTR dwData);
```

### Parameters

*nItem*<br/>
Index of the list item whose data is to be set.

*dwData*<br/>
A 32-bit value to be associated with the item.

### Return Value

Nonzero if successful; otherwise 0.

### Remarks

This value is the `lParam` member of the [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure, as described in the Windows SDK.

### Example

```cpp
    // Set the data of each item to be equal to its index.
    for (int i = 0; i < m_myListCtrl.GetItemCount(); i++)
    {
        m_myListCtrl.SetItemData(i, i);
    }
```

## <a name="setitemindexstate"></a> CListCtrl::SetItemIndexState

Sets the state of an item in the current list-view control.

```
BOOL SetItemIndexState(
    PLVITEMINDEX pItemIndex,
    DWORD dwState,
    DWORD dwMask) const;
```

### Parameters

*pItemIndex*\
[in] Pointer to an [LVITEMINDEX](/windows/win32/api/commctrl/ns-commctrl-lvitemindex) structure that describes an item. The caller is responsible for allocating this structure and setting its members.

*dwState*\
[in] The state to set the item, which is a bitwise combination of [list view item states](/windows/win32/Controls/list-view-item-states). Specify zero to reset, or one to set, a state.

*dwMask*\
[in] A mask of the valid bits of the state specified by the *dwState* parameter. Specify a bitwise combination (OR) of [list view item states](/windows/win32/Controls/list-view-item-states).

### Return Value

TRUE if this method is successful; otherwise, FALSE.

### Remarks

For more information about the *dwState* parameter, see [List View Item States](/windows/win32/Controls/list-view-item-states).

For more information about the *dwMask* parameter, see the *stateMask* member of the [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure.

This method sends the [LVM_SETITEMINDEXSTATE](/windows/win32/Controls/lvm-setitemindexstate) message, which is described in the Windows SDK.

## <a name="setitemposition"></a> CListCtrl::SetItemPosition

Moves an item to a specified position in a list view control.

```
BOOL SetItemPosition(
    int nItem,
    POINT pt);
```

### Parameters

*nItem*<br/>
Index of the item whose position is to be set.

*pt*<br/>
A [POINT](/windows/win32/api/windef/ns-windef-point) structure specifying the new position, in view coordinates, of the item's upper-left corner.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

The control must be in icon or small icon view.

If the list view control has the LVS_AUTOARRANGE style, the list view is arranged after the position of the item is set.

### Example

See the example for [CListCtrl::GetItemPosition](#getitemposition).

## <a name="setitemstate"></a> CListCtrl::SetItemState

Changes the state of an item in a list view control.

```
BOOL SetItemState(
    int nItem,
    LVITEM* pItem);

BOOL SetItemState(
    int nItem,
    UINT nState,
    UINT nMask);
```

### Parameters

*nItem*<br/>
Index of the item whose state is to be set. Pass -1 to apply the state change to all items.

*pItem*<br/>
Address of an [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure, as described in the Windows SDK. The structure's `stateMask` member specifies which state bits to change, and the structure's `state` member contains the new values for those bits. The other members are ignored.

*nState*<br/>
New values for the state bits. For a list of possible values, see [CListCtrl::GetNextItem](#getnextitem) and the [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) state member.

*nMask*<br/>
Mask specifying which state bits to change. This value corresponds to the stateMask member of  the [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

An item's "state" is a value that specifies the item's availability, indicates user actions, or otherwise reflects the item's status. A list view control changes some state bits, such as when the user selects an item. An application might change other state bits to disable or hide the item, or to specify an overlay image or state image.

### Example

See the example for [CListCtrl::GetTopIndex](#gettopindex).

## <a name="setitemtext"></a> CListCtrl::SetItemText

Changes the text of a list view item or subitem.

```
BOOL SetItemText(
    int nItem,
    int nSubItem,
    LPCTSTR lpszText);
```

### Parameters

*nItem*<br/>
Index of the item whose text is to be set.

*nSubItem*<br/>
Index of the subitem, or zero to set the item label.

*lpszText*<br/>
Pointer to a string that contains the new item text.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

This method is not intended for use with controls containing the LVS_OWNERDATA window style (in fact, this will cause an assertion in Debug builds). For more information about this list control style, see [List-View Controls Overview](/windows/win32/Controls/list-view-controls-overview).

### Example

See the example for [CListCtrl::InsertItem](#insertitem).

## <a name="setoutlinecolor"></a> CListCtrl::SetOutlineColor

Sets the color of the border of a list-view control if the [LVS_EX_BORDERSELECT](/windows/win32/Controls/list-view-window-styles) extended window style is set.

```
COLORREF SetOutlineColor(COLORREF color);
```

### Parameters

*color*<br/>
The new [COLORREF](/windows/win32/gdi/colorref) structure containing the outline color.

### Return Value

The previous `COLORREF` structure containing the outline color

### Remarks

This member function emulates the functionality of the [LVM_SETOUTLINECOLOR](/windows/win32/Controls/lvm-setoutlinecolor) message, as described in the Windows SDK.

## <a name="setselectedcolumn"></a> CListCtrl::SetSelectedColumn

Sets the selected column of the list view control.

```
LRESULT SetSelectedColumn(int iCol);
```

### Parameters

*iCol*<br/>
The index of the column to be selected.

### Return Value

The return value is not used.

### Remarks

This member function emulates the functionality of the [LVM_SETSELECTEDCOLUMN](/windows/win32/Controls/lvm-setselectedcolumn) message, as described in the Windows SDK.

## <a name="setselectionmark"></a> CListCtrl::SetSelectionMark

Sets the selection mark of a list view control.

```
int SetSelectionMark(int iIndex);
```

### Parameters

*iIndex*<br/>
The zero-based index of the first item in a multiple selection.

### Return Value

The previous selection mark, or -1 if there was no selection mark.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_SetSelectionMark](/windows/win32/api/commctrl/nf-commctrl-listview_setselectionmark), as described in the Windows SDK.

### Example

See the example for [CListCtrl::GetSelectionMark](#getselectionmark).

## <a name="settextbkcolor"></a> CListCtrl::SetTextBkColor

Sets the background color of text in a list view control.

```
BOOL SetTextBkColor(COLORREF cr);
```

### Parameters

*cr*<br/>
A COLORREF specifying the new text background color. For information, see [COLORREF](/windows/win32/gdi/colorref) in the Windows SDK.

### Return Value

Nonzero if successful; otherwise zero.

### Example

```cpp
        // Use the 3D button face color for the background.
        COLORREF crBkColor = ::GetSysColor(COLOR_3DFACE);
        m_myListCtrl.SetTextBkColor(crBkColor);
        ASSERT(m_myListCtrl.GetTextBkColor() == crBkColor);
```

## <a name="settextcolor"></a> CListCtrl::SetTextColor

Sets the text color of a list view control.

```
BOOL SetTextColor(COLORREF cr);
```

### Parameters

*cr*<br/>
A COLORREF specifying the new text color. For information, see [COLORREF](/windows/win32/gdi/colorref) in the Windows SDK.

### Return Value

Nonzero if successful; otherwise zero.

### Example

```cpp
    // Use the window text color for
    // the item text of the list view control.
    COLORREF crTextColor = ::GetSysColor(COLOR_WINDOWTEXT);
    m_myListCtrl.SetTextColor(crTextColor);
    ASSERT(m_myListCtrl.GetTextColor() == crTextColor);
```

## <a name="settileinfo"></a> CListCtrl::SetTileInfo

Sets the information for a tile of the list view control.

```
BOOL SetTileInfo(PLVTILEINFO pTileInfo);
```

### Parameters

*pTileInfo*<br/>
A pointer to an [LVTILEINFO](/windows/win32/api/commctrl/ns-commctrl-lvtileinfo) structure containing the information to be set.

### Return Value

Returns TRUE on success, FALSE on failure.

### Remarks

This member function emulates the functionality of the [LVM_SETTILEINFO](/windows/win32/Controls/lvm-settileinfo) message, as described in the Windows SDK.

## <a name="settileviewinfo"></a> CListCtrl::SetTileViewInfo

Sets information that a list view control uses in tile view.

```
BOOL SetTileViewInfo(PLVTILEVIEWINFO ptvi);
```

### Parameters

*ptvi*<br/>
A pointer to an [LVTILEVIEWINFO](/windows/win32/api/commctrl/ns-commctrl-lvtileviewinfo) structure containing the information to set.

### Return Value

Returns TRUE on success, FALSE on failure.

### Remarks

This member function emulates the functionality of the [LVM_SETTILEVIEWINFO](/windows/win32/Controls/lvm-settileviewinfo) message, as described in the Windows SDK.

## <a name="settooltips"></a> CListCtrl::SetToolTips

Sets the tooltip control that the list view control will use to display tooltips.

```
CToolTipCtrl* SetToolTips(CToolTipCtrl* pWndTip);
```

### Parameters

*pWndTip*<br/>
A pointer to a `CToolTipCtrl` object that the list control will use.

### Return Value

A pointer to a [CToolTipCtrl](ctooltipctrl-class.md) object containing the tooltip previously used by the control, or NULL if no tooltips were used previously.

### Remarks

This member function implements the behavior of the Win32 message [LVM_SETTOOLTIPS](/windows/win32/Controls/lvm-settooltips), as described in the Windows SDK.

To not use tooltips, indicate the LVS_NOTOOLTIPS style when you create the `CListCtrl` object.

## <a name="setview"></a> CListCtrl::SetView

Sets the view of the list view control.

```
DWORD SetView(int iView);
```

### Parameters

*iView*<br/>
The view to be selected.

### Return Value

Returns 1 if successful, or -1 otherwise. For example, -1 is returned if the view is invalid.

### Remarks

This member function emulates the functionality of the [LVM_SETVIEW](/windows/win32/Controls/lvm-setview) message, as described in the Windows SDK.

## <a name="setworkareas"></a> CListCtrl::SetWorkAreas

Sets the area where icons can be displayed in a list view control.

```cpp
void SetWorkAreas(
    int nWorkAreas,
    LPRECT lpRect);
```

### Parameters

*nWorkAreas*<br/>
The number of `RECT` structures (or [CRect](../../atl-mfc-shared/reference/crect-class.md) objects) in the array pointed to by *lpRect*.

*lpRect*<br/>
The address of an array of `RECT` structures (or `CRect` objects) that specify the new work areas of the list view control. These areas must be specified in client coordinates. If this parameter is NULL, the working area will be set to the client area of the control.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_SetWorkAreas](/windows/win32/api/commctrl/nf-commctrl-listview_setworkareas), as described in the Windows SDK.

### Example

```cpp
    // Remove all working areas.
    m_myListCtrl.SetWorkAreas(0, NULL);
```

## <a name="sortgroups"></a> CListCtrl::SortGroups

Uses an application-defined comparison function to sort groups by ID within a list view control.

```
BOOL SortGroups(
    PFNLVGROUPCOMPARE _pfnGroupCompare,
    LPVOID _plv);
```

### Parameters

*_pfnGroupCompare*<br/>
A pointer to the group comparison function.

*_plv*<br/>
A void pointer.

### Return Value

Returns TRUE on success, FALSE on failure.

### Remarks

This member function emulates the functionality of the [LVM_SORTGROUPS](/windows/win32/Controls/lvm-sortgroups) message, as described in the Windows SDK.

## <a name="sortitems"></a> CListCtrl::SortItems

Sorts list view items by using an application-defined comparison function.

```
BOOL SortItems(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);
```

### Parameters

*pfnCompare*<br/>
[in] Address of the application-defined comparison function.

The sort operation calls the comparison function each time the relative order of two list items needs to be determined. The comparison function must be either a static member of a class or a stand-alone function that is not a member of any class.

*dwData*<br/>
[in] Application-defined value that is passed to the comparison function.

### Return Value

TRUE if the method successful; otherwise FALSE.

### Remarks

This method changes the index of each item to reflect the new sequence.

The comparison function, *pfnCompare*, has the following form:

```
int CALLBACK CompareFunc(LPARAM lParam1,
    LPARAM lParam2,
    LPARAM lParamSort);
```

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equal.

The *lParam1* parameter is the 32-bit value associated with the first item that is compared, and the *lParam2* parameter is the value associated with the second item. These are the values that were specified in the *lParam* member of the items' [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure when they were inserted into the list. The *lParamSort* parameter is the same as the *dwData* value.

This method sends the [LVM_SORTITEMS](/windows/win32/Controls/lvm-sortitems) message, which is described in the Windows SDK.

### Example

The following is a simple comparison function that results in items being sorted by their *lParam* values.

```cpp
// Sort items by associated lParam
int CALLBACK CListCtrlDlg::MyCompareProc(LPARAM lParam1, LPARAM lParam2,
    LPARAM lParamSort)
{
    UNREFERENCED_PARAMETER(lParamSort);
    return (int)(lParam1 - lParam2);
}
```

```cpp
// Sort the items by passing in the comparison function.
void CListCtrlDlg::Sort()
{
    m_myListCtrl.SortItems(&CListCtrlDlg::MyCompareProc, 0);
}
```

## <a name="sortitemsex"></a> CListCtrl::SortItemsEx

Sorts the items of the current list-view control by using an application-defined comparison function.

```
BOOL SortItemsEx(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);
```

### Parameters

*pfnCompare*\
[in] Address of the application-defined comparison function. The sort operation calls the comparison function each time the relative order of two list items needs to be determined. The comparison function must be either a static member of a class or a stand-alone function that is not a member of any class.

*dwData*\
[in] Application-defined value passed to the comparison function.

### Return Value

TRUE if this method is successful; otherwise, FALSE.

### Remarks

This method changes the index of each item to reflect the new sequence.

The comparison function, *pfnCompare*, has the following form:

```
int CALLBACK CompareFunc(LPARAM lParam1,
    LPARAM lParam2,
    LPARAM lParamSort);
```

This message is like [LVM_SORTITEMS](/windows/win32/Controls/lvm-sortitems), except for the type of information passed to the comparison function. In [LVM_SORTITEMS](/windows/win32/Controls/lvm-sortitems), *lParam1* and *lParam2* are the values of the items to compare. In [LVM_SORTITEMSEX](/windows/win32/Controls/lvm-sortitemsex), *lParam1* is the current index of the first item to compare and *lParam2* is the current index of the second item. You can send an [LVM_GETITEMTEXT](/windows/win32/Controls/lvm-getitemtext) message to retrieve more information about an item.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equal.

> [!NOTE]
> During the sorting process, the list-view contents are unstable. If the callback function sends any messages to the list-view control other than [LVM_GETITEM](/windows/win32/Controls/lvm-getitem), the results are unpredictable.

This method sends the [LVM_SORTITEMSEX](/windows/win32/Controls/lvm-sortitemsex) message, which is described in the Windows SDK.

### Example

The following code example defines a variable, `m_listCtrl`, that is used to access the current list-view control. This variable is used in the next example.

```cpp
public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;
```

### Example

The following code example demonstrates the `SortItemEx` method. In an earlier section of this code example, we created a list-view control that displays two columns titled "ClientID" and "Grade" in a report view. The following code example sorts the table by using the values in the "Grade" column.

```cpp
// The ListCompareFunc() method is a global function used by SortItemEx().
int CALLBACK ListCompareFunc(
                             LPARAM lParam1,
                             LPARAM lParam2,
                             LPARAM lParamSort)
{
    CListCtrl* pListCtrl = (CListCtrl*) lParamSort;
    CString    strItem1 = pListCtrl->GetItemText(static_cast<int>(lParam1), 1);
    CString    strItem2 = pListCtrl->GetItemText(static_cast<int>(lParam2), 1)
    int x1 = _tstoi(strItem1.GetBuffer());
    int x2 = _tstoi(strItem2.GetBuffer());
    int result = 0;
    if ((x1 - x2) < 0)
        result = -1;
    else if ((x1 - x2) == 0)
        result = 0;
    else
        result = 1;

    return result;
}

void CCListCtrl_s2Dlg::OnBnClickedButton1()
{
    // SortItemsEx
    m_listCtrl.SortItemsEx( ListCompareFunc, (LPARAM)&m_listCtrl );
}
```

## <a name="subitemhittest"></a> CListCtrl::SubItemHitTest

Determines which list view item, if any, is at a given position.

```
int SubItemHitTest(LPLVHITTESTINFO pInfo);
```

### Parameters

*pInfo*<br/>
A pointer to the [LVHITTESTINFO](/windows/win32/api/commctrl/ns-commctrl-lvhittestinfo) structure.

### Return Value

The one-based index of the item, or subitem, being tested (if any), or -1 otherwise.

### Remarks

This member function implements the behavior of the Win32 macro, [ListView_SubItemHitTest](/windows/win32/api/commctrl/nf-commctrl-listview_subitemhittest), as described in the Windows SDK.

### Example

```cpp
void CListCtrlDlg::OnDblClk(NMHDR* pNMHDR, LRESULT* pResult)
{
    UNREFERENCED_PARAMETER(pResult);
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;
    LVHITTESTINFO lvhti;

    // Clear the subitem text the user clicked on.
    lvhti.pt = pia->ptAction;
    m_myListCtrl.SubItemHitTest(&lvhti);

    if (lvhti.flags & LVHT_ONITEMLABEL)
    {
        m_myListCtrl.SetItemText(lvhti.iItem, lvhti.iSubItem, NULL);
    }
}
```

## <a name="update"></a> CListCtrl::Update

Forces the list view control to repaint the item specified by *nItem*.

```
BOOL Update(int nItem);
```

### Parameters

*nItem*<br/>
Index of the item to be updated.

### Return Value

Nonzero if successful; otherwise zero.

### Remarks

This function also arranges the list view control if it has the LVS_AUTOARRANGE style.

### Example

See the example for [CListCtrl::GetSelectedCount](#getselectedcount).

## See also

[MFC Sample ROWLIST](../../overview/visual-cpp-samples.md)<br/>
[CWnd Class](cwnd-class.md)<br/>
[Hierarchy Chart](../hierarchy-chart.md)<br/>
[CImageList Class](cimagelist-class.md)