LVM_INSERTITEM message

Inserts a new item in a list-view control. You can send this message explicitly or by using the ListView_InsertItem macro.

Parameters

wParam

Must be zero.

lParam

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, the new item will be appended to the end of the list and assigned the correct index. Examine the message's return value to determine the actual index assigned to the item.

Return value

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 value for its pszText member.

The LVM_INSERTITEM message 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.

If the LVITEM structure does not contain LVIF_GROUPID in the mask member, the value of the iGroupId member is I_GROUPIDCALLBACK by default.

Requirements