CTreeCtrl

个 “ tree view 控件 ” 是一个用来显示项的层次列表的窗
口，比如一个文档中的标题，索引中的项，或磁盘中的文件和目录。每一个项都包括一个标签和一个可选的位图图像，每一个项还有一个与其相关的子项的列表。单击一个项，用户可以展开或缩进该项的相关子项的列表。

CTreeCtrl 类提供了 W indows 通用 tree view 控件的性能。这个控件（也就是

CTreeCtrl 类）只对运行在 W indows 95 和 W indows NT 3.51 或更高版本下的程序来说是可用的。

有关使用 CTreeCtrl 的更多信息，参见 “ V isual C++ 程序员指南 ” 中的 “ 控件主题 ” 和 “ 使用 CTreeCtrl” 。

#include <afxcmn.h>

请参阅 CImageList

CTreeCtrl 类成员

Construction
CTreeCtrl	构造一个	CTreeCtrl 对象
Create	创建一个	tree view 控件并将它与一个 CTreeCtrl 对
	象连接

Attributes

GetCount 获取与一个 treeview 控件相关联的 tree 项的数目

GetIndent 获取一个 tree view 项对它的父项的偏移（以像素

表示）

SetIndent 设置一个 tree view 项对它的父项的偏移（以像素

表示）

GetImageList 获取与一个 tree view 控件相关联的图像列表的句

柄

SetImageList 设置与一个 tree view 控件相关联的图像列表的句

柄

GetN e xtItem 获取与指定的关系匹配的下一个 tree view 项ItemHasChildren 如果指定项有子项则返回非零值 GetChildItem 获取一个指定 tree view 项的子项GetNextSiblingItem 获取指定 tree view 项的下一个兄弟项GetPrevSiblingItem 获取指定 tree view 项的前一个兄弟项GetParentItem 获取指定 tree view 项的父项GetFirstVisibleItem 获取指定 tree view 项的第一个可视项GetNextVisibleItem 获取指定 tree view 项的下一个可视项GetPrevVisibleItem 获取指定 tree view 项的前一个可视项GetSelectedItem 获取当前被选择的 tree view 项

续表

GetDropHilightItem 获取一次拖放操作的目标

GetRootItem 获取指定 tree view 项的根

GetItem 获取一个指定 tree view 项的属性

SetItem 设置一个指定 tree view 项的属性

GetItemState 返回一个项的状态

SetItemState 设置一个项的状态GetItemImage 获取与一个项相关联的图像SetItemImage 设置与一个项相关联的图像GetItemText 返回一个项的文本

SetItemText 设置一个项的文本

GetItemData 返回与一个项关联的 32 位的应用程序指定值SetItemData 设置与一个项关联的 32 位的应用程序指定值G etItemRect 获取一个 tree view 项的边界矩形

G etEditControl 获取用来编辑指定 tree view 项的编辑控件的句柄GetVisibleCount 获取与一个 tree view 项关联的可视 tree 项的编号GetToolTips 获取一个 tree view 控件使用的子 ToolTip 控件的的

句柄

SetToo lT ips 设置一个 tree view 控件的子 ToolTip 控件的的句柄

GetBkColor 获取控件的当前背景颜色

SetBkColor 设置控件的背景颜色

续表

GetItemHeight 获取 tree view 项的当前高度SetItemHeight 设置 tree view 项的当前高度GetTextColor 获取控件的当前文本颜色

SetTextColor 设置控件的文本颜色

SetInsertMark 设置一个 tree view 控件的插入标记

GetCheck 获取一个 tree 控件项的核选状态

SetCheck 设置一个 tree 控件项的核选状态

GetInsertMarkColor 获取 tree view 用来绘制插入标记的颜色

SetInsertMarkColor 设置 tree view 用来绘制插入标记的颜色

O perations

InsertItem 在一个 tree view 控件中插入一个新项。

DeleteItem 从一个 tree view 控件中删除一个项DeleteAllItems 从一个 tree view 控件中删除所有的项Expand 展开或收缩指定 tree view 项的子项

Select 选择，在视中滚动，或重画一个指定的 tree view

项

SelectItem 选择一个指定的 tree view 项

SelectDropTarget 重画作为一次拖放操作的目标的 tree 项

SelectSetFirstVisible 选择一个指定的 tree view 项作为第一个可视项

续表

EditLabel 现场编辑一个指定的 tree view 项

HitTest 返回与 CtreeCtrl 关联的光标的当前位置CreateDragImage 为指定的 tree view 项创建一个拖动位图SortChildren 排序一个给定父项的子项

EnsureVisible 确保一个 tree view 项在它的 tree view 控件中是可

视的

SortChildrenCB 使用一个由应用程序定义的排序函数来排列一个给

定父项的子项

成员函数

CTreeCtrl::Create

BOOL Create( DWORD dwStyle , const RECT& rect , CWnd* pParentWnd , UINT

nID );

返回值

如果初始化成功则返回非零值；否则返回 0 。

参数

dwStyle

指定 tree view 控件的风格。可以对这个控件使用 tree view 控件风格的任意组合。

rect

指定 tree view 控件的尺寸和位置。此参数可以是一个 CRect 对象或一个

RECT 结构。

pParentWnd

指定 tree view 控件的父窗口，通常是一个 CDialog 。它不能是 NULL 。

nID

说明

指定 tree view 控件的 ID 。

构造一个 CTreeCtrl 要分两步。首先调用构造函数，然后调用 Create 来创建这个 tree view 控件并将它与该 CTeeCtrl 对象连接。

下面的风格可以应用到一个 tree view 控件：

TVS_HASLINES tree view 控件的子项与它们的父项之间用线

连接。
TVS_LINESATROOT tree view 控件用线连接子项和根项。
TVS_HASBUTTONS tree view 在每一个父项的左边添加一个按

钮。
TVS_EDITLABELS tree view 控件允许用户编辑 tree view 项的标

签。
TVS_SHOWSELALWAYS 当 tree view 失去焦点时，使被选择的项

仍然保持被选择。
TVS_DISABLEDRAGDROP 该 tree view 控件被禁止发送。
TVN_BEGINDRAG 通知消息。
TVS_NOTOOLTIPS tree view 控件使用工具提示。
TVS_SINGLEEXPAND 当使用这个风格时，改变在 tree view 中

的选择将导致正被选择的项展开，而没有被选择的项收缩。如果用鼠标单击被选择的项，并且该项是关闭的，则该项就会展开。如果该被选择的项被单击时是打开的，则它就会收缩。

请参阅 CTreeCtrl:: CTreeCtrl, Tree View Control Window Styles in the Paltform SDK

CTreeCtrl::CreateDragImage

CImageList* CreateDragImage( HTREEITEM hItem );

返回值

如果成功，则返回指向图像列表的指针，拖动位图将被加入到其中去；否则返回 NULL 。

hItem

要被拖动的 tree 项的句柄。

说明

此成员函数用来为一个 tree view 控件中的给定项创建一个拖动位图，为位图创建一个图像列表，并将位图添加到该图像列表中。当项被拖动时，应用程序用图像 - 列表函数来显示图像。

CImageList 对象是持久的，当使用完它时你必须删除它。例如：

CImageList * pImageList = MyTreeCtrl.CreateDragImage( nItem, &point );

...

delete pImageList;

请参阅 CTreeCtrl::SelectDropTarget, CTreeCtrl::GetDropHilightItem, CTreeCtrl::SetImageList

CTreeCtrl::CTreeCtrl

CTreeCtrl( ) ;

此函数用来构造一个 CTreeCtrl 对象。

请参阅 CTreeCtrl::Create

CTreeCtrl::DeleteAllItems

BOOL DeleteAllItems( );

返回值

如果成功则返回非零值；否则返回 0 。

说明

此成员函数用来从 tree view 控件中删除所有的项。

请参阅 CTreeCtrl::DeleteItem, CTreeCtrl::InsertItem

CTreeCtrl::DeleteItem

BOOL DeleteItem( HTREEITEM hItem );

返回值

如果成功则返回非零值；否则返回 0 。

参数

hItem

要被删除的 tree view 项的句柄。如果 hItem 的值是 TVI_ROOT ，则所有的项都被从此 tree view 控件中删除。

说明

此成员函数用来从 tree view 控件中删除一个项。

请参阅 CTreeCtrl::DeleteAllItems, CTreeCtrl::InsertItem

CTreeCtrl::EditLabel

CEdir* EditLabel( HTREEITEM hItem );

返回值

如果成功则返回一个指向 CEdit 对象的指针，该对象被用来编辑该项的文本；否则返回 NULL 。

参数

hItem

要被编辑的 tree 项的句柄。

说明

此成员函数开始现场编辑指定项的文本。通过用一个单行编辑控件所包含的文本替换该项的文本来完成编辑。

请参阅 CTreeCtrl::GetEditControl

CTreeCtrl::EnsureVisible

BOOL EnsureVisible ( HTREEITEM hItem );

返回值

如果系统滚动 tree view 控件中的项以保证指定项可见则返回 TRU E 。否则，返回值为 FALSE 。

参数

hItem

要被变为可见的 tree 项的句柄。

说明

此成员函数用来保证一个 tree view 项是可见的。如果必要，函数扩展父项或滚动 tree view 扩展以使该项可见。

请参阅 CTreeCtrl::GetFirstVisibleItem, CTreeCtrl::GetVisibleCount

CTreeCtrl::Expand

BOOL Expand( HTREEETEM hItem , UINT nColor );

返回值

如果成功则返回非零值；否则返回 0 。

参数

hItem

要被扩展的 tree 项的句柄。

nCode

用来指示要被进行的动作的标志。这个标志可以是下列值之一：

TVE_COLLAPSE 收缩列表。
TVE_COLLAPSERESET 收缩列表并删除子项。
TVE_EXPAND 展开列表。
TVE_TOGGLE 如果列表当前是展开的则收缩列表；反之则

展开列表。

说明

此成员函数用来展开或收缩给定父项的子项列表（如果有）。

请参阅 CTreeCtrl::EnsureVisible

CTreeCtrl::GetBkColor

COLORREF GetBkColor( ) const;

返回值

返回一个代表当前背景颜色的 COLORREF 值。如果这个值是 -1 ，则控件正使用系统的颜色作为背景色。

说明

此成员函数用来实现 W in32 消息 TVM_GETBKCOLOR 的行为，就像在“ PlatformSDK ” 中描述的一样。

请参阅 CTreeCtrl::SetBkColor

CTreeCtrl::GetCheck

BOOL GetCheck( HTREEITEM hItem ) const;

返回值

如果该 tree 控件项是被核选的，则返回非零值；否则返回 0 。

参数

hItem

要获取有关其状态信息的 HTREEITEM 。

说明

此成员函数用来获取一个项的核选状态。

请参阅 CTreeCtrl::SetCheck

CTreeCtrl::GetChileItem

HTREEITEM GetChildItem( HTREEITEM hItem );

返回值

如果成功则返回该子项的句柄；否则返回 NULL 。

参数

hItem

个 tree 项的句柄。

说明

此成员函数用来获取由 hItem 指定的项的子项。

请参阅 CTreeCtrl::GetItem, CTreeCtrl::GetParentItem, CTreeCtrl::SortChildren

CTreeCtrl::GetCount

UINT GetCount( )

返回值

返回此 tree view 控件中的项的数目；否则返回 -1 。

此成员函数用来获取一个 tree view 控件中的项的数目。

请参阅 CTreeCtrl::GetVisibleCount

CTreeCtrl::GetDropHilightItem

HTREEITEM GetDropHilightItem( );

返回值

如果成功则返回项的句柄；否则返回 NULL 。

说明

此成员函数用来获取一次拖放操作的目标。

请参阅 CTreeCtrl::SelectDropTarget

CTreeCtrl::GetEditControl

CEdit* GetEditControl( )

如果成功则返回一个指向用来编辑项的文本的编辑控件的指针；否则返回

NULL 。

说明

此成员函数用来获取被用来编辑一个 tree view 项的文本的编辑控件的句柄。

请参阅 CTreeCtrl::EditLabel

CTreeCtrl::GetFirstVisibleItem

HTREEITEM GetFirstVisibleItem( );

返回值

如果成功则返回第一个可视项的句柄；否则返回 NULL 。

说明

此成员函数用来获取该 tree view 控件中的第一个可视项的句柄。

请参阅 CTreeCtrl::GetNextVisibleItem, CTreeCtrl::GetPrivVisibleItem, CTreeCtrl::EnsureVisible, CTreeCtrl::GetVisibleCount

CTreeCtrl::GetImageList

CImageList* GetImageList( UINT nImage )

返回值

如果成功则返回指向控件的图像列表的指针；否则返回 NULL 。

参数

nImage

要获取的图像列表的类型。该图像列表可以是下列类型之一：

TVSIL_NORMAL 获取常规的图像列表，它包含了该 tree view

项的被选择的和不被选择的图像。
TVSIL_STATE 获取状态图像列表，它包含了处于用户定义

状态的 tree view 项的图像。

说明

此成员函数用来获取与该 tree view 控件关联的常规或状态图像列表的句柄。一个 tree view 控件中的每一个项都有一对图像与之关联。当项被选择时就显示其中某一个图像，当项没有被选择时则显示另一个图像。例如，当一个项被选择时显示为一个打开的文件夹，而当它没有被选择时则显示为一个关闭的文件

夹。

有关图像列表的更多信息，参见 CImageList 类。

请参阅 CImageList, CTreeCtrl::SetImageList

CTreeCtrl::GetIndent

UINT GetIndent( );

返回值

返回以像素表示的缩进量。

说明

此成员函数用来获取子项相对于父项缩进的量。

请参阅 CTreeCtrl::SetIndent CTreeCtrl::GetInsertMarkColor COLORREF GetInsertMar k Color( ) const;

返回值

返回一个包含当前插入编辑颜色的 COLORREF 。

说明

此成员函数用来实现 W in32 消息 TVM_GETINSERTMARKCOLOR 的行为，就像在 “ PlatformSDK” 中描述的一样。

请参阅 CTreeCtrl::SetInsertMarkColor

CTreeCtrl::GetItem

BOOL GetItem( TVITEM* pItem );

返回值

如果成功则返回非零值；否则返回 0 。

参数

pItem

是一个指向 TVITEM 结构的指针，就像在 “ Platfor SDK” 中描述的一样。

说明

此成员函数用来获取指定 tree view 项的属性。

请参阅 CTreeCtrl::SetItem, CTreeCtrl::GetChildItem, CTreeCtrl::GetNextItem, CTreeCtrl::SelectItem

CTreeCtrl::GetItemData

DWORD GetItemData( HTREEITEM hItem ) const;

返回值

返回一个与由 hItem 指定的项关联的 32 位的应用程序指定值。

参数

hItem

要获取其数据的项的句柄。

说明

此成员函数用来获取与指定项关联 32 位的应用程序指定值。

请参阅 CTreeCtrl::SetItemData

CTreeCtrl::GetItemHeight

SHORT GetItemHeight( ) const;

返回值

返回以像素表示的项的高度。

说明

此成员函数用来实现 W in32 消息 TVM_GETITEMHEIGHT 的行为，就像在“ PlatformSDK ” 中描述的一样。

请参阅 CTreeCtrl::SetItemHeight

CTreeCtrl::GetItemImage

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

返回值

如果成功则返回非零值；否则返回 0 。

参数

hItem

要获取其图像的项的句柄。

nImage

个用来接收该 tree view 控件的图像列表中的该项图像
的索引的整数。

nSelectedImage

个用来接收该 tree view 控件的图像列表中的该项的被
选择图像的索引的整数。

说明

在一个 tree view 控件中每一个项有一对与之关联的位图图像。图像显示在一个项的标签的左边。其中一个项是在项被选择的时候显示的，另一个项是在项没有被选择的时候显示的。例如，当一个项被选择时它可能被显示为一个打开的文件夹，而当它没有被选择时则显示为一个关闭的文件夹。

此成员函数用来接收项的图像和被选择图像在该 tree view 控件的图像列表中的索引。

请参阅 CTreeCtrl::SetItemImage, CImageList

CTreeCtrl::GetItemRect

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

返回值

如果项是可视的则返回非零值，以及包含在 lpRect 中的边界矩形。否则，返回

0 和没有被初始化的 lpRect 。

参数

hItem

一个 tree view 项的句柄。

lpRec t

指向一个用来接收边界矩形的 RECT 结构的指针。其中的坐标是相对于该 tree view 控件的左上角的。

bTextOnly

如果这个参数是非零值，则边界矩形值包括项的文本。否则，它包括该项在 tree view 控件所占据的整个一行。

说明

此成员函数用来获取 hItem 的边界矩形，并确定该项是否是可视的。

请参阅 CTreeCtrl::GetVisibleCount, CTreeCtrl::GetNextVisibleItem, CTreeCtrl::GetPrevVisibleItem, CTreeCtrl::EnsureVisible

CTreeCtrl::GetItemState

UINT GetItemState( HTREEITEM hItem , UINT nStateMask ) const;

返回值

返回一个用来指定项的状态的 UINT 。可能取值的信息，参见

CTreeCtrl::GetItem 。

参数

hIte m

要获取其状态的项的句柄。

nStateMask

用来指定要获取哪些状态的掩码，有关 nStateMask 的可能取值的更多信息，参见 “ Platform SDK ” 中的有关 TVITEM 结构的 state 和 state M ask 成员的讨论。

说明

此成员函数返回由 hItem 指定的项的状态。

请参阅 CTreeCtrl::GetItem

CTreeCtrl::GetItemText

CString GetItemText( HTREEITEM hItem ) const;

返回值

返回一个包含该项的文本的 CString 对象。

参数

hItem

要获取其文本的项的句柄。

说明

此成员函数返回由 hItem 指定的项的文本。

请参阅 CTreeCtrl::SetItemText

CTreeCtrl::GetNextItem

HTREEITEM GetNextItem( HTREEITEM hItem , UINT nCode );

返回值

如果成功则返回下一个项的句柄；否则返回 NULL 。

参数

hItem

个 tree 项的句柄。

nCode

个用来指示与 hItem 的关系的类型的标志。这个标志

可以是下列值之一：
- TVGN_CARET 获取当前被选择的项。
- TVGN_CHILD 获取第一个子项。 hItem 参数必须是 NULL
  
  。
- TVGN_DROPHILITE 获取是一次拖放操作的目标的项。
- TVGN_FIRSTVISIBLE 获取第一个可见的项。
- TVGN_TEXT 获取下一个兄弟项。
- TVGN_NEXTVISIBLE 获取跟随在指定项之后的下一个可
  
  视项。
- TVGN_PARENT 获取指定项的父项。
- TVGN_PREVIOUS 获取前一个兄弟项。
- TVGN_PREVIOUSVISIBLE 获取在指定项之前的第一个可视
  
  项。
- TVGN_ROOT 获取根项的第一个子项，指定项是该根项
  
  的一个部分。

说明

此成员函数用来获取与 nItem 具有由 nCode 参数指定的关系的 tree view 项。

请参阅 CTreeCtrl::SetItem, CTreeCtrl::GetChildItem, CTreeCtrl::Getitem, CTreeCtrl::SelectItem, CTreeCtrl::GetPrevSiblingItem

CTreeCtrl::GetNextSiblingItem

HTREEITEM GgeNextSiblingItem ) HTREEITM hItem );

返回值

返回下一个兄弟项的句柄；否则返回 NULL 。

参数

hItem

一个 tree 项的句柄。

说明

此成员函数用来获取下一个兄弟项。

请参阅 CTreeCtrl::GetPrevSiblingItem, CTreeCtrl::GetChildItem, CTreeCtrl::GetItem, CTreeCtrl::SelectItem, CTreeCtrl::GetParentItem

CTreeCtrl::GetNextVisibleItem

HTREEITEM GetNextVisibleItem( HTREEITEM hItem );

返回值

返回下一个可视项的句柄；否则返回 NULL 。

参数

hItem

一个 tree 项的句柄。

说明

此成员函数用来获取 hItem 的下一个可视项。

请参阅 CTreeCtrl::GetPrevVisibleItem, CTreeCtrl::GetFirstVisibleItem, CTreeCtrl::EnsureVisible, CTreeCtrl::GetParentItem

CTreeCtrl::GetParentItem

HTREEITEM GetParentItem( HTREEITEM hItem );

返回值

返回父项的句柄；否则返回 NULL 。

参数

hItem

一个 tree 项的句柄。

说明

此成员函数用来获取 hItem 的父项。

请参阅 CTreeCtrl::GetChildItem, CTreeCtrl::GetRoolItem, CTreeCtrl::GetItem, CTreeCtrl::GetPrevSiblingItem

CTreeCtrl::GetPrevSiblingItem

HTREEITEM GetPrevSiblingItem(HTREEITEM hItem );

返回值

返回前一个兄弟项的句柄；否则返回 NULL 。

参数

hItem

一个 tree 项的句柄。

说明

此成员函数用来获取 hItem 的前一个兄弟项。

请参阅 CTreeCtrl::GetNextSiblingItem, CTreeCtrl::GetParentItem, CTreeCtrl::GetChildItem

CTreeCtrl::GetPrevVisibleItem

HTREEITEM GetPrevVisibleItem( HTREEITEM hItem );

返回值

返回前一个可视项的句柄；否则返回 NULL 。

参数

hItem

一个 tree 项的句柄。

说明

此成员函数用来获取 hItem 的前一个可视项。

请参阅 CTreeCtrl::GetNextVisibleItem, CTreeCtrl::GetFirstVisibleItem, CTreeCtrl::EnsureVisible, CTreeCtrl::GetVisibleCount

CTreeCtrl::GetRootItem

HTREEITEM GetRootItem( );

返回值

返回根项的句柄；否则返回 NULL 。

说明

此成员函数用来获取 hItem 的根项。

请参阅 CTreeCtrl::GetItem, CTreeCtrl::GetChildItem, CTreeCtrl::GetParentItem

CTreeCtrl::GetSelectedItem

HTREEITEM GetSelectedItem( );

返回值

返回被选择项的句柄；否则返回 NULL 。

说明

此成员函数用来获取此 tree view 控件中的当前被选择项。

请参阅 CTreeCtrl::Select, CTreeCtrl::SelectDropTarget, CTreeCtrl::GetDropHilightItem

CTreeCtrl::GetTextColor

COLORREF GetTextColor( ) const;

返回值

返回一个代表当前文本颜色的 COLORREF 值。如果这个值是 -1 ，则控件是使用系统颜色作为文本颜色。

说明

此成员函数用来实现 W in32 消息 TVM_GETTEXTCOLOR 的行为，就像在“ PlatformSDK ” 中描述的一样。

请参阅 CTreeCtrl::SetTextColor

CTreeCtrl::GetToolTips

CToolTipCtrl* GetToolTips( );

返回值

返回一个指向被 tree 控件使用的 CToolTipCtrl 对象的指针。如果 Create 成员函数使用了 TVS_NOTOOLTIPS 风格，则不会有工具提示控件被使用，此时返回值为 NULL 。

说明

此成员函数用来实现 W in32 消息 TVM_GETTOOLTIPS 的行为，就像在“ PlatformSDK ” 中描述的一样。

GetToolTips 的 MFC 实现返回一个被 tree 控件使用的 CToolTipCtrl 对象，而不是返回指向一个工具提示控件的句柄。

请参阅 CTreeCtrl::SetToolTips

CTreeCtrl::GetVisibleCount

UINT GetVisibleCount( );

返回值

返回 tree view 控件中的可见项的数目；否则返回 -1 。

说明

此成员函数用来获取一个 tree view 控件中的可视项的数目。

请参阅 CTreeCtrl::GetCount, CTreeCtrl::EnsureVisible

CTreeCtrl::HitTest

HTREEITEM HitT est( CPoint p t, UINT * pFlags ); HTREEITEM HitT est( TVHITTESTINFO* pHitTes tInfo );

返回值

返回位于指定点的 tree view 项的句柄，如果没有项位于该点，则返回 NULL 。

参数

要测试的点的客户坐标。

pFlags

指向一个用来接收有关点击测试的信息的整数的指针。它可以是说明部分中列出的 flags 成员值中的一个或多个。

pHitTes tInfo

一个包含点击测试的位置并接收测试结果的信息的 TVHITTESTINFO 结构的地址。

说明

此成员函数用来确定相对于一个 tree view 控件的客户区的指定点的定位。

当调用这个函数时， pt 参数指定要测试的点的坐标。此函数返回位于指定点的项的句柄，或者如果没有项位于该点则返回 NULL 。另外， pFlags 参数包含了指明指定点的定位的值。

请参阅 CTreeCtrl::GetItemRect

CTreeCtrl::InsertItem

HTREEITEM InsertItem( LPTVINSERTSTRUCT lpInsertStruct );

HTREEITEM InsertItem( UINT nMask , LPCTSTR lpszItem ,int nImage, int

nSelectedImage ,

UINT nState , UINT nStateMask , LPARAM lParam , HTREEITEM hParen t, HTREEITEM hInsertAfter );

H TREEITEM 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 );

返回值

如果成功则返回新项的句柄；否则返回 NULL 。

参数

lpInsertStruct

一个指向用来指定要插入的 tree view 项的属性的 TVINSERTSTRUCT 的指

nMask

用来指定要设置的属性的整数。

lpszItem

一个包含项的文本的字符串的地址。

nImage

项的图像在 tree view 控件的图像列表中的索引。

nSelectedImage

项的被选择图像在 tree view 控件的图像列表中的索引。

nState

为项的状态指定的值。

nStateMask

指定要设置的状态。

lParam

与此项关联的一个 32 位的应用程序指定的值。

hParent

要被插入的项的父项的句柄。

hInsertAfter

新项要被插入其后的项的句柄。

说明

此成员函数用来在一个 tree view 控件中插入一个新项。

请参阅 CTreeCtrl::DeleteItem, CTreeCtrl::HitTest, CTreeCtrl::SelectDropTarget, CTreeCtrl::Ge tItem

CTreeCtrl::ItemHasChildren

BOOL ItemHasChildren( HTREEITEM hItem );

返回值

如果由 hItem 指定的 tree 项有子项则返回非零值；否则返回 0 。

参数

hItem

一个 tree 项的句柄。

说明

此成员函数用来确定由 hItem 指定的 tree 项是否有子项。如果有，则你可以接着调用 CTreeCtrl::GetChildItem 来获取那些子项。

请参阅 CTreeCtrl::GetChildItem

CTreeCtrl::Select

BOOL Select( HTREEITEM hItem , UINT nCode );

返回值

如果成功则返回非零值；否则返回 0 。

参数

hItem

个 tree 项的句柄。

nCode

要进行的动作的类型。这个参数可以是下列值之一：

TVGN_CARET 设置给定项的选择。
TVGN_DROPHILITE 用指明一次拖放操作的目标的风格重画

给定的项。
TVGN_FIRSTVISIBLE 垂直滚动该 tree view 以使指定的项成为

第一个可见的项。

说明

此成员函数通过滚动使该项进入视中，或用指明一次拖放操作的目标的风格重

画该项，以选择给定的 tree view 项。

如果 nCode 包含的值是 TVGN_CARET ，则父窗口接收 TVN_SELCHANGING 和 TVN_SELCHANGED 通知消息。而且，如果指定项是一个收缩的父项的子项，则该父项的子项列表被展开以显示该指定项。在这种情况下，父窗口接收TVN_ITEMEXPANDING 和 TVN_ITEMEXPANDED 通知消息。

请参阅 CTreeCtrl::Select Item, CTreeCtrl::GetSelectedItem, CTreeCtrl::SelectDropTarget

CTreeCtrl::SelectDropTarget

BOOL SelectDropTarget( HTREEITEM hItem );

返回值

如果成功则返回非零值；否则返回 0 。

参数

hItem

一个 tree 项的句柄。

说明

此成员函数用指明一次拖放操作的目标的风格来重画该项。

请参阅 CTreeCtrl::SelectItem, CTreeCtrl::GetDropHilightItem, CTreeCtrl::CreateDragImage

CTreeCtrl::SetlectItem

BOOL SelectItem( HTREEITEM hItem );

返回值

如果成功则返回非零值；否则返回 0 。

参数

hItem

一个 tree 项的句柄。

说明

此成员函数用来选择给定的 tree view 项。如果 hItem 是 NULL ，则此函数不选择任何项。

请参阅 CTreeCtrl::Select, CTreeCtrl::GetSelectedItem, CTreeCtrl::SelectDropTarget

CTreeCtrl::SelectSetFirstVisible

BOOL SelectSetFirstVisible( HTREEITEM hItem );

返回值

如果成功则返回非零值；否则返回 0 。

参数

hItem

要被设置为第一个可视项的 tree 项的句柄。

说明

此成员函数用来垂直滚动该 tree view 以使指定的项成为第一个可视项。此函数用 TVM_SELECTITEM 和 TV G N _FIRSTVISIBLE 消息参数向窗口发送一个消息。

请参阅 CTreeCtrl::Select, CTreeCtrl::SelectItem, CTreeCtrl::SelectDropTarget

COLORREF SetBkColor( COLORREF clr );

返回值

返回一个代表当前文本颜色的 COLORREF 值。如果返回值是 -1 ，则控件正使用系统颜色作为文本颜色。

参数

clr

说明

个包含了新的背景颜色的 COLORREF 值。如果这个值是 -1
，则控件将改变为用系统颜色作为背景色。

此成员函数实现了 W in32 消息 TVM_SETBKCOLOR 的行为，就像在“ Platform SDK ” 中描述的一样。

请参阅 CTreeCtrl::GetBkColor

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

返回值

如果成功则返回非零值；否则返回 0 。

参数

hItem

用来接收改变的核选状态的 HTREEITEM 。

fCheck

表明是否要将 tree 控件项核选。缺省的， SetCheck 将该项设置为被核选的。

说明

此成员函数用来设置一个 tree 控件项的核选状态。当该 tree 控件项被核选（ fCheck

设置为 TRU E ），则该项显示一个邻近的核选标记。

请参阅 CTreeCtrl::GetCheck

CImageList* SetImageList( CImageList* pImageLis t, int nImageListType );

返回值

返回指向先前的图像列表的指针（如果有）；否则返回 NULL 。

参数

pImageList

指向要被分配的图像列表的指针。如果 pImageList 是 NULL ，则从 tree view

控件中删除所有的图像。

nImageListType

要设置的图像列表的类型。图像列表可以是下列值之一：

TVSIL_NORMAL 获取常规的图像列表，它包含了该 tree view

项的被选择的和不被选择的图像。
TVSIL_STATE 获取状态图像列表，它包含了处于用户定义

状态的 tree view 项的图像。

说明

此成员函数用来设置一个 tree view 控件的常规或状态图像列表，并使用新的图

像来重画该 tree view 项的图像。

请参阅 CImageList, CTreeCtrl::Get ImageList

CTreeCtrl::SetIndent

void SetIndent( UINT nIndent );

参数

nIndent

以像素表示的缩进的宽度。如果 nIndent 小于系统定义的最小宽度，则新的宽度被设置为系统定义的最小值。

说明

此成员函数用来为一个 tree view 控件设置缩进的宽度，并重画控件以反映新的宽度。

请参阅 CTreeCtrl::GetIndent, CTreeCtrl::GetItemRect

CTreeCtrl::SetInsertMark

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

如果成功则返回非零值；否则返回 0 。

参数

hItem

fAfter

用来指定将在哪一个项处放置插入标记的 HTREEITEM 。如果这个参数是 NULL ，则删除该插入标记。

用来指定是将插入标记放置在指定项的前面还是后面的 BOOL 值。如果这个参数是非零值，则插入标记将被放置在指定项之后。如果此参数是零，则将插入标记放置在指定项之前。

说明

此成员函数实现了 W in32 消息 TVM_SETINSERTMARK 的行为，就像在“ Platform SDK ” 中描述的一样。

CTreeCtrl::SetInsertMarkColor

COLORREF SetInsertMarkColor( COLORREF clrNew );

返回一个包含了先前的插入标记颜色的 COLORREF 值。

参数

clrNew

一个包含了新的插入标记颜色的 COLORREF 值。

说明

此成员函数实现了 W in32 消息 TVM_SETINSERTMARKCOLOR 的行为，就像在 “ Platform SDK ” 中描述的一样。

请参阅 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 );

如果成功则返回非零值；否则返回 0 。

参数

pItem

hItem

一个指向包含新项属性的 TVITEM 结构的指针，就像在 “ Platform SDK ” 中描述的一样。

要设置其属性的项的句柄。

nMask

指定要设置哪些属性的整数。

lpszItem

一个包含了项的文本的字符串的地址。

nImage

项的图像在 tree view 控件的图像列表中的索引。

nSelectedImage

该项的被选择图像在 tree view 控件的图像列表中的索引。

nState

指定项的状态值。

nStateMask

指定要设置哪些状态。

lParam

一个与该项关联的 32 位的应用程序定义值。

说明

此成员函数用来设置指定 tree view 项的属性。

在 TVITEM 结构中， hItem 成员标识了这个项， mask 成员指定了要设置的属性。如果 mask 成员或 nMask 参数指定的是 TVIF_TEXT 值，则 pszText 成员或 lpszItem

就是一个以空字符结尾的字符串的地址，而 cchTextMax 成员被忽略。如果 mask

（或 nMask ）指定的是 TVIF_STATE 值，则 stateMask 成员或 nStateMask 参数指定要改变的是哪一个项状态，而 state 成员或 nState 参数包含了那些状态的值。

请参阅 CTreeCtrl::GetItem

CTreeCtrl::SetItemData

BOOL SetItemData( HTREEITEM hItem , DWORD dwData );

返回值

如果成功则返回非零值；否则返回 0 。

参数

hItem

要获取其数据的项的句柄。

dwData

一个与由 hItem 指定的项关联的 32 位的应用程序指定值。

说明

此成员函数用来设置与指定项关联的 32 位的应用程序指定值。

请参阅 CTreeCtrl::GetIte mData

CTreeCtrl::SetItemHeight

SHORT SetItemHeight ( SHORT cyHeight );

返回值

返回以像素表示的项的先前的高度。

cyHeight

指定 tree view 中的每一个项的新高度。如果这个参数小于图像的高度，则它将被设置为图像的高度。如果这个参数不是偶数值，则它将被设置为与它最接近的小于它的偶数值。如果这个参数是 -1 ，则控件将变为使用它缺省的项高度。

说明

此成员函数实现了 W in32 消息 TVM_SETITEMHEIGHT 的行为，就像在“ Platform SDK ” 中描述的一样。

请参阅 CTreeCtrl::GetItemHeight

CTreeCtrl::SetItemImage

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

返回值

如果成功则返回非零值；否则返回 0 。

hItem

要设置其图像的项的句柄。

nImage

项的图像在 tree view 控件的图像列表中的索引。

nSelectedImage

项的被选择图像在 tree view 控件的图像列表中的索引。

说明

此成员函数用来设置项的图像和它的被选择图像在 tree view 控件的图像列表中的索引。

有关图像的更多信息，参见 CImageList 。

请参阅 CTreeCtrl::GetItemImage, CImageList

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

返回值

如果成功则返回非零值；否则返回 0 。

参数

hItem

要设置其状态的项的句柄。

nState

指定该项的新的状态。

nStateMask

指定要改变哪些状态。

说明

此成员函数用来设置由 hItem 指定的项的状态。有关状态的信息，参见

CTreeCtrl::GetItem 。

请参阅 CTreeCtrl::GetItem, CTreeCtrl::GetItemState

BOOL SetItemText( HTREEITEM hItem , LPCTSTR lpszItem );

返回值

如果成功则返回非零值；否则返回 0 。

参数

hItem

要设置其文本的项的句柄。

lpszItem

一个包含项的新文本的字符串的地址。

说明

此成员函数用来设置由 hItem 指定的项的文本。

请参阅 CTreeCtrl::GetItemText

CTreeCtrl::SetTextColor

COLORREF SetTextColor ( COLORREF clr );

个代表先前的文本颜色的 COLORREF 值。如果这个值是 -1
，则控件使用系统颜色作为文本的颜色。

参数

clr

个包含了新的文本颜色的 COLORREF 值。如果这个参数是
-1 ，则控件将变为使用系统颜色作为文本的颜色。

说明

此成员函数实现了 W in32 消息 TVM_SETTEXTCOLOR 的行为，就像在“ Platform SDK ” 中描述的一样。

请参阅 CTreeCtrl::GetTextColor

CTreeCtrl::SetToolTips

void SetToolTips( CToolTipCtrl* pWndTip ); CToolTipCtrl* SetToolTips ( CToolTipCtrl* pWndTip );

返回一个指向包含控件先前使用的工具提示的 CToolTipCtrl 对象，如果先前没有使用工具提示则返回 NULL 。

参数

pWndTip

一个指向将要被该 tree 控件使用的 CToolTipCtrl 对象的指针。

说明

此成员函数实现了 W in32 消息 TVM_SETTOOLTIPS 的行为，就像在 “ Platform SDK ” 中描述的一样。

要使用工具提示，则需要在创建 CTreeCtrl 对象时指定 TVS_NOTOOLTIPS 风格。

请参阅 CTreeCtrl::GetToolTips, CTreeCtrl::Create

CTreeCtrl::SortChildren

BOOL SortChildren ( HTREEITEM hItem );

如果成功则返回非零值；否则返回 0 。

参数

hItem

其子项要被排序的父项的句柄。如果 hItem 是 NULL ，则将从该 tree 的根项开始排序。

说明

此成员函数用来给一个 tree view 控件中的指定父项的子项进行排序。SorChildren

不会对整个 tree 进行递归；只对 hItem 的直接子项进行排序。

请参阅 CTreeCtrl::SortChildrenCB

CTreeCtrl::SortChildrenCB

BOOL SortChildrenCB( LPTVSORTCB pSort );

返回值

如果成功则返回非零值；否则返回 0 。

pSort

指向一个 TVSORTCB 结构的指针。

说明

此成员函数通过使用一个应用程序定义的用来比较各项的回收函数来排序 tree view 项。

如果第一项应该在第二项的前面，则结构的比较函数 lpfnCompare 必须返回一个负值；如果第一项应该在第二项的后面则返回一个正值，如果两个项相等则返回零。

lParam1 和 lParam2 参数分别对应于两个被比较项的 TVITEM 结构的 lParam 成员。 lParamSort 初始对应于 TV_SORTCB 结构的 lParam 成员。

请参阅 CTreeCtrl::SortChildren

CTreeCtrl

CTreeCtrl

CTreeCtrl 类 成 员

Attributes

O perations

成 员 函 数

CTreeCtrl 类成员

成员函数