DreamGUI
控件库

控件库

DreamGUIControls 中有什么——按类别划分的 Dream* 控件、它们所基于的 UI* 行为、操作栏、UMG 互操作,以及如何从 .dui 放置控件。

控件库位于 DreamGUIControls 模块中,在输入系统之上(L3)。它提供两层:

  • Dream* 控件:按钮、开关、滑条、列表、对话框……每一个都是 UDreamUserWidget 的子类,其层级由代码构建,而非从资产实例化。
  • UI* 行为:诸如 UUIButton、UUIToggle 和 UUISlider 这样的组件,你将它们挂到一个普通 widget 上,让它像按钮一样响应。控件就是由它们组装而成的。

使用这些类型的 C++ 会在其 Build.cs 中加入 DreamGUIControls。资产则无需任何操作。

为什么控件的层级是代码

插件的 Content/Controls/ 中仍然保留着一组预制蓝图(BP_Button、BP_Toggle、 BP_Dropdown……)——这是更早的做法,即控件是一棵可以打开并编辑的资产树。它有什么问题,在 UDreamButton 的头文件里说得很直白:BP_Button 发布数月却没有 UIButton,所以点击它毫无反应,而且没有任何地方报告这一点。

由代码构建的控件没有半成品状态。UDreamUIControl 在 NativeOnInitialized 中按固定顺序依次运行树、部件、行为和外观,而行为始终是控件自己添加的。代价是这棵树没人能打开,所以作者原本要伸手进层级里去改的一切都必须成为属性——这正是每个控件的 F…Style 结构体;参见样式与样式表。

控件

.dui 标签一列是你在 .dui 中写的节点类型;类名链接到其生成的参考页。

按钮与选择

控件.dui 标签是什么
UDreamButtonNative.Button一个面,面上有一个洞。它自己不绘制任何文字:按钮上显示什么,取决于宿主嵌进洞里的内容
UDreamToggleNative.Toggle复选框:一个框和一个勾。CheckedState 有 UMG 的第三个值;bIsOn 是它的布尔写法
UDreamRadioButtonNative.RadioButton开关的结构,单选的行为
UDreamInputKeySelectorNative.InputKeySelector一个标签为绑定按键的按钮,点击后会监听下一个按键

数值与进度

控件.dui 标签是什么
UDreamSliderNative.Slider一条轨道、一个填充和一个把手;横向或纵向只是一个属性 Direction,不是两个资产
UDreamSpinBoxNative.SpinBox[-] value [+],一行三段:一个数值、一个范围、一个步长
UDreamProgressBarNative.ProgressBar一条轨道和一个填充,没有行为
UDreamThrobberNative.ThrobberN 个片段脉动,只表达"有事在发生"。UMG 的 Throbber 和 CircularThrobber 在这里是一个类、调色板里的两行

文本

控件.dui 标签是什么
UDreamTextInputNative.TextInput带框的文本字段;bMultiLine = true 是多行版本。UMG 的 EditableTextBox / MultiLineEditableTextBox
UDreamEditableTextNative.EditableText不带框的输入框,UMG 的 EditableText
UDreamMultiLineEditableTextNative.MultiLineEditableText不带框的输入框,跨多行
UDreamRichTextBlockNative.RichText读取标记的一段文字,构建于 UDreamText::bRichText 之上

列表与滚动

控件.dui 标签是什么
UDreamListViewNative.List在滚动视口中从数据源构建的行——比 UMG 的 ListView 更小:没有条目 widget 协议要实现
UDreamTileViewNative.TileView行既横向又纵向排列的列表
UDreamTreeViewNative.TreeView行带缩进和展开箭头的列表
UDreamScrollBoxNative.ScrollBox一个面、一个裁剪视口、在其中滑动的内容栈,以及一个滚动条
UDreamScrollBarNative.ScrollBar一条轨道和一个把手;横竖同一个控件

三种列表都派生自 UDreamListViewBase,它持有视口、滚动条、行模板、行池和选中逻辑——"树就是会缩进的列表" 这句话在类结构上是字面成立的。

容器、弹层与导航

控件.dui 标签是什么
UDreamBorderNative.Border一个面、一圈内边距,以及一个放东西的洞
UDreamExpandableAreaNative.ExpandableArea一个可点击的标题和它收起的内容
UDreamTabViewNative.TabView一排标签页,加一个页面切换器
UDreamDialogNative.Dialog遮罩、居中面板、标题、消息和一排按钮。通过 UDreamUIModalSubsystem::ShowModal 打开,遮罩、输入拦截和焦点由子系统负责
UDreamMenuAnchorNative.MenuAnchor菜单从哪里弹出,以及谁负责把它收起来。菜单是每个玩家一层弹出层上的弹层
UDreamDropdownNative.Dropdown一个带标题的面,加一个弹出的列表
UDreamRingMenuNative.RingMenu围着中心的扇区,按方向选择

互操作

控件.dui 标签是什么
UDreamNativeWidgetHostNative.NativeWidgetHostDreamGUI 层级里的一个洞,由一个 UMG widget 填上。见下文 UMG 互操作

每个控件的基类是 UDreamUIControl,它是抽象的,没有标签。

原生滚动框在测量内容时使用视口实际的交叉轴尺寸,且沿滚动轴方向不设限制。因此,自动换行的文本和嵌套的 Fill 槽位会贡献它们在该视口中所需的高度(或宽度)。调整尺寸以及已提交的内容布局变更会重新测量范围;作者设置的内容内边距仍然可滚动。重复行和条件行、移除以及变化的文本都会更新范围,即使视口保持相同尺寸。内容范围跟随内部视口的大小通知,此时其缓存尺寸已经失效。因此,窗口和父布局的尺寸调整会更新内容的交叉轴尺寸,无需再次点击、重新应用样式或手动调用 RefreshContentExtent。

在 .dui 里放控件

文本字段 UUITextInput 的原生使用方可以订阅 GetOnInputActivateEvent(),以便与 GetOnValueChangedEvent() 和 GetOnSubmitEvent() 一同观察开始/结束编辑。激活事件在编辑开始时携带 true,在编辑结束时携带 false。

在 .dui 里,控件是由其注册表标签作类型的节点:Scope.Name,插件的控件都在 Native 下。

// DUI/UI/AudioSettings.dui
class /Game/UI/WBP_AudioSettings

events {
    MuteToggled()
    VolumeMoved()
    Applied()
    Closed()
}

VerticalBox Root {
    AnchorData.AnchorMin = (0, 0)
    AnchorData.AnchorMax = (1, 1)
    AnchorData.SizeDelta = (0, 0)
    Spacing = 12
    Padding = (48, 32, 48, 32)

    HorizontalBox {
        Spacing = 8
        Native.Toggle Mute {
            @slot MinDesiredSize = (28, 28)
            OnToggleChanged -> emit MuteToggled()
        }
        Text { Text = "Mute" }
    }
    Native.Slider Volume {
        MinValue = 0
        MaxValue = 1
        Value = 0.8
        OnValueChanged -> emit VolumeMoved()
    }
    HorizontalBox {
        Spacing = 16
        Native.Button Apply {
            Text { Text = "Apply" }
            OnClicked -> emit Applied()
        }
        Native.Button Back {
            Text { Text = "Back" }
            OnClicked -> emit Closed()
        }
    }
}

要点:

  • 节点的行设置控件的属性:MinValue 和 Value 是 UDreamSlider 的,命名与 UMG 一致(见从 UMG 过来)。样式结构体用点路径写:Style.TickChecked = #FF3355。
  • 嵌套内容进入控件的默认洞。 Native.Button 里的 Text { } 就是按钮的标签——按钮自己不绘制任何文字。开关没有洞;框旁边的文字是你自己的布局,所以上面它和一个 Text 同处一个 HorizontalBox 里。
  • 事件用路由接:OnClicked -> emit Applied() 会为打开它的一方触发屏幕自身的事件,而 OnClicked -> HandleApply 则会改为调用用户 widget 的同名函数(该类必须具有该函数:DUI6004 说明了它没有该函数时的情况)。emit 的参数是针对该类的表达式——控件的事件参数不在其中——因此 MuteToggled 不携带任何参数,而接收它的一方读取 Mute 和 Volume,即该类为这两个控件声明的变量。按原样复制,此文件在编译和布局时都不会产生错误和警告。
  • 开关只有其框那么大,默认为 14 x 19 px:@slot MinDesiredSize = (28, 28) 让它大到足以按下(layout 会报告小于 24 x 24 px 的控件,DUI8003)。
  • 打不出标签的类,可以用类路径作类型:/Script/DreamGUIControls.DreamDialog Confirm { … }。但写回(designer 编辑文件)总是写标签:类路径带着类所在的模块名,用类路径写出的文件,在类换模块的那天就读不回来了。

标签不是内建在语言里的。一个类在自己的 .cpp 里用一行把自己登记到注册表:

DECLARE_DREAM_GUI_WIDGET("Native", "Toggle", UDreamToggle)

项目插件用同一个宏声明自己的作用域(比如 Game.HealthBar);编译器、符号导出、"未知标签"诊断和写回都从同一张表读。节点类型完整的解析顺序见节点与值。

一个控件是怎么搭起来的

UDreamUIControl 在 NativeOnInitialized 里按这个顺序跑四步;子类只通过钩子说"我是什么":

树

有 Template 时实例化它的树(RealizeTemplate),否则由代码搭建(RealizeBuiltIn)。

部件

按名字在树里找部件(BindParts),名单来自 CollectParts 这一份声明。

行为

在找到的部件上挂行为(WireParts)。它用"缺了就加"的方式拿组件,所以模板树上作者没挂的 UUIButton 也会被补上。

外观

解析样式并推到部件上(ApplyStyle),之后任何属性变化都会再推一次。

把第 1 步和第 2 步分开,就是 Template 能成立的原因。它相当于 WPF 的 ControlTemplate:控件保留行为、状态机和样式约定;模板决定长什么样、有哪些节点。部件按名字匹配,所以一个模板就是"一个里面有 Face 和 Label 的 widget Blueprint",不需要继承什么、实现什么接口。模板缺了必需部件时会按名字报一次;GetUnboundRequiredParts 返回所有没找到的必需部件,空数组才是健康的。

Blueprint 子类想碰控件的部件,要等 On Control Ready(OnControlReady),不是 On Initialized:后者在四步之前就触发了,那时部件还不存在。FindPart 按显示名在控件自己的内容里找部件。

UI* 行为

行为是挂在 widget 上的 UDreamUIBehaviour 组件,在 .dui 里写成 + ClassName { } 块。控件由它们拼成,你也可以直接用它们让一个自己画的 widget 获得交互——+ UIButton { TransitionType = None } 在组件文件里很常见。

行为模块做什么
UUISelectableDreamGUIInput所有可交互行为的基类:普通、悬停、按下、禁用、聚焦五种状态和它们之间的过渡,导航,声音
UUIButtonDreamGUIControls点击
UUIToggle、UUIToggleGroupDreamGUIControls开关;一组开关互斥
UUISlider、UUIScrollbarDreamGUIControls拖动取值
UUIScrollView、UUIScrollViewWithScrollbar、UUIRecyclableScrollViewDreamGUIControls滚动视图;带滚动条的;回收复用格子的
UUIListView、UUITileView、UUITreeView、UUIListEntryDreamGUIControls回收式列表,以及每一行身上的条目行为
UUIDropdownDreamGUIControls下拉框
UUITextInputDreamGUIControls文本编辑:光标、选区、IME、虚拟键盘
UUITextHyperlinkDreamGUIControls文字里的超链接
UUIProgressBarDreamGUIControls进度条

UUISelectable 在输入层而不是控件层,因为导航和焦点需要它;控件层的行为都派生自它或 UDreamUIBehaviour。设计器的调色板把这些行为放在一个 legacy 分类里,正常情况下应该用对应的控件。

操作提示栏

UDreamUIActionBar 是屏幕底部那一排 "A:确认 B:返回"。它读动作路由器(action router),而不是由谁告诉它显示什么,所以不会和按键的真实作用脱节——这是手写提示栏的通病:屏幕改了绑定,下面的提示还在宣传旧的。

属性含义
EntryClass每条提示实例化一次的 widget 类,作为提示栏的子节点。没有它什么都不显示
UserIndex谁的提示。-1(默认)是拥有这个 widget 的玩家
MaxEntries最多几条(默认 8),防止失控的表格铺满屏幕

它只在答案变了时重建:绑定增减、玩家换了设备、换了另一种手柄(图标按手柄型号区分)。屏幕自己的动作之后,如果玩家有一个肩键能切换的标签页视图,还会追加"上一页 / 下一页"两条提示,按键取自项目设置的 PreviousTabKeys 和 NextTabKeys。GetPrompts 返回上次重建放上去的提示列表,不需要条目 widget 就能读。

每条提示的根上挂 UDreamUIActionBarEntry,指向画提示的两三个 widget:LabelText(动作说明)、IconImage(按键图标,当前设备没有图标时隐藏)、KeyText(没有图标时显示按键名)。更复杂的画法覆盖 Blueprint 事件 OnBindingChanged;长按动作的进度通过 OnHoldProgressChanged 推送,用来画填充的圆环。

UMG 互操作

UMG 放进 DreamGUI

Native.NativeWidgetHost(UDreamNativeWidgetHost)是 DreamGUI 层级里的一个洞,由一个 UMG widget 填上。它建立在早就存在的两个组件上:UDreamUMGWidget(.dui 里的视觉标签 UMGWidget)把一个 UUserWidget 渲染到渲染目标,再当作 DreamGUI 自己的几何体画出来;UDreamUMGWidgetInteraction 把指针事件转发进去。控件把这两件作者原本要自己加、自己接、自己定尺寸的事包成一个标签。

属性含义
WidgetClass要实例化并绘制的 UMG widget 类;为空就是一个空洞
ResolutionScale一个本地单位值多少渲染目标像素,1 是像素对像素。这是保真度和内存的取舍,所以不在样式里
BackgroundColor被托管的 widget 没画的地方透出什么,默认透明

它不是把 UMG 布局和 DreamGUI 布局混在一起的办法:被托管的 widget 按这个控件的尺寸画进一张纹理,对周围一无所知,既推不动 DreamGUI 的布局,DreamGUI 也伸不进它里面。这和 UMG 自己的世界空间 WidgetComponent 是同一笔交易。它还需要一个世界:没有世界时(无头测试、设计器里不建世界的部分),节点存在、有尺寸、有位置,只是什么都不画。

交互方面,表面上的每个 DreamGUI 指针都作为一个独立指针转发:鼠标作为 Slate 的光标,每根手指作为一个触点(UMG 的 ScrollBox 就是靠触点平移的)。多个 UDreamUMGWidgetInteraction 可以共用一个 VirtualUserIndex;同一时间只有一个能占用那个模拟光标,由每个世界一个的 UDreamUMGWidgetInteractionManager 仲裁。

UMG 叠在 DreamGUI 上

另一个方向是两套 UI 共用同一个视口。打开 Slate 输入源(Use Slate Input Source)后,指针落在绘制于视口上层的 UMG 控件上时,以及某个 UMG 控件持有键盘焦点时的按键输入,都不归 DreamGUI 管。当玩家拥有 DreamGUI 焦点或 Tab 停靠点时, UDreamGameViewportClient 会从光秃秃的视口接管 Slate 自身的导航(Tab、方向键),这样 Slate 就不会把焦点移进 UMG 层。输入的完整说明见输入。

示例

插件自带一个能直接运行的最小屏幕:Content/Samples/HelloDreamGUI.dui;用法见你的第一个屏幕。

DreamGUISamples 模块(L4,位于控件之上)放着两块展示屏幕的原生基类:

类用途
UDreamUIShowcasePanel媒体控制台展示屏幕的基类:其 .dui 绑定到的所有变量和函数——用于 <-> 绑定的 bMuted,用于表达式的 IsMuted() / GetFade(),用于 each 的 Tracks 和 GetHistory()
UDreamUIControlsGalleryPanel控件画廊的基类:每类输入控件一个处理函数,每次交互都会向绑定实时显示的事件日志追加一行——覆盖点击、开关、拖动、滚动、文本和选择
UDreamUIShowcaseDialog展示屏幕的对话框按钮所打开的 Native.Dialog 子类
UDreamUIShowcaseTrackeach 迭代的数据行

这两块屏幕的 .dui 文件和控件蓝图属于使用该插件的项目,不随插件发布;DreamGUISamples 只提供它们背后的 C++。

本页目录