Skip to content

树控件 (STreeCtrl)

Warning

The current page still doesn't have a translation for this language.

You can read it through google translate.

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

基本信息

  • 类名：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);

最佳实践

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

常见问题

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

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

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

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

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

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

相关控件