关于列表视图控件

请参阅虚拟列表视图控件示例。

列表视图控件是一个显示项目集合的窗口。 列表视图控件提供了多种排列和显示项目的方法，比简单的列表框要灵活得多。 例如，可以在图标和标签右侧的列中显示每个项目的附加信息。

• 列表视图样式和视图
  • 扩展列表视图样式
• 虚拟列表视图样式
  • 创建虚拟列表视图控件
  • 兼容性问题
  • 处理虚拟列表视图控件通知代码
  • 缓存管理
• 列表视图工作区
• 列表视图图像列表
• 列表视图项目和子项目
  • 列表视图项状态
  • 回调项和回调掩模
  • 列表视图项目位置
  • 排列、排序和查找项目
• 列表视图列
• 列表视图滚动位置
• 列表视图标签编辑
• 列表视图颜色
• 按组排列列表项目
• 插入标记

列表视图样式和视图

列表视图控件能以五种不同的视图来显示项目。 控件的窗口样式指定了默认视图。 其他窗口样式可指定项目的对齐方式和控件的特定功能。 下表介绍了这些视图。

视图名称	说明
图标视图	由 LVS_ICON 窗口样式指定，或通过 LVM_SETVIEW 消息传递 LV_VIEW_ICON 来指定。 每个项目都显示为一个全尺寸图标，其下方有一个标签。 用户可以将项拖到列表视图窗口中的任何位置。
小图标视图	由 LVS_SMALLICON 窗口样式指定，或通过 LVM_SETVIEW 传递 LV_VIEW_SMALLICON 来指定。 各项显示为一个小图标，小图标右侧有一个标签。 用户可以将项目拖到任何位置。
列表视图	由 LVS_LIST 窗口样式指定，或通过 LVM_SETVIEW 传递 LV_VIEW_LIST 来指定。 各项显示为一个小图标，小图标右侧有一个标签。 项目按列排列，用户无法将它们拖到任意位置。
报告（详细信息）视图	由 LVS_REPORT 窗口样式指定，或通过 LVM_SETVIEW 传递 LV_VIEW_DETAILS 来指定。 每个项目单独显示为一行，并且信息按列排列。 最左边一列始终左对齐，并包含小图标和标签。 后续列包含应用程序指定的子项目。 每个列都有一个标题，除非还指定了 LVS_NOCOLUMNHEADER 窗口样式。
图块视图	版本 6 及更高版本。 通过 LVM_SETVIEW 传递 LV_VIEW_TILE 来指定。 每个项目都显示为一个全尺寸图标，旁边有一行或多行标签。

 

以下屏幕截图使用视图显示了有关七只宠物的不同信息量。 这些视图展示了信息在 Windows Vista 上的显示方式。 通过使用 SetWindowTheme 将控件的视觉样式设置为“资源管理器”主题。

以下屏幕截图显示了详细信息视图。

以下屏幕截图显示了图标视图。

以下屏幕截图显示了列表视图。

以下屏幕截图显示了磁贴视图。

创建列表视图控件后，可以更改视图类型。 要检索和更改窗口样式，请使用 GetWindowLong 和 SetWindowLong 函数。 要确定当前视图的窗口样式，请使用 LVS_TYPEMASK 值。

可以通过指定 LVS_ALIGNTOP（默认）或 LVS_ALIGNLEFT 窗口样式来控制项目在图标或小图标视图中的排列方式。

可以在创建列表视图控件后更改对齐方式。 要确定当前对齐方式，请使用 LVS_ALIGNMASK 值。

其他窗口样式还提供其他选项，例如用户是否可以编辑标签或一次选择多个项目。 有关完整列表，请参阅列表视图窗口样式。

扩展列表视图样式

扩展列表视图控件样式提供了复选框、平面滚动条、网格线和热跟踪等选项。 有关完整列表，请参阅扩展列表视图样式。 访问扩展列表视图样式的方式与访问标准窗口样式的方式有所不同。 不能使用 GetWindowLong 和 SetWindowLong 函数进行扩展样式更改。

设置和检索扩展样式信息的消息有两种：LVM_SETEXTENDEDLISTVIEWSTYLE 和 LVM_GETEXTENDEDLISTVIEWSTYLE。 可以使用以下相应宏来代替显式发送消息：ListView_SetExtendedListViewStyle、ListView_SetExtendedListViewStyleEx 和 ListView_GetExtendedListViewStyle。

虚拟列表视图样式

虚拟列表视图是具有 LVS_OWNERDATA 样式的列表视图控件。 此样式让控件能够处理数百万个项目，因为所有者承担了管理项目数据的责任。 这样就可以在大型信息数据库中使用虚拟列表视图控件，因为在这些数据库中已经有了特定的数据访问方法。

虚拟列表视图控件本身只会维护很少的项目信息。 除项目选择和焦点信息外，控件所有者还必须管理所有项目信息。 其他进程通过使用 LVN_GETDISPINFO 通知代码来向所有者请求项目信息。

由于这种类型的列表控件适用于大型数据集，因此建议缓存请求的项数据以提高检索性能。 列表视图提供一种缓存提示机制，以帮助优化缓存。 提示以 LVN_ODCACHEHINT 通知代码的形式来实现。

创建虚拟列表视图控件

可以使用 CreateWindow 或 CreateWindowEx 函数来创建虚拟列表视图控件，并指定 LVS_OWNERDATA 窗口样式作为 dwStyle 函数参数的一部分。 不支持动态切换 LVS_OWNERDATA 样式。

可以将 LVS_OWNERDATA 样式与大多数其他窗口样式结合使用，但 LVS_SORTASCENDING 或 LVS_SORTDESCENDING 样式除外。 所有虚拟列表视图控件默认使用 LVS_AUTOARRANGE 样式。

要在列表中显示项目，必须首先显式发送或通过使用 ListView_SetItemCountEx 宏来发送 LVM_SETITEMCOUNT 消息。

LVS_OWNERDATA 样式不支持以下消息：LVM_ENABLEGROUPVIEW、LVM_GETITEMTEXT、LVM_SETTILEINFO 和 LVM_MAPIDTOINDEX。

兼容性问题

所有四种列表视图样式（图标、小图标、列表和报表视图）都支持 LVS_OWNERDATA 样式。 具有 LVS_OWNERDATA 样式的列表视图控件不会存储任何特定于项目的信息。 因此，能应用于项目的有效项目状态标志只有 LVIS_SELECTED 和 LVIS_FOCUSED。 不会存储其他状态信息。 具体而言，列表视图控件不会为每个项目保持状态或覆盖图像。 但是，可以通过向列表视图控件发送 LVM_SETCALLBACKMASK 消息，让列表视图控件查询应用程序中的这些图像。

完全支持大多数列表视图控制消息和关联的宏。 但是，在使用 LVS_OWNERDATA 样式时，某些消息会受到限制或不支持。 下表概述了受影响的消息。

Message	限制
LVM_ARRANGE	不支持 LVA_SNAPTOGRID 样式。
LVM_DELETEALLITEMS	将项目计数设置为 0，并清除所有内部选择变量，但实际上不会删除任何项目。 它会进行通知回调。
LVM_DELETEITEM	仅支持选择完整性，并且不会实际删除项目。
LVM_GETITEMSTATE	只返回焦点和选择状态（即列表视图控件存储的状态）。
LVM_GETNEXTITEM	不支持列表视图搜索条件 LVNI_CUT、LVNI_HIDDEN 或 LVNI_DROPHILITED。 支持所有其他条件。
LVM_GETWORKAREAS	不支持。
LVM_INSERTITEM	仅支持选择完整性。
LVM_SETITEM	不支持。 要设置项目状态，请使用 ListView_SetItemState 消息。
LVM_SETITEMCOUNT	设置当前列表中的项目数。 如果列表视图控件发出通知，要求提供最大集合内任何项目的数据，则所有者必须准备好提供这些数据。 消息参数支持虚拟列表视图控件。
LVM_SETITEMPOSITION	不支持。
LVM_SETITEMSTATE	只允许更改项目的选择和焦点状态。
LVM_SETITEMTEXT	不支持。 应用程序有责任维护项目文本。
LVM_SETWORKAREAS	不支持。
LVM_SORTITEMS	不支持。 应用程序有责任按照所需的顺序显示项目。

 

处理虚拟列表视图控件通知代码

具有 LVS_OWNERDATA 样式的列表视图控件会发送与其他列表视图控件相同的通知代码以及另外两个通知代码：LVN_ODCACHEHINT 和 LVN_ODFINDITEM。 以下是具有 LVS_OWNERDATA 样式的列表视图控件最常发送的通知。

通知	说明
LVN_GETDISPINFO	虚拟列表视图控件本身只会维护很少的项目信息。 因此，它经常发送 LVN_GETDISPINFO 通知代码来请求项目信息。 此消息的处理方式与标准列表控件中的回调项基本相同。 由于控件支持的项目数量可能非常大，因此缓存项目数据可以提高性能。 在处理 LVN_GETDISPINFO 时，控件所有者首先会尝试从缓存中提供所请求的项目信息（有关详细信息，请参阅缓存管理）。 如果请求的项目没有缓存，则所有者必须准备通过其他方式来提供信息。
LVN_ODCACHEHINT	虚拟列表视图会发送 LVN_ODCACHEHINT 通知代码，以帮助优化缓存。 通知代码会为其建议缓存的一系列项目提供包含的索引值。 在收到通知代码后，所有者必须准备好在缓存中加载所请求范围的项目信息，以便在发送 LVN_GETDISPINFO 消息时可以随时使用这些信息。
LVN_ODFINDITEM	当虚拟列表视图控件需要所有者查找特定回调项时，该控件会发送 LVN_ODFINDITEM 通知代码。 当列表视图控件收到快速键访问或收到 LVM_FINDITEM 消息时，将发送通知代码。 搜索信息以 LVFINDINFO 结构的形式发送，该结构是 NMLVFINDITEM 结构的成员。 所有者必须准备好搜索与列表视图控件提供的信息相匹配的项目。 如果成功，所有者将返回项目的索引；如果未找到匹配的项目，则返回 -1。

 

缓存管理

使用 LVS_OWNERDATA 样式的列表视图控件会生成大量 LVN_GETDISPINFO 通知代码，并且为了帮助优化缓存，还会生成 LVN_ODCACHEHINT 消息。 LVN_ODCACHEHINT 消息提供了有关缓存中建议包含的项目的信息。 这些消息以 WM_NOTIFY 消息的形式发送，其中 lParam 值用作 NMLVCACHEHINT 结构的地址。

NMLVCACHEHINT 结构包含两个整数成员，即 iFrom 和 iTo，它们表示最有可能需要的一系列项目的包含终结点。 所有者必须准备好在缓存中加载推荐范围内每个项目的信息。

列表控件通常需要第一个项目（偏移量 0）的项目信息。 LVN_ODCACHEHINT 通知代码可能并不总是包含项目 0，但它必须始终包含在缓存中。

列表中的最后一个项目经常被访问。 因此，所有者可能希望保留第二个缓存，其中包括列表末尾的项目。 LVN_ODCACHEHINT 中的请求范围可与末端缓存进行核对，以便使其自动可用，而不是每次都重新加载相同的结束范围。

列表视图工作区

列表视图控件支持工作区，工作区是矩形的虚拟区域，列表视图控件会用它来排列项目。 工作区不是窗口，不能有可见边框。 默认情况下，列表视图控件没有工作区。 通过创建工作区，可以在项目的左侧、顶部或右侧创建一个空边框，或者在通常没有水平滚动条的情况下显示水平滚动条。

创建工作区后，位于工作区内的项目就会成为工作区的成员。 同样，如果一个项目被移动到一个工作区，该项目就会成为该工作区的成员。 如果某个项不在任何工作区域内，它会自动成为第一个（索引 0）工作区域的成员。 要在特定工作区中放置新项目，必须首先创建项目，然后使用 LVM_SETITEMPOSITION 或 LVM_SETITEMPOSITION32 消息将其移至所需的工作区中。

下图是一个包含四个工作区的列表视图控件示例，而每个工作区都位于客户区的不同象限。

多个工作区可用于在一个视图中创建不同的区域。 可以在单个视图中创建具有不同含义的区域。 例如，文件系统的视图可能有一个区域用于读/写文件，而另一个区域用于只读文件。 用户可以通过将项目放置在不同的工作区来对它们进行分类。 如果文件被移动到只读区域，则它将自动变成只读文件。

多个工作区可以相交，但位于相交位置的任何项目都会成为索引较低的工作区的成员；因此，最好要避免这种情况。 在对多个工作区进行排序时，会将项目与同一工作区的其他项目进行比较排序。

工作区的数量可通过 LVM_GETNUMBEROFWORKAREAS 消息来获取。 工作区可通过 LVM_SETWORKAREAS 消息来更改，也可通过 LVM_GETWORKAREAS 消息进行检索。 这两条消息都将 RECT 结构数组的地址作为 lParam 值，将 RECT 结构的数量作为 wParam 值。 这些结构的左侧和顶部成员指定工作区左上角（原点）的坐标，右侧和底部成员指定工作区右下角的坐标。 所有坐标都在列表视图的客户端坐标中。 允许的最大工作区数量由 LV_MAX_WORKAREAS 值定义。

更改工作区对使用 LVS_LIST 或 LVS_REPORT 视图的列表视图控件没有影响，但在更改视图类型后，工作区将保持不变。 通过 LVS_ICON 和 LVS_SMALLICON 视图，可以修改工作区以更改项目的显示方式。 如果让工作区的宽度（右 - 左）大于控件的客户端宽度，会导致项目以该宽度进行包装，并显示水平滚动条。 如果使工作区的宽度小于控件客户区的宽度，则会导致项目被包装在工作区内，而不是客户区内。 将左侧或顶部成员设置为正值，会使项目从工作区开始显示，从而在控件边缘和项目之间形成空白。 还可以通过使工作区的宽度小于控件的客户区宽度，在控件右边缘和项目之间创建一个空白空间。

列表视图图像列表

默认情况下，列表视图控件不会显示项目图像。 要显示项目图片，必须创建图片列表并将其与控件相关联。 列表视图控件可以有三个图像列表：

• 一个包含全尺寸图标的图像列表，这些图标会在控件处于图标视图时显示。
• 一个包含小图标的图像列表，这些图标会在控件处于小图标视图、列表视图或报告视图时显示。
• 一个包含的状态图像的图像列表，这些图像显示在全尺寸或小图标的左侧。 可以使用状态图像（如选中和清除复选框）来表示应用程序定义的项目状态。 状态图像可在图标视图、小图标视图、列表视图和报告视图中显示。

全尺寸和小图标图像列表还可以包含覆盖图像，这些图像可以在项目图标上透明绘制。

在列表视图控件中使用覆盖图像：

1. 调用 ImageList_SetOverlayImage 函数，为全尺寸和小图标图像列表中的图像分配覆盖图像索引。 覆盖图像可通过从 1 开始的索引来识别。
2. 调用 ListView_InsertItem 或 ListView_SetItem 宏时，可以将覆盖图像索引与项目相关联。 使用 INDEXTOOVERLAYMASK 宏，在项目 LVITEM 结构的 state 成员中指定覆盖图像索引。 还必须设置 stateMask 成员中的 LVIS_OVERLAYMASK 位。

如果指定了状态图像列表，则列表视图控件会在每个项目图标的左侧为状态图像预留空间。

要将状态图像与项目相关联，请使用 INDEXTOSTATEIMAGEMASK 宏，在 LVITEM 结构的 state 成员中指定状态图像索引。 索引标识控件状态图像列表中的图像。 虽然图像列表索引是从 0 开始的，但控件使用从 1 开始的索引来标识状态图像。 状态图像索引为 0 表示项目没有状态图像。

默认情况下，在销毁列表视图控件时，它会销毁分配给它的图像列表。 但是，如果列表视图控件具有 LVS_SHAREIMAGELISTS 窗口样式，则应用程序应负责在图像列表不再使用时将其销毁。 如果将相同的图像列表分配给多个列表视图控件，则应指定此样式；否则，多个控件可能会尝试销毁同一个的图像列表。

列表视图项目和子项目

列表视图控件中的每个项目都有一个图标、一个标签、一个当前状态和一个应用程序定义的值。 通过使用列表视图消息，可以添加、修改和删除项目，也可以检索项目的相关信息。

每个项目可以有一个或多个子项目。 子项目是一个字符串，在报告视图中显示在与项目图标和标签分开的一列中。 要指定子项目的文本，请使用 LVM_SETITEMTEXT 或 LVM_SETITEM 消息。 列表视图控件中的所有项目都有相同数量的子项目。 子项目的数量由列表视图控件的列数决定。 向列表视图控件添加列时，需要指定其相关的子项目索引。

LVITEM 结构定义列表视图项目或子项目。 iItem 成员是项目从 0 开始的索引。 iSubItem 成员是子项目从 1 开始的索引，如果结构中包含一个项目的信息，则该索引从 0 开始。 其他成员指定项的文本、图标、状态和项数据。 项目数据是与列表视图项目相关联的应用程序定义的值。

要在列表视图控件中添加项目，请使用 LVM_INSERTITEM 消息，并指定 LVITEM 结构的地址。 在添加多个项目之前，可以向控件发送 LVM_SETITEMCOUNT 消息，指定控件最终将包含的项目数。 此消息可让列表视图控件只重新分配一次内部数据结构，而不是每次添加项目时都重新分配。 可以使用 LVM_GETITEMCOUNT 消息来确定列表视图控件中的项目数。 如果要在列表视图控件中添加大量项目，则可以在添加项目前禁用重新绘制，然后在添加项目后启用重新绘制，从而加快该过程。 使用 WM_SETREDRAW 消息i启用或禁用重新绘制。

要更改列表视图项目的属性，请使用 LVM_SETITEM 消息，指定 LVITEM 结构的地址。 此结构的 mask 成员指定了要更改的项目属性。 例如，要只更改项目或子项目的文本，请使用 LVM_SETITEMTEXT 消息。

要检索列表视图项目的信息，请使用 LVM_GETITEM 消息，指定要填写的 LVITEM 结构的地址。 此结构的 mask 成员指定要检索的项目属性。 要只检索项目或子项目的文本，请使用 LVM_GETITEMTEXT 消息。

要删除列表视图项目，请使用 LVM_DELETEITEM 消息。 可以使用 LVM_DELETEALLITEMS 消息来删除列表视图控件中的所有项目。

列表视图项状态

项目的状态是一个值，用于指定项目的可用性、指示用户操作或以其他方式反映项目的状态。 列表视图控件会改变一些状态位，例如当用户选择某个项目时。 应用程序可能会更改其他状态位，以禁用或隐藏项目，或者指定覆盖图像或状态图像。 有关覆盖图像和状态图像的更多信息，请参阅列表视图图像列表。

项目的状态由 LVITEM 结构的 state 成员指定。 在指定或更改某个项目的状态时，stateMask 成员会指定需要更改的状态位。 可以使用 LVM_SETITEMSTATE 消息来更改项目的状态。 可以在创建项目或更改其属性时使用 LVM_SETITEM 消息来指定项目的状态。 要确定项目的当前状态，请使用 LVM_GETITEMSTATE 或 LVM_GETITEM 消息。

要设置项目的覆盖图像，LVITEM 结构的 stateMask 成员必须包括 LVIS_OVERLAYMASK 值，而 state 成员必须包括通过使用 INDEXTOOVERLAYMASK 宏向左移动 8 位的覆盖图像从 1 开始的索引。 索引可以为 0，以指定没有覆盖图像。

要设置项目的状态图像，LVITEM 结构的 stateMask 成员必须包括 LVIS_STATEIMAGEMASK 值，而 state 成员必须包括通过使用 INDEXTOSTATEIMAGEMASK 宏向左移动 8 位的状态图像从 1 开始的索引。 索引可以为 0，以指定没有状态图像。

回调项和回调掩模

对于每个项目，列表视图控件通常会存储标签文本、项目图标的图像列表索引以及项目状态的一组位标志。 可以定义回调项目或更改控件的回调掩模，以表示由应用程序而不是控件来存储部分或全部信息。 如果应用程序存储了部分此类信息，则可能需要使用回调。

列表视图控件中的回调项是应用程序存储文本或图标索引（或两者）的项目。 在发送 LVM_INSERTITEM 消息向列表视图控件添加项目时，可以定义回调项目。 如果应用程序存储了项目或子项目的文本，则应将项目 LVITEM 结构的 pszText 成员设置为 LPSTR_TEXTCALLBACK。 如果应用程序存储了项目的图标索引，则应将项目的 LVITEM 结构中的 iImage 成员设置为 I_IMAGECALLBACK。

列表视图控件的回调掩模是一组位标志，用于指定应用程序（而不是控件）存储当前数据的项目状态。 回调掩模适用于控件的所有项，而回调项指示符则不同，它适用于特定项。 默认情况下，回调掩模为 0，这意味着列表视图控件会存储所有项目状态信息。 创建列表视图控件并初始化其项目后，可以发送 LVM_SETCALLBACKMASK 消息来更改回调掩模。 要检索当前回调掩模，请发送 LVM_GETCALLBACKMASK 消息。

当列表视图控件必须显示或排序应用程序存储了回调信息的列表视图项时，该控件会向控件的父窗口发送 LVN_GETDISPINFO 通知代码。 此消息指定了一个 NMLVDISPINFO 结构，其中包含所需的信息类型，并标识了要检索的项目或子项目。 父窗口必须处理 LVN_GETDISPINFO 以提供所请求的数据。

如果列表视图控件检测到项目的回调信息发生变化，例如文本、图标或状态信息发生变化，控件就会发送 LVN_SETDISPINFO 通知代码，以通知所发生的变化。

如果更改了回调项目的属性或状态位，则可以使用 LVM_UPDATE 消息来强制控件重新绘制该项目。 如果控件具有 LVS_AUTOARRANGE 样式，则此消息还会使控件排列其项目。 可以使用 LVM_REDRAWITEMS 消息，通过使列表视图控件客户区的相应部分无效来重新绘制一系列项目。

通过有效使用回调项目和回调掩模，可以确保每个项目属性只在一个地方维护。 这样做可以简化应用程序，但唯一节省的空间是存储项目标签和子项目文本所需的内存。

列表视图项目位置

每个列表视图项都有一个位置和大小，可以使用消息来检索和设置。 还可以确定哪个项目（如有）位于指定位置。 列表视图项目的位置是在视图坐标中指定的，该坐标是按滚动位置的客户坐标偏移量。

要检索和设置项目的位置，请使用 LVM_GETITEMPOSITION 和 LVM_SETITEMPOSITION 消息。 LVM_GETITEMPOSITION 适用于所有视图，但 LVM_SETITEMPOSITION 仅适用于图标和小图标视图。

可以使用 LVM_HITTEST 消息来确定特定位置上的项目（如有）。

要检索列表项目的边界矩形或仅检索其图标或标签的边界矩形，请使用 LVM_GETITEMRECT 消息。

排列、排序和查找项目

可以使用列表视图信息对项目进行排列和排序，并根据其属性或位置来查找项目。 排列会重新定位项目以使其在网格上对齐，但项目的索引不会变化。 排序会改变项目（及其相应的索引）的顺序，然后相应地重新定位它们。 只能在图标和小图标视图中排列项目，但可以在任何视图中对项目进行排序。 要查找项目，可发送指定项目位置或属性的列表视图消息。

要排列项目，请使用 LVM_ARRANGE 消息。 可以通过指定 LVS_AUTOARRANGE 窗口样式来确保项目始终已排列。

要对项目进行排序，请使用 LVM_SORTITEMS 消息。 使用此消息进行排序时，需要指定一个应用程序定义的回调函数，以便由列表视图控件调用该函数来比较任意两个项目的相对顺序。 该控件会将与两个项目中的每个项目相关联的项目数据传递给比较函数。 项目数据是在项目被插入列表时在项目 LVITEM 结构的 lParam 成员中指定的值。 通过指定适当的项目数据和提供适当的比较函数，可以按标签、任何子项目或任何其他属性对项目进行排序。 请注意，对项目进行排序不会对相应的子项目重新排序。 在对项目重新排序时，其相应的子项目也会随之进行排序；也就是说，整行的项目会保持在一起。 如果要将列与列之间分开排序，从而将子项目与其项目分离，则必须在使用 LVM_SETITEM 排序后重新生成列。

可以通过指定 LVS_SORTASCENDING 或 LVS_SORTDESCENDING 窗口样式来确保列表视图控件始终已排序。 具有这些样式的控件会使用项目的标签文本按升序或降序进行排序。 使用这些窗口样式时，无法提供比较函数。 如果列表视图控件具有这些样式中的任何一种，那么在尝试插入其 LVITEM 结构的 pszText 成员为 LPSTR_TEXTCALLBACK 的项目时，LVM_INSERTITEM 消息将提示失败。

可以使用 LVM_FINDITEM 消息来查找具有特定属性的列表视图项目。 可以使用 LVM_GETNEXTITEM 消息查找处于指定状态并与给定项目有指定关系的列表视图项目。 例如，可以检索指定项目右侧的下一个选定项目。

列表视图列

列控制项目及其子项目在报告视图中的显示方式。 每个列都有标题和宽度，并与特定的子项目相关联；子项目 0 是项目的图标和标签。 列的属性由 LVCOLUMN 结构定义。

要在列表视图控件中添加列，请使用 LVM_INSERTCOLUMN 消息。 要删除列，请使用 LVM_DELETECOLUMN 消息。

注意

仅 ComCtl32.dll 6 及更高版本支持删除列表视图控件的 0 列。 版本 5 也支持删除 0 列，但只有在使用 CCM_SETVERSION 将版本设置为 5 或更高版本后才能删除 0 列。 第 5 版之前的版本不支持删除 0 列。

 

可以使用 LVM_GETCOLUMN 和 LVM_SETCOLUMN 消息来检索和更改现有列的属性。 要检索或更改列宽，请使用 LVM_GETCOLUMNWIDTH 和 LVM_SETCOLUMNWIDTH 消息。

除非指定 LVS_NOCOLUMNHEADER 窗口样式，否则报告视图中将显示列标题。 用户可以单击列标题，从而向父窗口发送 LVN_COLUMNCLICK 通知代码。 通常情况下，在单击时父窗口会按指定列对列表视图控件进行排序。 用户还可以拖动标题之间的列参考线来调整列的大小。

列表视图控件可以在列标题旁边显示图像。 要实现这一功能，请指定 LVCF_IMAGE 值，并将图像索引分配给 LVCOLUMN 结构中的 iImage 成员。

列表视图控件可以设置列的显示顺序。 要实现此功能，请指定 LVCF_ORDER 值，并将列顺序分配给 LVCOLUMN 结构中的 iOrder 成员。 列顺序从 0 开始从左到右排列。 例如，0 表示最左边的一列。

列表视图滚动位置

除非指定了 LVS_NOSCROLL 窗口样式，否则列表视图控件可以滚动显示超过控件客户区所能容纳数量的项目。 可以检索列表视图控件的滚动位置和相关信息，按指定的数量滚动列表视图控件，或者滚动列表视图控件以使指定的列表项目可见。

在图标视图或小图标视图中，当前滚动位置由视图原点定义。 视图原点是相对于列表视图控件可见区域的一组坐标，与视图坐标（0，0）相对应。 要检索当前视图原点，请使用 LVM_GETORIGIN 消息。 此消息只能在图标或小图标视图中使用；在列表或报告视图中使用会返回错误。

在列表或报表视图中，当前滚动位置由顶部索引定义。 顶部索引是列表视图控件中第一个可见项目的索引。 要检索当前的顶层索引，请使用 LVM_GETTOPINDEX 消息。 此消息仅在列表或报告视图中返回有效结果；在图标或小图标视图中会返回 0。

可以使用 LVM_GETVIEWRECT 消息来检索列表视图控件中所有项目相对于控件可见区域的边界矩形。

LVM_GETCOUNTPERPAGE 消息返回适合列表视图控件一页中显示的项目数量。 此消息仅在列表和报告视图中返回有效结果；在图标和小图标视图中，它将返回项目总数。

要以特定幅度滚动列表视图控件，请使用 LVM_SCROLL 消息。 使用 LVM_ENSUREVISIBLE 消息，可以在必要时滚动列表视图控件，以确保指定项目可见。

列表视图标签编辑

具有 LVS_EDITLABELS 窗口样式的列表视图控件可让用户就地编辑项目标签。 用户通过单击具有焦点的项的标签开始编辑。 或者，应用程序可以使用 LVM_EDITLABEL 消息自动开始编辑。 当编辑开始、取消或完成时，列表视图控件都会通知父窗口。 在完成编辑后，父窗口将负责更新项目的标签（如适用）。

在开始编辑标签时，会创建、定位和初始化一个编辑控件。 在显示之前，列表视图控件会向其父窗口发送 LVN_BEGINLABELEDIT 通知代码。 如果需要修改标签编辑流程，可以为该通知设置一个处理程序。

LVN_BEGINLABELEDIT 通知处理程序的一个用途是控制用户可以编辑哪些标签。 要防止编辑标签，请返回一个非 0 值。 要自定义标签编辑，可让通知处理程序通过向列表视图控件发送 LVM_GETEDITCONTROL 消息来获取编辑控件的句柄。 在获得该句柄后，就可以通过发送通常的 EM_XXX 消息来定制编辑控件。 例如，要限制用户可输入的文本量，可向编辑控件发送 EM_LIMITTEXT 消息。 可以使用 SetWindowText 来更改编辑控件的默认文本。 甚至还可以对编辑控件进行子类化，以拦截和丢弃无效的字符。

在取消或完成标签编辑时，列表视图控件会向其父窗口发送一个 LVN_ENDLABELEDIT 通知代码。 lParam 参数是 NMLVDISPINFO 结构的地址。 此结构的 item 成员是一个 LVITEM 结构，其 iItem 成员用于标识项目。 如果取消编辑，则 LVITEM 结构的 pszText 成员为 NULL；否则，pszText 将是已编辑文本的地址。 如果父窗口希望保留新标签，则由父窗口负责更新项目的标签。

列表视图颜色

应用程序可以检索和设置列表视图控件的三种颜色。

Color	用于检索和设置颜色的消息
文本颜色	LVM_GETTEXTCOLOR、LVM_SETTEXTCOLOR
文本背景颜色	LVM_GETTEXTBKCOLOR、LVM_SETTEXTBKCOLOR
窗口背景颜色	LVM_GETBKCOLOR、LVM_SETBKCOLOR

 

要对列表视图控件的外观进行更大幅度的自定义，请使用 NM_CUSTOMDRAW（列表视图）或使用视觉样式（请参阅视觉样式和启用视觉样式）。

按组排列列表项目

通过列表视图控件的分组功能，可以对逻辑上相关的项目集直观地分组。 可根据项目属性、属性或其他特征创建组。 这些组在屏幕上通常由一个包含组名的水平标题分隔。 以下屏幕截图显示了已分组的项目。

可以使用 LVGROUP 结构来存储组的相关信息，例如页眉和页脚文本、组的当前状态等。 分组 API 包含的消息可以通过向组添加项目、向视图添加组、对组项目排序以及查询组的项目大小和其他信息来管理组和组元素。 例如，可以使用 ListView_SetGroupMetrics 和 ListView_GetGroupMetrics 宏来设置和检索每个组的显示参数。

除列表视图外，分组功能适用于所有视图。 它不适用于具有 LVS_OWNERDATA 样式的控件。

有关更多信息，请参阅使用列表视图控件。

插入标记

插入标记可向用户显示拖动项目的位置。 当用户将项目拖入开始菜单或快速启动栏时，当前会显示插入标记。 插入标记也适用于设置为自动排列的列表。 当用户将某项拖至两个其他项之间的位置时，插入标记会显示该项的预计新位置。 以下屏幕截图显示了一个插入标记。

插入标记 API 元素通过提供执行命中检测的消息和标志、按项目指定插入标记的位置和外观以及查询插入标记当前大小和外观的信息，来实现插入标记的放置。

另请参阅

• 虚拟列表视图控件示例