`CTreeCtrl` 類別

發行項
10/12/2023

提供 Windows 通用樹狀檢閱控制項的功能。

語法

class CTreeCtrl : public CWnd

成員

公用建構函式

名稱	描述
`CTreeCtrl::CTreeCtrl`	建構 `CTreeCtrl` 物件。

公用方法

名稱	描述
`CTreeCtrl::Create`	建立樹狀檢視控制項，並將它附加至 `CTreeCtrl` 物件。
`CTreeCtrl::CreateDragImage`	為指定的樹狀檢視專案建立拖曳點陣圖。
`CTreeCtrl::CreateEx`	使用指定的 Windows 擴充樣式建立樹狀結構控制項，並將它附加至 `CTreeCtrl` 物件。
`CTreeCtrl::DeleteAllItems`	刪除樹狀檢視控制項中的所有專案。
`CTreeCtrl::DeleteItem`	刪除樹狀檢視控制項中的新專案。
`CTreeCtrl::EditLabel`	就地編輯指定的樹狀檢視專案。
`CTreeCtrl::EndEditLabelNow`	取消目前樹狀檢視控制項中樹狀檢視專案標籤上的編輯作業。
`CTreeCtrl::EnsureVisible`	確保樹狀檢視專案在其樹狀檢視控制項中可見。
`CTreeCtrl::Expand`	展開或折迭指定樹狀檢視專案的子專案。
`CTreeCtrl::GetBkColor`	擷取控制項的目前背景色彩。
`CTreeCtrl::GetCheck`	擷取樹狀目錄控制項專案的檢查狀態。
`CTreeCtrl::GetChildItem`	擷取指定樹狀檢視專案的子系。
`CTreeCtrl::GetCount`	擷取與樹狀檢視控制項相關聯的樹狀專案數目。
`CTreeCtrl::GetDropHilightItem`	擷取拖放作業的目標。
`CTreeCtrl::GetEditControl`	擷取用來編輯指定樹狀檢視專案的編輯控制項控制碼。
`CTreeCtrl::GetExtendedStyle`	擷取目前樹狀檢視控制項所使用的擴充樣式。
`CTreeCtrl::GetFirstVisibleItem`	擷取指定樹狀檢視專案的第一個可見專案。
`CTreeCtrl::GetImageList`	擷取與樹狀檢視控制項相關聯的影像清單控制碼。
`CTreeCtrl::GetIndent`	從其父系擷取樹狀檢視專案的位移（以圖元為單位）。
`CTreeCtrl::GetInsertMarkColor`	擷取用來繪製樹狀檢視插入標記的色彩。
`CTreeCtrl::GetItem`	擷取指定之樹狀檢視專案的屬性。
`CTreeCtrl::GetItemData`	傳回與專案相關聯的應用程式特定值。
`CTreeCtrl::GetItemExpandedImageIndex`	擷取當目前樹狀檢視控制項的指定專案處於展開狀態時，要顯示的影像索引。
`CTreeCtrl::GetItemHeight`	擷取樹狀檢視專案的目前高度。
`CTreeCtrl::GetItemImage`	擷取與專案相關聯的影像。
`CTreeCtrl::GetItemPartRect`	擷取目前樹狀檢視控制項中指定專案之指定部分的周框。
`CTreeCtrl::GetItemRect`	擷取樹狀檢視專案的周框。
`CTreeCtrl::GetItemState`	傳回專案的狀態。
`CTreeCtrl::GetItemStateEx`	擷取目前樹狀檢視控制項中指定專案的擴充狀態。
`CTreeCtrl::GetItemText`	傳回專案的文字。
`CTreeCtrl::GetLastVisibleItem`	擷取目前樹狀檢視控制項中最後一個展開的專案。
`CTreeCtrl::GetLineColor`	擷取樹狀檢視控制項目前的線條色彩。
`CTreeCtrl::GetNextItem`	擷取符合指定關聯性的下一個樹狀檢視專案。
`CTreeCtrl::GetNextSiblingItem`	擷取指定樹狀檢視專案的下一個同層級。
`CTreeCtrl::GetNextVisibleItem`	擷取指定樹狀檢視專案的下一個可見專案。
`CTreeCtrl::GetParentItem`	擷取指定之樹狀檢視專案的父代。
`CTreeCtrl::GetPrevSiblingItem`	擷取指定之樹狀檢視專案的上一個同層級。
`CTreeCtrl::GetPrevVisibleItem`	擷取指定之樹狀檢視專案的上一個可見專案。
`CTreeCtrl::GetRootItem`	擷取指定樹狀檢視專案的根目錄。
`CTreeCtrl::GetScrollTime`	擷取樹狀檢視控制項的最大捲動時間。
`CTreeCtrl::GetSelectedCount`	擷取目前樹狀檢視控制項中選取的專案數目。
`CTreeCtrl::GetSelectedItem`	擷取目前選取的樹狀檢視專案。
`CTreeCtrl::GetTextColor`	擷取控制項的目前文字色彩。
`CTreeCtrl::GetToolTips`	擷取樹狀檢視控制項所使用的子 `ToolTip` 控制項控制碼。
`CTreeCtrl::GetVisibleCount`	擷取與樹狀檢視控制項相關聯的可見樹項數目。
`CTreeCtrl::HitTest`	傳回與物件相關的 `CTreeCtrl` 資料指標目前位置。
`CTreeCtrl::InsertItem`	在樹狀檢視控制項中插入新專案。
`CTreeCtrl::ItemHasChildren`	如果指定的專案具有子專案，則傳回非零。
`CTreeCtrl::MapAccIdToItem`	地圖目前樹狀檢視控制項中樹狀檢視專案的控制碼的指定協助工具識別碼。
`CTreeCtrl::MapItemToAccID`	地圖目前樹狀檢視控制項中樹狀檢視專案的指定控制碼，指向協助工具識別碼。
`CTreeCtrl::Select`	選取、捲動至檢視，或重新繪製指定的樹狀檢視專案。
`CTreeCtrl::SelectDropTarget`	將樹狀結構專案重新繪製為拖放作業的目標。
`CTreeCtrl::SelectItem`	選取指定的樹狀檢視專案。
`CTreeCtrl::SelectSetFirstVisible`	選取指定的樹狀檢視專案做為第一個可見專案。
`CTreeCtrl::SetAutoscrollInfo`	設定目前樹狀檢視控制項的自動標籤速率。
`CTreeCtrl::SetBkColor`	設定控制項的背景色彩。
`CTreeCtrl::SetCheck`	設定樹狀目錄控制項專案的檢查狀態。
`CTreeCtrl::SetExtendedStyle`	設定目前樹狀檢視控制項的延伸樣式。
`CTreeCtrl::SetImageList`	設定與樹狀檢視控制項相關聯的影像清單控制碼。
`CTreeCtrl::SetIndent`	從其父系設定樹狀檢視專案的位移（以圖元為單位）。
`CTreeCtrl::SetInsertMark`	設定樹狀檢視控制項中的插入標記。
`CTreeCtrl::SetInsertMarkColor`	設定用來繪製樹狀檢視插入標記的色彩。
`CTreeCtrl::SetItem`	設定指定之樹狀檢視專案的屬性。
`CTreeCtrl::SetItemData`	設定與專案相關聯的應用程式特定值。
`CTreeCtrl::SetItemExpandedImageIndex`	設定當目前樹狀檢視控制項的指定專案處於展開狀態時，要顯示的影像索引。
`CTreeCtrl::SetItemHeight`	設定樹狀檢視專案的高度。
`CTreeCtrl::SetItemImage`	將影像與專案產生關聯。
`CTreeCtrl::SetItemState`	設定專案的狀態。
`CTreeCtrl::SetItemStateEx`	設定目前樹狀檢視控制項中指定專案的擴充狀態。
`CTreeCtrl::SetItemText`	設定專案的文字。
`CTreeCtrl::SetLineColor`	設定樹狀檢視控制項目前的線條色彩。
`CTreeCtrl::SetScrollTime`	設定樹狀檢視控制項的最大捲動時間。
`CTreeCtrl::SetTextColor`	設定控制項的文字色彩。
`CTreeCtrl::SetToolTips`	設定樹狀檢視控制項的子 `ToolTip` 控制項。
`CTreeCtrl::ShowInfoTip`	顯示目前樹狀檢視控制項中指定專案的資訊提示。
`CTreeCtrl::SortChildren`	排序指定父專案的子系。
`CTreeCtrl::SortChildrenCB`	使用應用程式定義的排序函式，排序指定父專案的子系。

備註

「樹狀檢視控制項」是一個視窗，會顯示階層式專案清單，例如檔中的標題、索引中的專案，或磁片上的檔案和目錄。每個項目都包含標籤和選擇性點陣圖影像，因此，每個項目都可以擁有與自己相關的子項目清單。使用者可以按一下項目以展開和摺疊子項目的關聯清單。

此控制項（因此類別 CTreeCtrl ）僅適用于在 Windows 98 和 Windows NT 第 4 版和更新版本下執行的程式。

如需使用 CTreeCtrl 的詳細資訊，請參閱：

繼承階層架構

CObject

CCmdTarget

CWnd

CTreeCtrl

需求

標頭：afxcmn.h

`CTreeCtrl::Create`

如果您在對話方塊範本中指定樹狀控制項，或者如果您使用 CTreeView ，則會在建立對話方塊或檢視時自動建立樹狀目錄控制項。

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

參數

dwStyle
指定樹狀檢視控制項的樣式。套用視窗樣式，如 CreateWindow Windows SDK 中所述，以及樹狀檢視控制項樣式的任何組合。

rect
指定樹狀檢視控制項的大小和位置。它可以是 CRect 物件或 RECT 結構。

pParentWnd
指定樹狀檢視控制項的父視窗，通常是 CDialog 。它不得為 NULL 。

nID
指定樹狀檢視控制項的識別碼。

傳回值

如果初始化成功，則為非零;否則為 0。

備註

如果您想要將樹狀控制項建立為其他視窗的子視窗，請使用 Create 成員函式。如果您使用建立樹狀目錄控制項 Create ，除了其他樹狀檢視樣式之外，還必須傳遞它 WS_VISIBLE 。

您會在兩個步驟中建構 CTreeCtrl 。首先呼叫建構函式，然後呼叫 Create ，這會建立樹狀檢視控制項，並將它附加至 CTreeCtrl 物件。

若要建立具有延伸視窗樣式的樹狀結構控制項，請呼叫 CreateEx 而不是 Create 。

範例

// Assuming your window has a CTreeCtrl member named m_TreeCtrl,
// you can create the tree control window with a child ID of ID_MYTREE
// using a call like this:

m_TreeCtrl.Create(WS_VISIBLE | WS_TABSTOP | WS_CHILD | WS_BORDER |
                      TVS_HASBUTTONS | TVS_LINESATROOT | TVS_HASLINES |
                      TVS_DISABLEDRAGDROP | TVS_NOTOOLTIPS | TVS_EDITLABELS,
                  CRect(10, 10, 300, 100), this, ID_MYTREE);

// The control will have the appropriate window styles, and the tree
// control styles specified are those most commonly used.

`CTreeCtrl::CreateEx`

呼叫此函式來建立控制項（子視窗），並將它與 CTreeCtrl 物件產生關聯。

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

參數

dwExStyle
指定要建立之控制項的擴充樣式。如需擴充 Windows 樣式的清單，請參閱 dwExStyle Windows SDK 中的參數 CreateWindowEx 。

dwStyle
指定樹狀檢視控制項的樣式。套用視窗樣式，如 CreateWindow Windows SDK 中所述，以及樹狀檢視控制項樣式的任何組合。

rect
結構的參考 RECT ，描述要建立之視窗的大小和位置，在的用戶端座標中 pParentWnd 。

pParentWnd
控制項父系之視窗的指標。

nID
控制項的子視窗識別碼。

傳回值

如果成功則為非零，否則為 0。

備註

使用 CreateEx 而不是 Create 套用延伸的 Windows 樣式，由 Windows 擴充樣式前置詞 WS_EX_ 所指定。

`CTreeCtrl::CreateDragImage`

呼叫此函式，以在樹狀檢視控制項中建立指定專案的拖曳點陣圖、建立點陣圖的影像清單，並將點陣圖新增至影像清單。

CImageList* CreateDragImage(HTREEITEM hItem);

參數

hItem
要拖曳之樹狀專案的控制碼。

傳回值

如果成功，則為已加入拖曳點陣圖之影像清單的指標;否則 NULL 為。

備註

應用程式會使用影像清單函式，在拖曳專案時顯示影像。

物件 CImageList 是永久性的，而且您必須在完成時將其刪除。例如：

HTREEITEM hItem = m_TreeCtrl.GetSelectedItem();

CImageList *pImageList = m_TreeCtrl.CreateDragImage(hItem);

// Do something with the image list.

delete pImageList;

`CTreeCtrl::CTreeCtrl`

建構 CTreeCtrl 物件。

CTreeCtrl();

`CTreeCtrl::DeleteAllItems`

呼叫此函式以刪除樹狀檢視控制項中的所有專案。

BOOL DeleteAllItems();

傳回值

如果成功則為非零；否則為 0。

範例

// The underlying Windows API always returns TRUE
VERIFY(m_TreeCtrl.DeleteAllItems());

`CTreeCtrl::DeleteItem`

呼叫此函式以從樹狀檢視控制項中刪除專案。

BOOL DeleteItem(HTREEITEM hItem);

參數

hItem
要刪除之樹狀專案的控制碼。如果 hitem 具有 TVI_ROOT 值，則會從樹狀檢視控制項刪除所有專案。

傳回值

如果成功則為非零；否則為 0。

範例

// Look at all of the root-level items
HTREEITEM hCurrent = m_TreeCtrl.GetChildItem(TVI_ROOT);
while (hCurrent != NULL)
{
   // Get the text for the item. Notice we use TVIF_TEXT because
   // we want to retrieve only the text, but also specify TVIF_HANDLE
   // because we're getting the item by its handle.
   TVITEM item;
   TCHAR szText[1024];
   item.hItem = hCurrent;
   item.mask = TVIF_TEXT | TVIF_HANDLE;
   item.pszText = szText;
   item.cchTextMax = 1024;

   BOOL bWorked = m_TreeCtrl.GetItem(&item);

   // Try to get the next item
   hCurrent = m_TreeCtrl.GetNextItem(hCurrent, TVGN_NEXT);

   // If we successfuly retrieved an item, and the item's text
   // contains a lowercase letter 'e', delete the item.
   if (bWorked && _tcschr(item.pszText, 'e'))
      m_TreeCtrl.DeleteItem(item.hItem);
}

`CTreeCtrl::EditLabel`

呼叫此函式，開始就地編輯指定的專案文字。

CEdit* EditLabel(HTREEITEM hItem);

參數

hItem
要編輯之樹狀專案的控制碼。

傳回值

如果成功，則為用來編輯專案文字之物件的指標 CEdit ，否則 NULL 為。

備註

藉由將專案的文字取代為包含文字的單行編輯控制項，即可完成編輯。

範例

// Make sure the focus is set to the tree control.
m_TreeCtrl.SetFocus();

// Show the edit control on the label of the selected item.
// The tree control must have the TVS_EDITLABELS style set.
HTREEITEM hSel = m_TreeCtrl.GetSelectedItem();
CEdit *pmyEdit = m_TreeCtrl.EditLabel(hSel);
ASSERT(pmyEdit != NULL);

`CTreeCtrl::EndEditLabelNow`

結束目前樹狀檢視控制項中樹狀檢視專案的標籤上的編輯作業。

BOOL EndEditLabelNow(BOOL fCancelWithoutSave);

參數

fCancelWithoutSave
[in] TRUE 表示在結束編輯作業之前捨棄樹狀檢視專案的變更，或在 FALSE 結束作業之前儲存樹狀檢視專案的變更。

傳回值

TRUE 如果此方法成功，則為 ;否則為 FALSE 。

備註

這個方法會傳送 TVM_ENDEDITLABELNOW 訊息，如 Windows SDK 中所述。

`CTreeCtrl::EnsureVisible`

呼叫此函式，以確保樹狀檢視專案可見。

BOOL EnsureVisible(HTREEITEM hItem);

參數

hItem
要顯示之樹狀專案的控制碼。

傳回值

TRUE如果系統磁碟區動樹狀檢視控制項中的專案，以確保指定的專案可見，則傳回。否則，傳回值為 FALSE 。

備註

如有必要，函式會展開父專案或捲動樹狀檢視控制項，讓專案可見。

範例

HTREEITEM hItem = m_TreeCtrl.GetSelectedItem();
// hmyItem is the item that I want to ensure is visible.
HTREEITEM hmyItem = m_TreeCtrl.GetChildItem(hItem);

// Expand the parent, if possible.
HTREEITEM hParent = m_TreeCtrl.GetParentItem(hmyItem);
if (hParent != NULL)
   m_TreeCtrl.Expand(hParent, TVE_EXPAND);

// Ensure the item is visible.
m_TreeCtrl.EnsureVisible(hmyItem);

`CTreeCtrl::Expand`

呼叫此函式，以展開或折迭與指定父專案相關聯的子專案清單。

BOOL Expand(
    HTREEITEM hItem,
    UINT nCode);

參數

hItem
正在展開之樹狀專案的控制碼。

nCode
旗標，表示要採取的動作類型。此旗標可以有下列其中一個值：

TVE_COLLAPSE 折迭清單。
TVE_COLLAPSERESET 折迭清單並移除子專案。狀態 TVIS_EXPANDEDONCE 旗標已重設。此旗標必須與旗標搭配 TVE_COLLAPSE 使用。
TVE_EXPAND 展開清單。
TVE_TOGGLE 如果清單目前已展開，則折迭清單，如果清單目前已折迭，則會將其展開。

傳回值

如果成功則為非零；否則為 0。

範例

請參閱的 CTreeCtrl::EnsureVisible 範例。

`CTreeCtrl::GetBkColor`

此成員函式會實作 Win32 訊息 TVM_GETBKCOLOR 的行為，如 Windows SDK 中所述。

COLORREF GetBkColor() const;

傳回值

COLORREF值，表示控制項的目前視窗背景色彩。如果此值為 -1，控制項會使用系統視窗色彩。在此情況下，您可以使用 ::GetSysColor(COLOR_WINDOW) 來取得控制項所使用的目前系統色彩。

範例

請參閱的 CTreeCtrl::SetTextColor 範例。

`CTreeCtrl::GetCheck`

呼叫此成員函式以擷取專案的檢查狀態。

BOOL GetCheck(HTREEITEM hItem) const;

參數

hItem
HTREEITEM要接收狀態資訊的。

傳回值

如果已檢查樹狀結構控制項專案，則為非零;否則為 0。

範例

請參閱的 CTreeCtrl::SetCheck 範例。

`CTreeCtrl::GetChildItem`

呼叫此函式，以擷取樹狀檢視專案，該專案是所 hItem 指定專案的子系。

HTREEITEM GetChildItem(HTREEITEM hItem) const;

參數

hItem
樹狀專案的控制碼。

傳回值

如果成功，則為子專案的控制碼;否則 NULL 為。

範例

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Delete all of the children of hmyItem.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hNextItem;
   HTREEITEM hChildItem = m_TreeCtrl.GetChildItem(hmyItem);

   while (hChildItem != NULL)
   {
      hNextItem = m_TreeCtrl.GetNextItem(hChildItem, TVGN_NEXT);
      m_TreeCtrl.DeleteItem(hChildItem);
      hChildItem = hNextItem;
   }
}

`CTreeCtrl::GetCount`

呼叫此函式以擷取樹狀檢視控制項中的專案計數。

UINT GetCount() const;

傳回值

樹狀檢視控制項中的專案數目。

範例

// Delete all of the items from the tree control.
m_TreeCtrl.DeleteAllItems();
ASSERT(m_TreeCtrl.GetCount() == 0);

`CTreeCtrl::GetDropHilightItem`

呼叫此函式以擷取拖放作業的目標專案。

HTREEITEM GetDropHilightItem() const;

傳回值

如果成功，則卸載專案的控制碼;否則 NULL 為。

範例

// Set the item at the point myPoint as the drop target.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectDropTarget(hItem);
   ASSERT(m_TreeCtrl.GetDropHilightItem() == hItem);
}

`CTreeCtrl::GetEditControl`

呼叫此函式，擷取用來編輯樹狀檢視專案文字的編輯控制項控制碼。

CEdit* GetEditControl() const;

傳回值

如果成功，則為編輯控制項的指標，用來編輯專案文字;否則 NULL 為。

範例

// The string replacing the text in the edit control.
LPCTSTR lpszmyString = _T("New text!");

// Replace the text in the label edit control, if possible.
CEdit *pEdit = m_TreeCtrl.GetEditControl();

if (pEdit != NULL)
{
   pEdit->SetWindowText(lpszmyString);
}

`CTreeCtrl::GetExtendedStyle`

擷取目前樹狀檢視控制項所使用的擴充樣式。

DWORD GetExtendedStyle() const;

傳回值

值，包含目前樹狀檢視控制項擴充樣式的位組合（OR）。如需詳細資訊，請參閱樹狀檢視控制項擴充樣式。

備註

這個方法會傳送 TVM_GETEXTENDEDSTYLE 訊息，如 Windows SDK 中所述。

`CTreeCtrl::GetFirstVisibleItem`

呼叫此函式，以擷取樹狀檢視控制項的第一個可見專案。

HTREEITEM GetFirstVisibleItem() const;

傳回值

第一個可見專案的控制碼;否則 NULL 為。

範例

請參閱的 CTreeCtrl::SetCheck 範例。

`CTreeCtrl::GetImageList`

呼叫此函式，以擷取與樹狀檢視控制項相關聯的一般或狀態影像清單控制碼。

CImageList* GetImageList(UINT nImageList) const;

參數

nImageList
要擷取的影像清單類型。映射清單可以是下列其中一個值：

TVSIL_NORMAL 擷取一般影像清單，其中包含樹狀檢視專案的選取和未選取的影像。
TVSIL_STATE 擷取狀態影像清單，其中包含處於使用者定義狀態之樹狀檢視專案的影像。

傳回值

如果成功，則為控制項影像清單的指標;否則 NULL 為。

備註

樹狀檢視控制項中的每個專案都可以有一對與其相關聯的點陣圖影像。選取專案時會顯示一個影像，另一個影像則會在未選取專案時顯示。例如，專案可能會在選取時顯示開啟的資料夾，而未選取時會顯示關閉的資料夾。

如需影像清單的詳細資訊，請參閱類別 CImageList 。

範例

ASSERT(m_TreeCtrl.GetImageList(TVSIL_NORMAL) == NULL);

m_TreeCtrl.SetImageList(&m_TreeImages, TVSIL_NORMAL);
ASSERT(m_TreeCtrl.GetImageList(TVSIL_NORMAL) == &m_TreeImages);

`CTreeCtrl::GetIndent`

呼叫此函式，以圖元為單位擷取子專案相對於其父專案縮排的數量。

UINT GetIndent() const;

傳回值

以圖元為單位的縮排量。

範例

// Double the indent.
UINT uIndent = m_TreeCtrl.GetIndent();
m_TreeCtrl.SetIndent(2 * uIndent);

`CTreeCtrl::GetInsertMarkColor`

此成員函式會實作 Win32 訊息 TVM_GETINSERTMARKCOLOR 的行為，如 Windows SDK 中所述。

COLORREF GetInsertMarkColor() const;

傳回值

COLORREF值，包含目前的插入標記色彩。

範例

// Use the highliight color for the insert mark color.
COLORREF crColor = ::GetSysColor(COLOR_HIGHLIGHT);
m_TreeCtrl.SetInsertMarkColor(crColor);
ASSERT(m_TreeCtrl.GetInsertMarkColor() == crColor);

`CTreeCtrl::GetItem`

呼叫此函式以擷取指定樹狀檢視專案的屬性。

BOOL GetItem(TVITEM* pItem) const;

參數

pItem
結構的指標 TVITEM ，如 Windows SDK 中所述。

傳回值

如果成功則為非零；否則為 0。

範例

請參閱的 CTreeCtrl::DeleteItem 範例。

`CTreeCtrl::GetItemData`

呼叫此函式，以擷取與指定專案相關聯的應用程式特定值。

DWORD_PTR GetItemData(HTREEITEM hItem) const;

參數

hItem
要擷取其資料的專案控制碼。

傳回值

與所 hItem 指定專案相關聯的指標大小應用程式特定值。

範例

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Delete all of the children of hmyItem whose item data is
// not equal to zero.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hNextItem;
   HTREEITEM hChildItem = m_TreeCtrl.GetChildItem(hmyItem);

   while (hChildItem != NULL)
   {
      hNextItem = m_TreeCtrl.GetNextItem(hChildItem, TVGN_NEXT);

      if (m_TreeCtrl.GetItemData(hChildItem) != 0)
      {
         m_TreeCtrl.DeleteItem(hChildItem);
      }

      hChildItem = hNextItem;
   }
}

`CTreeCtrl::GetItemExpandedImageIndex`

擷取當目前樹狀檢視控制項的指定專案處於展開狀態時，要顯示的影像索引。

int GetItemExpandedImageIndex(HTREEITEM hItem)const;

參數

hItem
[in]樹狀檢視控制項專案的控制碼。

傳回值

當指定的專案處於展開狀態時所要顯示的影像索引。

備註

這個方法會傳送 TVM_GETITEM 訊息，如 Windows SDK 中所述。該訊息會傳 TVITEMEX 回描述樹狀檢視控制項專案的結構，然後這個方法會從該結構擷取 iExpandedImage 成員。

`CTreeCtrl::GetItemHeight`

此成員函式會實作 Win32 訊息 TVM_GETITEMHEIGHT 的行為，如 Windows SDK 中所述。

SHORT GetItemHeight() const;

傳回值

專案的高度，以圖元為單位。

範例

// Double the height of the items.
SHORT sHeight = m_TreeCtrl.GetItemHeight();
m_TreeCtrl.SetItemHeight(2 * sHeight);

`CTreeCtrl::GetItemImage`

樹狀檢視控制項中的每個專案都可以有一對與其相關聯的點陣圖影像。

BOOL GetItemImage(
    HTREEITEM hItem,
    int& nImage,
    int& nSelectedImage) const;

參數

hItem
要擷取其影像之專案的控制碼。

nImage
整數，會在樹狀檢視控制項的影像清單中接收專案影像的索引。

nSelectedImage
整數，會在樹狀檢視控制項的影像清單中接收專案所選取影像的索引。

傳回值

如果成功則為非零；否則為 0。

備註

影像會出現在專案標籤的左側。選取專案時會顯示一個影像，另一個影像則會在未選取專案時顯示。例如，專案可能會在選取時顯示開啟的資料夾，而未選取時會顯示關閉的資料夾。

呼叫此函式，以擷取專案影像的索引，以及在樹狀檢視控制項的影像清單中擷取其選取的影像。

範例

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// If the selected image is the same as the nonselected image
// then make the selected image one more than the nonselected image.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hItem = m_TreeCtrl.GetChildItem(hmyItem);
   int nImage, nSelectedImage;

   while (hItem != NULL)
   {
      m_TreeCtrl.GetItemImage(hItem, nImage, nSelectedImage);

      if (nImage == nSelectedImage)
      {
         m_TreeCtrl.SetItemImage(hItem, nImage, nImage + 1);
      }

      hItem = m_TreeCtrl.GetNextSiblingItem(hItem);
   }
}

`CTreeCtrl::GetItemPartRect`

擷取目前樹狀檢視控制項中指定專案之指定部分的周框。

BOOL GetItemPartRect(
    HTREEITEM hItem,
    int nPart,
    LPRECT lpRect)const;

參數

hItem
[in]樹狀檢視控制項專案的控制碼。

nPart
[in]元件的識別碼。必須設定為 TVGIPR_BUTTON。

lpRect
[out]結構的 RECT 指標。如果這個方法成功，結構會接收和 nPart 所 hItem 指定元件的矩形座標。

傳回值

TRUE 如果此方法成功，則為 ;否則為 FALSE 。

備註

每個樹狀結構控制項專案都會由圖形矩形系結。只要按一下該矩形中的某個點，專案就會被叫用。這個方法會傳回最大的矩形，如此一來，當按一下矩形中的某個點時，就會叫用參數所 hItem 識別的專案。

這個方法會傳送 TVM_GETITEMPARTRECT 訊息，如 Windows SDK 中所述。如需詳細資訊，請參閱 TreeView_GetItemPartRect 宏。

範例

第一個程式碼範例會定義用來存取目前樹狀檢視控制項的變數 m_treeCtrl 。程式碼範例也會定義不帶正負號的整數和數個 HTREEITEM 變數。下一個範例會使用這些變數。

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

下一個程式碼範例會使用協助工具識別碼和 CTreeCtrl::MapAccIdToItem 方法來擷取根樹狀檢視專案的控制碼。然後，此範例會使用控制碼和 CTreeCtrl::GetItemPartRect 方法來繪製該專案周圍的 3D 矩形。在未顯示的程式碼範例的先前區段中，我們建立了一個樹狀檢視，其中包含美國的根國家/地區節點、賓夕法尼亞州和華盛頓州的子節點，以及這些州城市樹狀專案。我們使用 CTreeCtrl::MapItemToAccID 方法將根樹狀檢視專案與協助工具識別碼產生關聯。

CRect rect;
HTREEITEM hUS = m_treeCtrl.MapAccIdToItem(accIdUS);
m_treeCtrl.GetItemPartRect(hUS, TVGIPR_BUTTON, &rect);
m_treeCtrl.GetDC()->Draw3dRect(&rect, RGB(255, 0, 0), RGB(0, 0, 255));

`CTreeCtrl::GetItemRect`

呼叫此函式以擷 取 hItem 的周框，並判斷它是否可見。

BOOL GetItemRect(
    HTREEITEM hItem,
    LPRECT lpRect,
    BOOL bTextOnly) const;

參數

hItem
樹狀檢視控制項專案的控制碼。

lpRect
RECT接收周框之結構的指標。座標相對於樹狀檢視控制項的左上角。

bTextOnly
如果此參數為非零值，周框只會包含專案的文字。否則，它會包含專案在樹狀檢視控制項中佔用的整行。

傳回值

如果專案可見，則為非零，且周框包含在中 lpRect 。否則，使用未初始化的 lpRect 0。

範例

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Dump the bounds of hmyItem.
if (hmyItem != NULL)
{
   RECT r;

   m_TreeCtrl.GetItemRect(hmyItem, &r, FALSE);

   TRACE(TEXT("left = %d, top = %d, right = %d, bottom = %d\r\n"),
         r.left,
         r.top,
         r.right,
         r.bottom);
}

`CTreeCtrl::GetItemState`

傳回所 hItem 指定專案的狀態。

UINT GetItemState(
    HTREEITEM hItem,
    UINT nStateMask) const;

參數

hItem
要擷取其狀態的專案控制碼。

nStateMask
表示要擷取之一或多個狀態的遮罩。如需有關之可能值 nStateMask 的詳細資訊，請參閱 Windows SDK 中結構的和 stateMask 成員 TVITEM 的討論 state 。

傳回值

UINT，保留所 nStateMask 指定值的 C++ 位 OR 運算子（ | ）。如需可能值的資訊，請參閱 CTreeCtrl::GetItem 。若要尋找特定狀態的值，請執行 C++ 位 AND 運算子（ & ） f 狀態值和傳回值，如下列範例所示。

範例

// Show all of the visible items in bold.
HTREEITEM hItem = m_TreeCtrl.GetFirstVisibleItem();

while (hItem != NULL)
{
   m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
   ASSERT(TVIS_BOLD & m_TreeCtrl.GetItemState(hItem, TVIS_BOLD));
   hItem = m_TreeCtrl.GetNextVisibleItem(hItem);
}

`CTreeCtrl::GetItemStateEx`

擷取目前樹狀檢視控制項中指定專案的擴充狀態。

UINT GetItemStateEx(HTREEITEM hItem) const;

參數

hItem
[in]樹狀檢視控制項專案的控制碼。

傳回值

專案的擴充狀態。如需詳細資訊，請參閱 uStateEx 結構的成員 TVITEMEX 。

備註

這個方法會傳送 TVM_GETITEM 訊息，如 Windows SDK 中所述。該訊息會傳 TVITEMEX 回描述樹狀檢視控制項專案的結構，而這個方法會 uStateEx 從該結構擷取成員。

`CTreeCtrl::GetItemText`

傳回所 hItem 指定專案的文字。

CString GetItemText(HTREEITEM hItem) const;

參數

hItem
要擷取其文字的專案控制碼。

傳回值

CString物件，包含專案的文字。

範例

請參閱的 CTreeCtrl::GetNextItem 範例。

`CTreeCtrl::GetLastVisibleItem`

擷取目前樹狀檢視控制項中最後一個未展開的節點專案。

HTREEITEM GetLastVisibleItem() const;

傳回值

如果方法成功，則為最後一個未展開之節點專案的控制碼;否則為 NULL 。

備註

這個方法會傳送 TVM_GETNEXTITEM 訊息，如 Windows SDK 中所述。如需詳細資訊，請參閱 TVGN_LASTVISIBLE 該訊息參數中的 flag 旗標。

範例

第一個程式碼範例會定義用來存取目前樹狀檢視控制項的變數 m_treeCtrl 。程式碼範例也會定義不帶正負號的整數和數個 HTREEITEM 變數。下一個範例會使用其中一或多個變數。

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

下一個程式碼範例會擷取最後一個未展開之樹狀檢視節點專案的控制碼，然後繪製該專案周圍的 3D 矩形。在未顯示的程式碼範例的先前區段中，我們建立了一個樹狀檢視，其中包含美國的根國家/地區節點、賓夕法尼亞州和華盛頓州的子節點，以及這些州城市樹狀專案。

CRect rect;
HTREEITEM hLast = m_treeCtrl.GetLastVisibleItem();
m_treeCtrl.GetItemPartRect(hLast, TVGIPR_BUTTON, &rect);
m_treeCtrl.GetDC()->Draw3dRect(&rect, RGB(255, 0, 0), RGB(0, 0, 255));

`CTreeCtrl::GetLineColor`

此成員函式會實作 Win32 訊息 TVM_GETLINECOLOR 的行為，如 Windows SDK 中所述。

COLORREF GetLineColor() const;

傳回值

目前的線條色彩。

範例

COLORREF cr = m_TreeCtrl.GetLineColor();

`CTreeCtrl::GetNextItem`

呼叫此函式，將具有指定關聯性的樹狀檢視專案擷 nCode 取至 hItem 。

HTREEITEM GetNextItem(
    HTREEITEM hItem,
    UINT nCode) const;

參數

hItem
樹狀專案的控制碼。

nCode
旗標，表示與的 hItem 關聯類型。此旗標可以是下列其中一個值：

TVGN_CARET 擷取目前選取的專案。
TVGN_CHILD 擷取參數所 hItem 指定專案的第一個子專案。
TVGN_DROPHILITE 擷取拖放作業的目標專案。
TVGN_FIRSTVISIBLE 擷取第一個可見專案。
TVGN_LASTVISIBLE 擷取樹狀結構中最後一個展開的專案。這不會擷取樹狀檢視視窗中顯示的最後一個專案。
TVGN_NEXT 擷取下一個同層級專案。
TVGN_NEXTVISIBLE 擷取指定專案後面的下一個可見專案。
TVGN_PARENT 擷取指定專案的父代。
TVGN_PREVIOUS 擷取上一個同層級專案。
TVGN_PREVIOUSVISIBLE 擷取指定專案前面的第一個可見專案。
TVGN_ROOT 擷取指定專案所屬根專案的第一個子專案。

傳回值

如果成功，則為下一個專案的控制碼;否則 NULL 為。

備註

如果所擷取的專案是樹狀結構的根節點，則此函式會傳回 NULL 。例如，如果您在樹狀檢視根節點的第一層子節點上搭配 TVGN_PARENT 旗標使用此訊息，訊息會傳回 NULL 。

範例

如需在迴圈中使用的 GetNextItem 範例，請參閱 CTreeCtrl::DeleteItem 。

// find the currently selected item
HTREEITEM hCurSel = m_TreeCtrl.GetNextItem(TVI_ROOT, TVGN_CARET);

// report it to the user
if (hCurSel == NULL)
{
   AfxMessageBox(_T("There is no selected item"));
}
else
{
   CString str;
   str.Format(_T("The currently selected item is \"%s\""),
              (LPCTSTR)m_TreeCtrl.GetItemText(hCurSel));
   AfxMessageBox((LPCTSTR)str);
}

`CTreeCtrl::GetNextSiblingItem`

呼叫此函式以擷取的下一個同層級 hItem 。

HTREEITEM GetNextSiblingItem(HTREEITEM hItem) const;

參數

hItem
樹狀專案的控制碼。

傳回值

下一個同層級專案的控制碼;否則 NULL 為。

範例

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Show all of the children of hmyItem in bold.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hItem = m_TreeCtrl.GetChildItem(hmyItem);

   while (hItem != NULL)
   {
      m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
      hItem = m_TreeCtrl.GetNextSiblingItem(hItem);
   }
}

`CTreeCtrl::GetNextVisibleItem`

呼叫此函式以擷取的下一個可見專案 hItem 。

HTREEITEM GetNextVisibleItem(HTREEITEM hItem) const;

參數

hItem
樹狀專案的控制碼。

傳回值

下一個可見專案的控制碼;否則 NULL 為。

範例

請參閱的 CTreeCtrl::SetCheck 範例。

`CTreeCtrl::GetParentItem`

呼叫此函式以擷取的父代 hItem 。

HTREEITEM GetParentItem(HTREEITEM hItem) const;

參數

hItem
樹狀專案的控制碼。

傳回值

父專案的控制碼;否則 NULL 為。

備註

如果指定專案的父系是樹狀結構的根節點，則此函式會傳回 NULL 。

範例

請參閱的 CTreeCtrl::EnsureVisible 範例。

`CTreeCtrl::GetPrevSiblingItem`

呼叫此函式以擷取先前的 hItem 同層級。

HTREEITEM GetPrevSiblingItem(HTREEITEM hItem) const;

參數

hItem
樹狀專案的控制碼。

傳回值

上一個同層級的控制碼;否則 NULL 為。

範例

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Show all of the previous siblings of hmyItem in bold.
HTREEITEM hItem = hmyItem;

while (hItem != NULL)
{
   m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
   hItem = m_TreeCtrl.GetPrevSiblingItem(hItem);
}

`CTreeCtrl::GetPrevVisibleItem`

呼叫此函式以擷取先前的可見專案 hItem 。

HTREEITEM GetPrevVisibleItem(HTREEITEM hItem) const;

參數

hItem
樹狀專案的控制碼。

傳回值

上一個可見專案的控制碼;否則 NULL 為。

範例

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Show all of the previous visible items of hmyItem in bold.
HTREEITEM hItem = hmyItem;

while (hItem != NULL)
{
   m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
   hItem = m_TreeCtrl.GetPrevVisibleItem(hItem);
}

`CTreeCtrl::GetRootItem`

呼叫此函式以擷取樹狀檢視控制項的根專案。

HTREEITEM GetRootItem() const;

傳回值

根專案的控制碼;否則 NULL 為。

範例

請參閱的 CTreeCtrl::EditLabel 範例。

`CTreeCtrl::GetScrollTime`

呼叫這個成員函式，以擷取樹狀檢視控制項的最大捲動時間。

UINT GetScrollTime() const;

傳回值

滾動時間上限，以毫秒為單位。

備註

此成員函式會實作 Win32 訊息 TVM_GETSCROLLTIME 的行為，如 Windows SDK 中所述。

`CTreeCtrl::GetSelectedCount`

擷取目前樹狀檢視控制項中選取的專案數目。

UINT GetSelectedCount();

傳回值

選取的專案數目。

備註

這個方法會傳送 TVM_GETSELECTEDCOUNT 訊息，如 Windows SDK 中所述。

`CTreeCtrl::GetSelectedItem`

呼叫此函式以擷取樹狀檢視控制項目前選取的專案。

HTREEITEM GetSelectedItem() const;

傳回值

選取專案的控制碼;否則 NULL 為。

範例

// Expand the selected item and make it visible, if possible.
HTREEITEM hItem = m_TreeCtrl.GetSelectedItem();

if ((hItem != NULL) && m_TreeCtrl.ItemHasChildren(hItem))
{
   m_TreeCtrl.Expand(hItem, TVE_EXPAND);
   m_TreeCtrl.EnsureVisible(hItem);
}

`CTreeCtrl::GetTextColor`

此成員函式會實作 Win32 訊息 TVM_GETTEXTCOLOR 的行為，如 Windows SDK 中所述。

COLORREF GetTextColor() const;

傳回值

COLORREF值，表示目前的文字色彩。如果此值為 -1，控制項會使用文字色彩的系統色彩。

範例

請參閱的 CTreeCtrl::SetTextColor 範例。

`CTreeCtrl::GetToolTips`

此成員函式會實作 Win32 訊息 TVM_GETTOOLTIPS 的行為，如 Windows SDK 中所述。

CToolTipCtrl* GetToolTips() const;

傳回值

樹狀目錄控制項所要使用的物件指標 CToolTipCtrl 。 Create如果成員函式使用樣式 TVS_NOTOOLTIPS ，則不會使用任何工具提示，而且 NULL 會傳回。

備註

的 GetToolTips MFC 實作會 CToolTipCtrl 傳回樹狀控制項所使用的物件，而不是工具提示控制項的控制碼。

範例

// If the tree control does not have a tooltips control,
// then use m_ToolTips as the tooltips for the tree control.
if (m_TreeCtrl.GetToolTips() == NULL)
{
   m_TreeCtrl.SetToolTips(&m_ToolTips);
}

`CTreeCtrl::GetVisibleCount`

呼叫此函式以擷取樹狀檢視控制項中可見專案的計數。

UINT GetVisibleCount() const;

傳回值

樹狀檢視控制項中可見專案的數目;否則 - 1。

範例

請參閱的 CTreeCtrl::SetCheck 範例。

`CTreeCtrl::HitTest`

呼叫此函式，以判斷相對於樹狀檢視控制項工作區的指定點位置。

HTREEITEM HitTest(
    CPoint pt,
    UINT* pFlags = NULL) const;

HTREEITEM HitTest(TVHITTESTINFO* pHitTestInfo) const;

參數

pt
要測試之點的用戶端座標。

pFlags
接收點擊測試結果相關資訊之整數的指標。它可以是一節中成員底下 flags 所列的一或多個值。

pHitTestInfo
TVHITTESTINFO結構位址，其中包含點擊測試的位置，以及接收點擊測試結果的相關資訊。

傳回值

佔用指定點的樹狀檢視專案控制碼， NULL 如果沒有專案佔用該點，則為。

備註

呼叫此函式時， pt 參數會指定要測試之點的座標。函式會在指定的點傳 NULL 回專案的控制碼，如果沒有專案佔用該點，則傳回。此外， pFlags 參數會包含值，指出指定點的位置。可能的值包括：

值	Description
`TVHT_ABOVE`	在工作區上方。
`TVHT_BELOW`	工作區下方。
`TVHT_NOWHERE`	在工作區中，但位於最後一個專案下方。
`TVHT_ONITEM`	在與專案相關聯的點陣圖或標籤上。
`TVHT_ONITEMBUTTON`	在與專案相關聯的按鈕上。
`TVHT_ONITEMICON`	在與專案相關聯的點陣圖上。
`TVHT_ONITEMINDENT`	在與專案相關聯的縮排中。
`TVHT_ONITEMLABEL`	在與專案相關聯的標籤（string）上。
`TVHT_ONITEMRIGHT`	在專案右邊的區域。
`TVHT_ONITEMSTATEICON`	在處於使用者定義狀態之樹狀檢視專案的狀態圖示上。
`TVHT_TOLEFT`	工作區左側。
`TVHT_TORIGHT`	工作區右側。

範例

// Select the item that is at the point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectItem(hItem);
}

`CTreeCtrl::InsertItem`

呼叫此函式，以在樹狀檢視控制項中插入新專案。

HTREEITEM InsertItem(LPTVINSERTSTRUCT lpInsertStruct);

HTREEITEM InsertItem(
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    int nSelectedImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam,
    HTREEITEM hParent,
    HTREEITEM hInsertAfter);

HTREEITEM InsertItem(
    LPCTSTR lpszItem,
    HTREEITEM hParent = TVI_ROOT,
    HTREEITEM hInsertAfter = TVI_LAST);

HTREEITEM InsertItem(
    LPCTSTR lpszItem,
    int nImage,
    int nSelectedImage,
    HTREEITEM hParent = TVI_ROOT,
    HTREEITEM hInsertAfter = TVI_LAST);

參數

lpInsertStruct
的指標 TVINSERTSTRUCT ，指定要插入之樹狀檢視專案的屬性。

nMask
整數，指定要設定的屬性。 TVITEM請參閱 Windows SDK 中的結構。

lpszItem
包含專案文字的字串位址。

nImage
樹狀檢視控制項影像清單中的專案影像索引。

nSelectedImage
樹狀檢視控制項影像清單中的專案選取影像的索引。

nState
指定專案狀態的值。如需適當的狀態清單，請參閱 Windows SDK 中的樹狀檢視控制項專案狀態。

nStateMask
指定要設定的狀態。 TVITEM請參閱 Windows SDK 中的結構。

lParam
與專案相關聯的指標大小應用程式特定值。

hParent
插入專案的父代控制碼。

hInsertAfter
要插入新專案的專案控制碼。

傳回值

如果成功，則為新專案的控制碼;否則 NULL 為。

備註

此範例顯示插入樹狀目錄控制項專案時，您可能想要使用函式的每個版本的情況。

範例

// Insert a root item using the structure. We must
// initialize a TVINSERTSTRUCT structure and pass its
// address to the call. 

TVINSERTSTRUCT tvInsert;
tvInsert.hParent = NULL;
tvInsert.hInsertAfter = NULL;
tvInsert.item.mask = TVIF_TEXT;
tvInsert.item.pszText = _T("United States");

HTREEITEM hCountry = m_TreeCtrl.InsertItem(&tvInsert);

// Insert subitems of that root. Pennsylvania is
// a state in the United States, so its item will be a child
// of the United States item. We won't set any image or states,
// so we supply only the TVIF_TEXT mask flag. This
// override provides nearly complete control over the
// insertion operation without the tedium of initializing
// a structure. If you're going to add lots of items
// to a tree, you might prefer the structure override
// as it affords you a performance win by allowing you
// to initialize some fields of the structure only once,
// outside of your insertion loop.

HTREEITEM hPA = m_TreeCtrl.InsertItem(TVIF_TEXT,
   _T("Pennsylvania"), 0, 0, 0, 0, 0, hCountry, NULL);

// Insert the "Washington" item and assure that it is
// inserted after the "Pennsylvania" item. This override is 
// more appropriate for conveniently inserting items with 
// images.

HTREEITEM hWA = m_TreeCtrl.InsertItem(_T("Washington"),
   0, 0, hCountry, hPA);

// We'll add some cities under each of the states.
// The override used here is most appropriate
// for inserting text-only items.

m_TreeCtrl.InsertItem(_T("Pittsburgh"), hPA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Harrisburg"), hPA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Altoona"), hPA, TVI_SORT);

m_TreeCtrl.InsertItem(_T("Seattle"), hWA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Kalaloch"), hWA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Yakima"), hWA, TVI_SORT);

`CTreeCtrl::ItemHasChildren`

使用此函式來判斷所 hItem 指定的樹狀專案是否具有子專案。

BOOL ItemHasChildren(HTREEITEM hItem) const;

參數

hItem
樹狀專案的控制碼。

傳回值

如果所 hItem 指定的樹狀專案具有子專案，則為非零;如果沒有，則為 0。

備註

如果是，您可以使用 CTreeCtrl::GetChildItem 來擷取這些子專案。

範例

請參閱的 CTreeCtrl::GetSelectedItem 範例。

`CTreeCtrl::MapAccIdToItem`

地圖目前樹狀檢視控制項中樹狀檢視專案控制碼的指定協助工具識別碼。

HTREEITEM MapAccIdToItem(UINT uAccId) const;

參數

uAccId
[in]樹狀檢視專案中專案的協助工具識別碼。

傳回值

對應至參數之 uAccId 樹狀檢視專案的控制碼。 HTREEITEM 如需詳細資訊，請參閱 hItem 結構的成員 TVITEMEX 。

備註

協助工具協助工具是協助殘障人士使用電腦的應用程式。介面會使用 IAccessible 協助工具識別碼來唯一指定視窗中的專案。如需 API 的詳細資訊 IAccessible ，請參閱 Microsoft Active Accessibility 。

這個方法會傳送 TVM_MAPACCIDTOHTREEITEM 訊息，如 Windows SDK 中所述。

範例

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

下一個程式碼範例會使用協助工具識別碼和 CTreeCtrl::MapAccIdToItem 方法來擷取根樹狀檢視專案的控制碼。此範例會使用控制碼和 CTreeCtrl::GetItemPartRect 方法，在該專案周圍繪製 3D 矩形。在未顯示的程式碼範例的先前區段中，我們建立了一個樹狀檢視，其中包含美國的根國家/地區節點、賓夕法尼亞州和華盛頓州的子節點，以及這些州城市樹狀專案。我們使用 CTreeCtrl::MapItemToAccID 方法將根樹狀檢視專案與協助工具識別碼產生關聯。

CRect rect;
HTREEITEM hUS = m_treeCtrl.MapAccIdToItem(accIdUS);
m_treeCtrl.GetItemPartRect(hUS, TVGIPR_BUTTON, &rect);
m_treeCtrl.GetDC()->Draw3dRect(&rect, RGB(255, 0, 0), RGB(0, 0, 255));

`CTreeCtrl::MapItemToAccID`

地圖目前樹狀檢視控制項中樹狀檢視專案的指定控制碼，指向協助工具識別碼。

UINT MapItemToAccID(HTREEITEM hItem) const;

參數

hItem
[in]控制項中樹狀檢視專案的控制碼。如需詳細資訊，請參閱 hItem 結構的成員 TVITEMEX 。

傳回值

對應至 hItem 參數的 協助工具識別碼。

備註

這個方法會傳送 TVM_MAPHTREEITEMTOACCID 訊息，如 Windows SDK 中所述。

範例

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

下一個程式碼範例會取得樹狀檢視控制項專案的識別碼。在未顯示的程式碼範例的先前區段中，我們建立了一個樹狀檢視，其中包含美國的根國家/地區節點、賓夕法尼亞州和華盛頓州的子節點，以及這些州城市樹狀專案。此程式碼範例會取得根國家/地區節點的唯一識別碼。

// Map an accessibility identifier to the Pennsylvania node.
accIdUS = m_treeCtrl.MapItemToAccId(hCountry);

`CTreeCtrl::Select`

呼叫此函式以選取指定的樹狀檢視專案、將專案捲動到檢視中，或重新繪製用來指出拖放作業目標的樣式中的專案。

BOOL Select(
    HTREEITEM hItem,
    UINT nCode);

參數

hItem
樹狀專案的控制碼。

nCode
要採取的動作類型。這個參數可以是下列其中一個值：

TVGN_CARET 將選取範圍設定為指定的專案。
TVGN_DROPHILITE 在樣式中重新繪製指定專案，以指出拖放作業的目標。
TVGN_FIRSTVISIBLE 垂直捲動樹狀檢視，使指定的專案是第一個可見的專案。

傳回值

如果成功則為非零；否則為 0。

備註

如果 nCode 包含值 TVGN_CARET ，則父視窗會收到 TVN_SELCHANGING 和 TVN_SELCHANGED 通知訊息。此外，如果指定的專案是折迭父專案的子專案，則會展開父項的子專案清單以顯示指定的專案。在此情況下，父視窗會收到 TVN_ITEMEXPANDING 和 TVN_ITEMEXPANDED 通知訊息。

範例

請參閱的 CTreeCtrl::HitTest 範例。

`CTreeCtrl::SelectDropTarget`

呼叫此函式，以重新繪製樣式中的專案，以指出拖放作業的目標。

BOOL SelectDropTarget(HTREEITEM hItem);

參數

hItem
樹狀專案的控制碼。

傳回值

如果成功則為非零；否則為 0。

範例

// Set the item at the point myPoint as the drop target.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectDropTarget(hItem);
   ASSERT(m_TreeCtrl.GetDropHilightItem() == hItem);
}

`CTreeCtrl::SelectItem`

呼叫此函式以選取指定的樹狀檢視專案。

BOOL SelectItem(HTREEITEM hItem);

參數

hItem
樹狀專案的控制碼。

傳回值

如果成功則為非零；否則為 0。

備註

如果 hItem 為 NULL ，則此函式不會選取任何專案。

範例

// Select the item that is at the point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectItem(hItem);
}

`CTreeCtrl::SelectSetFirstVisible`

呼叫此函式以垂直捲動樹狀檢視，讓指定的專案是第一個可見的專案。

BOOL SelectSetFirstVisible(HTREEITEM hItem);

參數

hItem
要設定為第一個可見專案的樹狀專案控制碼。

傳回值

如果成功則為非零；否則為 0。

備註

函式會使用 TVM_SELECTITEM 和 TVGN_FIRSTVISIBLE 訊息參數，將訊息傳送至視窗。

範例

// Select the item at the point myPoint as the first visible item.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectSetFirstVisible(hItem);
}

`CTreeCtrl::SetAutoscrollInfo`

設定目前樹狀檢視控制項的自動標籤速率。

BOOL SetAutoscrollInfo(
    UINT uPixelsPerSec,
    UINT uUpdateTime);

參數

uPixelsPerSec
[in]要捲動的每秒圖元數。

uUpdateTime
[in]控制項更新之間的時間間隔。

傳回值

一律傳回 TRUE。

備註

autoscroll 參數可用來捲動至目前看不到的專案。樹狀檢視控制項必須具有 TVS_EX_AUTOHSCROLL 延伸樣式，如樹狀檢視控制項擴充樣式中所述。

這個方法會傳送 TVM_SETAUTOSCROLLINFO 訊息，如 Windows SDK 中所述。

範例

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

下一個程式碼範例會設定目前樹狀檢視控制項的自動捲動行為。在未顯示的程式碼範例的先前區段中，我們建立了一個樹狀檢視，其中包含美國的根國家/地區節點、賓夕法尼亞州和華盛頓州的子節點，以及這些州城市樹狀專案。我們刻意將樹狀檢視控制項縮小，使其必須自動捲動以顯示具有焦點的樹狀結構專案。程式碼範例會將樹狀檢視控制項設定為每隔 5 秒自動捲動 30 圖元，直到樹狀目錄專案處於檢視中為止。

// Scroll 30 pixels/sec and redraw every 5 seconds.
m_treeCtrl.SetAutoscrollInfo(30, 5);

`CTreeCtrl::SetBkColor`

此成員函式會實作 Win32 訊息 TVM_SETBKCOLOR 的行為，如 Windows SDK 中所述。

COLORREF SetBkColor(COLORREF clr);

參數

clr
COLORREF值，包含新的背景色彩。如果此值為 -1，控制項會還原為使用背景色彩的系統色彩。

傳回值

COLORREF值，表示目前的文字色彩。如果此值為 -1，控制項會使用文字色彩的系統色彩。

範例

請參閱的 CTreeCtrl::SetTextColor 範例。

`CTreeCtrl::SetCheck`

呼叫這個成員函式來設定樹狀控制項專案的檢查狀態。

BOOL SetCheck(
    HTREEITEM hItem,
    BOOL fCheck = TRUE);

參數

hItem
HTREEITEM要接收檢查狀態變更的。

fCheck
指出要檢查或取消核取樹狀目錄控制項專案。根據預設， SetCheck 設定要檢查的專案。

傳回值

如果成功則為非零；否則為 0。

備註

核取樹狀目錄控制項專案時（ fCheck 設定為 TRUE ），專案會出現連續的核取記號。

範例

UINT uCount = m_TreeCtrl.GetVisibleCount();
HTREEITEM hItem = m_TreeCtrl.GetFirstVisibleItem();

// Toggle the check state of all the visible items.
for (UINT i = 0; i < uCount; i++)
{
   ASSERT(hItem != NULL);
   m_TreeCtrl.SetCheck(hItem, !m_TreeCtrl.GetCheck(hItem));
   hItem = m_TreeCtrl.GetNextVisibleItem(hItem);
}

若要使用核取方塊，請在填入樹狀目錄控制項之前設定 TVS_CHECKBOXES 。

m_TreeCtrl.ModifyStyle(0, TVS_CHECKBOXES);

HTREEITEM aItem = m_TreeCtrl.InsertItem(_T("AAA"));
m_TreeCtrl.SetCheck(aItem);

`CTreeCtrl::SetExtendedStyle`

設定目前樹狀檢視控制項的延伸樣式。

DWORD SetExtendedStyle(
    DWORD dwExMask,
    DWORD dwExStyles);

參數

dwExMask
[in]位元遮罩，指定目前樹狀檢視控制項中哪些樣式會受到這個方法的影響。如果此參數為零，則會忽略此參數，並將參數的值 dwExStyles 指派給樹狀檢視控制項。指定樹狀檢視控制項擴充樣式中所述之樣式的零或位組合（OR）。

dwExStyles
[in]位元遮罩，指定要設定或清除目前樹狀檢視控制項中的樣式。若要設定樣式的組合，請指定樹狀檢視控制項擴充樣式中所述的位組合（OR）樣式。若要清除一組樣式，請指定零。

傳回值

值，包含先前的擴充控制項樣式。

備註

這個方法會清除參數中指定的 dwExMask 樣式，然後設定參數中指定的 dwExStyles 樣式。只有對應至變更中 dwExMask 位的擴充樣式。

這個方法會傳送 TVM_SETEXTENDEDSTYLE 訊息，如 Windows SDK 中所述。

範例

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

下一個程式碼範例會將 TVS_EX_AUTOHSCROLL 擴充樣式新增至目前的樹狀檢視控制項。在未顯示的程式碼範例的先前區段中，我們建立了一個樹狀檢視，其中包含美國的根國家/地區節點、賓夕法尼亞州和華盛頓州的子節點，以及這些州城市樹狀專案。我們刻意將樹狀檢視控制項縮小，使其必須自動捲動以顯示具有焦點的樹狀結構專案。

m_treeCtrl.SetExtendedStyle(TVS_EX_AUTOHSCROLL, TVS_EX_AUTOHSCROLL);

`CTreeCtrl::SetImageList`

呼叫此函式來設定樹狀檢視控制項的一般或狀態影像清單，並使用新的影像重新繪製控制項。

CImageList* SetImageList(
    CImageList* pImageList,
    int nImageListType);

參數

pImageList
要指派之影像清單的指標。如果 pImageList 為 NULL ，則會從樹狀檢視控制項中移除所有影像。

nImageListType
要設定的影像清單類型。映射清單可以是下列其中一個值：

TVSIL_NORMAL 設定一般影像清單，其中包含樹狀檢視專案的選取和未選取的影像。您必須將此狀態用於重迭影像。
TVSIL_STATE 設定狀態影像清單，其中包含處於使用者定義狀態之樹狀檢視專案的影像。

傳回值

如果有任何，則為上一個影像清單的指標;否則 NULL 為。

範例

請參閱的 CTreeCtrl::GetImageList 範例。

`CTreeCtrl::SetIndent`

呼叫此函式來設定樹狀檢視控制項的縮排寬度，並重新繪製控制項以反映新的寬度。

void SetIndent(UINT nIndent);

參數

nIndent
縮排的寬度，以圖元為單位。如果 nIndent 小於系統定義的最小寬度，新的寬度會設定為系統定義的最小值。

範例

請參閱的 CTreeCtrl::GetIndent 範例。

`CTreeCtrl::SetInsertMark`

此成員函式會實作 Win32 訊息 TVM_SETINSERTMARK 的行為，如 Windows SDK 中所述。

BOOL SetInsertMark(
    HTREEITEM hItem,
    BOOL fAfter = TRUE);

參數

hItem
HTREEITEM ，指定要放置插入標記的專案。如果這個引數為 Null，則會移除插入標記。

fAfter
BOOL 值，指定插入標記是否放在指定專案之前或之後。如果這個引數為非零，插入標記將會放在專案之後。如果這個引數為零，插入標記會放在專案之前。

傳回值

如果成功則為非零；否則為 0。

範例

// Set the insert mark to be before the item at the point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SetInsertMark(hItem, FALSE);
}

`CTreeCtrl::SetInsertMarkColor`

此成員函式會實作 Win32 訊息 TVM_SETINSERTMARKCOLOR 的行為，如 Windows SDK 中所述。

COLORREF SetInsertMarkColor(COLORREF clrNew);

參數

clrNew
COLORREF值，包含新的插入標記色彩。

傳回值

COLORREF值，包含先前的插入標記色彩。

範例

請參閱的 CTreeCtrl::GetInsertMarkColor 範例。

`CTreeCtrl::SetItem`

呼叫此函式以設定指定之樹狀檢視專案的屬性。

BOOL SetItem(TVITEM* pItem);

BOOL SetItem(
    HTREEITEM hItem,
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    int nSelectedImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam);

參數

pItem
結構指標 TVITEM ，其中包含新的專案屬性，如 Windows SDK 中所述。

hItem
要設定其屬性的專案控制碼。 hItem請參閱 Windows SDK 中結構的成員 TVITEM 。

nMask
整數，指定要設定的屬性。 mask請參閱結構的成員 TVITEM 。

lpszItem
包含專案文字的字串位址。

nImage
樹狀檢視控制項影像清單中的專案影像索引。 iImage請參閱結構的成員 TVITEM 。

nSelectedImage
樹狀檢視控制項影像清單中的專案選取影像的索引。 iSelectedImage請參閱結構的成員 TVITEM 。

nState
指定專案狀態的值。 State請參閱結構的成員 TVITEM 。

nStateMask
指定要設定的狀態。 stateMask請參閱結構的成員 TVITEM 。

lParam
與專案相關聯的指標大小應用程式特定值。

傳回值

如果成功則為非零；否則為 0。

備註

在結構中 TVITEMhItem ，成員會識別專案，而 mask 成員會指定要設定的屬性。

mask如果成員或參數指定 TVIF_TEXT 值，則 pszText 成員或 nMasklpszItem 是 Null 終止字串的位址，而且 cchTextMax 會忽略成員。如果 mask （或 nMask ）指定 TVIF_STATE 值，則 stateMask 成員或 nStateMask 參數會指定要變更的專案狀態，而 state 成員或 nState 參數包含這些狀態的值。

範例

// Show the item at the point myPoint in bold.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SetItem(hItem, TVIF_STATE, NULL, 0, 0, TVIS_BOLD,
                      TVIS_BOLD, 0);
}

`CTreeCtrl::SetItemData`

呼叫此函式，以設定與指定專案相關聯的應用程式特定值。

BOOL SetItemData(
    HTREEITEM hItem,
    DWORD_PTR dwData);

參數

hItem
要擷取其資料的專案控制碼。

dwData
與所 hItem 指定專案相關聯的指標大小應用程式特定值。

傳回值

如果成功則為非零；否則為 0。

範例

CString str;
HTREEITEM hItem;

// Insert 20 items into the tree control making every item's
// data be the handle of the item.
for (int i = 0; i < 20; i++)
{
   str.Format(TEXT("item %d"), i);
   hItem = m_TreeCtrl.InsertItem(str);

   if (hItem != NULL)
   {
      m_TreeCtrl.SetItemData(hItem, (DWORD_PTR)hItem);
   }
}

`CTreeCtrl::SetItemExpandedImageIndex`

設定當目前樹狀檢視控制項的指定專案處於展開狀態時，要顯示的影像索引。

BOOL SetItemExpandedImageIndex(
    HTREEITEM hItem,
    int iExpandedImage);

參數

hItem
[in]樹狀檢視控制項專案的控制碼。

iExpandedImage
[in]當指定的專案處於展開狀態時所要顯示的影像索引。

傳回值

TRUE 如果此方法成功，則為 ;否則為 FALSE 。

備註

這個方法會傳送 TVM_SETITEM 訊息，如 Windows SDK 中所述。這個方法會將 iExpandedImage 參數指派給 iExpandedImage 結構的成員 TVITEMEX ，然後在訊息中使用該結構。

範例

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

下一個程式碼範例是一項簡單的測試，可判斷方法是否 CTreeCtrl::GetItemExpandedImageIndex 傳回方法所 CTreeCtrl::SetItemExpandedImageIndex 設定的值。在未顯示的程式碼範例的先前區段中，我們建立了一個樹狀檢視，其中包含美國的根國家/地區節點、賓夕法尼亞州和華盛頓州的子節點，以及這些州城市樹狀專案。

CString str;
CString msg = _T("The set and retrieved item expanded image ")
              _T("indexes are%s equal.");
int nSetItem = 0;
m_treeCtrl.SetItemExpandedImageIndex(hCountry, nSetItem);
int nItem = m_treeCtrl.GetItemExpandedImageIndex(hCountry);
if (nItem == nSetItem)
   str.Format(msg, _T(""));
else
   str.Format(msg, _T(" not"));
AfxMessageBox(str, MB_ICONINFORMATION);

`CTreeCtrl::SetItemHeight`

此成員函式會實作 Win32 訊息 TVM_SETITEMHEIGHT 的行為，如 Windows SDK 中所述。

SHORT SetItemHeight(SHORT cyHeight);

參數

cyHeight
指定樹狀檢視中每個專案的新高度，以圖元為單位。如果這個引數小於影像的高度，則會將它設定為影像的高度。如果這個引數不是偶數，則會將它四捨五入為最接近的偶數值。如果這個引數是 -1，控制項會使用其預設專案高度還原為。

傳回值

專案先前的高度，以圖元為單位。

範例

請參閱的 CTreeCtrl::GetItemHeight 範例。

`CTreeCtrl::SetItemImage`

將影像與專案產生關聯。

BOOL SetItemImage(
    HTREEITEM hItem,
    int nImage,
    int nSelectedImage);

參數

hItem
要設定其影像的專案控制碼。

nImage
樹狀檢視控制項影像清單中的專案影像索引。

nSelectedImage
樹狀檢視控制項影像清單中的專案選取影像的索引。

傳回值

如果成功則為非零；否則為 0。

備註

樹狀檢視控制項中的每個專案都可以有一對與其相關聯的點陣圖影像。影像會出現在專案標籤的左側。選取專案時會顯示一個影像，另一個影像則會在未選取專案時顯示。例如，專案可能會在選取時顯示開啟的資料夾，而未選取時會顯示關閉的資料夾。

呼叫此函式，以在樹狀檢視控制項的影像清單中設定專案的影像及其選取影像的索引。

如需影像的詳細資訊，請參閱 CImageList 。

範例

請參閱的 CTreeCtrl::GetItemImage 範例。

`CTreeCtrl::SetItemState`

設定所 hItem 指定專案的狀態。

BOOL SetItemState(
    HTREEITEM hItem,
    UINT nState,
    UINT nStateMask);

參數

hItem
要設定其狀態的專案控制碼。

nState
指定專案的新狀態。

nStateMask
指定要變更的狀態。

傳回值

如果成功則為非零；否則為 0。

備註

如需狀態的資訊，請參閱 CTreeCtrl::GetItem 。

範例

請參閱的 CTreeCtrl::GetItemState 範例。

`CTreeCtrl::SetItemStateEx`

設定目前樹狀檢視控制項中指定專案的擴充狀態。

BOOL SetItemStateEx(
    HTREEITEM hItem,
    UINT uStateEx);

參數

hItem
[in]樹狀檢視控制項專案的控制碼。

uStateEx
[in]專案的擴充狀態。如需詳細資訊，請參閱 uStateEx 結構的成員 TVITEMEX 。

傳回值

TRUE 如果此方法成功，則為 ;否則為 FALSE 。

備註

這個方法會傳送 TVM_SETITEM 訊息，如 Windows SDK 中所述。這個方法會將 uStateEx 參數指派給 uStateEx 結構的成員 TVITEMEX ，然後在訊息中使用該結構。

範例

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

下一個程式碼範例會將樹狀檢視專案設定為停用狀態。在未顯示的程式碼範例的先前區段中，我們建立了一個樹狀檢視，其中包含美國的根國家/地區節點、賓夕法尼亞州和華盛頓州的子節點，以及這些州城市樹狀專案。此程式碼範例會將賓夕法尼亞州節點設定為停用狀態。

// Disable the Pennsylvania node.
m_treeCtrl.SetItemStateEx(hPA, TVIS_EX_DISABLED);

`CTreeCtrl::SetItemText`

設定所 hItem 指定專案的文字。

BOOL SetItemText(
    HTREEITEM hItem,
    LPCTSTR lpszItem);

參數

hItem
要設定其文字的專案控制碼。

lpszItem
包含專案新文字的字串位址

傳回值

如果成功則為非零；否則為 0。

範例

// Clear the text of the item at point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SetItemText(hItem, NULL);
}

`CTreeCtrl::SetLineColor`

呼叫這個成員函式，以設定樹狀檢視控制項目前的線條色彩。

COLORREF SetLineColor(COLORREF clrNew = CLR_DEFAULT);

參數

clrNew
新的線條色彩。

傳回值

上一行色彩。

備註

此成員函式會實作 Win32 訊息 TVM_SETLINECOLOR 的行為，如 Windows SDK 中所述。

範例

COLORREF clrPrev = m_TreeCtrl.SetLineColor(RGB(255, 0, 0));

`CTreeCtrl::SetScrollTime`

呼叫這個成員函式，以設定樹狀檢視控制項的最大捲動時間。

UINT SetScrollTime(UINT uScrollTime);

參數

uScrollTime
新的最大捲動時間，以毫秒為單位。如果此值小於 100，則會四捨五入為 100。

傳回值

先前的捲動時間上限，以毫秒為單位。

備註

此成員函式會實作 Win32 訊息 TVM_SETSCROLLTIME 的行為，如 Windows SDK 中所述。

`CTreeCtrl::SetTextColor`

此成員函式會實作 Win32 訊息 TVM_SETTEXTCOLOR 的行為，如 Windows SDK 中所述。

COLORREF SetTextColor(COLORREF clr);

參數

clr
COLORREF值，包含新的文字色彩。如果這個引數是 -1，控制項會還原為使用文字色彩的系統色彩。

傳回值

COLORREF值，表示先前的文字色彩。如果此值為 -1，控制項會針對文字色彩使用系統色彩。

範例

// change text color to white and background to dark blue
m_TreeCtrl.SetTextColor(RGB(255, 255, 255));
ASSERT(m_TreeCtrl.GetTextColor() == RGB(255, 255, 255));
m_TreeCtrl.SetBkColor(RGB(0, 0, 128));
ASSERT(m_TreeCtrl.GetBkColor() == RGB(0, 0, 128));

// force repaint immediately
m_TreeCtrl.Invalidate();

`CTreeCtrl::SetToolTips`

此成員函式會實作 Win32 訊息 TVM_SETTOOLTIPS 的行為，如 Windows SDK 中所述。

CToolTipCtrl* SetToolTips(CToolTipCtrl* pWndTip);

參數

pWndTip
樹狀目錄控制項將使用之物件的指標 CToolTipCtrl 。

傳回值

物件的指標 CToolTipCtrl ，包含控制項先前使用的工具提示，或 NULL 先前未使用任何工具提示。

備註

若要使用工具提示，請在 TVS_NOTOOLTIPS 建立 CTreeCtrl 物件時指出樣式。

範例

請參閱的 CTreeCtrl::GetToolTips 範例。

`CTreeCtrl::ShowInfoTip`

顯示目前樹狀檢視控制項中指定專案的資訊提示。

void ShowInfoTip(HTREEITEM hItem);

參數

hItem
[in]控制項中樹狀檢視專案的控制碼。如需詳細資訊，請參閱 hItem 結構的成員 TVITEMEX 。

備註

如需工具提示與資訊提示之間差異的詳細資訊，請參閱工具提示和資訊提示。

這個方法會傳送 TVM_SHOWINFOTIP 訊息，如 Windows SDK 中所述。

`CTreeCtrl::SortChildren`

呼叫此函式，以依字母順序排序樹狀檢視控制項中指定父專案的子專案。

BOOL SortChildren(HTREEITEM hItem);

參數

hItem
要排序其子專案之父專案的控制碼。如果 hItem 為 NULL ，則排序會從樹狀結構的根目錄繼續。

傳回值

如果成功則為非零；否則為 0。

備註

SortChildren 不會透過樹狀結構遞迴;只會排序的 hItem 直接子系。

範例

// Sort all of the items in the tree control.
m_TreeCtrl.SortChildren(TVI_ROOT);

`CTreeCtrl::SortChildrenCB`

呼叫此函式，以使用比較專案的應用程式定義回呼函式來排序樹狀檢視專案。

BOOL SortChildrenCB(LPTVSORTCB pSort);

參數

pSort
TVSORTCB 結構的指標。

傳回值

如果成功則為非零；否則為 0。

備註

如果第一個專案應位於第二個專案之前，則結構比較函 lpfnCompare 式必須傳回負值、如果第一個專案應該遵循第二個專案，則傳回正值，如果兩個專案相等，則傳回零。

lParam1和 lParam2 參數會對應至 lParam 所比較之兩個專案之 TVITEM 結構的成員。參數 lParamSort 會對應至 lParam 結構的成員 TV_SORTCB 。

範例

// Sort the item in reverse alphabetical order.
int CALLBACK MyCompareProc(LPARAM lParam1, LPARAM lParam2, LPARAM lParamSort)
{
   // lParamSort contains a pointer to the tree control.
   // The lParam of an item is just its handle, 
   // as specified with SetItemData
   CTreeCtrl* pmyTreeCtrl = (CTreeCtrl*)lParamSort;
   CString strItem1 = pmyTreeCtrl->GetItemText((HTREEITEM)lParam1);
   CString strItem2 = pmyTreeCtrl->GetItemText((HTREEITEM)lParam2);

   return strItem2.Compare(strItem1);
}

TVSORTCB tvs;

// Sort the tree control's items using my
// callback procedure.
tvs.hParent = TVI_ROOT;
tvs.lpfnCompare = MyCompareProc;
tvs.lParam = (LPARAM)&m_TreeCtrl;

m_TreeCtrl.SortChildrenCB(&tvs);

另請參閱

MFC 範例 CMNCTRL1
CWnd 類
 階層架構圖表
 CImageList 類

共用方式為

CTreeCtrl 類別

語法

成員

公用建構函式

公用方法

備註

繼承階層架構

需求

CTreeCtrl::Create

參數

傳回值

備註

範例

CTreeCtrl::CreateEx

參數

傳回值

備註

CTreeCtrl::CreateDragImage

參數

傳回值

備註

CTreeCtrl::CTreeCtrl

CTreeCtrl::DeleteAllItems

傳回值

範例

CTreeCtrl::DeleteItem

參數

傳回值

範例

CTreeCtrl::EditLabel

參數

傳回值

備註

範例

CTreeCtrl::EndEditLabelNow

參數

傳回值

備註

CTreeCtrl::EnsureVisible

參數

傳回值

備註

範例

CTreeCtrl::Expand

參數

傳回值

範例

CTreeCtrl::GetBkColor

傳回值

範例

CTreeCtrl::GetCheck

參數

傳回值

範例

CTreeCtrl::GetChildItem

參數

傳回值

範例

CTreeCtrl::GetCount

傳回值

範例

CTreeCtrl::GetDropHilightItem

傳回值

範例

CTreeCtrl::GetEditControl

傳回值

範例

CTreeCtrl::GetExtendedStyle

傳回值

備註

CTreeCtrl::GetFirstVisibleItem

傳回值

範例

CTreeCtrl::GetImageList

參數

傳回值

備註

範例

CTreeCtrl::GetIndent

`CTreeCtrl` 類別

`CTreeCtrl::Create`

`CTreeCtrl::CreateEx`

`CTreeCtrl::CreateDragImage`

`CTreeCtrl::CTreeCtrl`

`CTreeCtrl::DeleteAllItems`

`CTreeCtrl::DeleteItem`

`CTreeCtrl::EditLabel`

`CTreeCtrl::EndEditLabelNow`

`CTreeCtrl::EnsureVisible`

`CTreeCtrl::Expand`

`CTreeCtrl::GetBkColor`

`CTreeCtrl::GetCheck`

`CTreeCtrl::GetChildItem`

`CTreeCtrl::GetCount`

`CTreeCtrl::GetDropHilightItem`

`CTreeCtrl::GetEditControl`

`CTreeCtrl::GetExtendedStyle`

`CTreeCtrl::GetFirstVisibleItem`

`CTreeCtrl::GetImageList`

`CTreeCtrl::GetIndent`

`CTreeCtrl::GetInsertMarkColor`

`CTreeCtrl::GetItem`

`CTreeCtrl::GetItemData`

`CTreeCtrl::GetItemExpandedImageIndex`

`CTreeCtrl::GetItemHeight`

`CTreeCtrl::GetItemImage`

`CTreeCtrl::GetItemPartRect`

`CTreeCtrl::GetItemRect`

`CTreeCtrl::GetItemState`

`CTreeCtrl::GetItemStateEx`

`CTreeCtrl::GetItemText`

`CTreeCtrl::GetLastVisibleItem`

`CTreeCtrl::GetLineColor`

`CTreeCtrl::GetNextItem`

`CTreeCtrl::GetNextSiblingItem`

`CTreeCtrl::GetNextVisibleItem`

`CTreeCtrl::GetParentItem`