`CListCtrl` 类

项目
06/16/2023

封装显示一组项的“列表视图控件”功能，每一项均包含一个图标（来自图像列表）和标签。

语法

class CListCtrl : public CWnd

成员

公共构造函数

名称	描述
`CListCtrl::CListCtrl`	构造 `CListCtrl` 对象。

公共方法

名称	描述
`CListCtrl::ApproximateViewRect`	确定显示列表视图控件项需要的宽度和高度。
`CListCtrl::Arrange`	对齐网格上的项。
`CListCtrl::CancelEditLabel`	取消项文本编辑操作。
`CListCtrl::Create`	创建列表控件并将它附加到 `CListCtrl` 对象。
`CListCtrl::CreateDragImage`	为指定项创建拖拽图像列表。
`CListCtrl::CreateEx`	创建具有指定 Windows 扩展样式的列表控件，并将其附加到 `CListCtrl` 对象。
`CListCtrl::DeleteAllItems`	删除控件中所有的项。
`CListCtrl::DeleteColumn`	从列表视图控件删除列。
`CListCtrl::DeleteItem`	删除控件中的项。
`CListCtrl::DrawItem`	在所有者绘制的控件的可视特征发生变化时调用。
`CListCtrl::EditLabel`	开始对项的文本进行就地编辑。
`CListCtrl::EnableGroupView`	启用或禁用控制列表视图控件中的项是否显示为组的功能。
`CListCtrl::EnsureVisible`	确保项可见。
`CListCtrl::FindItem`	搜索具有指定特征的列表视图项。
`CListCtrl::GetBkColor`	检索列表视图控件的背景色。
`CListCtrl::GetBkImage`	检索列表视图控件的当前背景图像。
`CListCtrl::GetCallbackMask`	检索列表视图控件的回调掩码。
`CListCtrl::GetCheck`	检索与项关联的状态图像的当前显示状态。
`CListCtrl::GetColumn`	检索控件的列的属性。
`CListCtrl::GetColumnOrderArray`	检索列表视图控件的列顺序（从左到右）。
`CListCtrl::GetColumnWidth`	检索报表视图或列表视图中的列的宽度。
`CListCtrl::GetCountPerPage`	计算列表视图控件中可垂直容纳的项数。
`CListCtrl::GetEditControl`	检索用于编辑项文本的编辑控件的句柄。
`CListCtrl::GetEmptyText`	检索显示当前列表视图控件是否空的字符串。
`CListCtrl::GetExtendedStyle`	检索列表视图控件当前的扩展样式。
`CListCtrl::GetFirstSelectedItemPosition`	检索列表视图控件中第一个选定的列表视图项的位置。
`CListCtrl::GetFocusedGroup`	检索当前列表视图控件中具有键盘焦点的组。
`CListCtrl::GetGroupCount`	检索当前列表视图控件中的组数。
`CListCtrl::GetGroupInfo`	获取列表视图控件的指定组的信息。
`CListCtrl::GetGroupInfoByIndex`	检索关于当前列表视图控件中的指定组的信息。
`CListCtrl::GetGroupMetrics`	检索组的指标。
`CListCtrl::GetGroupRect`	检索当前列表视图控件中的指定组的边框。
`CListCtrl::GetGroupState`	检索当前列表视图控件中的指定组的状态。
`CListCtrl::GetHeaderCtrl`	检索列表视图控件的标头控件。
`CListCtrl::GetHotCursor`	检索为列表视图控件启用了热跟踪时使用的光标。
`CListCtrl::GetHotItem`	检索当前位于光标下的列表视图项。
`CListCtrl::GetHoverTime`	检索列表视图控件的当前悬停时间。
`CListCtrl::GetImageList`	检索用于绘制列表视图项的图像列表的句柄。
`CListCtrl::GetInsertMark`	检索插入标记的当前位置。
`CListCtrl::GetInsertMarkColor`	检索插入标记的当前颜色。
`CListCtrl::GetInsertMarkRect`	检索绑定插入点的矩形。
`CListCtrl::GetItem`	检索列表视图项的属性。
`CListCtrl::GetItemCount`	检索列表视图控件中的项数。
`CListCtrl::GetItemData`	检索与项关联的特定于应用程序的值。
`CListCtrl::GetItemIndexRect`	检索当前列表视图控件中的子项的全部或部分的边框。
`CListCtrl::GetItemPosition`	检索列表视图项的位置。
`CListCtrl::GetItemRect`	检索项的边框。
`CListCtrl::GetItemSpacing`	计算当前列表视图控件中的项之间的间距。
`CListCtrl::GetItemState`	检索列表视图项的状态。
`CListCtrl::GetItemText`	检索列表视图项或子项的文本。
`CListCtrl::GetNextItem`	搜索一个列表视图项，它具有指定属性并具有与给定项的指定关系。
`CListCtrl::GetNextItemIndex`	检索具有指定属性集的当前列表视图控件中的项的索引。
`CListCtrl::GetNextSelectedItem`	检索一个列表视图项位置的索引，以及下一个用于迭代的列表视图项的位置。
`CListCtrl::GetNumberOfWorkAreas`	检索列表视图控件当前工作区域的数量。
`CListCtrl::GetOrigin`	检索列表视图控件当前视图原点。
`CListCtrl::GetOutlineColor`	检索列表视图控件的边框颜色。
`CListCtrl::GetSelectedColumn`	检索列表控件中当前选定的列的索引。
`CListCtrl::GetSelectedCount`	检索列表视图控件中选定项的数量。
`CListCtrl::GetSelectionMark`	检索列表视图控件的选择标记。
`CListCtrl::GetStringWidth`	确定显示给定字符串的全部所必需的最小列宽。
`CListCtrl::GetSubItemRect`	检索列表视图控件中的项的边框。
`CListCtrl::GetTextBkColor`	检索列表视图控件的文本背景色。
`CListCtrl::GetTextColor`	检索列表视图控件的文本颜色。
`CListCtrl::GetTileInfo`	检索有关列表视图控件中的图块的信息。
`CListCtrl::GetTileViewInfo`	检索有关平铺视图中的列表视图控件的信息。
`CListCtrl::GetToolTips`	检索列表视图控件用于显示工具提示的工具提示控件。
`CListCtrl::GetTopIndex`	检索最上面的可见项的索引。
`CListCtrl::GetView`	获取列表视图控件的视图。
`CListCtrl::GetViewRect`	检索列表视图控件中所有项的边框。
`CListCtrl::GetWorkAreas`	检索列表视图控件的当前工作区域。
`CListCtrl::HasGroup`	确定列表视图控件是否具有指定组。
`CListCtrl::HitTest`	确定位于指定位置的列表视图项。
`CListCtrl::InsertColumn`	在列表视图控件中插入新列。
`CListCtrl::InsertGroup`	在列表视图控件中插入组。
`CListCtrl::InsertGroupSorted`	将指定组插入已排序的组列表中。
`CListCtrl::InsertItem`	在列表视图控件中插入新项。
`CListCtrl::InsertMarkHitTest`	检索最靠近指定点的插入点。
`CListCtrl::IsGroupViewEnabled`	确定是否为列表视图控件启用了组视图。
`CListCtrl::IsItemVisible`	指示指定项在当前列表视图控件中是否可见。
`CListCtrl::MapIDToIndex`	将当前列表视图控件中的项的唯一 ID 映射到索引。
`CListCtrl::MapIndexToID`	将当前列表视图控件中的项的索引映射到唯一 ID。
`CListCtrl::MoveGroup`	移动指定组。
`CListCtrl::MoveItemToGroup`	将指定组移到列表视图控件的指定的从零开始的索引。
`CListCtrl::RedrawItems`	强制列表视图控件重新绘制一系列的项。
`CListCtrl::RemoveAllGroups`	从列表视图控件中删除所有的组。
`CListCtrl::RemoveGroup`	从列表视图控件中删除指定的组。
`CListCtrl::Scroll`	滚动列表视图控件的内容。
`CListCtrl::SetBkColor`	设置列表视图控件的背景色。
`CListCtrl::SetBkImage`	设置列表视图控件的当前背景图像。
`CListCtrl::SetCallbackMask`	设置列表视图控件的回调掩码。
`CListCtrl::SetCheck`	设置与项关联的状态图像的当前显示状态。
`CListCtrl::SetColumn`	设置列表视图列的属性。
`CListCtrl::SetColumnOrderArray`	设置列表视图控件的列顺序（从左到右）。
`CListCtrl::SetColumnWidth`	更改报表视图或列表视图中的列的宽度。
`CListCtrl::SetExtendedStyle`	设置列表视图控件当前的扩展样式。
`CListCtrl::SetGroupInfo`	设置列表视图控件的指定组的信息。
`CListCtrl::SetGroupMetrics`	设置列表视图控件的组指标。
`CListCtrl::SetHotCursor`	设置为列表视图控件启用了热跟踪时使用的光标。
`CListCtrl::SetHotItem`	设置列表视图控件的当前热项。
`CListCtrl::SetHoverTime`	设置列表视图控件的当前悬停时间。
`CListCtrl::SetIconSpacing`	设置列表视图控件中的图标间的间距。
`CListCtrl::SetImageList`	向列表视图控件分配图像列表。
`CListCtrl::SetInfoTip`	设置工具提示文本。
`CListCtrl::SetInsertMark`	将插入点设置为定义的位置。
`CListCtrl::SetInsertMarkColor`	设置插入点的颜色。
`CListCtrl::SetItem`	设置列表视图项的部分属性或全部属性。
`CListCtrl::SetItemCount`	准备一个列表视图控件，用于添加大量的项。
`CListCtrl::SetItemCountEx`	设置虚拟列表视图控件的项计数。
`CListCtrl::SetItemData`	设置项的应用程序特定的值。
`CListCtrl::SetItemIndexState`	设置当前列表视图控件中的项的状态。
`CListCtrl::SetItemPosition`	将项移到列表视图控件中的指定位置。
`CListCtrl::SetItemState`	更改列表视图控件中的项的状态。
`CListCtrl::SetItemText`	更改列表视图项或子项的文本。
`CListCtrl::SetOutlineColor`	设置列表视图控件的边框颜色。
`CListCtrl::SetSelectedColumn`	设置列表视图控件的选定列。
`CListCtrl::SetSelectionMark`	设置列表视图控件的选择标记。
`CListCtrl::SetTextBkColor`	设置列表视图控件中的文本的背景色。
`CListCtrl::SetTextColor`	设置列表视图控件的文本颜色。
`CListCtrl::SetTileInfo`	设置列表视图控件的图块的信息。
`CListCtrl::SetTileViewInfo`	设置列表视图控件在平铺视图中使用的信息。
`CListCtrl::SetToolTips`	设置列表视图控件将用于显示工具提示的工具提示控件。
`CListCtrl::SetView`	设置列表视图控件的视图。
`CListCtrl::SetWorkAreas`	设置可在列表视图控件中显示图标的区域。
`CListCtrl::SortGroups`	使用用户定义的函数对列表视图控件的组进行排序。
`CListCtrl::SortItems`	使用应用程序定义的比较函数对列表视图项排序。
`CListCtrl::SortItemsEx`	使用应用程序定义的比较函数对列表视图项排序。
`CListCtrl::SubItemHitTest`	确定哪一个列表视图项（如果有）位于给定位置。
`CListCtrl::Update`	强制控件重新绘制指定的项。

备注

除了图标和标签之外，各项还可以在图标和标签右侧的列中显示信息。此控件（以及 CListCtrl 类）仅适用于在 Windows 95/98 和 Windows NT 版本 3.51 及更高版本下运行的程序。

下面是 CListCtrl 类的简要概述。有关详细、概念性的介绍，请参阅使用 CListCtrl 和控件。

Views

列表视图控件可通过四种不同的方式（称为“视图”）显示其内容。

图标视图

各项显示为一个全尺寸图标（32 x 32 像素），下有一个标签。用户可以将项拖到列表视图窗口中的任何位置。
小图标视图

各项显示为一个小图标（16 x 16 像素），小图标右侧有一个标签。用户可以将项拖到列表视图窗口中的任何位置。
列表视图

各项显示为一个小图标，小图标右侧有一个标签。项按列排列，不能将项拖到列表视图窗口中的任何位置。
报表视图

各项显示在自己的行上，其他信息位于右侧的列中。最左边的列包含小图标和标签，后面的列包含应用程序指定的子项。嵌入的标头控件（CHeaderCtrl 类）实现这些列。有关报表视图中的标头控件和列的详细信息，请参阅使用 CListCtrl：向控件添加列（报表视图）。

控件的当前列表视图的样式决定当前视图。有关这些样式及其用法的详细信息，请参阅使用 CListCtrl：更改列表控件样式。

扩展样式

除了标准列表样式外，CListCtrl 类还支持一大组提供丰富功能的扩展样式。此功能的一些示例包括：

悬停选择

启用后，当光标在项上停留了一定时间时，允许自动选择某个项。
虚拟列表视图

启用后，允许控件最多支持 DWORD 项。这可通过将管理项数据的开销归置到应用程序上来实现。除了项选择和焦点信息外，所有项信息都必须由应用程序管理。有关详细信息，请参阅使用 CListCtrl：虚拟列表控件。
单击激活和双击激活

启用后，支持对突出显示的项进行热跟踪（自动突出显示项文本）以及单击激活/双击激活。
拖放式列排序

启用后，能够在列表视图控件中通过拖放的方式对列进行重新排序。仅在报表视图中提供此功能。

有关使用这些新扩展样式的信息，请参阅使用 CListCtrl：更改列表控件样式。

项和子项

列表视图控件中的各项都包含图标（来自图像列表）、标签、当前状态以及应用程序定义的值（称为“项数据”）。还可以将一个或多个子项与各个项关联起来。 “子项”是一个字符串，在报表视图中可将该字符串显示在项的图标和标签右侧的列中。列表视图控件中的所有项都必须具有相同数量的子项。

CListCtrl 类提供多个用于插入、删除、查找和修改这些项的函数。有关详细信息，请参阅 CListCtrl::GetItem、CListCtrl::InsertItem、CListCtrl::FindItem、向控件添加项，以及在列表控件中滚动、排列、排序和查找。

默认情况下，列表视图控件负责存储项的图标和文本属性。但是，除了这些项类型外，CListCtrl 类还支持“回调项”。回调项是一种列表视图项，应用程序（而不是控件）为其存储文本和/或图标。回调掩码用于指定哪些项属性（文本和/或图标）是由应用程序提供的。如果应用程序使用回调项，它必须能够按需提供文本和/或图标属性。应用程序已维护这些信息中的一部分时，回调项非常有用。有关详细信息，请参阅使用 CListCtrl：回调项和回调掩码。

图像列表

列表视图项的图标、标头项图像和应用程序定义的状态包含在你创建并分配给列表视图控件的若干图像列表（由 CImageList 类实现）中。每个列表视图控件最多可拥有四种不同类型的图像列表：

大图标

用于全尺寸图标的图标视图中。
小图标

用于图标视图中所用的较小版图标的小图标视图、列表视图和报表视图中。
应用程序定义的状态

包含状态图像，这些图像显示在项的图标旁，用以指示应用程序定义的状态。
标头项

用于显示在每个标头控件项中的小图像的报表视图中。

默认情况下，列表视图控件会在自身被销毁时销毁分配给它的图像列表；但是，开发人员可以通过在不再使用每个图像列表时（由应用程序确定）销毁它们来自定义此行为。有关详细信息，请参阅使用 CListCtrl：列表项和图像列表。

继承层次结构

CObject

CCmdTarget

CWnd

CListCtrl

要求

标头：afxcmn.h

`CListCtrl::ApproximateViewRect`

确定显示列表视图控件项需要的宽度和高度。

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

参数

sz
建议的控件维度（以像素为单位）。如果未指定维度，框架使用控件的当前宽度值或高度值。

iCount
要在控件中显示的项数。传递 -1 可使用控件中当前的总项数。

返回值

一个 CSize 对象，其中包含显示项所需的大致宽度和高度（以像素为单位）。

注解

此成员函数实现 Win32 宏 ListView_ApproximateViewRect 的行为，如 Windows SDK 中所述。

`CListCtrl::Arrange`

重新定位图标视图中的项，使它们在网格上对齐。

BOOL Arrange(UINT nCode);

参数

nCode
指定项的对齐样式。可以为下列值之一：

LVA_ALIGNLEFT 沿窗口左边缘对齐项。
LVA_ALIGNTOP 沿窗口上边缘对齐项。
LVA_DEFAULT 根据列表视图的当前对齐样式（默认值）对齐项。
LVA_SNAPTOGRID 将所有图标对齐到最近的网格位置。

返回值

如果成功，则不为零，否则为零。

注解

nCode 参数指定对齐样式。

示例

// 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);

`CListCtrl::CancelEditLabel`

取消项文本编辑操作。

void CancelEditLabel();

注解

此成员函数模拟 LVM_CANCELEDITLABEL 消息的功能，如 Windows SDK 中所述。

`CListCtrl::CListCtrl`

构造 CListCtrl 对象。

CListCtrl();

`CListCtrl::Create`

创建列表控件并将它附加到 CListCtrl 对象。

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

参数

dwStyle
指定列表控件的样式。将列表控件样式的任意组合应用于控件。请参阅 Windows SDK 中的列表视图窗口样式，了解这些样式的完整列表。使用 SetExtendedStyle 设置特定于控件的扩展样式。

rect
指定列表控件的大小和位置。它可以是 CRect 对象或 RECT 结构。

pParentWnd
指定列表控件的父窗口（通常为 CDialog）。不得为 NULL。

nID
指定列表控件的 ID。

返回值

如果成功，则不为零，否则为零。

备注

分两步构建 CListCtrl。先调用构造函数，再调用 Create，这将创建列表视图控件并将其附加到 CListCtrl 对象。

若要将 Windows 扩展样式应用于列表控件对象，请调用 CreateEx 而不是 Create。

示例

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

`CListCtrl::CreateEx`

创建一个控件（子窗口）并将其与 CListCtrl 对象相关联。

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

参数

dwExStyle
指定要创建的控件的扩展样式。有关扩展 Windows 样式的列表，请参阅 Windows SDK 中 CreateWindowEx 的 dwExStyle 参数。

dwStyle
指定列表控件的样式。将列表控件样式的任意组合应用于控件。请参阅 Windows SDK 中的列表视图窗口样式，了解这些样式的完整列表。

rect
对 RECT 结构的引用，该结构描述了要在客户端坐标 pParentWnd 中创建的窗口的大小和位置。

pParentWnd
指向作为控件父级的窗口的指针。

nID
控件的子窗口 ID。

返回值

如果成功，则不为 0；否则为 0。

备注

使用 CreateEx（而不是 Create）应用由 Windows 扩展样式前缀 WS_EX_ 指定的扩展 Windows 样式。

CreateEx 使用 dwExStyle 指定的扩展 Windows 样式创建控件。若要设置特定于控件的扩展样式，请调用 SetExtendedStyle。例如，使用 CreateEx 设置 WS_EX_CONTEXTHELP 等样式，但使用 SetExtendedStyle 设置 LVS_EX_FULLROWSELECT 等样式。有关详细信息，请参阅 Windows SDK 中扩展列表视图样式一文所述的样式。

`CListCtrl::CreateDragImage`

为 nItem 指定的项创建拖拽图像列表。

CImageList* CreateDragImage(
    int nItem,
    LPPOINT lpPoint);

参数

*nItem*
要创建拖拽图像列表的项的索引。

lpPoint
POINT 结构的地址（用视图坐标表示），该结构接收图像左上角的初始位置。

返回值

如果成功，返回指向拖拽图像列表的指针；否则返回 NULL。

备注

该 CImageList 对象是永久性的，必须在完成后将其删除。例如：

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

// do something

delete pImageList;

`CListCtrl::DeleteAllItems`

从列表视图控件中删除所有项。

BOOL DeleteAllItems();

返回值

如果成功，则不为零，否则为零。

示例

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

`CListCtrl::DeleteColumn`

从列表视图控件删除列。

BOOL DeleteColumn(int nCol);

参数

nCol
要删除的列的索引。

返回值

如果成功，则不为零，否则为零。

示例

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

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

`CListCtrl::DeleteItem`

从列表视图控件中删除项。

BOOL DeleteItem(int nItem);

参数

nItem
指定要删除的项的索引。

返回值

如果成功，则不为零，否则为零。

示例

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);
}

`CListCtrl::DrawItem`

当所有者绘制的列表视图控件的可视特征发生变化时由框架调用。

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

参数

lpDrawItemStruct
指向 DRAWITEMSTRUCT 结构的长指针，其中包含有关所需绘图类型的信息。

注解

DRAWITEMSTRUCT 结构的 itemAction 成员定义要执行的绘制操作。

默认情况下，此成员函数不执行任何操作。替代此成员函数以实现所有者绘制 CListCtrl 对象的绘制。

在此成员函数终止之前，应用程序应还原为 lpDrawItemStruct 中提供的显示上下文选择的所有图形设备接口 (GDI) 对象。

`CListCtrl::EditLabel`

开始对项的文本进行就地编辑。

CEdit* EditLabel(int nItem);

参数

nItem
要编辑的列表视图项的索引。

返回值

如果成功，则返回指向用于编辑项文本的 CEdit 对象的指针；否则返回 NULL。

注解

具有 LVS_EDITLABELS 窗口样式的列表视图控件使用户能就地编辑项标签。用户通过单击具有焦点的项的标签开始编辑。

使用此函数，可开始对指定列表视图项的文本进行就地编辑。

示例

// 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);

`CListCtrl::EnableGroupView`

启用或禁用控制列表视图控件中的项是否显示为组的功能。

LRESULT EnableGroupView(BOOL fEnable);

参数

fEnable
指示是否启用列表视图控件来对显示的项分组。 TRUE 指示启用分组；FALSE 指示禁用分组。

返回值

返回以下值之一：

0：已启用或禁用以组的形式显示列表视图项的功能。
1：已成功更改控件的状态。
-1：操作失败。

注解

此成员函数模拟 LVM_ENABLEGROUPVIEW 消息的功能，如 Windows SDK 中所述。

`CListCtrl::EnsureVisible`

确保列表视图项至少部分可见。

BOOL EnsureVisible(
    int nItem,
    BOOL bPartialOK);

参数

nItem
要使其可见的列表视图项的索引。

bPartialOK
指定是否可接受部分可见性。

返回值

如果成功，则不为零，否则为零。

备注

如有必要，会滚动列表视图控件。如果 bPartialOK 参数不为零，则当项部分可见时，不会发生滚动。

示例

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

`CListCtrl::FindItem`

搜索具有指定特征的列表视图项。

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

参数

pFindInfo
指向 LVFINDINFO 结构的指针，该结构包含关于要搜索的项的信息。

nStart
作为搜索的开始的项的索引；从头开始搜索，则为 -1。如果 nStart 不等于 -1，则从搜索中排除 nStart 处的项。

返回值

如果成功，返回项的索引；否则返回 -1。

注解

pFindInfo 参数指向 LVFINDINFO 结构，该结构包含用于搜索列表视图项的信息。

示例

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);
}

`CListCtrl::GetBkColor`

检索列表视图控件的背景色。

COLORREF GetBkColor() const;

返回值

用于指定 RGB 颜色的 32 位值。

示例

请参阅 CListCtrl::SetBkColor 的示例。

`CListCtrl::GetBkImage`

检索列表视图控件的当前背景图像。

BOOL GetBkImage(LVBKIMAGE* plvbkImage) const;

参数

plvbkImage
指向 LVBKIMAGE 结构的指针，该结构包含列表视图的当前背景图像。

返回值

如果成功，返回不为零的值；否则返回零。

备注

此方法实现 Win32 宏 ListView_GetBkImage 的行为，如 Windows SDK 中所述。

示例

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);
}

`CListCtrl::GetCallbackMask`

检索列表视图控件的回调掩码。

UINT GetCallbackMask() const;

返回值

列表视图控件的回调掩码。

备注

回调项是一种列表视图项，应用程序（而不是控件）为其存储文本和/或图标。虽然列表视图控件可以为你存储这些属性，但如果应用程序已维护一部分这些信息，你可能想要使用回调项。回调掩码指定应用程序维护的项状态位，它适用于整个控件，而不是特定的项。回调掩码默认为零，这意味着控件将跟踪所有项状态。如果应用程序使用回调项或指定不为零的回调掩码，则必须能够按需提供列表视图项属性。

示例

请参阅 CListCtrl::SetCallbackMask 的示例。

`CListCtrl::GetCheck`

检索与项关联的状态图像的当前显示状态。

BOOL GetCheck(int nItem) const;

参数

nItem
列表控件项的从零开始的索引。

返回值

如果选定了项，返回不为 0 的值；否则返回 0。

注解

此成员函数实现 Win32 宏 ListView_GetCheckState 的行为，如 Windows SDK 中所述。

示例

请参阅 CListCtrl::SetCheck 的示例。

`CListCtrl::GetColumn`

检索列表视图控件的列的属性。

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

参数

nCol
要检索其属性的列的索引。

pColumn
LVCOLUMN 结构的地址，该结构指定要检索的信息并接收有关列的信息。 mask 成员指定要检索的列属性。如果 mask 成员指定 LVCF_TEXT 值，则 pszText 成员必须包含接收项文本的缓冲区的地址，并且 cchTextMax 成员必须指定缓冲区的大小。

返回值

如果成功，则不为零，否则为零。

备注

LVCOLUMN 结构包含有关报表视图中的列的信息。

示例

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);
}

`CListCtrl::GetColumnOrderArray`

检索列表视图控件的列顺序（从左到右）。

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

参数

piArray
指向将包含列表视图控件中列的索引值的缓冲区的指针。缓冲区必须足够大，能包含列表视图控件中的总列数。

iCount
列表视图控件中的列数。如果此参数为 -1，框架会自动检索列数。

返回值

如果成功，则不为零，否则为零。

注解

此成员函数实现 Win32 宏 ListView_GetColumnOrderArray 的行为，如 Windows SDK 中所述。

示例

// 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);
}

`CListCtrl::GetColumnWidth`

检索报表视图或列表视图中的列的宽度。

int GetColumnWidth(int nCol) const;

参数

nCol
指定要检索其宽度的列的索引。

返回值

nCol 指定的列的宽度（以像素为单位）。

示例

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

`CListCtrl::GetCountPerPage`

计算在列表视图或报表视图中时，列表视图控件的可见区域中可垂直容纳的项数。

int GetCountPerPage() const;

返回值

在列表视图或报表视图中时，列表视图控件的可见区域中可垂直容纳的项数。

示例

请参阅 CListCtrl::GetTopIndex 的示例。

`CListCtrl::GetEditControl`

检索用于编辑列表视图项的文本的编辑控件的句柄。

CEdit* GetEditControl() const;

返回值

如果成功，则返回指向用于编辑项文本的 CEdit 对象的指针；否则返回 NULL。

示例

// 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);
}

`CListCtrl::GetEmptyText`

检索显示当前列表视图控件是否空的字符串。

CString GetEmptyText() const;

返回值

包含控件为空时要显示的文本的 CString。

注解

此方法将发送 LVM_GETEMPTYTEXT 消息，如 Windows SDK 中所述。

`CListCtrl::GetExtendedStyle`

检索列表视图控件当前的扩展样式。

DWORD GetExtendedStyle();

返回值

列表视图控件当前正在使用的扩展样式的组合。有关这些扩展样式的描述性列表，请参阅 Windows SDK 中的扩展列表视图样式一文。

备注

此成员函数实现 Win32 宏 ListView_GetExtendedListViewStyle 的行为，如 Windows SDK 中所述。

示例

请参阅 CListCtrl::SetExtendedStyle 的示例。

`CListCtrl::GetFirstSelectedItemPosition`

获取列表视图控件中第一个选定的项的位置。

POSITION GetFirstSelectedItemPosition() const;

返回值

可用于迭代或对象指针检索的 POSITION 值；如果未选定任何项，则为 NULL。

示例

下面的代码示例演示此函数的用法。

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
    }
}

`CListCtrl::GetFocusedGroup`

检索当前列表视图控件中具有键盘焦点的组。

int GetFocusedGroup() const;

返回值

状态为 LVGS_FOCUSED 的组的索引（如果有这样的组）；否则为 -1。

备注

此方法将发送 LVM_GETFOCUSEDGROUP 消息，如 Windows SDK 中所述。有关详细信息，请参阅 LVGROUP 结构的 state 成员的 LVGS_FOCUSED 值。

`CListCtrl::GetGroupCount`

检索当前列表视图控件中的组数。

int GetGroupCount()const;

返回值

列表视图控件中的组数。

注解

此方法将发送 LVM_GETGROUPCOUNT 消息，如 Windows SDK 中所述。

`CListCtrl::GetGroupInfo`

获取列表视图控件的指定组的信息。

int GetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp) const;

参数

iGroupId
将检索其信息的组的标识符。

pgrp
指向包含关于指定组的信息的 LVGROUP 的指针。

返回值

如果成功，返回组的 ID，否则返回 -1。

注解

此成员函数模拟 LVM_GETGROUPINFO 消息的功能，如 Windows SDK 中所述。

`CListCtrl::GetGroupInfoByIndex`

检索关于当前列表视图控件中的指定组的信息。

BOOL GetGroupInfoByIndex(
    int iIndex,
    PLVGROUP pGroup) const;

参数

iIndex
[in] 组的从零开始的索引。

pGroup
[out] 指向 LVGROUP 结构的指针，该结构接收 iIndex 参数指定的组的相关信息。调用方负责初始化 LVGROUP 结构的成员。将 cbSize 成员设置为结构的大小，并设置 mask 成员的标志以指定要检索的信息。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

备注

此方法将发送 LVM_GETGROUPINFOBYINDEX 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_listCtrl，它用于访问当前的列表视图控件。此变量将在下一个示例中使用。

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

下一个代码示例演示了 GetGroupInfoByIndex 方法。在此代码示例较前面的部分中，我们创建了一个列表视图控件，它在报表视图中显示标题为“ClientID”和“Grade”的两列。以下代码示例检索索引为 0 的组的相关信息（如果有这样的组）。

// 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."));
}

`CListCtrl::GetGroupMetrics`

检索组的指标。

void GetGroupMetrics(PLVGROUPMETRICS pGroupMetrics) const;

参数

pGroupMetrics
指向包含组指标信息的 LVGROUPMETRICS 的指针。

备注

此成员函数模拟 LVM_GETGROUPMETRICS 消息的功能，如 Windows SDK 中所述。

`CListCtrl::GetGroupRect`

检索当前列表视图控件中的指定组的边框。

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

参数

iGroupId
[in] 指定组。

lpRect
[in, out] 指向 RECT 结构的指针。如果此方法成功，该结构接收由 iGroupId 指定的组的直角坐标。

iCoords
[in] 指定要检索的直角坐标。使用下列值之一：

LVGGR_GROUP - （默认）整个展开的组的坐标。
LVGGR_HEADER - 仅标头（折叠的组）的坐标。
LVGGR_SUBSETLINK - 仅子集链接（标记子集）的坐标。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

注解

调用方负责分配 pRect 参数指向的 RECT 结构。

此方法将发送 LVM_GETGROUPRECT 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_listCtrl，它用于访问当前的列表视图控件。此变量将在下一个示例中使用。

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

下一个代码示例演示了 GetGroupRect 方法。在此代码示例较前面的部分中，我们创建了一个列表视图控件，它在报表视图中显示标题为“ClientID”和“Grade”的两列。下面的代码示例在索引为 0 的组周围绘制一个三维矩形（如果有这样的组）。

// 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);
}

`CListCtrl::GetGroupState`

检索当前列表视图控件中的指定组的状态。

UINT GetGroupState(
    int iGroupId,
    DWORD dwMask) const;

参数

iGroupId
[in] 组的从零开始的索引。

dwMask
[in] 指定用于检索指定组的状态值的掩码。有关详细信息，请参阅 LVGROUP 结构的 mask 成员。

返回值

指定组的请求状态；如果找不到组，则为 0。

备注

返回值是对 dwMask 参数和表示当前列表视图控件的 LVGROUP 结构的 state 成员的值的按位与运算的结果。

此方法将发送 LVM_GETGROUPSTATE 消息，如 Windows SDK 中所述。有关更多信息，请参见 ListView_GetGroupState 宏。

`CListCtrl::GetHeaderCtrl`

检索列表视图控件的标头控件。

CHeaderCtrl* GetHeaderCtrl();

返回值

指向列表视图控件使用的标头控件的指针。

备注

此成员函数实现 Win32 宏 ListView_GetHeader 的行为，如 Windows SDK 中所述。

示例

请参阅 CListCtrl::GetColumnOrderArray 的示例。

`CListCtrl::GetHotCursor`

检索为列表视图控件启用了热跟踪时使用的光标。

HCURSOR GetHotCursor();

返回值

列表视图控件正在使用的当前热光标资源的句柄。

注解

此成员函数实现 Win32 宏 ListView_GetHotCursor 的行为，如 Windows SDK 中所述。热光标（仅在启用了悬停选择时可见）在光标经过任何列表视图项时显示。设置 LVS_EX_TRACKSELECT 扩展样式可启用悬停选择。

示例

// 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);

`CListCtrl::GetHotItem`

检索当前位于光标下的列表视图项。

int GetHotItem();

返回值

列表视图控件的当前热项的索引。

备注

此成员函数实现 Win32 宏 ListView_GetHotItem 的行为，如 Windows SDK 中所述。启用了热跟踪（和悬停选择）时，热项被定义为当前选定的项。

如果启用了热跟踪，当用户在某个列表视图项上暂停时，系统会自动突出显示项标签，而不需要用户用到鼠标按钮。

示例

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

`CListCtrl::GetHoverTime`

检索列表视图控件的当前悬停时间。

DWORD GetHoverTime() const;

返回值

返回鼠标光标在选定项之前必须悬停在项上的延迟（以毫秒为单位）。如果返回值为 -1，则悬停时间为默认的悬停时间。

注解

此成员函数实现 Win32 宏 ListView_GetHoverTime 的行为，如 Windows SDK 中所述。

示例

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

`CListCtrl::GetImageList`

检索用于绘制列表视图项的图像列表的句柄。

CImageList* GetImageList(int nImageList) const;

参数

nImageList
指定要检索的图像列表的值。它可以是以下值之一：

LVSIL_NORMAL 包含大图标的图像列表。
LVSIL_SMALL 包含小图标的图像列表。
LVSIL_STATE 包含状态图像的图像列表。

返回值

指向用于绘制列表视图项的图像列表的指针。

示例

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

`CListCtrl::GetInsertMark`

检索插入标记的当前位置。

BOOL GetInsertMark(LPLVINSERTMARK plvim) const;

参数

plvim
指向 LVINSERTMARK 结构的指针，该结构包含插入标记的信息。

返回值

如果成功，则返回 TRUE，否则返回 FALSE。如果 LVINSERTMARK 结构的 cbSize 成员中的大小不等于该结构的实际大小，返回 FALSE。

注解

此成员函数模拟 LVM_GETINSERTMARK 消息的功能，如 Windows SDK 中所述。

`CListCtrl::GetInsertMarkColor`

检索插入标记的当前颜色。

COLORREF GetInsertMarkColor() const;

返回值

返回包含插入点颜色的 COLORREF 结构。

备注

此成员函数模拟 LVM_GETINSERTMARKCOLOR 消息的功能，如 Windows SDK 中所述。

`CListCtrl::GetInsertMarkRect`

检索绑定插入点的矩形。

int GetInsertMarkRect(LPRECT pRect) const;

参数

pRect
指向 RECT 结构的指针，该结构包含作为插入点界限的矩形的坐标。

返回值

返回以下值之一：

0 未找到插入点。
1 找到了插入点。

备注

此成员函数模拟 LVM_GETINSERTMARKRECT 消息的功能，如 Windows SDK 中所述。

`CListCtrl::GetItem`

检索列表视图项的部分属性或全部属性。

BOOL GetItem(LVITEM* pItem) const;

参数

pItem
指向 LVITEM 结构的指针，该结构接收项的属性。

返回值

如果成功，则不为零，否则为零。

备注

LVITEM 结构指定或接收列表视图项的属性。

`CListCtrl::GetItemCount`

检索列表视图控件中的项数。

int GetItemCount() const;

返回值

列表视图控件中的项数。

示例

请参阅 CListCtrl::DeleteItem 的示例。

`CListCtrl::GetItemData`

检索与 nItem 指定的项关联的 32 位（如果是为 x64 执行编译，则为 64 位）应用程序特定的值。

DWORD_PTR GetItemData(int nItem) const;

参数

nItem
要检索其数据的列表项的索引。

返回值

与指定项关联的 32 位（如果是为 x64 执行编译，则为 64 位）应用程序特定的值。

备注

此值是 LVITEM 结构的 lParam 成员，如 Windows SDK 中所述

示例

// 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);
    }
}

`CListCtrl::GetItemIndexRect`

检索当前列表视图控件中的子项的全部或部分的边框。

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

参数

pItemIndex
[in] 指向 LVITEMINDEX 的结构的指针，该结构为子项的父项。调用方负责分配并设置 LVITEMINDEX 结构的成员。此参数不能为 NULL。

iColumn
[in] 控件中的列的从零开始的索引。

rectType
[in] 要为其检索边框的列表视图子项的一部分。指定以下值之一：

LVIR_BOUNDS - 返回整个子项（包括图标和标签）的边框。
LVIR_ICON - 返回子项的图标或小图标的边框。
LVIR_LABEL - 返回子项文本的边框。

pRect
[out] 指向 RECT 结构的指针，该结构接收有关子项边框的信息。调用方负责分配 RECT 结构。此参数不能为 NULL。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

备注

此方法将发送 LVM_GETITEMINDEXRECT 消息，如 Windows SDK 中所述。有关更多信息，请参阅 ListView_GetItemIndexRect 宏。

示例

第一个代码示例定义变量 m_listCtrl，它用于访问当前的列表视图控件。此变量将在下一个示例中使用。

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

下一个代码示例演示了 GetGroupRect 方法。在进入此代码示例前，我们创建了一个列表视图控件，它在报表视图中显示标题为“ClientID”和“Grade”的两列。下面的代码示例两个列中的第二个子项周围都绘制了一个三维矩形。

// 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) );

`CListCtrl::GetItemPosition`

检索列表视图项的位置。

BOOL GetItemPosition(
    int nItem,
    LPPOINT lpPoint) const;

参数

nItem
要检索位置的项的索引。

lpPoint
POINT 结构的地址（用视图坐标表示），该结构接收项的左上角的位置。

返回值

如果成功，则不为零，否则为零。

示例

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);
}

`CListCtrl::GetItemRect`

检索当前列表视图中项的整体或部分的边框。

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

参数

nItem
要检索位置的项的索引。

lpRect
接收边框的 RECT 结构的地址。

nCode
要为其检索边框的列表视图项的一部分。它可以是以下值之一：

LVIR_BOUNDS 返回整个项（包括图标和标签）的边框。
LVIR_ICON 返回图标或小图标的边框。
LVIR_LABEL - 返回项文本的边框。

返回值

如果成功，则不为零，否则为零。

示例

// 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++;
    }
}

`CListCtrl::GetItemSpacing`

计算当前列表视图控件中的项之间的间距。

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

参数

fSmall
[in] 要为其检索项间距的视图。为小图标视图指定 TRUE为图标视图指定 FALSE。

pnHorzSpacing
[out] 包含项间的水平间距。

pnVertSpacing
[out] 包含项间的垂直间距。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

备注

此方法将发送 LVM_GETITEMSPACING 消息，如 Windows SDK 中所述。

`CListCtrl::GetItemState`

检索列表视图项的状态。

UINT GetItemState(
    int nItem,
    UINT nMask) const;

参数

nItem
要检索其状态的项的索引。

nMask
指定要返回的项状态标志的掩码。

返回值

指定的列表视图项的状态标志。

注解

项的状态由 LVITEM 结构的 state 成员指定，如 Windows SDK 中所述。指定或更改项的状态时，stateMask 成员指定要更改的状态位。

示例

请参阅 CListCtrl::GetTopIndex 的示例。

`CListCtrl::GetItemText`

检索列表视图项或子项的文本。

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

CString GetItemText(
    int nItem,
    int nSubItem) const;

参数

nItem
将检索其文本的项的索引。

nSubItem
指定要检索其文本的子项。

lpszText
指向要接收项文本的字符串的指针。

nLen
lpszText 指向的缓冲区的长度。

返回值

返回 int 的版本返回已检索的字符串的长度。

返回 CString 的版本返回项文本。

备注

如果 nSubItem 为零，此函数检索项标签；如果 nSubItem 不为零，则检索子项的文本。有关子项参数的详细信息，请参阅 Windows SDK 中关于 LVITEM 结构的讨论。

`CListCtrl::GetNextItem`

搜索具有指定属性且具有与给定项的指定关系的列表视图项。

int GetNextItem(
    int nItem,
    int nFlags) const;

参数

nItem
用于开始搜索的项的索引；如果要查找与指定标志匹配的第一项，则为 -1。指定的项本身不在搜索范围内。

nFlags
请求的项与指定项的几何关系，以及请求的项的状态。几何关系可以是以下值之一：

LVNI_ABOVE 搜索位于指定项上方的项。
LVNI_ALL 按索引搜索后面的项（默认值）。
LVNI_BELOW 搜索位于指定项下方的项。
LVNI_TOLEFT 搜索位于指定项左方的项。
LVNI_TORIGHT 搜索位于指定项右方的项。

状态可以是零，也可以是以下值中的一个或多个：

LVNI_DROPHILITED 项设置了 LVIS_DROPHILITED 状态标志。
LVNI_FOCUSED 项设置了 LVIS_FOCUSED 状态标志。
LVNI_SELECTED 项设置了 LVIS_SELECTED 状态标志。

如果某个项未设置所有指定的状态标志，则继续搜索下一项。

返回值

如果成功，返回下一个项的索引；否则返回 -1。

`CListCtrl::GetNextItemIndex`

检索具有指定属性集的当前列表视图控件中的项的索引。

BOOL GetNextItemIndex(
    PLVITEMINDEX pItemIndex,
    int nFlags) const;

参数

pItemIndex
[in, out] 指向LVITEMINDEX 结构的指针，该结构描述开始搜索的项；如果要查找与 nFlags 参数中的标志匹配的第一个项，则为 -1。如果此方法成功，LVITEMINDEX 结构描述搜索找到的项。

nFlags
[in] 指定如何执行搜索的标志的按位组合 (OR)。搜索可取决于目标项的索引、状态或外观，也可取决于目标项相对于 pItemIndex 参数指定的项的物理位置。有关详细信息，请参阅 LVM_GETNEXTITEMINDEX 消息中的 flags 参数。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

备注

调用方负责分配并设置 pItemIndex 参数指向的 LVITEMINDEX 结构的成员。

此方法将发送 LVM_GETNEXTITEMINDEX 消息，如 Windows SDK 中所述。

`CListCtrl::GetNextSelectedItem`

获取由 pos 标识的列表项的索引，然后将 pos 设置为 POSITION 值。

int GetNextSelectedItem(POSITION& pos) const;

参数

pos
由对 GetNextSelectedItem 或 GetFirstSelectedItemPosition 的先前调用返回的 POSITION 值的引用。此值通过此调用更新到下一个位置。

返回值

由 pos 标识的列表项的索引。

注解

如果通过调用 GetFirstSelectedItemPosition 建立初始位置，则可以在正向迭代循环中使用 GetNextSelectedItem。

必须确保 POSITION 值有效。如果该值无效，则 Microsoft 基础类库的调试版本会断言。

示例

下面的代码示例演示此函数的用法。

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
    }
}

`CListCtrl::GetNumberOfWorkAreas`

检索列表视图控件当前工作区域的数量。

UINT GetNumberOfWorkAreas() const;

返回值

目前未使用。

备注

此成员函数实现 Win32 宏 ListView_GetNumberOfWorkAreas 的行为，如 Windows SDK 中所述。

示例

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!"));
}

`CListCtrl::GetOutlineColor`

检索列表视图控件的边框颜色。

COLORREF GetOutlineColor() const;

返回值

返回 COLORREF 包含轮廓颜色的结构。

备注

此成员函数模拟 LVM_GETOUTLINECOLOR 消息的功能，如 Windows SDK 中所述。

`CListCtrl::GetOrigin`

检索列表视图控件当前视图原点。

BOOL GetOrigin(LPPOINT lpPoint) const;

参数

lpPoint
接收视图源的 POINT 结构的地址。

返回值

如果成功，则不为零，否则为零。但是，如果控件在报表视图中，则返回值始终为零。

`CListCtrl::GetSelectedColumn`

检索列表控件中当前选定的列的索引。

UINT GetSelectedColumn() const;

返回值

选定列的索引。

注解

此成员函数模拟 LVM_GETSELECTEDCOLUMN 消息的功能，如 Windows SDK 中所述。

`CListCtrl::GetSelectedCount`

检索列表视图控件中选定项的数量。

UINT GetSelectedCount() const;

返回值

列表视图控件中选定项的数量。

示例

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);
    }
}

`CListCtrl::GetSelectionMark`

检索列表视图控件的选择标记。

int GetSelectionMark();

返回值

从零开始的选择标记；如果没有选择标记，则为 -1。

备注

此成员函数实现 Win32 宏 ListView_GetSelectionMark 的行为，如 Windows SDK 中所述。

示例

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

`CListCtrl::GetStringWidth`

确定显示给定字符串的全部所必需的最小列宽。

int GetStringWidth(LPCTSTR lpsz) const;

参数

lpsz
以 null 结尾的字符串（要其确定宽度）的地址。

返回值

lpsz 指向的字符串的宽度（以像素为单位）。

备注

返回的宽度考虑了控件的当前字体和列边距，但未考虑小图标的宽度。

示例

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);
}

`CListCtrl::GetSubItemRect`

检索列表视图控件中的项的边框。

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

参数

iItem
子项的父项的索引。

iSubItem
子项的从 1 开始的索引。

nArea
确定要检索的（列表视图子项的）边框部分。通过将按位 OR 运算符应用于下面的一个或多个值来指定边框部分（图标、标签或这两者）：

LVIR_BOUNDS 返回整个项（包括图标和标签）的边框。
LVIR_ICON 返回图标或小图标的边框。
LVIR_LABEL 返回整个项（包括图标和标签）的边框。这等同于 LVIR_BOUNDS。

ref
对 CRect 对象的引用，该对象包含子项边框的坐标。

返回值

如果成功，则不为零，否则为零。

注解

此成员函数实现 Win32 宏 ListView_GetSubItemRect 的行为，如 Windows SDK 中所述。

`CListCtrl::GetTextBkColor`

检索列表视图控件的文本背景色。

COLORREF GetTextBkColor() const;

返回值

用于指定 RGB 颜色的 32 位值。

示例

请参阅 CListCtrl::SetTextBkColor 的示例。

`CListCtrl::GetTextColor`

检索列表视图控件的文本颜色。

COLORREF GetTextColor() const;

返回值

用于指定 RGB 颜色的 32 位值。

示例

请参阅 CListCtrl::SetTextColor 的示例。

`CListCtrl::GetTileInfo`

检索有关列表视图控件中的图块的信息。

BOOL GetTileInfo(PLVTILEINFO plvti) const;

参数

plvti
指向 LVTILEINFO 结构的指针，该结构接收平铺信息。

返回值

不使用返回值。

备注

此成员函数模拟 LVM_GETTILEINFO 消息的功能，如 Windows SDK 中所述。

`CListCtrl::GetTileViewInfo`

检索有关平铺视图中的列表视图控件的信息。

BOOL GetTileViewInfo(PLVTILEVIEWINFO ptvi) const;

参数

ptvi
指向 LVTILEVIEWINFO 结构的指针，该结构接收检索的信息。

返回值

不使用返回值。

备注

此成员函数模拟 LVM_GETTILEVIEWINFO 消息的功能，如 Windows SDK 中所述。

`CListCtrl::GetToolTips`

检索列表视图控件用于显示工具提示的工具提示控件。

CToolTipCtrl* GetToolTips() const;

返回值

指向列表控件要使用的 CToolTipCtrl 对象的指针。如果 Create 成员函数使用样式 LVS_NOTOOLTIPS，则不使用任何工具提示，并返回 NULL。

备注

此成员函数实现 Win32 消息 LVM_GETTOOLTIPS 的行为，如 Windows SDK 中所述。 GetToolTips 的 MFC 实现返回列表控件使用的 CToolTipCtrl 对象，而不是工具提示控件的句柄。

示例

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

`CListCtrl::GetTopIndex`

在列表视图或报表视图中时，检索最上面的可见项的索引。

int GetTopIndex() const;

返回值

最上面的可见项的索引。

示例

// 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);
}

`CListCtrl::GetView`

获取列表视图控件的视图。

DWORD GetView() const;

返回值

列表视图控件的当前视图。

注解

此成员函数模拟 LVM_GETVIEW 消息的功能，如 Windows SDK 中所述。

`CListCtrl::GetViewRect`

检索列表视图控件中所有项的边框。

BOOL GetViewRect(LPRECT lpRect) const;

参数

lpRect
RECT 结构的地址。

返回值

如果成功，则不为零，否则为零。

备注

列表视图必须在图标视图或小图标视图中。

`CListCtrl::GetWorkAreas`

检索列表视图控件的当前工作区域。

void GetWorkAreas(
    int nWorkAreas,
    LPRECT pRect) const;

参数

nWorkAreas
pRect 数组中包含的 RECT 结构的数量。

pRect
指向 RECT 结构（或 CRect 对象）的数组的指针，这些结构（或对象）接收列表视图控件的工作区域。这些结构中的值用客户端坐标表示。

注解

此成员函数实现 Win32 宏 ListView_GetWorkAreas 的行为，如 Windows SDK 中所述。

示例

请参阅 CListCtrl::GetNumberOfWorkAreas 的示例。

`CListCtrl::HasGroup`

确定列表视图控件是否具有指定组。

BOOL HasGroup(int iGroupId) const;

参数

iGroupId
请求的组的标识符。

返回值

成功时返回 TRUE，失败时返回 FALSE。

注解

此成员函数模拟 LVM_HASGROUP 消息的功能，如 Windows SDK 中所述。

`CListCtrl::HitTest`

确定位于指定位置的列表视图项（如果有）。

int HitTest(LVHITTESTINFO* pHitTestInfo) const;

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

参数

pHitTestInfo
LVHITTESTINFO 结构的地址，该结构包含命中测试的位置并接收命中测试结果的相关信息。

pt
要测试的点。

pFlags
指向接收测试结果信息的整数的指针。请参阅对 Windows SDK 中 LVHITTESTINFO 结构的 flags 成员的说明。

返回值

位于由 pHitTestInfo 指定的位置的项的索引（如果有）；否则为 -1。

备注

你可以使用结构的 flag 成员的 LVHT_ABOVE、LVHT_BELOW、LVHT_TOLEFT 和 LVHT_TORIGHT 值来确定是否滚动列表视图控件的内容。可将其中的两个标志结合起来，例如位置位于工作区的左上方。

可以测试结构的 flag 成员的 LVHT_ONITEM 值，以确定给定位置是否在列表视图项上方。此值是对结构的 flag 成员的 LVHT_ONITEMICON、LVHT_ONITEMLABEL 和 LVHT_ONITEMSTATEICON 值的按位或运算。

示例

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;
}

`CListCtrl::InsertColumn`

在列表视图控件中插入新列。

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

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

参数

nCol
新列的索引。

pColumn
包含新列属性的 LVCOLUMN 结构的地址。

lpszColumnHeading
包含列标题的字符串的地址。

nFormat
指定列的对齐方式的整数。可以是以下值之一：LVCFMT_LEFT、LVCFMT_RIGHT 或 LVCFMT_CENTER。

nWidth
列的宽度（以像素为单位）。如果此参数为 -1，说明未设置列宽。

nSubItem
与列相关联的子项的索引。如果此参数为 -1，说明没有与列关联的子项。

返回值

如果成功，返回下一列的索引；否则返回 -1。

注解

列表视图控件中最左侧的列必须是左对齐的。

LVCOLUMN 结构包含报表视图中的列的属性。它还用于接收与列相关的信息。 Windows SDK 中介绍了此结构。

`CListCtrl::InsertGroup`

在列表视图控件中插入组。

LRESULT InsertGroup(
    int index,
    PLVGROUP pgrp);

参数

index
要插入组的项的索引。

pgrp
指向 LVGROUP 结构的指针，该结构包含要添加的组。

返回值

返回将组添加到的项的索引；如果操作失败，则返回 -1。

备注

此成员函数模拟 LVM_INSERTGROUP 消息的功能，如 Windows SDK 中所述。

`CListCtrl::InsertGroupSorted`

将指定组插入已排序的组列表中。

LRESULT InsertGroupSorted(PLVINSERTGROUPSORTED pStructInsert);

参数

pStructInsert
指向 LVINSERTGROUPSORTED 结构的指针，该结构包含要插入的组。

返回值

不使用返回值。

备注

此成员函数模拟 LVM_INSERTGROUPSORTED 消息的功能，如 Windows SDK 中所述。

`CListCtrl::InsertItem`

在列表视图控件中插入项。

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);

参数

pItem
指向指定项的属性的 LVITEM 结构的指针，如 Windows SDK 中所述。

nItem
要插入的项的索引。

lpszItem
包含项标签的字符串的地址；如果项为回调项，则为 LPSTR_TEXTCALLBACK。有关回调项的信息，请参阅 CListCtrl::GetCallbackMask。

nImage
项的图像的索引；如果项为回调项，则为 I_IMAGECALLBACK。有关回调项的信息，请参阅 CListCtrl::GetCallbackMask。

nMask
nMask 参数指定哪些作为参数传递的项属性有效。可以是 Windows SDK 中的LVITEM 结构中所述的一个或多个掩码值。可将这些有效值与按位或运算符结合使用。

nState
指示项的状态、状态图像和覆盖图像。有关详细信息，请参阅 Windows SDK 主题 LVITEM 结构和列表视图项状态来了解有效标志的列表。

nStateMask
指示将检索或修改状态成员的哪些位。有关详细信息，请参阅 Windows SDK 中的 LVITEM 结构。

lParam
与项关联的 32 位（如果是为 x64 执行编译，则为 64 位）应用程序特定的值。如果指定了此参数，则必须设置 nMask 属性 LVIF_PARAM。

返回值

如果成功，返回新项的索引；否则返回 -1。

注解

调用此方法可能会导致 LVM_INSERTITEM 消息被发送到控件窗口。控件的关联消息处理程序也许未能在某些条件下（例如使用 LVS_OWNERDRAW 等窗口样式）设置项文本。有关这些条件的详细信息，请参阅 Windows SDK 中的 LVM_INSERTITEM。

示例

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);
    }
}

`CListCtrl::InsertMarkHitTest`

检索最靠近指定点的插入点。

int InsertMarkHitTest(
    LPPOINT pPoint,
    LPLVINSERTMARK plvim) const;

参数

pPoint
指向 POINT 结构的指针，该结构包含相对于列表控件工作区的命中测试坐标。

plvim
指向 LVINSERTMARK 结构的指针，该结构指定最靠近点参数定义的坐标的插入点。

返回值

最靠近指定点的插入点。

备注

此成员函数模拟 LVM_INSERTMARKHITTEST 消息的功能，如 Windows SDK 中所述。

`CListCtrl::IsGroupViewEnabled`

确定是否为列表视图控件启用了组视图。

BOOL IsGroupViewEnabled() const;

返回值

如果启用了组视图，返回 TRUE；否则返回 FALSE。

注解

此成员函数模拟 LVM_ISGROUPVIEWENABLED 消息的功能，如 Windows SDK 中所述。

`CListCtrl::IsItemVisible`

指示指定项在当前列表视图控件中是否可见。

BOOL IsItemVisible(int index) const;

参数

index
[in] 当前列表视图控件中的项的从零开始的索引。

返回值

如果指定项可见，返回 TRUE；否则返回 FALSE。

备注

此方法将发送 LVM_ISITEMVISIBLE 消息，如 Windows SDK 中所述。

`CListCtrl::MapIDToIndex`

将当前列表视图控件中的项的唯一 ID 映射到索引。

UINT MapIDToIndex(UINT id) const;

参数

id
[in] 项的唯一 ID。

返回值

指定 ID 的当前索引。

备注

列表视图控件在内部按索引跟踪项。这可能会产生问题，因为索引在控件的生存期内可能发生更改。列表视图控件可在创建项时用 ID 来标记项，你可以使用此 ID 确保在列表视图控件生存期内的唯一性。

在多线程环境中，仅保证在托管列表视图控件的线程上（而不是在后台线程上）提供索引。

此方法将发送 LVM_MAPIDTOINDEX 消息，如 Windows SDK 中所述。

`CListCtrl::MapIndexToID`

将当前列表视图控件中的项的索引映射到唯一 ID。

UINT MapIndexToID(UINT index) const;

参数

index
[in] 项的从零开始的索引。

返回值

指定的项的唯一 ID。

注解

列表视图控件在内部按索引跟踪项。这可能会产生问题，因为索引在控件的生存期内可能发生更改。创建项时，列表视图控件可使用 ID 来标记项。你可以使用此 ID 在列表视图控件生存期内访问特定项。

在多线程环境中，仅保证在托管列表视图控件的线程上（而不是在后台线程上）提供索引。

此方法将发送 LVM_MAPINDEXTOID 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_listCtrl，它用于访问当前的列表视图控件。此变量将在下一个示例中使用。

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

下一个代码示例演示了 MapIndexToID 方法。在此代码示例较前面的部分中，我们创建了一个列表视图控件，它在报表视图中显示标题为“ClientID”和“Grade”的两列。以下示例将每个列表视图项的索引映射到标识号，再检索每个标识号的索引。最后，该示例报告是否检索了原始索引。

// 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);

`CListCtrl::MoveGroup`

将指定组移到列表视图控件的指定的从零开始的索引。

LRESULT MoveGroup(
    int iGroupId,
    int toIndex);

参数

iGroupId
要移动的组的标识符。

toIndex
要移动组的从零开始的索引。

返回值

不使用返回值。

备注

此成员函数模拟 LVM_MOVEGROUP 消息的功能，如 Windows SDK 中所述。

`CListCtrl::MoveItemToGroup`

将指定项移到指定组中。

void MoveItemToGroup(
    int idItemFrom,
    int idGroupTo);

参数

idItemFrom
[in] 要移动的项的索引。

idGroupTo
[in] 项将移到的组的标识符。

注解

注意

目前未实现该方法。

此方法模拟 LVM_MOVEITEMTOGROUP 消息的功能，如 Windows SDK 中所述。

`CListCtrl::RedrawItems`

强制列表视图控件重新绘制一系列的项。

BOOL RedrawItems(
    int nFirst,
    int nLast);

参数

nFirst
要重新绘制的第一个项的索引。

nLast
要重新绘制的最后一个项的索引。

返回值

如果成功，则不为零，否则为零。

备注

直到列表视图窗口收到 WM_PAINT 消息，才重新绘制指定的项。若要立即重新绘制，请在使用此函数后调用 Windows UpdateWindow 函数。

`CListCtrl::RemoveAllGroups`

从列表视图控件中删除所有的组。

void RemoveAllGroups();

注解

此成员函数模拟 LVM_REMOVEALLGROUPS 消息的功能，如 Windows SDK 中所述。

`CListCtrl::RemoveGroup`

从列表视图控件中删除指定的组。

LRESULT RemoveGroup(int iGroupId);

参数

iGroupId
要删除的组的标识符。

返回值

如果成功，返回组的索引，否则返回 -1。

注解

此成员函数模拟 LVM_REMOVEGROUP 消息的功能，如 Windows SDK 中所述。

`CListCtrl::Scroll`

滚动列表视图控件的内容。

BOOL Scroll(CSize size);

参数

size
一个 CSize 对象，它指定水平滚动量和垂直滚动量（以像素为单位）。大小的 y 成员除以列表视图控件行的高度（以像素为单位），并且将控件滚动所得的行数。

返回值

如果成功，则不为零，否则为零。

`CListCtrl::SetBkColor`

设置列表视图控件的背景色。

BOOL SetBkColor(COLORREF cr);

参数

cr
要设置的背景色；没有背景色时，则为 CLR_NONE 值。就重新绘制自身的速度而言，有背景色的列表视图控件比无背景色的控件快得多。有关信息，请参阅 Windows SDK 中的 COLORREF。

返回值

如果成功，则不为零，否则为零。

示例

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

`CListCtrl::SetBkImage`

设置列表视图控件的背景图像。

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);

参数

plvbkImage
包含新背景图像信息的 LVBKIMAGE 结构的地址。

hBitmap
位图的图柄。

pszUrl
包含背景图像 URL 的以 NULL 结尾的字符串。

fTile
如果要将图像平铺在列表视图控件的背景中，不为 0；否则为 0。

xOffsetPercent
图像左边缘离列表视图控件原点的偏移量（以像素为单位）。

yOffsetPercent
图像上边缘离列表视图控件原点的偏移量（以像素为单位）。

返回值

如果成功，返回不为零的值；否则返回零。

备注

注意

因为 CListCtrl::SetBkImage 使用 OLE COM 功能，所以必须在使用 SetBkImage 之前初始化 OLE 库。最好在初始化应用程序时初始化 COM 库，在应用程序终止时取消这些库的初始化。这是在使用 ActiveX 技术、OLE 自动化、OLE 链接/嵌入或者 ODBC/DAO 操作的 MFC 应用程序中自动完成的。

示例

请参阅 CListCtrl::GetBkImage 的示例。

`CListCtrl::SetCallbackMask`

设置列表视图控件的回调掩码。

BOOL SetCallbackMask(UINT nMask);

参数

nMask
回调掩码的新值。

返回值

如果成功，则不为零，否则为零。

示例

// 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));

`CListCtrl::SetCheck`

确定列表控件项的状态图像是否可见。

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

参数

nItem
列表控件项的从零开始的索引。

fCheck
指定项的状态图像是否应是可见的。默认情况下，fCheck 为 TRUE且状态图像可见。如果 fCheck 为 FALSE，则不可见。

返回值

如果选定了项，不为 0；否则为 0。

示例

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;
}

`CListCtrl::SetColumn`

设置列表视图列的属性。

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

参数

nCol
要设置属性的列的索引。

pColumn
包含新列属性的 LVCOLUMN 结构的地址，如 Windows SDK 中所述。结构的 mask 成员指定要设置的列属性。如果 mask 成员指定 LVCF_TEXT 值，则结构的 pszText 成员是以 null 结尾的字符串的地址，并且将忽略 cchTextMax 成员。

返回值

如果成功，则不为零，否则为零。

示例

请参阅 CListCtrl::GetColumn 的示例。

`CListCtrl::SetColumnOrderArray`

设置列表视图控件的列顺序（从左到右）。

BOOL SetColumnOrderArray(
    int iCount,
    LPINT piArray);

参数

piArray
指向缓冲区的指针，该缓冲区包含列表视图控件中的列（从左到右）的索引值。缓冲区必须足够大，能包含列表视图控件中的总列数。

iCount
列表视图控件中的列数。

返回值

如果成功，则不为零，否则为零。

注解

此成员函数实现 Win32 宏 ListView_SetColumnOrderArray 的行为，如 Windows SDK 中所述。

示例

请参阅 CListCtrl::GetColumnOrderArray 的示例。

`CListCtrl::SetColumnWidth`

更改报表视图或列表视图中的列的宽度。

BOOL SetColumnWidth(
    int nCol,
    int cx);

参数

nCol
要为其设置宽度的列的索引。在列表视图中，此参数必须为 0。

cx
列的新宽度。可以是 LVSCW_AUTOSIZE 或 LVSCW_AUTOSIZE_USEHEADER，如 Windows SDK 中的 LVM_SETCOLUMNWIDTH 中所述。

返回值

如果成功，则不为零，否则为零。

`CListCtrl::SetExtendedStyle`

设置列表视图控件当前的扩展样式。

DWORD SetExtendedStyle(DWORD dwNewStyle);

参数

dwNewStyle
要由列表视图控件使用的扩展样式的组合。有关这些样式的描述性列表，请参阅 Windows SDK 中的扩展列表视图样式主题。

返回值

列表视图控件使用的以前的扩展样式的组合。

注解

此成员函数实现 Win32 宏 ListView_SetExtendedListViewStyle 的行为，如 Windows SDK 中所述。

示例

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

`CListCtrl::SetGroupInfo`

设置描述当前列表视图控件的指定组的信息。

int SetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp);

参数

iGroupId
设置了信息的组的标识符。

pgrp
指向包含要设置的信息的 LVGROUP 结构的指针。调用方负责分配此结构并设置它的成员。

返回值

如果方法成功，为组的 ID；否则为 -1。

注解

此方法将发送 LVM_SETGROUPINFO 消息，如 Windows SDK 中所述。

`CListCtrl::SetGroupMetrics`

设置列表视图控件的组指标。

void SetGroupMetrics(PLVGROUPMETRICS pGroupMetrics);

参数

pGroupMetrics
指向 LVGROUPMETRICS 结构的指针，该结构包含要设置的组指标信息。

注解

此成员函数模拟 LVM_SETGROUPMETRICS 消息的功能，如 Windows SDK 中所述。

`CListCtrl::SetHotCursor`

设置为列表视图控件启用了热跟踪时使用的光标。

HCURSOR SetHotCursor(HCURSOR hc);

参数

hc
光标资源的句柄，用于表示热光标。

返回值

列表视图控件正在使用的上一个热光标资源的句柄。

注解

此成员函数实现 Win32 宏 ListView_SetHotCursor 的行为，如 Windows SDK 中所述。

热光标（仅在启用了悬停选择时可见）在光标经过任何列表视图项时显示。悬停选择是通过设置 LVS_EX_TRACKSELECT 扩展样式启用的。

示例

请参阅 CListCtrl::GetHotCursor 的示例。

`CListCtrl::SetHotItem`

设置列表视图控件的当前热项。

int SetHotItem(int iIndex);

参数

iIndex
要设为热项的项的从零开始的索引。

返回值

之前为热项的项的从零开始的索引。

备注

此成员函数实现 Win32 宏 ListView_SetHotItem 的行为，如 Windows SDK 中所述。

示例

请参阅 CListCtrl::GetHotItem 的示例。

`CListCtrl::SetHoverTime`

设置列表视图控件的当前悬停时间。

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

参数

dwHoverTime
鼠标光标在选定项之前必须悬停在项上的新延迟（以毫秒为单位）。如果传递的是默认值，则时间设置为默认悬停时间。

返回值

上一次悬停时间，以毫秒为单位。

备注

此成员函数实现 Win32 宏 ListView_SetHoverTime 的行为，如 Windows SDK 中所述。

示例

请参阅 CListCtrl::GetHoverTime 的示例。

`CListCtrl::SetIconSpacing`

设置列表视图控件中的图标间的间距。

CSize SetIconSpacing(
    int cx,
    int cy);

CSize SetIconSpacing(CSize size);

参数

cx
x 轴上的图标之间的距离（以像素为单位）。

cy
y 轴上的图标之间的距离（以像素为单位）。

size
一个 CSize 对象，它指定 x 轴和 y 轴上的图标之间的距离（以像素为单位）。

返回值

一个 CSize 对象，其中包含之前的图标间距值。

注解

此成员函数实现 Win32 宏 ListView_SetIconSpacing 的行为，如 Windows SDK 中所述。

示例

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

`CListCtrl::SetImageList`

向列表视图控件分配图像列表。

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

参数

pImageList
指向要分配的图像列表的指针。

nImageListType
图像列表类型。它可以是以下值之一：

LVSIL_NORMAL 包含大图标的图像列表。
LVSIL_SMALL 包含小图标的图像列表。
LVSIL_STATE 包含状态图像的图像列表。

返回值

指向上一个图像列表的指针。

示例

请参阅 CListCtrl::GetImageList 的示例。

`CListCtrl::SetInfoTip`

设置工具提示文本。

BOOL SetInfoTip(PLVSETINFOTIP plvInfoTip);

参数

plvInfoTip
指向 LVFSETINFOTIP 结构的指针，该结构包含要设置的信息。

返回值

成功时返回 TRUE，失败时返回 FALSE。

注解

此成员函数模拟 LVM_SETINFOTIP 消息的功能，如 Windows SDK 中所述。

`CListCtrl::SetInsertMark`

将插入点设置为定义的位置。

BOOL SetInsertMark(LPLVINSERTMARK plvim);

参数

plvim
指向 LVINSERTMARK 结构的指针，该结构指定设置插入点的位置。

返回值

如果成功，则返回 TRUE，否则返回 FALSE。如果 LVINSERTMARK 结构的 cbSize 成员中的大小不等于该结构的实际大小，或者当前视图中未应用插入点时，返回 FALSE。

备注

此成员函数模拟 LVM_SETINSERTMARK 消息的功能，如 Windows SDK 中所述。

`CListCtrl::SetInsertMarkColor`

设置插入点的颜色。

COLORREF SetInsertMarkColor(COLORREF color);

参数

color
指定用于设置插入点颜色的 COLORREF 结构。

返回值

返回包含先前的颜色的 COLORREF 结构。

备注

此成员函数模拟 LVM_SETINSERTMARKCOLOR 消息的功能，如 Windows SDK 中所述。

`CListCtrl::SetItem`

设置列表视图项的部分属性或全部属性。

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);

参数

pItem
包含新项属性的 LVITEM 结构的地址，如 Windows SDK 中所述。结构的 iItem 和 iSubItem 成员分别标识项和子项，结构的 mask 成员指定要设置的属性。有关 mask 成员的详细信息，请参阅“注解”。

nItem
要设置属性的项的索引。

nSubItem
要设置属性的子项的索引。

nMask
指定要设置的属性（请参阅“注解”）。

lpszItem
指定项标签的以 null 结尾的字符串的地址。

nImage
图像列表内的项的图像的索引。

nState
指定要更改的状态的值（请参阅“注解”）。

nStateMask
指定要更改的状态（请参阅“注解”）。

lParam
与项关联的 32 位（如果是为 x64 执行编译，则为 64 位）应用程序特定的值。

nIndent
缩进的宽度（以像素为单位）。如果 nIndent 小于系统定义的最小宽度，则新宽度会被设置为系统定义的最小值

返回值

如果成功，则不为零，否则为零。

备注

LVITEM 结构的 iItem 和 iSubItem 成员以及 nItem 和 nSubItem 两个参数标识要设置属性的项和子项。

LVITEM 结构的 mask 成员和 nMask 参数指定要设置的项属性：

LVIF_TEXT - pszText 成员或 lpszItem 参数是以 null 结尾的字符串的地址；忽略了 cchTextMax 成员。
LVIF_STATE - stateMask 成员或 nStateMask 参数指定要更改的项状态，state 成员或 nState 参数包含那些状态的值。

示例

请参阅 CListCtrl::HitTest 的示例。

`CListCtrl::SetItemCount`

准备一个列表视图控件，用于添加大量的项。

void SetItemCount(int nItems);

参数

nItems
控件最终将包含的项数。

备注

要设置虚拟列表视图控件的项计数，请参阅 CListCtrl::SetItemCountEx。

此成员函数实现 Win32 宏 ListView_SetItemCount 的行为，如 Windows SDK 中所述。

示例

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);
}

`CListCtrl::SetItemCountEx`

设置虚拟列表视图控件的项计数。

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

参数

iCount
控件最终将包含的项数。

dwFlags
指定列表视图控件在重置项计数后的行为。该值可为以下项的组合：

LVSICF_NOINVALIDATEALL - 列表视图控件不会重绘，除非受影响的项当前位于视图中。这是默认值。
LVSICF_NOSCROLL - 项计数更改时，列表视图控件不会更改滚动位置。

返回值

如果成功，则不为零，否则为零。

备注

此成员函数实现 Win32 宏 ListView_SetItemCountEx 的行为（如 Windows SDK 中所述），并且只应为虚拟列表视图调用此函数。

示例

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);
}

`CListCtrl::SetItemData`

设置与 nItem 指定的项关联的 32 位（如果是为 x64 执行编译，则为 64 位）应用程序特定的值。

BOOL SetItemData(int nItem, DWORD_PTR dwData);

参数

nItem
要设置其数据的列表项的索引。

dwData
与项关联的 32 位（如果是为 x64 执行编译，则为 64 位）的值。

返回值

如果成功，则不为 0；否则为 0。

备注

此值是 LVITEM 结构的 lParam 成员，如 Windows SDK 中所述。

示例

// 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);
}

`CListCtrl::SetItemIndexState`

设置当前列表视图控件中的项的状态。

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

参数

pItemIndex
[in] 指向描述项的 LVITEMINDEX 结构的指针。调用方负责分配此结构并设置它的成员。

dwState
[in] 用于设置项的状态，是列表视图项状态的按位组合。指定 0，重置状态；指定 1，设置状态。

dwMask
[in] dwState 参数指定的状态的有效位的掩码。指定列表视图项状态的按位组合 (OR)。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

备注

有关 dwState 参数的详细信息，请参阅列表视图项状态。

有关 dwMask 参数的详细信息，请参阅 LVITEM 结构的 stateMask 成员。

此方法将发送 LVM_SETITEMINDEXSTATE 消息，如 Windows SDK 中所述。

`CListCtrl::SetItemPosition`

将项移到列表视图控件中的指定位置。

BOOL SetItemPosition(
    int nItem,
    POINT pt);

参数

nItem
要设置位置的项的索引。

pt
一个 POINT 结构，指定项的左上角的新位置（用视图坐标表示）。

返回值

如果成功，则不为零，否则为零。

备注

控件必须在图标或小图标视图中。

如果列表视图控件具有 LVS_AUTOARRANGE 样式，则在设置项的位置后排列列表视图。

示例

请参阅 CListCtrl::GetItemPosition 的示例。

`CListCtrl::SetItemState`

更改列表视图控件中的项的状态。

BOOL SetItemState(
    int nItem,
    LVITEM* pItem);

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

参数

nItem
要设置其状态的项的索引。传递 -1 可将状态更改应用于所有项。

pItem
LVITEM 结构的地址，如 Windows SDK 中所述。该结构的 stateMask 成员指定要更改的状态位，它的 state 成员包含那些位的新值。忽略其他成员。

nState
状态位的新值。有关可能的值的列表，请参阅 CListCtrl::GetNextItem 和 LVITEM 状态成员。

nMask
指定要更改的状态位的掩码。此值对应于 LVITEM 结构的 stateMask 成员。

返回值

如果成功，则不为零，否则为零。

备注

项的状态是一个指定项的可用性、指示用户操作或反映项的状态的值。列表视图控件更改一些状态位，例如当用户选择项时。此外，应用程序可能通过更改其他状态位，来禁用/隐藏项或指定覆盖图像或状态图像。

示例

请参阅 CListCtrl::GetTopIndex 的示例。

`CListCtrl::SetItemText`

更改列表视图项或子项的文本。

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

参数

nItem
要设置文本的项的索引。

nSubItem
子项的索引；若要设置项标签，则为零。

lpszText
指向包含新项文本的字符串的指针。

返回值

如果成功，则不为零，否则为零。

备注

此方法的目的不是为了与包含 LVS_OWNERDATA 窗口样式的控件一起使用（事实上，这样做会导致调试版本中的断言）。有关此列表控件样式的详细信息，请参阅列表视图控件概述。

示例

请参阅 CListCtrl::InsertItem 的示例。

`CListCtrl::SetOutlineColor`

如果设置了 LVS_EX_BORDERSELECT 扩展窗口样式，设置列表视图控件的边框的颜色。

COLORREF SetOutlineColor(COLORREF color);

参数

color
包含轮廓颜色的新的 COLORREF 结构。

返回值

包含轮廓颜色的上一个 COLORREF 结构

备注

此成员函数模拟 LVM_SETOUTLINECOLOR 消息的功能，如 Windows SDK 中所述。

CListCtrl::SetSelectedColumn

设置列表视图控件的选定列。

LRESULT SetSelectedColumn(int iCol);

参数

iCol
要选择的列的索引。

返回值

不使用返回值。

备注

此成员函数模拟 LVM_SETSELECTEDCOLUMN 消息的功能，如 Windows SDK 中所述。

`CListCtrl::SetSelectionMark`

设置列表视图控件的选择标记。

int SetSelectionMark(int iIndex);

参数

iIndex
多重选择中的第一项的从零开始的索引。

返回值

以前的选择标记；如果没有选择标记，则为 -1。

备注

此成员函数实现 Win32 宏 ListView_SetSelectionMark 的行为，如 Windows SDK 中所述。

示例

请参阅 CListCtrl::GetSelectionMark 的示例。

`CListCtrl::SetTextBkColor`

设置列表视图控件中的文本的背景色。

BOOL SetTextBkColor(COLORREF cr);

参数

cr
指定新的文本背景色的 COLORREF。有关信息，请参阅 Windows SDK 中的 COLORREF。

返回值

如果成功，则不为零，否则为零。

示例

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

`CListCtrl::SetTextColor`

设置列表视图控件的文本颜色。

BOOL SetTextColor(COLORREF cr);

参数

cr
指定新文本颜色的 COLORREF。有关信息，请参阅 Windows SDK 中的 COLORREF。

返回值

如果成功，则不为零，否则为零。

示例

// 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);

`CListCtrl::SetTileInfo`

设置列表视图控件的图块的信息。

BOOL SetTileInfo(PLVTILEINFO pTileInfo);

参数

pTileInfo
指向 LVTILEINFO 结构的指针，该结构包含要设置的信息。

返回值

成功时返回 TRUE，失败时返回 FALSE。

注解

此成员函数模拟 LVM_SETTILEINFO 消息的功能，如 Windows SDK 中所述。

`CListCtrl::SetTileViewInfo`

设置列表视图控件在平铺视图中使用的信息。

BOOL SetTileViewInfo(PLVTILEVIEWINFO ptvi);

参数

ptvi
指向 LVTILEVIEWINFO 结构的指针，该结构包含要设置的信息。

返回值

成功时返回 TRUE，失败时返回 FALSE。

注解

此成员函数模拟 LVM_SETTILEVIEWINFO 消息的功能，如 Windows SDK 中所述。

`CListCtrl::SetToolTips`

设置列表视图控件将用于显示工具提示的工具提示控件。

CToolTipCtrl* SetToolTips(CToolTipCtrl* pWndTip);

参数

pWndTip
指向列表控件将使用的 CToolTipCtrl 对象的指针。

返回值

指向包含控件之前使用的工具提示的 CToolTipCtrl 对象的指针，如果之前未使用任何工具提示，则返回 NULL。

备注

此成员函数实现 Win32 消息 LVM_SETTOOLTIPS 的行为，如 Windows SDK 中所述。

如果不使用工具提示，请在创建 CListCtrl 对象时指示 LVS_NOTOOLTIPS 样式。

`CListCtrl::SetView`

设置列表视图控件的视图。

DWORD SetView(int iView);

参数

iView
要选择的视图。

返回值

如果成功，返回 1；否则返回 -1。例如，如果视图无效，返回 -1。

备注

此成员函数模拟 LVM_SETVIEW 消息的功能，如 Windows SDK 中所述。

`CListCtrl::SetWorkAreas`

设置可在列表视图控件中显示图标的区域。

void SetWorkAreas(
    int nWorkAreas,
    LPRECT lpRect);

参数

nWorkAreas
在 lpRect 指向的数组中，RECT 结构（或 CRect 对象）的数量。

lpRect
指定列表视图控件的新工作区域的 RECT 结构（或 CRect 对象）的数组的地址。必须在客户端坐标中指定这些区域。如果此参数为 NULL，系统会将工作区域设置为控件的工作区。

注解

此成员函数实现 Win32 宏 ListView_SetWorkAreas 的行为，如 Windows SDK 中所述。

示例

// Remove all working areas.
m_myListCtrl.SetWorkAreas(0, NULL);

`CListCtrl::SortGroups`

使用应用程序定义的比较函数在列表视图控件内将组按 ID 排序。

BOOL SortGroups(
    PFNLVGROUPCOMPARE _pfnGroupCompare,
    LPVOID _plv);

参数

_pfnGroupCompare
指向组比较函数的指针。

_plv
void 指针。

返回值

成功时返回 TRUE，失败时返回 FALSE。

注解

此成员函数模拟 LVM_SORTGROUPS 消息的功能，如 Windows SDK 中所述。

`CListCtrl::SortItems`

通过使用应用程序定义的比较函数来对列表视图项排序。

BOOL SortItems(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);

参数

pfnCompare
[in] 应用程序定义的比较函数的地址。

每次需要确定两个列表项的相对顺序时，排序操作都调用比较函数。比较函数必须是类的静态成员，或者是不属于任何类的成员的独立函数。

dwData
[in] 传递给比较函数的应用程序定义值。

返回值

如果此方法成功，返回 TRUE；否则返回 FALSE。

备注

此方法通过更改各项的索引来反映新序列。

比较函数 pfnCompare 具有以下形式：

int CALLBACK CompareFunc(LPARAM lParam1,
    LPARAM lParam2,
    LPARAM lParamSort);

如果第一项应该在第二项之前，比较函数必须返回负值；如果第一项应该在第二项之后，该函数必须返回正值；如果这两项相等，则返回零。

lParam1 参数是与比较的第一项关联的 32 位（如果是为 x64 执行编译，则为 64 位）的值，lParam2 参数是与第二项关联的值。这些值是在将它们插入列表中时，在项的 LVITEM 结构的 lParam 成员中指定的值。 lParamSort 参数与 dwData 值相同。

此方法将发送 LVM_SORTITEMS 消息，如 Windows SDK 中所述。

示例

下面是一个简单的比较函数，它使项按其 lParam 值排序。

// Sort items by associated lParam
int CALLBACK CListCtrlDlg::MyCompareProc(LPARAM lParam1, LPARAM lParam2,
    LPARAM lParamSort)
{
    UNREFERENCED_PARAMETER(lParamSort);
    return (int)(lParam1 - lParam2);
}

// Sort the items by passing in the comparison function.
void CListCtrlDlg::Sort()
{
    m_myListCtrl.SortItems(&CListCtrlDlg::MyCompareProc, 0);
}

`CListCtrl::SortItemsEx`

使用应用程序定义的比较函数，对当前列表视图控件的项排序。

BOOL SortItemsEx(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);

参数

pfnCompare
[in] 应用程序定义的比较函数的地址。每次需要确定两个列表项的相对顺序时，排序操作都调用比较函数。比较函数必须是类的静态成员，或者是不属于任何类的成员的独立函数。

dwData
[in] 传递给比较函数的应用程序定义值。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

备注

此方法通过更改各项的索引来反映新序列。

比较函数 pfnCompare 具有以下形式：

int CALLBACK CompareFunc(LPARAM lParam1,
    LPARAM lParam2,
    LPARAM lParamSort);

此消息就像 LVM_SORTITEMS 一样，除了传递给比较函数的信息类型以外。在 LVM_SORTITEMS 中，lParam1 和 lParam2 是要比较的项的值。在 LVM_SORTITEMSEX 中，lParam1 是要比较的第一个项的当前索引，lParam2 是第二个项的当前索引。你可以发送 LVM_GETITEMTEXT 消息来检索与项相关的更多信息。

如果第一项应该在第二项之前，比较函数必须返回负值；如果第一项应该在第二项之后，该函数必须返回正值；如果这两项相等，则返回零。

注意

在排序过程中，列表视图内容不稳定。如果回调函数向列表视图控件发生除 LVM_GETITEM 以外的任何消息，结果都是不可预测的。

此方法将发送 LVM_SORTITEMSEX 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_listCtrl，它用于访问当前的列表视图控件。此变量将在下一个示例中使用。

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

下一个代码示例演示了 SortItemEx 方法。在此代码示例较前面的部分中，我们创建了一个列表视图控件，它在报表视图中显示标题为“ClientID”和“Grade”的两列。以下代码示例使用“Grade”列中的值对表进行排序。

// 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 );
}

`CListCtrl::SubItemHitTest`

确定哪一个列表视图项（如果有）位于给定位置。

int SubItemHitTest(LPLVHITTESTINFO pInfo);

参数

pInfo
指向 LVHITTESTINFO 结构的指针。

返回值

如果有要测试的项或子项，返回其从 1 开始的索引；否则返回 -1。

注解

此成员函数实现 Win32 宏 ListView_SubItemHitTest 的行为，如 Windows SDK 中所述。

示例

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);
    }
}

`CListCtrl::Update`

强制列表视图控件重新绘制由 nItem 指定的项。

BOOL Update(int nItem);

参数

nItem
要更新的项的索引。

返回值

如果成功，则不为零，否则为零。

注解

如果列表视图控件具有 LVS_AUTOARRANGE 样式，此函数也会排列该控件。

示例

请参阅 CListCtrl::GetSelectedCount 的示例。

另请参阅

MFC Sample ROWLIST
CWnd 类
 层次结构图
 CImageList 类

通过

CListCtrl 类

语法

成员

公共构造函数

公共方法

备注

Views

扩展样式

项和子项

图像列表

继承层次结构

要求

CListCtrl::ApproximateViewRect

参数

返回值

注解

CListCtrl::Arrange

参数

返回值

注解

示例

CListCtrl::CancelEditLabel

注解

CListCtrl::CListCtrl

CListCtrl::Create

参数

返回值

备注

示例

CListCtrl::CreateEx

参数

返回值

备注

CListCtrl::CreateDragImage

参数

返回值

备注

CListCtrl::DeleteAllItems

返回值

示例

CListCtrl::DeleteColumn

参数

返回值

示例

CListCtrl::DeleteItem

参数

返回值

示例

CListCtrl::DrawItem

参数

注解

CListCtrl::EditLabel

参数

返回值

注解

示例

CListCtrl::EnableGroupView

参数

返回值

注解

CListCtrl::EnsureVisible

参数

返回值

备注

示例

CListCtrl::FindItem

参数

返回值

注解

示例

CListCtrl::GetBkColor

返回值

示例

CListCtrl::GetBkImage

参数

返回值

备注

示例

CListCtrl::GetCallbackMask

`CListCtrl` 类

`CListCtrl::ApproximateViewRect`

`CListCtrl::Arrange`

`CListCtrl::CancelEditLabel`

`CListCtrl::CListCtrl`

`CListCtrl::Create`

`CListCtrl::CreateEx`

`CListCtrl::CreateDragImage`

`CListCtrl::DeleteAllItems`

`CListCtrl::DeleteColumn`

`CListCtrl::DeleteItem`

`CListCtrl::DrawItem`

`CListCtrl::EditLabel`

`CListCtrl::EnableGroupView`

`CListCtrl::EnsureVisible`

`CListCtrl::FindItem`

`CListCtrl::GetBkColor`

`CListCtrl::GetBkImage`

`CListCtrl::GetCallbackMask`

`CListCtrl::GetCheck`

`CListCtrl::GetColumn`

`CListCtrl::GetColumnOrderArray`

`CListCtrl::GetColumnWidth`

`CListCtrl::GetCountPerPage`

`CListCtrl::GetEditControl`

`CListCtrl::GetEmptyText`

`CListCtrl::GetExtendedStyle`

`CListCtrl::GetFirstSelectedItemPosition`

`CListCtrl::GetFocusedGroup`

`CListCtrl::GetGroupCount`

`CListCtrl::GetGroupInfo`

`CListCtrl::GetGroupInfoByIndex`

`CListCtrl::GetGroupMetrics`

`CListCtrl::GetGroupRect`

`CListCtrl::GetGroupState`

`CListCtrl::GetHeaderCtrl`