CListCtrl::InsertItem

[アーティクル]
08/09/2011

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

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