DreamGUI
类参考

UDreamTreeView

UDreamTreeView

继承自 UDreamListViewBase。

声明于 Public/Controls/DreamTreeView.h。

一棵层次结构由代码而非资产定义的树:一个列表,其行带有缩进和一个折叠箭头。

树本质上就是一个带缩进的列表,而这个类正是被写成一个比 UDreamListView 恰好多出这些的东西——两者都派生自 UDreamListViewBase,后者拥有视口、滚动列、行模板和行;而本类则为每个条目增加一个深度、每行一个缩进,以及一个可展开和折叠的折叠箭头。FDreamTreeViewStyle 的构建方式也是如此:它携带一个完整的 FDreamListStyle 而不是重新陈述其字段,因此为项目的列表设置样式也就为它的树的行设置了样式。

源是扁平的,而且是有意为之

条目(或 ItemObjects)加上 ItemDepths:树的先序遍历,每个条目旁边带着它的深度。这正是 UUITreeView 在能够布局一行之前将其源展平成的那种形状(Items + ItemDepths,每当展开状态变化时重建),而且它是控件能从设计者那里接受的唯一形状——嵌套的源需要在条目类上有一个接口,而那是 .dui 作者无法签署、细节面板也无法绘制的契约。

扁平形式除了可作者化之外还带来什么:一行的子树正是紧随其后、深度更大的那段连续行,因此折叠是一次跳过而不是一次图遍历,而且永远不需要询问任何条目它的子项是谁。

最初一切都是展开的——作者编写的列表就是你看到的——而 CollapsedItems 是例外集合。选择保持为对源的索引,因此它能挺过一次折叠。

OnGetItemChildren 构建扁平源;它不会替换扁平源

UMG 的 TreeView 向每个条目询问其子项并遍历答案,这个类也是如此——SetRootItems 加上 OnGetItemChildren(或 IUITreeViewItem::GetTreeChildren,本插件的行为端树已经使用它)按先序将层次结构展平为上面那个精确的 Items + ItemDepths 对。

展平而不是惰性遍历就是整个设计,也正是它让这个控件 API 中的每个索引都有意义:SelectedIndex、ItemDepths、GetRowWidget、ScrollItemIntoView 和 CollapsedItems 都是对源的索引,而一个只物化当前展开内容的源每次折叠箭头移动时都会重新编号。因此遍历会走整棵树,包括折叠节点的子项,而折叠仍然保持它在这里一贯的样子:在显示时跳过一段更深的行。折叠的父项保留它的折叠箭头,因为它的子项仍在源中可供计数。

这个决定的代价是被陈述出来而不是被隐藏:无界或惰性加载的层次结构无法用这种方式表达,因为遍历会访问每个节点一次。那么大的树反而需要回收栈(UUITreeView),这正是那个类保留的原因。

循环是可以存活的:一个已经访问过的条目不会被再次访问,因此图会产生一棵树而不是卡死。

左和右是树的

上和下像列表那样在显示的行之间步进。左和右像 STreeView::OnKeyDown 所定义的那样打开和关闭:在一个折叠的父项上按右会展开它,在一个已展开的父项上按右会移动到它的第一个子项;在一个已展开的父项上按左会折叠它,在其他任何地方按左会移动到父项。当该键无事可做时——在叶子上按右、在一个已经折叠的根上按左——它仍然属于树,焦点保持不动,这正是 STreeView 对方向键所做的。本库为键盘和游戏手柄提供同一条导航路径,因此方向键得到相同的答案;在 UMG 中方向键会绕过 OnKeyDown,反而会让树横向移动。折叠箭头不是导航停靠点(UMG 的展开箭头也不可聚焦),因此在其上点击后紧接着的一次按下会从该行开始。

关于它所构建的树的形状、为什么它承载普通滚动视图而不是回收视图,以及这些控件如何与 each 语言特性并置,请参见 UDreamListViewBase。

属性

名称类型类别在细节面板中来自蓝图描述
StyleFDreamTreeViewStyleTree ViewyesGetStyle / SetStyle此实例自身的外观。当 StyleSource 如此指示且确实存在一个样式表时,项目样式表胜出;当项目中没有样式表时,这就是实际生效的外观——这正是它保持可编辑而不是被该枚举门控的原因。
ItemDepthsTArray<int32>Tree ViewyesGetItemDepths / SetItemDepths每个条目一个深度,与 Items / ItemObjects 平行:0 是根,1 是最近的前一个 0 的子项,依此类推。缺失的条目读作 0,因此一个完全没有给出深度的树就是一个扁平列表——这对它来说是正确的。
CollapsedItemsTSet<int32>Tree ViewyesGetCollapsedItems / SetCollapsedItems折叠的条目,按源索引。是一个例外集合而不是展开集合,因为一棵打开时什么都不显示的树是没人看得出是自己编写的树。
CollapsedItemObjectsTSet<TObjectPtr<UObject> >Tree View-read only同样的例外,按身份标识,适用于有 ItemObjects 的源。
TwistyTemplateNodeTObjectPtr<UDreamWidget>Tree View-read only模板的折叠箭头。每一行都有它的一个副本,通过显示名称找到。
TwistyGlyphTemplateNodeTObjectPtr<UDreamWidget>Tree View-read only其中的字形——用于代替某个画刷不包含图像的状�态的替代物。
RootItemsTArray<TObjectPtr<UObject> >Tree Viewyesread / write层次结构的顶部,适用于作为图而不是扁平数组编写的树。
OnGetItemChildrenFDreamTreeGetItemChildrenTree View-read / write一个条目的子项是谁。UMG 的 OnGetItemChildren,具有它的签名和它的职责。

函数

函数种类描述
void CollapseAll()callable全部折叠
void ExpandAll()callable全部展开
TSet<int32> GetCollapsedItems()pure获取折叠的条目
TArray<int32> GetItemDepths()pure获取条目深度
float GetRowIndent(int32 InItemIndex)pure此条目的行从多少像素处开始:它的深度乘以样式的 IndentPerLevel。
FDreamTreeViewStyle GetStyle()pure按值而非按引用:UFUNCTION 的返回值必须是值,而样式是一个小结构体。
bool IsItemExpanded(int32 InItemIndex)pure条目是否已展开
bool ItemHasChildren(int32 InItemIndex)pure当下一个条目更深时为真——在先序扁平列表中,这就是父项。
void RefreshTree()callable再次遍历根,并根据子项提供者现在所说的内容重建扁平源。
void SetCollapsedItems(TSet<int32> InCollapsed)callable一次性替换整个折叠状态并重新推导可见行。
void SetItemDepths(TArray<int32> InDepths)callable仅替换深度,适用于没有移动的源。
void SetItemExpanded(int32 InItemIndex, bool bInExpanded)callable移动折叠箭头,重建可见行,然后通知。如果它原本就已在那里,则为无操作。
void SetItemExpansion(int32 InItemIndex, bool bInExpanded)callableUMG 对 SetItemExpanded 的称呼,而本控件正是以那个名称编写的。
void SetItemsWithDepths(TArray<FText> InItems, TArray<int32> InDepths)callable一起替换源及其深度,这是它们唯一保持一致的途径。
void SetRootItems(TArray<UObject*> InRootItems)callable替换根并重新遍历。SetItemsWithDepths 的层次化对应物。
void SetStyle(FDreamTreeViewStyle InStyle)callable替换整个外观并重新推送它。缩进和折叠箭头是样式,因此行会重建。
void ToggleItemExpansion(int32 InItemIndex)callable切换条目展开

事件

事件签名描述
OnItemExpansionChangedvoid DreamTreeExpansionChangedEvent__DelegateSignature(int32 ItemIndex, bool bExpanded)按深度层级,朝点击折叠箭头的任意方向。

与 UMG 对比

UMG 类中所有面向蓝图的成员,以及它们去了哪里。adopt:名称相同,含义相同。map:在这里以另一个名称或另一个类型出现。reject:有意缺失,并附原因。

UMG成员状态此处备注
UTreeViewSetItemExpansionadoptSetItemExpansion一行转发到 SetItemExpanded,这是本控件编写时所用的名称,也是所有现有调用方使用的名称。按源索引,因此能承受其上方发生的折叠。玩家也能触达它:一行上的左键和右键会打开、关闭并走到父项或第一个子项,就像 STreeView::OnKeyDown 对方向键所做的那样——而且,由于本库只有一条导航路径,方向键(D-pad)也有相同效果,而在 UMG 中它会侧向离开树。
UTreeViewExpandAlladoptExpandAll
UTreeViewCollapseAlladoptCollapseAll
UTreeViewBP_OnGetItemChildrenmapOnGetItemChildrenFDreamTreeGetItemChildren,带有 UMG 的签名。像 UMG 的一样是单播:这是一个问题,而一个问题有两个答案是任何东西都无法解决的歧义。未绑定时,遍历回退到 IUITreeViewItem::GetTreeChildren。
UTreeViewBP_OnItemExpansionChangedmapOnItemExpansionChanged携带源索引和新状态。在可见行重建之后触发,因此统计行的处理器看到的是用户刚刚生成的树。

本页目录