控件蓝图
一棵 UI 树是一个类——UDreamWidgetBlueprint 编译为 UDreamUserWidget——支持子类化和嵌套、命名槽、按名称绑定到子项、无需应用步骤即可编辑类的设计器、它所取代的预制体模型,以及作为蓝图源文件的 .dui。
DreamGUI 中的 UI 树是一个类,而不是你实例化的资产。编写一棵树会给你一个 UDreamWidgetBlueprint,它生成的类是 UDreamUserWidget;你可以子类化它、将它放入另一棵树中,并按名称绑定到它命名的子项——与 UMG 的控件蓝图形状相同,由 DreamGUI 自己的 FDreamWidgetBlueprintCompilerContext 编译。
资产、类、实例
| 它是什么 | |
|---|---|
UDreamWidgetBlueprint | 编写用资产(其类型在内容浏览器中显示为 DreamUI Widget Blueprint,添加菜单将其列为 DreamGUI Widget),持有设计器编辑的树(WidgetTree)和图表 |
UDreamWidgetGeneratedClass | 它编译成的产物。编译会将树复制到类上作为模板(原型),实例由它构建 |
UDreamUserWidget | 一个实例。它本身就是一个 UDreamWidget,正如 UUserWidget 是一个 UWidget |
这两份副本是有意为之,并且与 UMG 一致:原地编辑模板会在会话中途改变每个活动实例的模板。
因为 UDreamUserWidget 是一个控件,嵌套自然就有了:一个类的实例放入另一棵树中就只是那棵树中的一个控件,而它自己的内容来自它自己的类。这些内容位于 WidgetTree (UDreamWidgetTree)之后,而不是直接在其子项之中,这种间接并非装饰:没有它, “一个控件的类”和“一棵树的类”就会是同一回事。WidgetTree 是瞬态的——类模板绝不能携带展开的子树,否则嵌套类会被烘焙进其父级的模板中,并停止跟踪它自己的类—— 并且在 Initialize 时、每次根据类构建。
和 UWidgetBlueprint 一样,该资产永远不会被烘焙:烘焙后的构建拥有生成的类(包含字节码),不需要其他任何东西。未烘焙内容则是另一回事:编辑器构建在加载时会丢弃蓝图保存的字节码,并从蓝图重新构建它,因此任何运行未烘焙内容的进程——包括使用 -game 启动的游戏或以独立游戏方式启动的游戏 ——都需要这个类及其编译器。这就是为什么 DreamGUIEditor 是一个 UncookedOnly 模块,而不是 Editor 模块;否则控件蓝图的图表在 -game 中将不起作用。
实例的生命周期
UDreamUserWidget 可以重写的时刻,与 UMG 中一样:
| 事件 | 时机 |
|---|---|
PreConstruct(bIsDesignTime) | 在 Initialize 的开头,设计器预览和运行时都是如此 |
OnInitialized | 内容构建完成后(C++ 中为 NativeOnInitialized);在预览中也是如此 |
OnConstruct | 开始播放:树已注册并显示在屏幕上;仅限游戏世界 |
OnDestruct | 在拆除时 |
OnTick | 仅在开启 bWantsTick 时每帧执行,而默认情况下并未开启——从未使用的 tick 仍需付出管理器列表条目、虚函数调用和 ProcessEvent 的代价 |
在 NativeOnInitialized 中无法保证 world 一定存在。 它会在控件正在创建、尚未被赋予父级或注册时运行,而 GetWorld() 沿控件的外层链向上查找:控件的树尚未到达某个层级或 world(嵌套实例、为预览而创建的实例或作为副本创建的实例)时,在那里可能返回 null。任何需要 world 的操作——通过子系统隐藏自身、查找玩家、启动需要 tween 管理器的 tween——都应放在 NativeOnConstruct 中,此时树已注册且管理器已启动;或者交给创建该控件的代码,在创建调用返回之后执行。
指针、拖拽、按键、焦点和导航事件(OnPointerClick、OnDrop、OnKeyDown、OnFocusReceived、 OnNavigate……)也在这里。bAllowEventBubbleUp 默认开启:用户控件是一个容器,而一个静默吞掉内部每次点击的容器会破坏它所放置的每个屏幕;将其关闭以在此边界处消费事件。 bCanNavigateHere 默认关闭,因此导航搜索会像以往一样越过该控件;当你想要 OnNavigate 时将其开启。
C++ 命名与 UMG 的命名对比
这些虚函数沿用 UMG 的函数结构而非其名称,并以 DreamGUI 的事件数据取代几何信息与 Slate 事件。返回 bool 的虚函数回答事件是否可以继续向父级冒泡(bAllowEventBubbleUp 是默认答案),而 UMG 的对应函数返回 FReply。重写者调用 Super 并返回它的返回值。
UMG UUserWidget | UDreamUserWidget |
|---|---|
NativeOnInitialized() | NativeOnInitialized() |
NativePreConstruct() | C++ 中没有;对应的蓝图事件为 PreConstruct(bIsDesignTime) |
NativeConstruct() | NativeOnConstruct() |
NativeDestruct() | NativeOnDestruct() |
NativeTick(Geometry, DeltaTime) | NativeOnTick(DeltaTime),仅在 bWantsTick 开启时 |
| 无 | NativeOnEnable(), NativeOnDisable() |
NativeOnMouseEnter / NativeOnMouseLeave | NativeOnPointerEnter / NativeOnPointerExit |
NativeOnMouseButtonDown / NativeOnMouseButtonUp | NativeOnPointerDown / NativeOnPointerUp(以及 NativeOnPointerClick,UMG 没有对应事件) |
NativeOnMouseMove | NativeOnPointerMove(返回 void) |
NativeOnMouseWheel | NativeOnPointerScroll |
NativeOnMouseButtonDoubleClick | NativeOnPointerDoubleClick |
NativeOnDragDetected | NativeOnBeginDrag,然后是 NativeOnDrag 和 NativeOnEndDrag |
NativeOnDragEnter / NativeOnDragOver / NativeOnDragLeave | 名称相同,参数为事件数据与操作(返回 void) |
NativeOnDrop / NativeOnDragCancelled | 名称相同 |
NativeOnTouchGesture | NativeOnPointerPinch 和 NativeOnPointerSwipe |
NativeOnKeyDown / NativeOnKeyUp / NativeOnKeyChar / NativeOnAnalogValueChanged | 名称相同,参数为一个 UDreamKeyEventData |
调用 SetWantsTick(false) 取消临时交互,也可以从 NativeOnDisable 中取消。在该回调期间退出会立即移除管理器注册;它不会让已禁用的控件继续 tick,也不会在控件再次激活时恢复已取消的交互。 | NativeOnFocusReceived / NativeOnFocusLost | 名称相同,参数为用户与指针索引(返回 void) | | NativeOnNavigation | NativeOnNavigate(Direction, OutNextWidget) |
蓝图事件在有对应 UMG 事件时沿用其名称(On Mouse Wheel、On Mouse Move、On Double Click),但不带 Native 前缀。在蓝图中实现的 On Tick 或 On Mouse Move 会自动开启 bWantsTick。
子类化与嵌套
- 子类化。 只添加逻辑的子类不声明自己的树,而是实例化其父级的树(
FindWidgetTreeArchetype查找最近的拥有树的类)——否则为了更改一个函数而对屏幕进行子类化会静默地产生一个空屏幕。属性绑定和事件路由沿链累积:未添加任何绑定的子类仍然遵循其父级的绑定,而添加了一些绑定的子类也不会替换它们。 - 嵌套。 将一个类拖入另一棵树(或在
.dui中将其写为节点类型),设计器会将那个实例折叠为一行——这适用于按钮或滑块这类成品控件。要让宿主能在其中放入内容,该类必须有意识地开一个洞:命名槽。
命名槽
UDreamNamedSlot 是一种行为,它将其控件标记为一个洞,由放置该类的宿主来填充:类说明位置,宿主说明内容。
- 槽的名称就是控件的显示名称——作者已经输入并在层级中看到的内容,与 UMG 为
UNamedSlot所做的选择相同。 - 默认情况下接收一个控件(类似
UDreamContentWidget:接收多个的洞会变成面板)。当该洞本身已经是面板时,开启bAcceptsSeveral。 bIsDefaultSlot标记默认槽,未指定槽名称的嵌套内容会去那里。每个类一个(DUI3022)。
宿主放入槽中的是宿主自己树中的控件,而不是针对另一个资产记录的差异;在 Initialize 结束时,它们会被挂到匹配的槽下。相关调用位于 UDreamUserWidget 上:GetContentForNamedSlot、 SetContentForNamedSlot、FindSlotWidget、GetDefaultSlotName(C++ 类可以重写它)和 GetNativeSlotNames (内容由代码而非模板构建的类如何声明其洞)。
还有 UDreamNamedSlotHost,名称相似但作用不同:它是 UMG 的 INamedSlotInterface 的对应物,是一棵树内部的运行时名称到子项映射(SetContentForSlot、GetContentForSlot、 ClearSlot、GetSlotNames),不涉及其他资产。不要将其与类之间的命名槽混淆。
在 .dui 中,组件用 slot 开一个洞,并声明宿主可以设置什么,用 props;宿主在实例中嵌套内容以填充默认槽:
class /Game/UI/Components/WBP_Card
props {
Text Title
}
VerticalBox Root {
Spacing = 8
Padding = (16, 16, 16, 16)
Text Heading {
Text <- Title
FontSize = 22
}
slot Body default
}use "UI/Components/Card.dui" as Card
Widget Root {
+ Overlay {}
Card Audio {
Title = "Audio"
Text Hint { Text = "Master volume and effects" }
}
}完整语法见 .dui 组件。
按名称绑定到子项
树中每个带 id 的控件都会成为该类的一个成员变量,图表可以直接读取它。在 C++ 父类中声明的控件类型属性会绑定到树中同名的控件:InitializeWidgetStatic 绑定在 UDreamUserWidget 之下声明的每个控件类型属性,无论是否标记。该标记决定的是另一件事—— meta = (BindDreamWidget) 使缺失的控件成为编译错误:
UCLASS()
class UMySettingsScreen : public UDreamUserWidget
{
GENERATED_BODY()
protected:
// The tree must contain a widget named Confirm, or the compile fails
UPROPERTY(meta = (BindDreamWidget))
TObjectPtr<UDreamWidget> Confirm;
};它有意不采用 UMG 的 BindWidget。两者在运行时从不冲突,但头文件是给人读的,一个裸的 meta=(BindWidget) 加在 Dream 控件上会表明它属于一个它并不属于的框架。动画方面的对应物是 BindDreamWidgetAnim,以及不带错误的 BindDreamWidgetAnimOptional。在运行时,GetWidgetFromName 按其变量名查找控件。
访问控件的部件
控件变量是 UDreamWidget,无论该节点绘制什么:Text 节点是一个带有 UDreamText 视觉的控件,而 VerticalBox 节点是一个带有垂直框布局容器的控件。一个节点可以同时承载视觉、布局容器、布局自身和行为,而其中的每一项都是一个拥有自己 API 的部件。
从控件的引脚上拖出连线,菜单会列出其部件能执行的操作,并按控件、再按部件归类:
Player Label
Dream Text (Visual)
Get Dream Text (Visual)
Set Text
Set Font Size
...
UMG Vertical Box (Layout)
Get Spacing
Set Spacing
...选择 Set Text 会放置一个节点 Set Text,其目标是控件本身:PlayerLabel 直接连入它。该节点会在编译时找到部件,因此没有 Get Visual、没有 Cast,也没有失败分支。部件向图表公开的属性会以其 Get 和 Set 列出,同样各一个节点。部件继承的函数(例如来自 UDreamVisual)会列在该部件下,正如控件实际拥有它一样。
Get Dream Text (Visual) 用于需要部件本身的情况——将它传给自己的函数,或保存在变量中:其输出类型为部件自身的类。
编译会对照其构建的层级结构检查每个此类节点。如果 .dui 将 PlayerLabel 从 Text 变成 RectBlock,下一次编译会在 Set Text 处失败,并说明 PlayerLabel 的视觉现在是什么:修改图表,或把节点改回去。每个视觉都接受的调用(例如在 UDreamVisual 上声明的调用)仍然可以编译。部件保持可替换;编译会找出替换所破坏的每个图表。
这些节点也接受不属于控件树的控件(函数输入、数组元素)。没有可供检查的依据,因此不带该部件的控件在那里什么也不做,就像失败的 Cast 一样。
在 C++ 中,同样的读取是模板:用于行为的 GetVisual<UDreamText>()、GetLayoutContainer<T>()、GetLayoutSelf<T>() 和 GetComponent<T>();当部件不是 T 时,各自为 nullptr。
事件通过路由处理:OnClick -> HandleConfirm 将一个事件连接到用户控件上的一个函数,这也正是 UMG 放置事件处理的地方。编译器将每条路由解析为 UDreamWidgetBlueprint::EventBindings,而 UDreamUserWidget::BindEventBindings 在 Initialize 时附加它们。在设计器中,同样的事情是细节面板的 Events 部分: + 会创建一个具有正确签名的自定义事件以及命名它的路由。
设计器编辑类
设计器编辑类的预览实例并将更改写回类,因此没有应用步骤,也没有需要协调的每实例覆盖列表。预览宿主是瞬态且非事务性的;编写树是唯一可撤销的部分。设计器本身在设计器中描述。
注意:
此插件所衍生的预制体资产模型已经消失,连同 SavePrefab、Apply、ClearLoadedPrefab 和 Save on Apply 一起。插件不附带重定向:针对旧类名保存的资产需用 1.0.0 重新保存一次,借用 2.1.0 的重定向块;请参阅迁移。
.dui:蓝图的源文件
一棵树也可以写成文本。UDreamTextUserWidget 是一个用户控件,其层级来自 .dui 文件:它的 SourceFile 指定文件名,编译时 FDreamWidgetBlueprintCompilerContext 读取该文件、构建树,并将其安装为蓝图的编写层级 —— 在类声明其变量之前。从那时起,它在每个方面都是一个普通的 UDreamUserWidget:相同的生成类、每个控件相同的成员变量、相同的属性绑定、相同的设计器。
- 文本替代的是编写步骤,而非运行时间。
SourceFile只能在类默认值上编辑(EditDefaultsOnly):一个类,一棵树。文件在编译时读取,这是唯一能为每个控件声明成员变量、解析绑定、检查绑定并将层级交给设计器绘制的时刻。- 它是仅编辑器数据,在烘焙时剥离;相对路径以
DUI/源目录为根。 - 设计器工具栏中的 Set Source File... 可将类指向某个文件,在设计器中所做的编辑会写回文件中保存该值的那一行。
如何编写:.dui 概览。
显示它
| 调用 | 作用 |
|---|---|
| Create Dream Widget 节点 | UMG 的 Create Widget 节点:选择一个类会为每个 Expose on Spawn 属性生成一个引脚(.dui 的每个 props 和 viewmodels 条目各一个),以及一个 Owning Player 引脚,并将结果类型设为此类。这些引脚在控件初始化之前赋值,因此 Pre Construct、On Initialized、On Construct 以及每个绑定的初始值都能看到它们;UMG 在 Create 之后赋值,对 On Initialized 来说太晚了 |
UDreamUserWidget::AddToViewport | UMG 的 Add to Viewport:显示在拥有者玩家的屏幕上(未指定时为第一个本地玩家),并开启显示。与 UMG 一样,已有父级的控件会被拒绝。RemoveFromParent 会将其再次移除 |
UDreamUserWidget::AddToPlayerScreen | 同上,但没有拥有者玩家时拒绝,而不是回退到屏幕 0 |
UDreamUIBPLibrary::AddWidgetOfClassToViewport | 一次调用即可创建并放入视口;返回引脚采用该类的形状 |
UDreamUIBPLibrary::CreateDreamWidgetOfClass | 实例化它但不放置在任何地方(与 ConstructWidget 相同的未上屏状态)。与 UMG 的 Create 一样,不在蓝图菜单中 —— Create Dream Widget 节点代表它;已经调用它的图表仍可编译 |
BeginCreateDreamWidget / FinishCreateDreamWidget | C++:该节点的两部分。在初始化之前,于两者之间写入新控件自身的属性(例如 SetViewModel) |
UDreamScreenUISubsystem::CreateWidgetOnScreen / AddToPlayerScreen | 指定玩家的屏幕 |
UDreamWorldWidgetComponent::SetWidgetClass | 放入关卡;请参阅世界空间 UI |
该类的成员与 UMG 的 UUserWidget 逐项对比,见 UDreamUserWidget 参考。