This documentation is archived and is not being maintained.


Inserts an item into the list view control.

int InsertItem(
   const LVITEM* pItem 
int InsertItem(
   int nItem,
   LPCTSTR lpszItem 
int InsertItem(
   int nItem,
   LPCTSTR lpszItem,
   int nImage 
int InsertItem(
   UINT nMask,
   int nItem,
   LPCTSTR lpszItem,
   UINT nState,
   UINT nStateMask,
   int nImage,
   LPARAM lParam


Pointer to an LVITEM structure that specifies the item's attributes, as described in the Windows SDK.


Index of the item to be inserted.


Address of a string containing the item's label, or LPSTR_TEXTCALLBACK if the item is a callback item. For information on callback items, see CListCtrl::GetCallbackMask.


Index of the item's image, or I_IMAGECALLBACK if the item is a callback item. For information on callback items, see CListCtrl::GetCallbackMask.


The nMask parameter specifies which item attributes passed as parameters are valid. It can be one or more of the mask values described in LVITEM Structure in the Windows SDK. The valid values can be combined with the bitwise OR operator.


Indicates the item's state, state image, and overlay image. See the Windows SDK topics LVITEM Structure for more information and List-View Item States for a list of valid flags.


Indicates which bits of the state member will be retrieved or modified. See LVITEM Structure in the Windows SDK for more information.


A 32-bit application-specific value associated with the item. If this parameter is specified, you must set the nMask attribute LVIF_PARAM.

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

Calling this method may cause the LVM_INSERTITEM message to be sent to your control window. The associated message handler for the control may fail to set the item text under certain conditions (such as using window styles such as LVS_OWNERDRAW). For more information on these conditions, refer to LVM_INSERTITEM in the Windows SDK.

		CString strText;
		int nColumnCount = m_myListCtrl.GetHeaderCtrl()->GetItemCount();

		// Insert 10 items in the list view control. 
		for (int i = 0; i < 10; i++)
			strText.Format(TEXT("item %d"), i);

			// Insert the item, select every other item.
			m_myListCtrl.InsertItem(LVIF_TEXT | LVIF_STATE, i, strText, 
				(i % 2) == 0 ? LVIS_SELECTED : 0, LVIS_SELECTED, 0, 0);

			// Initialize the text of the subitems. 
			for (int j = 1; j < nColumnCount; j++)
				strText.Format(TEXT("sub-item %d %d"), i, j);
				m_myListCtrl.SetItemText(i, j, strText);

Header: afxcmn.h