ListView_InsertItem巨集 （commctrl.h）

在清單檢視控件中插入新專案。 您可以使用此巨集或明確傳送 LVM_INSERTITEM 訊息。

語法

int ListView_InsertItem(
         HWND     hwnd,
   const LPLVITEM pitem
);

參數

hwnd

類型：HWND

清單檢視控件的句柄。

pitem

類型：const LPLVITEM

LVITEM 結構的指標，指定清單檢視項目的屬性。 使用 iItem 成員來指定應該插入新專案之以零起始的索引。 如果此值大於 listview 控件目前所包含的項目數目，新專案將會附加至清單結尾，並指派正確的索引。 檢查巨集的傳回值，以判斷指派給專案的實際索引。

傳回值

類型：int

如果成功，則傳回新專案的索引，否則會傳回 -1。

言論

您無法使用 ListView_InsertItem 或 LVM_INSERTITEM 來插入子專案。 iSubItemLVITEM 結構的成員必須是零。 如需設定子項目的相關信息，請參閱 LVM_SETITEM。

如果清單檢視控件已設定 LVS_EX_CHECKBOXES 樣式，則會忽略置於 LVITEM 結構之 狀態 位 12 到 15 位的任何值。 新增此樣式集的專案時，一律會設定為未核取的狀態。

如果清單檢視控件具有 LVS_SORTASCENDING 或 LVS_SORTDESCENDING 視窗樣式，如果您嘗試插入LPSTR_TEXTCALLBACK做為其 LVITEM 結構成員的 pszText 成員的專案，LVM_INSERTITEM 訊息將會失敗。

如果下列條件保留，則 ListView_InsertItem 巨集會在排序順序中將新專案插入適當的位置：

• 您使用其中一個LVS_SORTXXX樣式。
• 您不是使用LVS_OWNERDRAW樣式。
• pszText 結構 pitem 所指向的成員未設定為LPSTR_TEXTCALLBACK。

要求