树控件 (STreeCtrl)¶

树控件是一个用于显示具有层级关系数据的控件，支持节点展开/折叠、复选框、图标显示等功能。它适合用于展示组织结构、文件系统等具有树形结构的数据。

基本信息¶

类名：STreeCtrl
控件标签：treectrl
基类：SScrollView
功能：提供树形结构数据的显示和管理功能

属性说明¶

基本属性¶

属性名	类型	默认值	说明
indent	int	-	缩进宽度
itemHeight	int	-	行高
itemMargin	int	-	项目边距
checkBox	bool	0	有复选框（0-没有，1-有）
rightClickSel	bool	0	右键选择（0-不支持，1-支持）

外观属性¶

属性名	类型	默认值	说明
itemBkgndSkin	string	-	列表项背景皮肤
itemSelSkin	string	-	选中项皮肤
toggleSkin	string	-	切换按钮皮肤
iconSkin	string	-	图标皮肤
checkSkin	string	-	复选框皮肤
colorItemBkgnd	color	-	Item背景颜色
colorItemSelBkgnd	color	-	选中项背景颜色
colorItemText	color	-	Item文本颜色
colorItemSelText	color	-	选中项文本颜色

使用示例¶

基本树控件¶

<treectrl name="treeBasic" 
          pos="10,10,310,310" 
          itemHeight="30"
          indent="20"
          colorItemText="#333333"
          colorItemBkgnd="#FFFFFF"
          colorItemSelBkgnd="#007ACC"
          toggleSkin="skin_tree_toggle"
          iconSkin="skin_tree_icons">
    <item text="组织机构" img="0" selImg="1" expand="1">
        <item text="市场部" img="0" selImg="1">
            <item text="南一区" img="2"/>
            <item text="北二区" img="2"/>
            <item text="西三区" img="2">
                <item text="第一分队" img="0" selImg="1" expand="0">
                    <item text="张三组" img="2"/>
                    <item text="李四组" img="2"/>
                    <item text="王五组" img="2"/>
                </item>
            </item>
        </item>
        <item text="宣传部" img="0" selImg="1" expand="0">
            <item text="南一区" img="2"/>
            <item text="北二区" img="2"/>
            <item text="西三区" img="2"/>
        </item>
    </item>
</treectrl>

带复选框的树控件¶

<treectrl name="treeWithCheckbox" 
          pos="330,10,630,310" 
          itemHeight="25"
          indent="25"
          checkBox="1"
          checkSkin="skin_tree_checkbox"
          colorItemText="#333333"
          colorItemSelText="#FFFFFF"
          colorItemBkgnd="#FFFFFF"
          colorItemSelBkgnd="#007ACC">
    <item text="项目" img="0" selImg="1">
        <item text="子项目1" img="2">
            <item text="任务1" img="3"/>
            <item text="任务2" img="3"/>
        </item>
        <item text="子项目2" img="2">
            <item text="任务3" img="3"/>
            <item text="任务4" img="3"/>
        </item>
    </item>
</treectrl>

自定义样式的树控件¶

<treectrl name="treeStyled" 
          pos="10,330,310,530" 
          itemHeight="35"
          indent="30"
          itemBkgndSkin="skin_tree_item"
          itemSelSkin="skin_tree_item_sel"
          toggleSkin="skin_tree_toggle_styled"
          iconSkin="skin_tree_icons_styled"
          colorItemText="#333333"
          colorItemSelText="#FFFFFF">
    <item text="我的电脑" img="0" selImg="1" expand="1">
        <item text="本地磁盘(C:)" img="2">
            <item text="Program Files" img="3"/>
            <item text="Windows" img="3"/>
        </item>
        <item text="本地磁盘(D:)" img="2">
            <item text="数据" img="3"/>
            <item text="备份" img="3"/>
        </item>
    </item>
</treectrl>

事件处理¶

树控件支持以下事件：

事件名	EventID	说明
EVT_TC_SELCHANGED	EventTCSelChanged::EventID	选择项改变事件
EVT_TC_ITEMEXPAND	EventTCItemExpand::EventID	项目展开/折叠事件
EVT_TC_ITEMCHECKED	EventTCItemChecked::EventID	项目复选框状态改变事件
EVT_TC_DBCLICK	EventTCDbClick::EventID	项目双击事件

// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_NAME_HANDLER(L"treeBasic", EventTCSelChanged::EventID, OnTCSelChanged)
    EVENT_NAME_HANDLER(L"treeWithCheckbox", EventTCItemChecked::EventID, OnTCItemChecked)
EVENT_MAP_END()

void OnTCSelChanged(IEvtArgs *pEvt)
{
    EventTCSelChanged *pRealEvt = sobj_cast<EventTCSelChanged>(pEvt);
    HSTREEITEM hSelItem = pRealEvt->hItem;
    // 处理选择项改变
}

void OnTCItemChecked(IEvtArgs *pEvt)
{
    EventTCItemChecked *pRealEvt = sobj_cast<EventTCItemChecked>(pEvt);
    HSTREEITEM hItem = pRealEvt->hItem;
    BOOL bChecked = pRealEvt->bChecked;
    // 处理复选框状态改变
}

代码操作¶

// 查找树控件
STreeCtrl *pTreeCtrl = FindChildByName2<STreeCtrl>(L"treeBasic");

// 插入新项
HSTREEITEM hRoot = pTreeCtrl->InsertItem(L"根节点", 0, 1);
HSTREEITEM hChild = pTreeCtrl->InsertItem(L"子节点", 2, 2, hRoot);

// 获取当前选中项
HSTREEITEM hSelItem = pTreeCtrl->GetSelectedItem();

// 选中指定项
pTreeCtrl->SelectItem(hChild);

// 获取项文本
SStringT strText = pTreeCtrl->GetItemText(hChild);

// 设置项文本
pTreeCtrl->SetItemText(hChild, L"新文本");

// 展开/折叠项
pTreeCtrl->Expand(hRoot, TVE_EXPAND);  // 展开
pTreeCtrl->Expand(hRoot, TVE_COLLAPSE); // 折叠

// 删除项
pTreeCtrl->DeleteItem(hChild);

// 获取父项
HSTREEITEM hParent = pTreeCtrl->GetParentItem(hChild);

// 获取子项
HSTREEITEM hFirstChild = pTreeCtrl->GetChildItem(hRoot);

最佳实践¶

合理设置缩进：通过 indent 属性设置合适的缩进宽度，确保层级关系清晰可见
视觉反馈：使用不同的皮肤和颜色属性区分不同状态的节点
交互设计：根据需要启用 checkBox 和 rightClickSel 属性
图标使用：合理使用图标提高节点可识别性
性能优化：对于大型树结构，考虑使用虚拟模式或延迟加载技术

常见问题¶

Q: 节点缩进显示不正确怎么办？¶

A: 检查 indent 属性是否设置合适，确保层级关系清晰可见。

Q: 复选框功能不工作怎么办？¶

A: 确保设置了 checkBox 属性为 1，并正确处理 EVT_TC_ITEMCHECKED 事件。

Q: 节点图标显示异常怎么办？¶

A: 检查 iconSkin 是否正确设置，以及 img 和 selImg 属性是否指定正确的图标索引。