TVITEMEXW 結構 (commctrl.h)

發行項
03/13/2024

指定或接收樹檢視項目的屬性。這個結構是 TVITEM 結構的增強功能。新的應用程式應適當地使用此結構。

語法

typedef struct tagTVITEMEXW {
  UINT      mask;
  HTREEITEM hItem;
  UINT      state;
  UINT      stateMask;
  LPWSTR    pszText;
  int       cchTextMax;
  int       iImage;
  int       iSelectedImage;
  int       cChildren;
  LPARAM    lParam;
  int       iIntegral;
  UINT      uStateEx;
  HWND      hwnd;
  int       iExpandedImage;
  int       iReserved;
} TVITEMEXW, *LPTVITEMEXW;

成員

mask

類型： UINT

旗標的陣列，指出其他結構成員包含有效的數據。當這個結構與 TVM_GETITEM 訊息搭配使用時，遮罩成員會指出要擷取的項目屬性。如果與 TVM_SETITEM 訊息搭配使用，遮罩會指出要設定的屬性。這個成員可以是下列一或多個值：

值	意義
TVIF_CHILDREN	cChildren 成員有效。
TVIF_DI_SETITEM	樹視圖控件會保留所提供的資訊，且不會再次要求。只有在處理 TVN_GETDISPINFO 通知時，此旗標才有效。
TVIF_EXPANDEDIMAGE	6.00 版和 Windows Vista。iExpandedImage 成員有效。
TVIF_HANDLE	hItem 成員有效。
TVIF_IMAGE	iImage成員有效。
TVIF_INTEGRAL	iIntegral 成員有效。
TVIF_PARAM	lParam成員有效。
TVIF_SELECTEDIMAGE	iSelectedImage 成員有效。
TVIF_STATE	狀態和 stateMask 成員有效。
TVIF_STATEEX	6.00 版和 Windows Vista。uStateEx 成員有效。
TVIF_TEXT	pszText 和 cchTextMax 成員有效。

hItem

類型： HTREEITEM

專案的句柄。

state

類型： UINT

指出項目狀態的位旗標和影像清單索引集。設定項目的狀態時， stateMask 成員會指出這個成員的有效位。擷取項目的狀態時，此成員會傳回 stateMask 成員中所指出位的目前狀態。如需有關此成員的詳細資訊，請參閱一節。

此成員的位 0 到 7 包含項目狀態旗標。如需可能項目狀態旗標的清單，請參閱樹檢視控件項目狀態。

此成員的位 8 到 11 指定單一重疊影像索引。重疊影像會覆疊在項目的圖示影像上。如果這些位為零，則項目沒有重疊影像。若要隔離這些位，請使用 TVIS_OVERLAYMASK 遮罩。若要在此成員中設定重疊影像索引，請使用 INDEXTOOVERLAYMASK 宏。影像清單的重疊影像是使用 ImageList_SetOverlayImage 函式來設定。

狀態影像會顯示在專案的圖示旁邊，以指出應用程式定義的狀態。傳送 TVM_SETIMAGELIST 訊息來指定狀態映像清單。若要設定專案的狀態影像，請在TVITEM結構的 stateMask 成員中包含TVIS_STATEIMAGEMASK值。結構狀態成員的位 12 到 15 會指定要繪製之影像的狀態影像清單中索引。

若要設定狀態影像索引，請使用 INDEXTOSTATEIMAGEMASK。此宏會採用索引，並適當地設定位 12 到 15。若要指出項目沒有狀態影像，請將索引設定為零。此慣例表示狀態映像清單中的影像零不能當做狀態影像使用。若要隔離狀態成員的位 12 到 15，請使用 TVIS_STATEIMAGEMASK 遮罩。

stateMask

類型： UINT

有效狀態成員的位。如果您要擷取項目的狀態，請設定 stateMask 成員的位，以指出 狀態成員中 要傳回的位。如果您要設定項目的狀態，請設定 stateMask 成員的位，以指出您要設定 的狀態 成員位。若要設定或擷取專案的重疊影像索引，請設定 TVIS_OVERLAYMASK 位。若要設定或擷取項目的狀態影像索引，請設定 TVIS_STATEIMAGEMASK 位。

pszText

類型： LPTSTR

如果結構指定專案屬性，則為包含專案文字之 Null 終止字串的指標。如果這個成員是LPSTR_TEXTCALLBACK值，父視窗會負責儲存名稱。在此情況下，樹視圖控件會在專案文字變更時，將父視窗傳送 TVN_GETDISPINFO 通知程序代碼，以便顯示、排序或編輯，以及 TVN_SETDISPINFO 通知程式代碼。如果結構正在接收專案屬性，這個成員就是接收專案文字的緩衝區位址。請注意，雖然樹視圖控件允許任何長度字串儲存為項目文字，但只會顯示前 260 個字元。

cchTextMax

類型： int

pszText 成員所指向的緩衝區大小，以字元為單位。如果使用這個結構來設定項目屬性，則會忽略這個成員。

iImage

類型： int

當項目處於非選取狀態時，樹視圖控件的圖示影像影像清單中的索引。如果這個成員是I_IMAGECALLBACK值，父視窗會負責儲存索引。在此情況下，樹視圖控件會傳送父系 TVN_GETDISPINFO 通知程序代碼，以在需要顯示影像時擷取索引。

iSelectedImage

類型： int

樹檢視控件影像清單中的索引，表示專案處於選取狀態時所要使用的圖示影像清單。如果這個成員是I_IMAGECALLBACK值，父視窗會負責儲存索引。在此情況下，樹視圖控件會傳送父系 TVN_GETDISPINFO 通知程序代碼，以在需要顯示影像時擷取索引。

cChildren

類型： int

旗標，指出專案是否有相關聯的子專案。這個成員可以是下列其中一個值：

值	意義
零	項目沒有子專案。
一個	專案有一或多個子專案。
I_CHILDRENCALLBACK	父視窗會持續追蹤專案是否有子專案。在此情況下，當樹視圖控件需要顯示專案時，控件會將 TVN_GETDISPINFO 通知程式代碼傳送給父代，以判斷專案是否有子專案。如果樹檢視控件具有 TVS_HASBUTTONS 樣式，它會使用此成員來判斷是否要顯示指出子專案的按鈕。您可以使用這個成員來強制控件顯示按鈕，即使項目沒有插入任何子專案也一樣。這可讓您顯示按鈕，同時將控件的記憶體使用量降至最低，方法是只在專案可見或展開時插入子專案。
I_CHILDRENAUTO	6.0 版適用於內部使用;不建議在應用程式中使用。樹視圖控件會自動判斷專案是否有子專案。注意未來版本的 Comctl32.dll 可能不支援此旗標。此外，commctrl.h 中未定義此旗標。將下列定義新增至應用程式的來源檔案，以使用旗標： `#define I_CHILDRENAUTO (-2)`

lParam

類型： LPARAM

要與專案相關聯的值。

iIntegral

類型： int

專案的高度，以標準專案高度的倍數表示， (請參閱 TVM_SETITEMHEIGHT) 。例如，將此成員設定為 2 會提供專案兩倍的標準高度。樹視圖控件不會在出現在項目內容下方的額外區域中繪製，但應用程式可以在使用自定義繪製時使用此空間進行繪圖。不使用自定義繪製的應用程式應該將此值設定為 1，否則行為是未定義的。

uStateEx

類型： UINT

Internet Explorer 6 和更新版本。一或多個 (為下列擴充狀態的位元組合) 。

值	意義
TVIS_EX_DISABLED	Windows Vista 和更新版本。建立以灰色繪製的控件，用戶無法與其互動。
TVIS_EX_FLAT	建立一般專案—專案為虛擬專案，且在樹狀結構中看不到;相反地，其子系會放在樹狀結構階層中。只有在將專案新增至樹視圖控件時，此狀態才有效。
TVIS_EX_HWND	為專案建立個別的 HWND。只有在將專案新增至樹視圖控件時，此狀態才有效。

hwnd

類型： HWND

Internet Explorer 6 和更新版本。未使用;必須是 NULL。

iExpandedImage

類型： int

Internet Explorer 6 和更新版本。控件影像清單中的影像索引，當專案處於展開狀態時顯示。

iReserved

類型： int

保留的成員。請勿使用。

備註

注意

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

規格需求

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

另請參閱

新增 Tree-View 專案

共用方式為

TVITEMEXW 結構 (commctrl.h)

語法

成員

備註

規格需求

另請參閱

意見反應

其他資源