TTyTreeView 是 TyControls 库中的虚拟树控件,继承自 TTyCustomControl。它借鉴 VirtualTreeView 的架构:节点不是常规对象树,而是紧凑的 TTyTreeNode 记录链,按需(懒惰)初始化——控件只知道每层有多少节点,节点的文本 / 图标 / 子节点数量全部通过事件在真正需要绘制时才计算。因此它能在恒定内存下承载百万级节点。典型用途:文件资源管理器、多列数据表、带复选框 / 单选钮的层级列表、可拖拽重排的分组树。
在这之上还有一层可选的节点对象模型 Items(TTyTreeNodes),给"设计器里把树填好"和"从 LCL TTreeView 移植过来的代码"用。两种模式互斥,同时用会报错。Items 为空时(默认)控件与这层不存在时逐字节相同。详见第 3.5 节。
| 项目 | 值 |
|---|---|
| 单元 | tyControls.TreeView(列 / 表头模型在 tyControls.Columns) |
GetStyleTypeKey 返回值 |
'TyTreeView' |
| 基类 | TTyCustomControl(继承自 TCustomControl) |
在 .tycss 文件中,控件外框对应选择器前缀 TyTreeView。此外控件在绘制时还会解析若干子部件 typeKey(均不是独立控件,只是主题查找键):TyTreeNode(行)、TyTreeHeader(表头带)、TyTreeHeaderSection(表头分区)、TyTreeCheckBox(复选 / 单选框槽)。详见第 5 节。
主列的留白与间距。 主列的内容从 --treeview-margin(默认 4px,与列表的 --listview-text-margin 相同)开始,每一层的缩进都加在它后面,展开按钮、树线、复选框、图标和文字一起移动;文字前面的间距是 --treeview-icon-gap(默认 2px,前面有图标或复选框时生效)。这两个令牌可以只给这一棵树改,写进它的 StyleOverride,比如 --treeview-margin: 10px;;整个应用统一改,就写在主题或控制器的 StyleOverride 里,见 tycss 参考 §3.4。
树线与展开符号。 默认只在每个祖先的展开符号下面画一条竖线(--treeview-lines: guides),节点自己这一层不画,所以线不会穿过展开符号;要完整连线写 classic,不要线写 none。线型用 --treeview-lines-style(solid、dotted、dashed,或 6px 3px 这样的长度),颜色用 --treeview-lines-color(默认是树的边框色)。--treeview-expander: plus-minus 把展开符号换成带方框的 +/-,画在连线交汇的地方。内置皮肤 classic、xp 用的就是方框 +/- 加点线。这几个令牌同样可以只写进这棵树的 StyleOverride;ShowTreeLines := False 时一律不画线。详见 tycss 参考 §3.5。
uses tyControls.TreeView, tyControls.Columns;| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
Options |
TTyTreeOptions |
[] |
树级功能开关集合(见下表),默认全部关闭 |
Header |
TTyHeader |
见下 | 表头 / 列模型子对象(TPersistent,随控件流式保存) |
Items |
TTyTreeNodes |
空 | 设计期 / .lfm 里的节点树(集合,随控件流式保存)。非空即进入条目模式,此时节点的标题与结构由集合拥有。空集合=虚拟模式,与本属性存在之前逐字节相同。详见第 3.5 节 |
NodeDataSize |
Integer |
-1 |
每个节点尾部附带的用户数据块字节数;-1 表示无数据块。设置后每个节点分配 TreeNodeSize + NodeDataSize 字节 |
DefaultNodeHeight |
Integer |
18 |
未启用变高时每行的逻辑像素高度 |
RootNodeCount |
Cardinal |
0 |
根级(顶层)节点数量。写入即创建这么多未初始化的根节点骨架 |
Indent |
Integer |
16 |
每一层的缩进逻辑像素 |
Images |
TCustomImageList |
nil |
主列节点图标的图像列表,配合 OnGetImageIndex 使用。类型是 TCustomImageList(对齐 LCL),任何派生自它的列表都能赋值。列表是 TTyVirtualImageList / TTyLucideImageList 时,其中的字形图标跟着该行的文字色画(选中、禁用时也跟着变),图片不染色,见 imagecollection.md |
EmptyListMessage |
TCaption |
'' |
树为空时在内容区居中显示的提示文字 |
ShowButtons |
Boolean |
True |
是否绘制展开 / 折叠按钮(±方块) |
ShowTreeLines |
Boolean |
True |
是否绘制树线(总开关);画成什么样由主题令牌决定,见上文「树线与展开符号」 |
ShowRoot |
Boolean |
True |
根节点是否显示展开按钮 / 缩进(False 时根节点平铺无缩进) |
ToggleOnDblClick |
Boolean |
True |
双击一行是否展开 / 折叠该节点(双击展开按钮或复选框不算,那两处每次按下已经各自生效) |
HotTrack |
Boolean |
False |
是否高亮鼠标悬停行(:hover 状态) |
SearchTimeout |
Integer |
1000 |
键入查找(type-to-find)缓冲区空闲多少毫秒后自动重置 |
ScrollBars |
TScrollStyle |
ssBoth |
允许出现哪些方向的滚动条。ssNone = 视口固定(嵌在外层滚动容器里时用);被禁掉的那一轴偏移会归零 |
ScrollBarAutoHide |
TTyScrollBarAutoHide |
sbahDefault |
内嵌滚动条闲下来之后要不要淡出,转发给它们。默认跟主题走,三个值的含义与主题令牌见 scrollbar.md §7 |
AutoExpand |
Boolean |
False |
焦点移入的节点自动展开、移出的自动折叠(新焦点在旧节点子树内时不折叠) |
RightClickSelect |
Boolean |
True |
右键按下是否把焦点移到点中的节点。默认与 LCL 不同:LCL 默认 False,本控件一直是"右键跟随",故保留 True;要 LCL 行为设 False |
HideSelection |
Boolean |
True |
控件失去焦点时是否隐藏选中高亮(并排两棵树不会都显示强高亮)。隐藏=该行按普通行的主题样式绘制,不在控件里凭空造颜色 |
ShowSeparators |
Boolean |
False |
是否在每个顶层行下画一条分隔线(颜色取控件边框色 token,与树状连线同源) |
TabStop |
Boolean |
True |
是否参与键盘 Tab 焦点循环 |
这些成员只是把已有状态换成 LCL 的拼法暴露出来,不额外流式保存(避免 .lfm 里同一个开关出现两份互相打架的值):
| 成员 | 等价于 | 说明 |
|---|---|---|
RowSelect |
toFullRowSelect in Options |
整行选中 |
MultiSelect |
toMultiSelect in Options |
多选 |
ShowLines |
ShowTreeLines |
树状连线 |
ReadOnly |
not (toEditable in Options) |
默认 True(本控件就地编辑是 opt-in);ReadOnly := False 等于 Options + [toEditable] |
DefaultItemHeight |
DefaultNodeHeight |
同一个读写器,未显式设定时同样跟随 --item-height 密度令牌 |
| 标志 | 作用 |
|---|---|
toMultiSelect |
启用多选(Ctrl / Shift / Ctrl+A + 键盘范围扩展) |
toCheckSupport |
启用复选框 / 三态 / 单选钮支持(CheckType 生效、点击复选槽切换状态) |
toFullRowSelect |
整行高亮(而非仅标签区) |
toAutoTristateTracking |
复选状态自动向下传播(父勾则子全勾,之后才建出来的子节点也一样)+ 向上重算三态父节点;鼠标点击和代码设置 CheckState / Checked 都会联动 |
toVariableNodeHeight |
启用每节点变高,配合 OnMeasureItem 返回逐行高度 |
toIncrementalSearch |
启用键入查找:有焦点时键入可打印字符跳转到下一匹配的可见节点 |
toOwnerDraw |
启用逐单元格自绘 OnDrawNode(替换默认的文本和图标;行背景、选中高亮、树线、展开按钮、复选框照常绘制) |
toEditable |
启用就地编辑:F2 / 双击可编辑单元格弹出主题化 TTyEdit 覆盖框 |
toNodeDrag |
启用树内节点拖放(拖动节点在兄弟间重排 / 重设父级) |
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
Height |
Integer |
22 |
表头带高度 |
Columns |
TTyColumns |
空集合 | 列集合(TCollection);Columns.Add 追加一个 TTyColumn |
MainColumn |
Integer |
0 |
主列(绘制展开按钮 / 图标 / 树缩进的那一列)。见下方警告 |
SortColumn |
Integer |
-1 |
当前排序列(-1 = 未排序);点击表头自动更新 |
SortDirection |
TTySortDirection |
sdAscending |
当前排序方向 |
AutoSizeIndex |
Integer |
-1 |
自动填充剩余宽度的列索引(配合 hoAutoResize) |
Images |
TCustomImageList |
nil |
列头图标的图像源,按 TTyColumn.ImageIndex 取图。TTyVirtualImageList 早已是 TCustomImageList 的后代,本库的列表和 LCL 的列表都能赋值。目前只有 TTyListView 的报表表头会读它;树的表头绘制尚未接上。 |
Options |
TTyHeaderOptions |
[hoVisible, hoColumnResize, hoShowSortGlyphs, hoHeaderClickAutoSort, hoDrag] |
表头选项(见下) |
⚠️ 关键陷阱:MainColumn必须在列添加之后设置。SetMainColumn在Columns.Count = 0时会把任何赋值夹紧为NoColumn(-1)。若在添加任何列之前写MainColumn := 0,它会被夹成 -1,导致主列块永远不匹配——展开按钮、节点图标、主列文字全部消失,只剩平铺文本格。正确顺序是先Columns.Add,再设MainColumn。 作为兜底,控件在添加第一列且MainColumn仍为NoColumn时会自动把它默认为0(与 VirtualTreeView 一致);但显式的错误顺序仍应避免。示例(来自 showcase):with ColTree.Header do begin Columns.Add; Columns.Add; Columns.Add; Columns.Add; // 先加 4 列 MainColumn := 0; // 再设主列 end;
| 标志 | 作用 |
|---|---|
hoVisible |
在节点区上方绘制表头带 |
hoColumnResize |
允许拖动列分隔线调整列宽 |
hoShowSortGlyphs |
在排序列显示排序三角字形 |
hoHeaderClickAutoSort |
点击表头分区触发 SortTree(关掉时点击只触发 OnHeaderClick) |
hoDrag |
允许拖动列头重排列顺序 |
hoAutoResize |
令 AutoSizeIndex 列填充剩余宽度 |
| (表头图标) | Header.Images 设了时,列的 ImageIndex 画在表头分区标题前面 |
hoHotTrack |
高亮悬停的表头分区(TyTreeHeaderSection:hover);按住的分区按 :selected 画 |
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
Width |
Integer |
100 |
列宽(写入时夹紧到 [MinWidth, MaxWidth]) |
MinWidth |
Integer |
10 |
最小列宽 |
MaxWidth |
Integer |
10000 |
最大列宽 |
Position |
Cardinal |
添加顺序 | 视觉位置(0 基),可与集合 Index 不同(拖拽重排后) |
Alignment |
TAlignment |
taLeftJustify |
单元格文本对齐(主列也照它对齐) |
CaptionAlignment |
TAlignment |
taLeftJustify |
表头标题对齐 |
Text |
string |
'' |
表头标题文字 |
ImageIndex |
Integer |
-1 |
表头图标索引 |
Options |
TTyColumnOptions |
[coVisible, coResizable, coAllowClick, coDraggable] |
列级选项(coVisible / coResizable / coAllowClick / coDraggable / coAutoSpring)。coAutoSpring 的列在控件变宽 / 变窄时按各自宽度的比例分掉变化量;SizePriority 只有网格的 AutoFillColumns 用,树和列表视图的列在对象查看器里不显示它 |
Tag |
NativeInt |
0 |
用户自定义标记 |
Visible |
Boolean |
True |
列可见性。存储仍是 Options 里的 coVisible,这是它的一个视图(对标 LCL TGridColumn.Visible);stored False,由 Options 负责流式化 |
MinSize / MaxSize |
Integer |
同 MinWidth / MaxWidth |
LCL 对宽度上下限的叫法,别名。注意默认值与 LCL 不同:LCL 的 DEFMINSIZE/DEFMAXSIZE 都是 0(无界),这里是 10 / 10000 —— 要无界请显式写 0 |
SizePriority |
Integer |
1 |
分配多余宽度时这一列的权重(见 TTyCustomGrid.AutoFillColumns)。0 = 永不自动调宽。对标 LCL TGridColumn.SizePriority |
本控件有两个互斥的数据来源,选哪个由 Items 空不空决定:
| 虚拟模式(默认) | 条目模式 | |
|---|---|---|
| 触发 | Items.Count = 0 |
Items.Count > 0 |
| 结构 | RootNodeCount / SetChildCount / AddChild / OnInitChildren |
Items.AddChild(...)、.lfm 里的 Items 块 |
| 标题 | OnGetText / OnGetTextWithType 现算 |
TTyTreeNodeItem.Text |
| 每节点内存 | TreeNodeSize(+ NodeDataSize) |
TreeNodeSize + 4(块首 4 字节存条目下标) |
| 适用 | 百万节点、数据在 app 手里 | 设计期填好的树、从 LCL TTreeView 移植过来的代码 |
两边同时用会抛 ETyTreeItemMode,不会静默择一。 这是有意的:静默偏向 Items
就是"我的 OnGetText 不触发了",静默偏向事件就是"设计器里填的节点运行时不见了"——
两种都是要查很久的 bug。具体的闸门:
Items非空时再挂OnGetText/OnGetTextWithType→ 抛(反方向同样抛);Items非空时设NodeDataSize > 0→ 抛(条目模式征用了数据块头 4 字节;反方向同样抛);- 条目模式下调
RootNodeCount :=/SetChildCount/AddChild/DeleteNode→ 抛, 消息里会指出对应的条目层方法; - 流式化(
csLoading)期间发现的冲突记账、到Loaded再抛——否则报不报错就 取决于.lfm里Items和OnGetText谁先出现,而那个顺序不是用户写的。
Clear 是例外:它在两种模式下是同一件事("这棵树空了"),所以条目模式下它照做,
连 Items 一起清空,然后退回虚拟模式。
TTyTreeNodes 是 TCollection,顺序就是前序遍历序,父子关系由 Level 缩进推出。
三个好处:.lfm 里是可读可 diff 的文本块(LCL 存的是 Items.Data 十六进制 blob);
对象查看器的集合编辑器开箱即用;Items[i] 与 LCL 的绝对下标语义逐个对上。
Level 的规范化只在物化时做一次并写回:首项必须是 0,其余至多比前一项深 1 层。
于是手写 .lfm 里任何一串 Level 都对应唯一一棵合法树。
| 成员 | 类型 | 说明 |
|---|---|---|
Text |
TCaption |
节点标题。条目模式下这是标题的唯一来源 |
Level |
Integer |
缩进层级=树形。0 是顶层 |
ImageIndex / SelectedIndex |
Integer |
常态 / 选中态图标下标(-1 = 交给 OnGetImageIndex) |
Expanded |
Boolean |
展开态,物化后施加到记录节点上 |
CheckType / CheckState |
枚举 | 复选框类型与状态 |
Data |
Pointer |
app 的负载,不流式化(LCL TTreeNode.Data 的等价物) |
Node |
PTyTreeNode |
物化后对应的记录节点(只读) |
Parent / Count / Items(i) / HasChildren / SubTreeCount |
结构导航,全部由扁平序 + Level 现算 |
TTyTreeNodes 的建节点方法沿用 LCL TTreeNodes 的形状:
Add(Sibling, S) / AddFirst / AddChild(Parent, S) / AddChildFirst / Insert(Sibling, S),
外加 DeleteItem(Item)(连子树一起删——只 Delete(i) 会把子条目留成孤儿)、
GetFirstNode、TopLvlCount / TopLvlItems[]。
双击树(或右键「编辑节点...」)打开专用的节点结构编辑器——一棵树看全整个
Items 模型(任意深度),右侧「加节点 / 加子节点 / 删除 / 上移 / 下移」原地增删排序:
加节点插在选中行正下方(同层),加子节点下钻一层,删除连整棵子树,上下移动的是整个
子树块(跨过邻居的整个块,不是逐行挪)。树里选中任何节点,Object Inspector 直接显示
它的属性(文字、图标、展开态、勾选)当场改;窗口非模态,可以一直开着边搭边调。这就是
Delphi 的 "TreeView Items Editor" 体验——此前的标准集合编辑器(平面行 + 手填 Level
数字)仍可从 OI 里 Items 的省略号进入,做逐行手术用。
自己拥有数据源的后代(覆写了 DoGetText、自己调 AddChild 建树的那种,
典型如 TTyShellTreeView)必须覆写 SupportsItemModel 返回 False。
返回 False 时 Items 被当场拒绝(一句说得清的异常),设计期也不给它挂节点编辑动词。
TTyTreeView 继承自 TTyCustomControl(tyControls.Base),并 re-publish 了下列成员:
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
Align |
TAlign |
alNone |
父容器内停靠方式 |
Anchors |
TAnchors |
[akLeft, akTop] |
锚点布局 |
Font |
TFont |
系统默认 | 仅用于传递 PPI;字体族 / 字号由主题控制 |
StyleClass |
string |
'' |
CSS 变体类名,对应 .tycss 选择器的 .classname |
Controller |
TTyCustomStyleController |
nil(使用全局 TyDefaultController) |
指定样式控制器 |
树的行状态不存在单一 FHover / FPressed 上,而是逐节点记录在 TTyTreeNode.States(TTyNodeStates)里,绘制时逐行解析样式:
| 字段 / 集合成员 | 说明 |
|---|---|
FHotNode |
鼠标悬停的节点(HotTrack 时触发该行 :hover);nil 表示无 |
nsSelected(节点状态) |
该节点被选中,触发行 :selected |
nsExpanded / nsHasChildren |
展开态 / 是否有子节点(含未物化) |
nsInitialized / nsHeightMeasured |
懒惰初始化 / 变高测量标记 |
FFocusedNode / FSelectedNode |
当前焦点 / 单选节点指针 |
FSelectionCount |
多选计数(SelectedCount 读取) |
控件没有重写
CurrentStates——TyTreeView外框沿用基类的:hover/:focus/:disabled机制;行 / 复选框的:hover/:selected是绘制时对子 typeKey 单独解析样式实现的(见第 5 节)。
TTyTreeView 暴露的专有事件极多,按用途分组。
4.0 起这些事件的 Sender 是 TTyCustomTreeView(照 LCL:TTVExpandingEvent 一类写的是 TCustomTreeView)。TTyShellTreeView 和第三方从 TTyCustomTreeView 派生的树不是 TTyTreeView,事件交出来的就是它们自己。处理过程的签名照此写;3.0 的 Sender: TTyTreeView 要改成 Sender: TTyCustomTreeView,.lfm 不用动。
| 事件 | 类型 | 触发时机 |
|---|---|---|
OnInitNode |
TTyTreeInitNodeEvent |
节点首次初始化时;app 在 var InitStates 里 Include(ivsHasChildren) 等声明该节点特性 |
OnInitChildren |
TTyTreeInitChildrenEvent |
展开一个已声明 ivsHasChildren 的节点时;app 通过 var ChildCount 返回子节点数 |
OnFreeNode |
TTyTreeNodeEvent |
节点被释放前(用于清理节点数据块中的托管字段) |
OnExpanding |
TTyTreeChangingEvent |
展开之前;var Allowed := False 可否决 |
OnExpanded |
TTyTreeNodeEvent |
展开完成后 |
OnCollapsing |
TTyTreeChangingEvent |
折叠之前;var Allowed := False 可否决 |
OnCollapsed |
TTyTreeNodeEvent |
折叠完成后 |
| 事件 | 类型 | 触发时机 |
|---|---|---|
OnChanging |
TTyTreeChangingEvent |
选择 / 焦点移动之前;var Allowed := False 可否决——焦点和选中都不动。一次手势只问一次(FocusedNode := X 内部会转调 SetSelected,不会重复发问),对"同一个节点再设一次"这种空操作不发问 |
OnChange |
TTyTreeNodeEvent |
单选选择集实际变化时(SetSelected / ClearSelection) |
OnFocusChanged |
TTyTreeNodeEvent |
焦点节点变化时 |
OnSelectionChanged |
TNotifyEvent |
多选集合每次手势变化后触发一次(toMultiSelect) |
OnNodeClick |
TTyTreeNodeEvent |
单击某节点 |
OnNodeDblClick |
TTyTreeNodeEvent |
双击某节点 |
| 事件 | 类型 | 触发时机 |
|---|---|---|
OnChecking |
TTyTreeCheckingEvent |
勾选状态变化之前;var Allowed := False 可否决 |
OnChecked |
TTyTreeNodeEvent |
勾选状态变化后 |
| 事件 | 类型 | 触发时机 |
|---|---|---|
OnGetText |
TTyTreeGetTextEvent |
取节点文本(简单签名 var Text;单列 / 主列常用) |
OnGetTextWithType |
TTyTreeGetTextWithTypeEvent |
取单元格文本(完整签名,带 Column + TextType: ttNormal/ttStatic;多列用) |
OnGetImageIndex |
TTyTreeGetImageIndexEvent |
取节点图标索引(带 Kind + Column + var Ghosted)。Ghosted := True 会被采纳:该行图标按"不可用"绘制(走 TCustomImageList.Draw 的禁用灰化)。以前这个标志被收下就丢掉;后来只在多列分支接上,0 列(默认形态)仍然丢——现在两条分支都接上了。Kind 现在会被真的问到三次:ikNormal 每行都问,ikSelected 只对选中行问(以当前 ikNormal 结果为初值,handler 不管它就保持原图标,老代码渲染不变),ikOverlay 初值 -1、答了就叠画在普通图标之上。ikState 仍未实现(需要第二个图像列表和自己的槽位,见"注意事项") |
OnPaintText |
TTyTreePaintTextEvent |
画文字之前触发(同 VTV):TargetCanvas.Font 已经是这个单元格的字体,handler 改了颜色、样式(粗 / 斜 / 下划线 / 删除线)、字号或字体名,文字就按改后的画 |
OnMeasureItem |
TTyTreeMeasureItemEvent |
从 InitNode 触发(仅 toVariableNodeHeight),app 通过 var ANodeHeight 返回逐行高度(逻辑像素)。运行时打开该选项、或默认行高变了(DefaultNodeHeight、密度),已初始化的节点会再测一次 |
OnDrawNode |
TTyTreeDrawNodeEvent |
逐单元格自绘(仅 toOwnerDraw);在 BGRA 合成后、裁剪到单元格设备矩形时触发。这个单元格不再画默认的文本和图标,也不触发 OnPaintText;行背景、选中高亮、树线、展开按钮、复选框照常画在下面,复选框也照常能点。handler 在它们之后画,需要时可以盖住 |
OnAfterCellPaint |
TTyTreeCellPaintEvent |
每个绘制单元格之上的叠加层(独立于 toOwnerDraw),用于徽标 / 焦点环等装饰 |
OnIncrementalSearch |
TTyTreeIncrementalSearchEvent |
键入查找的自定义匹配谓词(不赋值时默认对主列文本做大小写不敏感前缀匹配) |
| 事件 | 类型 | 触发时机 |
|---|---|---|
OnColumnResized |
TTyTreeColumnEvent |
某列被拖动改变宽度后 |
OnColumnReorder |
TTyTreeColumnReorderEvent |
列被拖到新位置后(OldPosition, NewPosition) |
OnCompareNodes |
TTyTreeCompareEvent |
排序引擎比较两节点;app 返回 <0 / 0 / >0(自然序,方向由内部处理)。没挂时按该列的文字比较(不分大小写),表头点击排序也就能用了 |
OnHeaderClick |
TTyTreeColumnEvent |
点击表头分区后(若触发了排序,在排序之后发出)。不开 hoHeaderClickAutoSort 也触发;列去掉 coAllowClick 则不触发 |
| 事件 | 类型 | 触发时机 |
|---|---|---|
OnEditing |
TTyTreeEditingEvent |
编辑器打开之前;var Allowed(默认 True)设 False 否决该单元格编辑 |
OnNewText |
TTyTreeNewTextEvent |
提交时仅在文本实际改变才触发;app 把 NewText 写入自己的节点数据块 |
OnEditCancelled |
TTyTreeColumnNodeEvent |
Esc / 程序化 CancelEdit 时 |
OnEditingEnd |
TTyTreeEditingEndEvent |
编辑会话结束时必定触发一次,提交 Cancel = False,取消 Cancel = True。OnNewText 只在文本变了才发,所以它不能当"编辑器关了"的信号用 |
| 事件 | 类型 | 触发时机 |
|---|---|---|
OnNodeDragOver |
TTyTreeDragOverEvent |
拖拽过程中的逐目标 / 逐模式否决;Allowed 入参为 CanMoveNode(...) 结果,handler 只能进一步收紧(对无效移动设 Allowed := True 仍被 MoveNode 的硬闸拦下)。此前叫 OnDragOver,那个名字已还给 LCL 的拖放钩子 |
OnNodeMoved |
TTyTreeNodeEvent |
一次成功放下后(Node.Parent 已是新父节点) |
除上表外,
TTyTreeView还暴露基线事件集(Tier A 鼠标 / 通用 + Tier B 键盘 / 焦点事件,因其为可聚焦的TTyCustomControl)。完整清单见 ../events.md。内部内嵌的两个滚动条(VScroll/HScroll)是私有子部件,不暴露其事件。
表头的颜色、字重和分隔线颜色与数据表格共用 --grid-header-* 令牌,排序标记的形状、大小和颜色用 --sort-glyph、--sort-glyph-size、--sort-glyph-color。见 tycss 参考 §3.7。
外框 TyTreeView 沿用基类状态机;行 / 复选框子部件在绘制时单独解析伪类:
| 子 typeKey | 伪类 | 触发条件 |
|---|---|---|
TyTreeView |
:hover / :focus / :disabled |
外框整体(基类 CurrentStates) |
TyTreeNode |
:hover |
该行被鼠标悬停(HotTrack = True 时的 FHotNode) |
TyTreeNode |
:selected |
该节点 nsSelected |
TyTreeNode |
:disabled |
该节点不可用 |
TyTreeHeaderSection |
:hover / :selected |
表头分区的底色 / 文字色 / 字体;hoHotTrack 时鼠标下的分区是 :hover,按住的分区是 :selected |
TyTreeCheckBox |
:active / :selected / :disabled |
已勾选 / 选中行内 / 禁用的复选槽 |
TyTreeView { background: var(--input-bg); color: var(--on-surface);
border-color: var(--border); border-width: var(--input-border-width);
border-radius: var(--radius); padding: 2px;
font-size: var(--font-size-base); }
TyTreeNode { background: none; color: var(--on-surface); }
TyTreeNode:hover { background: var(--surface-hover); }
TyTreeNode:selected { background: var(--accent); color: var(--on-accent); }
TyTreeNode:disabled { color: var(--muted); }
TyTreeHeader { background: var(--surface-chrome); border-color: var(--border);
border-width: var(--input-border-width); color: var(--on-surface);
font-size: var(--font-size-base); font-weight: var(--font-weight-bold); }
TyTreeHeaderSection { background: none; color: var(--on-surface);
border-color: var(--border); }
TyTreeHeaderSection:hover { background: var(--surface-hover); }
TyTreeHeaderSection:selected{ background: var(--surface-active); }
TyTreeCheckBox { background: var(--input-bg); color: var(--on-surface);
border-color: var(--border);
border-width: var(--input-border-width);
border-radius: var(--radius-sm); }
TyTreeCheckBox:active { background: var(--accent); color: var(--on-accent);
border-color: var(--accent); }
TyTreeCheckBox:selected { background: var(--accent); color: var(--on-accent);
border-color: var(--accent); }
TyTreeCheckBox:disabled { color: var(--muted); }- 每行独立解析
TyTreeNode样式:先按:selected/:hover求得行背景,再在其上绘制展开按钮、树连线、图标、复选槽、文本。 - 主列(
MainColumn)承载缩进 / 展开按钮 / 图标 / 复选槽;其余列只绘制平铺文本。Indent决定每层左移量。 - 复选槽(
TyTreeCheckBox)依CheckType绘制勾号(ctCheckBox/ctTriStateCheckBox)或圆点(ctRadioButton);三态csMixed绘制半勾。 - 排序三角字形仅在
hoShowSortGlyphs且该列为SortColumn时绘制。 - 内嵌滚动条使用各自的
TyScrollBar主题,且 thumb 不做缓动动画(内嵌滚动直接跟随)。
横轴只有两处算 x。 列的屏幕跨度出自
TyColumnSpan(tyControls.Columns.pas)—— 绘制、表头、拖列浮标、GetCellRect与两个命中函数都从它取Left/Right; 节点内部的缩进 / 展开槽 / 复选槽 / 图标槽 / 标题起点出自NodeCaptionSlots(它包装纯函数TyTreeCaptionSlots)——两处绘制、命中判定、CellTextRect和DisplayExpandSignRect都读它。这两条是有意维持的: "画在这边、点在那边"这类 bug 只能从第二份算式里长出来。 改这个文件时请保持它 —— 任何在这两个函数之外新算出来的 x,都是一条会走散的第二路径。锚点也统一了。 命中判定曾经给
NodeCaptionSlots传锚点0,即假设主列从内容区 左缘开始;Header.MainColumn不是最左可见列时该假设不成立,展开箭头画在Scale(MainColumn.Left)处、却在原处接收点击 —— 点箭头不展开。现在它传MainCellAnchor,与绘制端取自同一个Span()。随之确定了一条分区规则: 主列单元格左边的那一段属于别的列的正文,回答hpLabel,不带任何 chrome —— 和主列右边的非主列单元格一直以来的答案一致。坐标空间也只剩一个:设备像素。
ColumnFromPosition/DetermineSplitterIndex收的(AX, AOriginX, APPI)就是绘制端交给Span()的同一组参数。它们曾经先折算成 逻辑像素再比较,同一条边界被取整两次,PPI ≠ 96 时某一列的最后一个设备像素会命中成 下一列。分隔条的 ±3/5 容差仍是逻辑量(描述手感),在函数内部按 APPI 放大。
设计期填树用对象查看器(双击控件即可);代码里就是下面这样——这也是从 LCL
TTreeView 移植过来的写法,Items.AddChild(nil, 'Root') 一字不改:
uses tyControls.TreeView;
var
Tree: TTyTreeView;
Root, Docs: TTyTreeNodeItem;
begin
Tree := TTyTreeView.Create(Self);
Tree.Parent := Self;
Tree.Align := alClient;
Root := Tree.Items.AddChild(nil, 'This PC');
Docs := Tree.Items.AddChild(Root, 'Documents');
Tree.Items.AddChild(Docs, 'report.odt');
Tree.Items.AddChild(Root, 'Pictures');
Root.Expanded := True;
// 树上显示的字就是条目的 Text
Assert(Tree.NodeText[Docs.Node] = 'Documents');
Assert(Tree.IsItemMode);
// 注意:此时再挂 OnGetText 会抛 ETyTreeItemMode —— 两个数据源不能同时用
end;批量建树请包在 Tree.Items.BeginUpdate / EndUpdate 里:每次结构变更都会重物化
一次整棵树,批处理里只做一次。
下例镜像 showcase 中「Columns + Sort」页的用法:多列 + 数据在节点 + 稳定排序 + 就地编辑 + 图标。注意它没有用 Items——两种模式互斥。
uses
tyControls.Controller, tyControls.TreeView, tyControls.Columns;
type
{ 稳定的逐节点数据(存在节点数据块里,不依赖 Node^.Index,排序后仍随行走) }
TRowRec = record NameIdx, Kind: Integer; Size: Int64; end;
PRowRec = ^TRowRec;
// 加载主题
TyDefaultController.LoadTheme('themes/light.tycss');
// 创建树
var Tree: TTyTreeView;
Tree := TTyTreeView.Create(Self);
Tree.Parent := Self;
Tree.Align := alClient;
// 每节点附带 TRowRec 数据块
Tree.NodeDataSize := SizeOf(TRowRec);
// 启用就地编辑
Tree.Options := [toEditable];
// 挂接虚拟模型 + 绘制 + 排序事件
Tree.OnInitNode := @TreeInitNode;
Tree.OnInitChildren := @TreeInitChildren;
Tree.OnGetTextWithType := @TreeGetText;
Tree.OnCompareNodes := @TreeCompareNodes;
// 建列 —— 先加列,再设 MainColumn(顺序至关重要,见第 3 节警告)
with Tree.Header do
begin
Options := [hoVisible, hoColumnResize, hoShowSortGlyphs,
hoHeaderClickAutoSort, hoDrag];
(Columns.Add as TTyColumn).Text := 'Name';
(Columns.Add as TTyColumn).Text := 'Size';
MainColumn := 0; // ← 一定在 Columns.Add 之后
end;
// 3 个根节点(懒惰初始化,此刻不创建任何子结构)
Tree.RootNodeCount := 3;
// —— 事件处理器 ——
procedure TForm1.TreeInitNode(Sender: TTyCustomTreeView;
ParentNode, Node: PTyTreeNode; var InitStates: TTyNodeInitStates);
var data: PRowRec;
begin
if Sender.GetNodeLevel(Node) = 0 then
Include(InitStates, ivsHasChildren); // 顶层是文件夹,可展开
data := PRowRec(Sender.GetNodeData(Node));
if data <> nil then
data^.NameIdx := Integer(Node^.Index); // 存稳定 key,排序后不失效
end;
procedure TForm1.TreeInitChildren(Sender: TTyCustomTreeView;
Node: PTyTreeNode; var ChildCount: Cardinal);
begin
ChildCount := 5; // 展开时懒惰返回子节点数
end;
procedure TForm1.TreeGetText(Sender: TTyCustomTreeView; Node: PTyTreeNode;
Column: Integer; TextType: TTyVSTTextType; var CellText: string);
var data: PRowRec;
begin
if TextType <> ttNormal then Exit;
data := PRowRec(Sender.GetNodeData(Node));
case Column of
0: CellText := Format('Item %d', [data^.NameIdx]);
1: CellText := IntToStr(data^.Size);
end;
end;
procedure TForm1.TreeCompareNodes(Sender: TTyCustomTreeView;
Node1, Node2: PTyTreeNode; Column: Integer; var CompareResult: Integer);
var d1, d2: PRowRec;
begin
d1 := PRowRec(Sender.GetNodeData(Node1));
d2 := PRowRec(Sender.GetNodeData(Node2));
CompareResult := d1^.NameIdx - d2^.NameIdx; // 读数据块,绝不读 Node^.Index
end;启用其他能力只需改 Options + 挂对应事件:
// 复选框(三态自动传播)
Tree.Options := [toCheckSupport, toAutoTristateTracking];
// 在 OnInitNode 里:Node^.CheckType := ctTriStateCheckBox;(或 ctCheckBox / ctRadioButton)
// 多选 + 整行高亮
Tree.Options := [toMultiSelect, toFullRowSelect];
Tree.OnSelectionChanged := @OnSelChanged; // 内读 Tree.SelectedCount
// 节点拖放
Tree.Options := [toNodeDrag];
Tree.OnNodeMoved := @OnMoved;| 现在 | 以前 | 为什么必须改 |
|---|---|---|
GetNodeAt(X, Y: Integer): PTyTreeNode |
—— | LCL 的 GetNodeAt 就是"客户区某点上的节点"(comctrls.pp:3716) |
GetNodeAtOffset(Y; out ANodeTop) |
GetNodeAt(Y; out ANodeTop) |
同名、同参数个数、两个参数都是 Integer,所以移植过来的 Tree.GetNodeAt(X, Y) 会编译通过:把调用方的 X 当成滚动空间的 Y 用,再把调用方的 Y 变量用 out 参数覆写掉,返回错误的节点且没有任何警告。改名当天本仓库自己的 12 条断言立刻变红,就是这条路径 |
NodeSelected[Node]: Boolean |
Selected[Node]: Boolean |
Selected 在 LCL 是当前节点(comctrls.pp:3778)。if Tree.Selected <> nil / Tree.Selected := N 这两句最常写的代码在带下标的布尔属性上根本编不过 |
OnNodeDragOver |
OnDragOver |
OnDragOver 是 TControl 的 LCL 拖放钩子,TTyTreeView 跟别的 Ty 控件一样发布它。树把这个名字占成了内部节点拖放的否决事件,于是整个库里只有这一个控件不能当 LCL 拖放目标——往上挂一个正常的 TDragOverEvent 是类型错误 |
迁移只有三条替换:GetNodeAt(y, top) → GetNodeAtOffset(y, top);Selected[n] → NodeSelected[n];OnDragOver := @H → OnNodeDragOver := @H。
| 成员 | 说明 |
|---|---|
Selected: PTyTreeNode |
当前节点。读:焦点节点(选中时),否则第一个选中节点,都没有则 nil。写:独占选中并把焦点移过去;写 nil 等于 ClearSelection |
SelectionCount / Selections[i] |
多选的随机访问,让 for i := 0 to SelectionCount-1 do Use(Selections[i]) 直接可用。类型是 Integer 不是 LCL 的 Cardinal——空选择时 Cardinal(0) - 1 会绕成 40 亿。Selections[i] 每次都是 O(n) 线性走,热循环仍请用 GetFirstSelected / GetNextSelected |
GetLastSelected |
屏幕序里最后一个选中节点 |
NodeVisible[Node]: Boolean |
隐藏单个节点及其子树而不删除它——过滤要的就是这个形状。引擎一直支持不可见节点(各处遍历都看 nsVisible),只是开关没暴露,于是过滤只能删了再加。隐藏会把该节点的子树高度从祖先链上扣掉(ContentHeight / 滚动条 / 位置缓存同步),并且不会把光标或选中留在一个不绘制的行上。故意不叫 Visible:LCL 把它挂在 TTreeNode(一个类)上,我们的节点是记录,只能挂到控件上——而控件上的 Visible 已经是"这个控件显不显示",同名带下标属性会把 TControl.Visible 遮掉,Tree.Visible := False 直接编不过。命名与 NodeSelected 一致 |
HasChildren[Node]: Boolean |
可反复设置的"有没有子节点"。以前只能从 OnInitNode 的 ivsHasChildren 回答一次,ivsReInit 又没有公开触发点,所以一个"后来才变成非空"的目录永远长不出展开箭头。写 False 会先折叠,避免留下一堆没法收起来的行 |
ScrolledTop / ScrolledLeft |
可读可写的滚动位置(LCL 的符号约定:已滚走的像素数,即 -OffsetY / -OffsetX)。刷新前后保存 / 恢复滚动位置靠它 |
TopItem / BottomItem |
视口顶 / 底的节点;TopItem := N 把 N 滚到顶部 |
DisplayRect(Node, TextOnly, out R) |
行矩形 / 仅标题矩形(设备像素,ContentRect 坐标系) |
DisplayTextLeft(Node, out L) |
标题起始 X——把浮层锚到文字而不是整格时要的那个值 |
DisplayExpandSignRect(Node, out R) |
展开箭头的方框;没有箭头的节点返回 False |
GetNodeWithExpandSignAt(X, Y) |
只在展开箭头上才回答的命中测试 |
GetHitTestInfoAt(X, Y): THitTests |
LCL 的集合型命中结果(comctrls.pp:41),能同时表达 htOnItem + htOnLabel;我们自己的 GetNodeAtPoint 返回的是单值枚举,表达不了这种组合 |
AlphaSort(Node = nil) |
按节点主列文本排序,不需要任何 compare handler。Sort / SortTree 都走 DoCompare → OnCompareNodes,没挂 handler 时按单元格文字比较(以前返回 0,"按字母排序"这个最常见的需求是个静默的空操作) |
CustomSort(SortProc, Node = nil) |
用一个普通函数(非方法指针)排序;结束后归还 app 原来的 OnCompareNodes |
Items: TTyTreeNodes |
可流式化、设计期可编辑的节点集合。Items.AddChild(nil, 'Root') 这一行移植过来现在编得过也真的建树。详见第 3.5 节 |
NodeText[Node]: string |
LCL Node.Text 的等价物(只读)。节点是记录不是类,挂不了成员,所以按本控件既有约定挂到控件上做带下标属性——与 NodeSelected[] / NodeVisible[] 同一条命名规则。两种模式都答"屏幕上那一行真正显示的字" |
NodeItem[Node]: TTyTreeNodeItem |
记录节点 → 条目对象的 O(1) 反查;虚拟模式下恒为 nil |
IsItemMode: Boolean |
当前数据源是 Items 还是事件。模式是从 Items 空不空推出来的,所以必须能读出来 |
SupportsItemModel: Boolean(virtual) |
这个后代能不能用条目模型。自己拥有数据源的后代覆写成 False |
NodeMemSize: Integer |
一个节点占多少字节。"一百万个节点要多少内存"是这个控件该能回答的问题,也是"虚拟模式一个字节都不多占"唯一的可断言形式 |
—— 已实现,见第 3.5 节。结论从"不打算有"翻过来的理由:本库一个文件之外的Items/TTreeNodes/Node.Text那套可流式化的节点对象模型没有,也不打算有TTyListView早就同时有集合模式与虚拟模式(OwnerData),并且只有一处模式分支;树照抄那条约定即可,虚拟路径逐字节不变。仍与 LCL 有两处有意的差异:.lfm里存的是可读的集合文本块(Items = <item Text=... Level=...>),不是 LCL 的Items.Data十六进制 blob——所以 LCL 的.lfm节点块不能直接拷过来,反之亦然;- 条目没有
SubItems:LCL 的TTreeNode也没有,所以多列树的第 2 列及以后在条目模式下是空的。要多列内容仍需虚拟模式。这是个纯增量的缺口,以后补不会破坏现在的行为。
ikState/StateImages:需要第二个图像列表和它自己的行内槽位(会牵动命中测试、标题矩形、编辑器定位三处几何),本轮没做。ikNormal/ikSelected/ikOverlay已可用。ToolTips:没有"标题被裁剪时自动弹出完整文本"的逐项提示,只有继承自TControl的整控件Hint。SortType(插入时自动保持有序)、Cut/DropTarget逐节点显示态、逐节点Enabled/DisabledFontColor、OnCustomDraw*整行/整控件分阶段绘制、InsertMark*外部拖放插入标记——均未实现。TreeLineColor/TreeLinePenStyle/ExpandSignColor|Size|Width/SeparatorColor这类逐控件颜色与线型旋钮按本库硬规则不做:视觉值一律走主题 token。树状连线与分隔线取控件边框色 token,展开箭头取行文字色 token 并支持--glyph-chevron-down/--glyph-chevron-right覆盖。
MainColumn必须在列添加之后设置(本文档最重要的陷阱):Columns.Count = 0时SetMainColumn把值夹紧为NoColumn(-1),主列块永不匹配 → 展开按钮 / 图标 / 主列文字全部消失。控件仅在添加第一列时自动把NoColumn兜底为0;显式错误顺序仍会出问题。删除列时控件会自动跟随重编号修正MainColumn。Items与OnGetText不能同时用(本轮新增的第二重要陷阱):Items非空即进入条目模式,此时再挂OnGetText/OnGetTextWithType/ 设NodeDataSize/ 调RootNodeCount :=都会抛ETyTreeItemMode,反方向同样。控件不会静默择一。二选一:清空Items走虚拟模式,或者移除事件走条目模式。见第 3.5 节。- 虚拟 = 数据在你手里,不在树里(这一段只适用于虚拟模式,即
Items为空时):树本身不存文本 / 图标 / 子节点。文本经OnGetText/OnGetTextWithType现算;子节点数经OnInitChildren现算。持久数据放进节点数据块(NodeDataSize+GetNodeData),不要用Node^.Index作为持久 key——排序会重新戳Index,稳定 key 必须存在数据块里。 - 三阶段懒惰初始化:①
RootNodeCount :=创建根节点骨架(未初始化);② 首次需要一个节点时InitNode触发OnInitNode,app 声明ivsHasChildren/ivsExpanded/ivsSelected;③ 展开一个声明了有子节点的节点时InitChildren触发OnInitChildren物化子节点。恒定内存直到用户实际展开。 - 变高节点:
toVariableNodeHeight+OnMeasureItem才生效;测量在InitNode末尾进行一次,运行时打开选项或默认行高变化时,已初始化的节点重新测量。未启用时每行都用DefaultNodeHeight,用NodeHeight[]单独设过高度的行除外。PgUp / PgDn 按各行的实际高度翻一页。 OnNodeDragOver只能收紧不能放宽:CanMoveNode是硬闸(非空、模式非dmNone、目标不在源子树内、非空操作等),对无效移动即便 handler 设Allowed := True也会被MoveNode拦下。OnAfterCellPaint与OnDrawNode的裁剪时机:二者都在 BGRA 图层合成到画布之后触发(跨平台后处理路径)。因此没有「在默认文本下方绘制背景」的OnBeforeCellPaint——那需要不同的绘制路径,目前未实现。ACellRect是整个单元格,不是标题文字的位置:0 列树里它就是整行(Column = -1),左边缘属于缩进、展开箭头和图标槽。从ACellRect.Left起画,不同层级的标题会全落在同一个 x 上、压在箭头和树线上。要问「这一行的标题该从哪开始」,用DisplayRect(Node, True, R)(或DisplayTextLeft)——它走的是绘制侧同一次槽位走查,与默认标题的落点逐像素一致。- 自绘 handler 借的是宿主画布,改了什么就要还回去:
ACanvas是控件自己的画布,同一次绘制里后面每个单元格、以及下一次绘制,都继承你留下的Font.Color/Brush/Pen。本库自带的 Owner-draw 示例就栽在这上面:叠加层把Font.Color留成了clWhite,白底上的子行标题整片消失。 toCheckSupport是复选框总开关:未加入Options时,即使给节点设了CheckType,ToggleCheck也直接返回、不绘制复选槽。三态自动传播还额外需要toAutoTristateTracking。- 单选 vs 多选事件:单选走
OnChange(FSelectedNode变化);多选走OnSelectionChanged(每次手势后一次)。二者是不同的通道。 - 展开 / 折叠键:小键盘的
+展开、-折叠、*全部展开(和 LCL 一样只认小键盘);按着 Ctrl 或 Alt 时不处理,留给程序。 - 表头排序后再展开:表头排过序时,之前折叠着的子树在展开时按同样的列和方向排好。
- 选中被清掉后:再点(或把
FocusedNode设成)当前焦点节点,会重新选中它。 Enabled = False不响应输入:与全库一致,禁用时不触发点击 / 键盘 / 滚轮驱动的事件。- 你设的
Cursor不会被吞掉:拖放反馈(crDrag/crNoDrop)与列分隔线提示(crHSplit)都只是临时借用Cursor,手势结束后还原成你原本设的那个。以前是硬还原成crDefault——给树设了crHandPoint,只要在分隔线上划过一次就永久没了。 - 五个事件同时是子类的重写点:
OnGetText/OnInitNode/OnExpanding/OnGetImageIndex/OnChange各有一个 protected 虚方法(DoGetText/DoInitNode/DoExpanding/DoGetImageIndex/DoTreeChange),默认实现就是"发这个事件"。像TTyShellTreeView这样自带行为的子类重写虚方法而不是抢占事件槽,因此应用照常可以挂这些事件,不会把子类的行为顶掉(重写里调inherited即可两者兼得)。 - DFM / LFM 序列化:声明了
default的属性(Options=[]、NodeDataSize=-1、DefaultNodeHeight=18、RootNodeCount=0、Indent=16、ShowButtons/ShowTreeLines/ShowRoot/ToggleOnDblClick=True、HotTrack=False、SearchTimeout=1000、ScrollBars=ssBoth、AutoExpand=False、RightClickSelect=True、HideSelection=True、ShowSeparators=False、TabStop=True)等于默认值时不写入文件。Header/Columns作为子对象随控件流式保存(列类已在单元initialization中RegisterClass)。 - 内嵌滚动条是私有的:
VScroll/HScroll只读可访问(供测试 / 布局),不暴露OnScroll,且不做缓动动画。应监听宿主树自身的事件。
BiDiMode := bdRightToLeft 时本控件整体镜像。BiDiMode 不 published(全库统一,见
docs/rtl.md),从代码或从窗体继承设置。
会动的:
| 部位 | 镜像后 |
|---|---|
| 列轴 | 第 0 列贴内容区右缘,其余向左排;表头、单元格、GetCellRect、拖列浮标同源 |
| 列分隔线 / 拖宽抓手 | 是一列的左缘;向左拖是变宽 |
| 表头 | 标题靠右,排序三角换到单元格的阅读起点(右侧) |
| 主列槽位 | 从单元格右缘向内:缩进 → 展开箭头 → 复选框 → 图标 → 标题。整段是把左到右那一份整体反射一次,不是倒着重排一遍 |
| 树状连线 | 跟着缩进走 —— 祖先竖线、肘部竖线、肘部横段三处都过同一个 TreeLineX |
| 内联编辑器 | 落在标题上,不跨到 chrome 上(CellTextRect 取的是槽位记录自己的两条边) |
←/→ |
跟着眼睛:← 展开、→ 收起(子节点画在左边)。按 plans/2026-08-04-rtl-mirroring-scope.md §6.3 第 4 条的判据,这一下按键移动的是节点而不是光标,属布局方向。Home/End/↑/↓ 不翻 |
不动的,而且是有意的:
- 竖滚动条仍在右缘。 反射轴是内容矩形
ContentRect(padding 内缩、扣掉滚动条之后 那一条),滚动条槽在它之外。与TTyCustomGrid/TTyListView同一条取舍,理由与守卫 见docs/rtl.md;tests/test.rtl.pas的TRtlExclusionTest把 "条的边"与"反射轴"钉在一起,只改一处会红。 - 容器不镜像子控件的
Align/Anchors布局(全库规则)。
槽位记录的字段语义(改这块前必读):TTyTreeCaptionSlots 的
ButtonSlotX / CheckX / ImageX / CaptionX 在两个方向下都是物理左缘,不是"前缘"。
六个消费者里有五个是拿 [X, X+W) 拼矩形的,这个写法只有在 X 是物理左缘时才两个方向都对;
改成"前缘"会让那五处在镜像下全部反过来,各自要再算一次 X - W —— 又是五份新的 x 计算。
真正读顺序(而不是矩形)的只有 GetNodeAtPoint 那道阶梯,记录里的
RightToLeft 位就是给它一个用的。标题是余量不是定宽槽,所以额外给了
CaptionRight:左到右时它就是单元格右缘,镜像后它是图标槽的起点。
后代:TTyShellTreeView 不覆写 RtlLayout —— 它只重写了 DoGetText / DoInitNode /
DoGetImageIndex / DoExpanding / DoTreeChange,一个 x 也没有自己算。加后代时先问:
它自己算 x 吗? 算,就覆写成 False。
守卫在 tests/test.rtl.pas 的 TRtlTreeViewTest。槽位探针一律打在边界像素上,
不打槽位中点 —— 本控件真正出过的两个故障(锚点差一整列、PPI≠96 时边界差一像素)
对中点探针完全免疫。