LVITEMA 結構 （commctrl.h）

指定或接收清單檢視項目的屬性。 此結構已更新為支援可啟用項目縮排的新遮罩值 （LVIF_INDENT）。 這個結構會取代 LV_ITEM 結構。

語法

typedef struct tagLVITEMA {
  UINT   mask;
  int    iItem;
  int    iSubItem;
  UINT   state;
  UINT   stateMask;
  LPSTR  pszText;
  int    cchTextMax;
  int    iImage;
  LPARAM lParam;
  int    iIndent;
  int    iGroupId;
  UINT   cColumns;
  PUINT  puColumns;
  int    *piColFmt;
  int    iGroup;
} LVITEMA, *LPLVITEMA;

成員

mask

類型：UINT

一組旗標，指定要設定的這個結構成員包含要設定的數據，或要求哪些成員。 此成員可以設定下列一或多個旗標：

價值	意義
LVIF_COLFMT	Windows Vista 和更新版本。 piColFmt 成員有效或必須設定。 如果使用這個旗標，cColumns 成員有效或必須設定。
LVIF_COLUMNS	cColumns 成員有效或必須設定。
LVIF_DI_SETITEM	操作系統應該儲存所要求的清單項目資訊，而不會再次要求它。 此旗標只會與 LVN_GETDISPINFO 通知程式代碼搭配使用。
LVIF_GROUPID	iGroupId 成員有效或必須設定。 如果在傳送 LVM_INSERTITEM 訊息時未設定此旗標 ，則會假設 iGroupId 的值I_GROUPIDCALLBACK。
LVIF_IMAGE	iImage 成員有效或必須設定。
LVIF_INDENT	iIndent 成員有效或必須設定。
LVIF_NORECOMPUTE	如果控件收到 LVM_GETITEM 訊息，則不會產生 LVN_GETDISPINFO 來擷取文字資訊。 相反地，pszText 成員 會包含LPSTR_TEXTCALLBACK。
LVIF_PARAM	lParam 成員有效或必須設定。
LVIF_STATE	狀態 成員有效或必須設定。
LVIF_TEXT	pszText 成員有效或必須設定。

iItem

類型：int

這個結構所參考之專案之以零起始的索引。

iSubItem

類型：int

這個結構所參考之子專案的一個基底索引，如果這個結構參考專案而非子專案，則為零。

state

類型：UINT

指出專案的狀態、狀態影像和重疊影像。 stateMask 成員表示這個成員的有效位。

此成員的位 0 到 7 包含項目狀態旗標。 這可以是一或多個 項目狀態 值。

此成員的位 8 到 11 指定一個架構的重疊影像索引。 完整大小的圖示影像清單和小型圖示影像清單都可以有重疊影像。 重疊影像會加疊在項目的圖示影像上。 如果這些位為零，則項目沒有重疊影像。 若要隔離這些位，請使用 LVIS_OVERLAYMASK 遮罩。 若要在此成員中設定重疊影像索引，您應該使用 INDEXTOOVERLAYMASK 巨集。 影像清單的重疊影像會使用 ImageList_SetOverlayImage 函式來設定。

此成員的位 12 到 15 指定狀態映像索引。 狀態影像會顯示在項目圖示旁，以指出應用程式定義的狀態。 如果這些位為零，則項目沒有狀態影像。 若要隔離這些位，請使用 LVIS_STATEIMAGEMASK 遮罩。 若要設定狀態影像索引，請使用 INDEXTOSTATEIMAGEMASK 巨集。 狀態影像索引會指定應該繪製的狀態影像清單中的影像索引。 狀態映像清單是使用 LVM_SETIMAGELIST 訊息來指定。

stateMask

類型：UINT

值，指定要擷取或修改成員 狀態 位。 例如，將此成員設定為 LVIS_SELECTED 只會擷取項目的選取狀態。

這個成員可讓您修改一或多個項目狀態，而不需要先擷取所有項目狀態。 例如，將此成員設定為 LVIS_SELECTED，並將 狀態 為零會導致專案選取狀態被清除，但不會影響其他狀態。

若要擷取或修改所有狀態，請將這個成員設定為 （UINT）-1。

您可以使用巨集 ListView_SetItemState 來設定和清除位。

pszText

類型：LPTSTR

如果 結構指定專案屬性，pszText 是包含專案文字之 Null 終止字串的指標。 回應 LVN_GETDISPINFO 通知時，請確定此指標會維持有效狀態，直到收到下一個通知之後。

如果結構收到專案屬性，pszText 是接收專案文字之緩衝區的指標。 請注意，雖然清單檢視控件允許將任何長度字串儲存為項目文字，但只會顯示前 259 TCHAR。

如果 pszText 的值是LPSTR_TEXTCALLBACK，則專案是 回呼專案。 如果回呼文字變更，您必須明確地將 pszText 設定為LPSTR_TEXTCALLBACK，並藉由傳送 LVM_SETITEM 或 LVM_SETITEMTEXT 訊息來通知清單檢視控件變更。

如果清單檢視控件具有 LVS_SORTASCENDING 或 LVS_SORTDESCENDING 樣式，請勿將 pszText 設定為LPSTR_TEXTCALLBACK。

cchTextMax

類型：int

pszText所指向之緩衝區中的 TCHAR 數目，包括終止 NULL。

只有當結構收到項目屬性時，才會使用這個成員。 當結構指定項目屬性時，會忽略它。 例如，cchTextMax 會在 LVM_SETITEM 和 LVM_INSERTITEM期間忽略。 在 LVN_GETDISPINFO 和其他LVN_通知期間，它是唯讀的。

Note 絕不會複製超過 cchTextMaxTCHARs，其中 cch LVN_ TextMax 包含終止 NULL，否則您的程式可能會失敗。

 

iImage

類型：int

控件影像清單中的項目圖示索引。 這同時適用於大型和小型映像清單。 如果這個成員是I_IMAGECALLBACK值，父視窗會負責儲存索引。 在此情況下，清單檢視控件會傳送父系 LVN_GETDISPINFO 通知程式代碼，以在需要顯示影像時擷取索引。

lParam

類型：LPARAM

專案特定的值。 如果您使用 LVM_SORTITEMS 訊息，清單檢視控件會將此值傳遞至應用程式定義的比較函式。 您也可以使用 LVM_FINDITEM 訊息來搜尋具有指定 lParam 值之專案的清單檢視控件。

iIndent

類型：int

4.70 版。 要縮排專案的影像寬度數目。 單一縮排等於專案影像的寬度。 因此，值 1 會依一個影像的寬度將項目縮排、值 2 縮排為兩個影像等等。 請注意，只有專案才支援此欄位。 嘗試設定子項目縮排會導致呼叫函式失敗。

iGroupId

類型：int

6.0 版 項目所屬群組的標識碼，或下列其中一個值。

價值	意義
I_GROUPIDCALLBACK	listview 控件會將 LVN_GETDISPINFO 通知程式代碼傳送給父代，以擷取群組的索引。
I_GROUPIDNONE	項目不屬於群組。

cColumns

類型：UINT

版本 6.0 磚檢視中顯示此項目的數據行數目（子專案）。 最大值為 20。 如果這個值是I_COLUMNSCALLBACK，數據行數組的大小和陣列本身（puColumns）是藉由傳送 LVN_GETDISPINFO 通知來取得。

puColumns

類型：PUINT

6.0 版 資料行索引陣列的指標、指定此項目顯示的數據行，以及這些數據行的順序。

piColFmt

類型：int*

Windows Vista： 未實作。 Windows 7 和更新版本： 下列旗標數位的指標（單獨或組合），指定擴充磚檢視中每個子專案的格式。

價值	意義
LVCFMT_LINE_BREAK	強制數據行換行至下一個數據行清單的頂端。
LVCFMT_FILL	填滿磚區域的其餘部分。 可能有標題。
LVCFMT_WRAP	允許數據行在其數據列清單中的剩餘空間內換行。
LVCFMT_NO_TITLE	從子專案中移除標題。
LVCFMT_TILE_PLACEMENTMASK	相當於LVCFMT_LINE_BREAK和LVCFMT_FILL的組合。

iGroup

類型：int

Windows Vista：專案的群組索引。 僅適用於擁有者數據/回呼（多個群組中的單一專案）。

言論

LVITEM 結構會與數個訊息搭配使用，包括 LVM_GETITEM、LVM_SETITEM、LVM_INSERTITEM和 LVM_DELETEITEM。

在圖格檢視中，專案名稱會顯示在圖示右側。 您可以指定其他子項目（對應至詳細數據檢視中的資料行），以顯示在專案名稱下方的行上。 puColumns 數位包含要顯示的子專案的索引。 索引應該大於 0，因為項目名稱子專案 0 已經顯示。 修改清單專案時，也可以在 LVTILEINFO 結構中設定數據行資訊。

如需範例程式代碼，請參閱使用 List-View Controls。

注意 Comctl32.dll 第 6 版不可轉散發，但它包含在 Windows 或更新版本中。 若要使用第 6 版 Comctl32.dll，請在指令清單中指定它。 如需指令清單的詳細資訊，請參閱 啟用可視化樣式。

 

注意

commctrl.h 標頭會將 LVITEM 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的 慣例。

要求

要求	價值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
標頭	commctrl.h