LVM_INSERTITEM消息

  • 项目

在列表视图控件中插入新项。 可以显式发送此消息，也可以使用 ListView_InsertItem 宏发送。

参数

wParam

必须为零。

lParam

指向 LVITEM 结构的指针，该结构指定列表视图项的属性。 使用 iItem 成员指定应插入新项的从零开始的索引。 如果此值大于 listview 当前包含的项数，则新项将追加到列表末尾并分配正确的索引。 检查消息的返回值以确定分配给该项的实际索引。

返回值

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

备注

不能使用 ListView_InsertItem 或 LVM_INSERTITEM 插入子项。 LVITEM 结构的 iSubItem 成员必须为零。 有关设置子项的信息，请参阅 LVM_SETITEM 。

如果列表视图控件具有LVS_EX_CHECKBOXES样式集，则将忽略 LVITEM 结构的状态成员的第 12 位到 15 位的任何值。 添加具有此样式集的项时，将始终将其设置为未选中状态。

如果列表视图控件具有LVS_SORTASCENDING或LVS_SORTDESCENDING窗口样式，则尝试插入的项LPSTR_TEXTCALLBACK为其 pszText 成员的值时，LVM_INSERTITEM消息将失败。

如果满足以下条件， LVM_INSERTITEM 消息将在排序顺序中的正确位置插入新项：

  • 你正在使用LVS_SORTXXX样式之一。
  • 未使用 LVS_OWNERDRAW 样式。
  • pitem 指向的结构的 pszText 成员未设置为 LPSTR_TEXTCALLBACK。

如果 LVITEM 结构在 掩码 成员中不包含LVIF_GROUPID，则默认情况下I_GROUPIDCALLBACK iGroupId 成员的值。

要求

要求 值
最低受支持的客户端
 Windows Vista [仅限桌面应用]
最低受支持的服务器
 Windows Server 2003 [仅限桌面应用]
标头
Commctrl.h
Unicode 和 ANSI 名称
 LVM_INSERTITEMW (Unicode) 和 LVM_INSERTITEMA (ANSI)