CListCtrl::InsertItem

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

リストビューコントロールにアイテムを挿入します。

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
);

パラメータ

pItem
Windows SDK に記述されているように、アイテムの属性を指定する LVITEM 構造体へのポインタ。
nItem
挿入するアイテムのインデックス
lpszItem
アイテムのラベルを持つ文字列のアドレス。または、アイテムがコールバックアイテムのときは LPSTR_TEXTCALLBACK。コールバックアイテムの詳細については、「CListCtrl::GetCallbackMask」を参照してください。
nImage
アイテムのイメージのインデックス。または、アイテムがコールバックアイテムのときは I_IMAGECALLBACK。コールバックアイテムの詳細については、「CListCtrl::GetCallbackMask」を参照してください。
nMask
nMask パラメータは、パラメータとして渡される項目属性で有効なものを指定します。これは、Windows SDK の「LVITEM Structure」で説明されている 1 つ以上のマスク値にすることができます。有効な値は、ビットごとの OR 演算子を使って組み合わせることができます。
nState
項目の状態、状態イメージ、およびオーバーレイイメージを示します。詳細については Windows SDK のトピック「LVITEM Structure」を、有効なフラグの一覧については同じく「List-View Item States」を参照してください。
nStateMask
state メンバの取得または変更されるビットを示します。詳細については、Windows SDK の「LVITEM Structure」を参照してください。
lParam
アイテムに関連付けられた 32 ビットアプリケーション固有の値。このパラメータが指定されている場合は、nMask 属性を LVIF_PARAM に設定する必要があります。

戻り値

正常終了した場合は新しいアイテムのインデックスを返します。それ以外の場合は -1 を返します。

解説

このメソッドを呼び出すと LVM_INSERTITEM メッセージがコントロールウィンドウに送信されます。コントロールに関連付けられたメッセージハンドラは、特定の条件下 (LVS_OWNERDRAW などのウィンドウスタイルを使用している場合など) ではアイテムのテキストの設定に失敗することがあります。これらの条件の詳細については、Windows SDK の「LVM_INSERTITEM」を参照してください。

使用例

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);
   }
}