Edit

Share via

ListView_InsertItem macro (commctrl.h)

  • Article

Inserts a new item in a list-view control. You can use this macro or send the LVM_INSERTITEM message explicitly.

Syntax

int ListView_InsertItem(
         HWND     hwnd,
   const LPLVITEM pitem
);

Parameters

hwnd

Type: HWND

A handle to the list-view control.

pitem

Type: const LPLVITEM

A pointer to an LVITEM structure that specifies the attributes of the list-view item. Use the iItem member to specify the zero-based index at which the new item should be inserted. If this value is greater than the number of items currently contained by the listview control, the new item will be appended to the end of the list and assigned the correct index. Examine the macro's return value to determine the actual index assigned to the item.

Return value

Type: int

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

Remarks

You cannot use ListView_InsertItem or LVM_INSERTITEM to insert subitems. The iSubItem member of the LVITEM structure must be zero. See LVM_SETITEM for information on setting subitems.

If a list-view control has the LVS_EX_CHECKBOXES style set, any value placed in bits 12 through 15 of the state member of the LVITEM structure will be ignored. When an item is added with this style set, it will always be set to the unchecked state.

If a list-view control has either the LVS_SORTASCENDING or LVS_SORTDESCENDING window style, an LVM_INSERTITEM message will fail if you try to insert an item that has LPSTR_TEXTCALLBACK as the pszText member of its LVITEM structure.

The ListView_InsertItem macro will insert the new item in the proper position in the sort order if the following conditions hold:

  • You are using one of the LVS_SORTXXX styles.
  • You are not using the LVS_OWNERDRAW style.
  • The pszText member of the structure pointed to by pitem is not set to LPSTR_TEXTCALLBACK.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header commctrl.h