共用方式為

LVITEMW 結構 (commctrl.h)

  • 發行項

指定或接收清單檢視專案的屬性。 此結構已更新，以支援啟用專案縮排的新遮罩值 (LVIF_INDENT) 。 這個結構會取代 LV_ITEM 結構。

語法

typedef struct tagLVITEMW {
  UINT   mask;
  int    iItem;
  int    iSubItem;
  UINT   state;
  UINT   stateMask;
  LPWSTR pszText;
  int    cchTextMax;
  int    iImage;
  LPARAM lParam;
  int    iIndent;
  int    iGroupId;
  UINT   cColumns;
  PUINT  puColumns;
  int    *piColFmt;
  int    iGroup;
} LVITEMW, *LPLVITEMW;

成員

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 是接收專案文字之緩衝區的指標。 請注意，雖然清單檢視控制項允許任何長度字串儲存為專案文字，但只會顯示前 260 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_通知期間，它是唯讀的。

注意請勿在LVN_通知期間，將cchTextMax包含終止Null的cchTextTCHAR複製到pszText，否則您的程式可能會失敗。
 

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，則會透過傳送LVN_GETDISPINFO通知來取得資料行陣列的大小和陣列本身 (puColumns) 。

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 控制項。

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

注意

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

規格需求

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