样式与样式表
每个控件的 F…Style 结构体、StyleSource 与外观的来源、项目样式表 UDreamUIStyleSheet 及其命名变体,以及面刷子、状态面和图片刷子。
控件的树由代码构建,没人能打开它,所以每个外观决定都必须是一个旋钮,否则就只能 fork。这些旋钮集中存在于每个控件的样式结构体中——Slate 的 FButtonStyle 那种形状,存在的理由也一样。
分工是固定的:外观在样式里,行为在控件上。按钮的颜色、圆角和内边距是 FDreamButtonStyle 的字段;它什么时候算点击(ClickMethod)、接受哪些鼠标键(AcceptedMouseButtons)是 UDreamButton 自己的属性。这就是为什么有几个 UMG 属性在这里低了一层:列表条目之间的间距是外观,于是 UMG 的 EntrySpacing 是 Style.RowSpacing(见从 UMG 过来)。
注意:
这里说的是控件的样式结构体。.dui 里的 style Name { … } 块是另一回事—— 一组按名字套到节点上的属性行,见样式与资源。
每个控件的样式结构体
每个控件有一个 Style 属性,类型是它这一族的结构体;项目样式表里每一族有一个默认值和一张命名变体表。
| 控件 | 样式结构体 | 样式表里的字段 |
|---|---|---|
UDreamButton | FDreamButtonStyle | Button, ButtonVariants |
UDreamToggle | FDreamToggleStyle | Toggle, ToggleVariants |
UDreamRadioButton | FDreamRadioButtonStyle | RadioButton, RadioButtonVariants |
UDreamInputKeySelector | FDreamInputKeySelectorStyle | InputKeySelector, InputKeySelectorVariants |
UDreamSlider | FDreamSliderStyle | Slider, SliderVariants |
UDreamSpinBox | FDreamSpinBoxStyle | SpinBox, SpinBoxVariants |
UDreamProgressBar | FDreamProgressBarStyle | ProgressBar, ProgressBarVariants |
UDreamThrobber | FDreamThrobberStyle | Throbber, ThrobberVariants |
UDreamTextInput, UDreamEditableText, UDreamMultiLineEditableText | FDreamTextInputStyle | TextInput, TextInputVariants |
UDreamRichTextBlock | FDreamRichTextStyle | RichText, RichTextVariants |
UDreamListView | FDreamListStyle | List, ListVariants |
UDreamTileView | FDreamTileViewStyle | TileView, TileViewVariants |
UDreamTreeView | FDreamTreeViewStyle | TreeView, TreeViewVariants |
UDreamScrollBox | FDreamScrollBoxStyle | ScrollBox, ScrollBoxVariants |
UDreamScrollBar | FDreamScrollBarStyle | ScrollBar, ScrollBarVariants |
UDreamBorder | FDreamBorderStyle | Border, BorderVariants |
UDreamExpandableArea | FDreamExpandableAreaStyle | ExpandableArea, ExpandableAreaVariants |
UDreamTabView | FDreamTabViewStyle | TabView, TabViewVariants |
UDreamDialog | FDreamDialogStyle | Dialog, DialogVariants |
UDreamMenuAnchor | FDreamMenuAnchorStyle | MenuAnchor, MenuAnchorVariants |
UDreamDropdown | FDreamDropdownStyle | Dropdown, DropdownVariants |
UDreamRingMenu | FDreamRingMenuStyle | RingMenu, RingMenuVariants |
UDreamNativeWidgetHost 没有样式:它唯一的旋钮 ResolutionScale 是保真度与内存的取舍,针对一个托管的控件,样式表对它没什么可说的。
几条贯穿所有样式的约定:
- 颜色是
FColor,整个样式家族都是。 - 字体是
Font,即位于FontSize旁边的字体数据资产,用于自行绘制文本的控件样式:文本输入、微调框、富文本、可展开区域(其标题)和环形菜单(其条目与中心标题)。为 Null 时文本沿用项目的默认字体。 - 按钮没有文字样式。按钮自己不画字;标签是宿主放进洞里的东西,所以
FDreamButtonStyle没有LabelColor或FontSize——一个无处可写的旋钮比没有旋钮更糟。需要由控件提供标签的地方,由那个控件自己的样式说(FDreamDialogStyle::ButtonLabelColor)。 - 禁用色和聚焦色也是样式状态。推一个聚焦色就是打开 selectable 的聚焦视觉,所以手柄用户的导航总会落在有反应的东西上。
外观从哪里来:StyleSource
每个控件上都有两个属性决定用哪份样式:
| 属性 | 含义 |
|---|---|
StyleSource | ProjectStyleSheet(默认):从项目样式表解析;ProjectStyleSheetOverride:样式表的值,再写上这个实例勾选了的字段;Inline:整个用这个实例自己的 Style |
StyleVariant | 样式表里的命名条目("Danger"、"Compact");为空表示这一族的默认值。只在从样式表解析时有意义 |
默认是样式表,因为那就是有样式表的意义:一个代码搭的控件没有树可以打开重新上色,没有项目级的答案,每个实例都是一份手调的 fork。
项目里没有样式表时,实例自己的 Style 就是生效的外观——不管 StyleSource 写的是什么。这也是 Style 一直可以编辑、没有被 StyleSource 置灰的原因。
逐字段的覆盖位
每个样式结构体的每个字段旁边都有一个 bOverride_<Field> 位——UE 自己的习惯,就是 FPostProcessSettings 用的那个:细节面板上是值旁边的一个勾,没勾的值显示为灰色(但仍然显示——那是这个实例勾上的话会推什么)。合并只认这些位:
- 变体:这一族的默认值,再写上变体勾选了的字段。一个字段不勾,就是"跟这一族的默认值走"——没有 Parent 指针、也没有环要检查的继承。
ProjectStyleSheetOverride:样式表解析出的样式,再写上这个实例勾选了的字段。
注意:
所有位默认都是勾上的,这样既有的东西一个字节都不变:每个位都勾着的变体就是它一直以来那份完整的 fork。反过来,切到 ProjectStyleSheetOverride 却什么都没取消勾选,效果和 Inline 一样。要跟随样式表的字段,得把它的勾去掉。
在 .dui 和运行时里
class /Game/UI/WBP_DeleteSave
HorizontalBox Root {
Spacing = 16
Native.Button Delete {
StyleVariant = "Danger"
Text { Text = "Delete" }
OnClicked -> HandleDelete
}
Native.Toggle AutoSave {
StyleSource = Inline
Style.TickChecked = #FF3355
}
}Style.TickChecked = #FF3355 只写入实例自身 Style 的那一个字段,别的什么都不改。.dui 从不改变 bOverride_ 位,因此 Style.X = v 不会打开 bOverride_X,也不需要打开:每个位初始都是勾选状态。决定该值是否被使用的是 StyleSource:
Inline,或项目中没有样式表:实例的Style整体就是外观,不会读取那些位。这就是上面的示例要写StyleSource = Inline的原因。ProjectStyleSheet(默认值)且项目中存在样式表:实例的Style会被忽略,因此文件中的Style.X行能通过编译,却不改变任何东西。请写StyleSource = Inline,或用StyleVariant挑选样式表条目。ProjectStyleSheetOverride:以样式表的样式为基础,再覆盖写入实例中已勾选的字段。每个字段初始都是勾选的,所以你没有写的字段也会覆盖,用的是结构体的默认值。应跟随样式表的字段要逐个取消勾选,每行一个:Style.bOverride_Y = false。位处于关闭状态的字段(Style.bOverride_X = false,或在资产中未勾选)不会因为写入Style.X而打开;还要写入该位。
运行时:SetStyle、SetStyleSource 和 SetStyleVariant 都会立刻重推,因为一个改了来源却不重新解析的样式,效果在别的东西碰巧触发推送之前完全不可见。如果你在原地改了一个样式结构体,自己调一次 ApplyStyle。
注意 SetStyle 写的是实例的 Style:样式表正在生效时写内联样式,你看不到任何变化。推送照样会跑,但赢的仍然是 StyleSource 说的那一份。
项目样式表
UDreamUIStyleSheet 是一个数据资产:项目的控件在这里约定怎么长。每一族一个默认值加一张命名变体表,这就是一个控件需要说的全部——哪一族,可选再加一个名字。
建一个样式表
在内容浏览器里新建一个数据资产,类选 DreamUIStyleSheet。
指给项目
在 Project Settings ▸ Plugins ▸ Dream GUI 的 Assets 分类里,把 Default Style Sheet 指向它。这个设置是 UDreamGUISettings::DefaultStyleSheet。
在控件上选变体
控件默认从样式表解析;要特殊外观的实例填 StyleVariant。
几件值得知道的事:
- 插件不带样式表。 没有样式表的项目是受支持的状态,不是缺东西:结构体自己的 C++ 默认值就是内置主题。
DefaultStyleSheet是TSoftObjectPtr<UDataAsset>,因为核心模块不认识控件库的类型;选择器只列样式表,UDreamUIStyleSheet::GetProjectSheet()负责转换。它在第一次被调用时加载样式表,没配置时返回空,调用方把它读作 "用内联默认值",而不是错误。- 解析发生在构造时,按名字查找,和 Slate 的样式集一样。这里没有运行时换主题,也不打算有:它换来的是——改项目的强调色只需编辑一个资产的一处,而不用走访每一个放过开关的屏幕。
- 拼错的变体名回落到这一族的默认值,而不是失败:屏幕上总有可见的东西,十次里有九次是对的。
面刷子、状态面和图片刷子
FDreamUIFaceBrush:控件面的皮肤
每个控件的面都是一个程序化圆角矩形(UDreamRectBlock);UMG 的手感大多就在这里。 FDreamUIFaceBrush 是可选的一层皮:为空时面保持普通矩形;给了图,面在同一个轮廓里画这张图——圆角、边框和 selectable 的着色都照常工作,因为皮是矩形的主体纹理,而不是另一个视觉。控件的面永远不会不再是矩形。
| 字段 | 含义 |
|---|---|
Image | 一张纹理或一个图集精灵,拖哪个进来都行 |
Tint | 乘在图上,Slate 的 tint。和样式的状态色是两条独立通道;两者相乘 |
ScaleMode | Stretch / FitIn / Envelop,对应 UMG 的 Stretch / ScaleToFit / ScaleToFill |
DrawMode | Image / Box / Border,Slate 的 DrawAs。后两个是九宫格,只对普通纹理生效;精灵总是按 Image 绘制 |
Margin | 九宫格边距,单位是纹理像素:文件里八像素宽的边,在任何矩形尺寸下都保持八像素宽 |
ImageSize | 图自己的绘制尺寸。零表示不表态;非零时覆盖带尺寸字段的部件(开关的框和勾、单选的框和点、滑条的把手)的样式尺寸 |
FDreamUIStateFaces:一个面的五种画法
样式原本只能靠颜色区分五种状态,所以普通按钮和按下按钮是两张不同的图的项目只能 fork 控件。 FDreamUIStateFaces 补上这个缺口,而且不引入第二个状态机:selectable 已经决定了控件处于哪个状态,这里只决定那个决定画成什么。
| 字段 | 含义 |
|---|---|
Normal、Hovered、Pressed、Disabled、Focused | 每种状态一个面刷子。没有图的状态回落到 Normal,Normal 也没有图就回落到控件自己那一张刷子 |
bTintForeground + 五个 …Foreground 颜色 | 控件自己的前景部件——自己的标签或图标,从不碰宿主的内容——每种状态的颜色。默认关闭 |
bUsePressedPadding + PressedPadding | 按下时内容周围的边距,经典的"按下去"效果。静止时的边距是控件自己的 ContentPadding |
HoveredSound、PressedSound、ClickedSound | 控件出声的三个时刻,作为样式决定:一次点击应该和这个 UI 里别的点击听起来一样 |
每个字段都是可选的,所以它什么都不改变:空的状态组画出来和以前逐像素完全相同。它是按钮、开关、下拉框的面和列表行这些样式的一个字段,而不是基结构体——USTRUCT 继承经不住覆盖位的合并。
焦点和悬停是两个问题——焦点在指针离开后仍然存在,手柄上根本没有指针——所以 Focused 单独占一格。
FDreamUIImageBrush:Image 视觉的刷子
FDreamUIImageBrush 是核心模块 Image 视觉(UDreamImage::Brush)的刷子,UUIToggle、UUIDropdown 和 UDreamSelectableStyle 也用它。它不是控件的面,能画的方式更多:
| 字段 | 含义 |
|---|---|
ResourceObject | 一张纹理、一个精灵或一个材质 |
TintColor | 颜色 |
DrawAs | None、Box、Border、Image、Tiled(按自身尺寸平铺)、Filled(只显示一部分,进度条那样)、RoundedBox(圆角轮廓) |
ImageSize、Margin、UVRegion、PixelsPerUnitMultiplier | 尺寸、0 到 1 的边距、UV 区域、像素密度 |
FillAmount、FillMethod、FillOrigin、FillDirectionFlip | 仅 Filled:显示多少、切割形状、从哪端开始、另一个方向 |
CornerRadius, CornerSegments | 仅 RoundedBox:每个角的半径(像素,从左上角开始顺时针),以及每段圆弧的点数(矩形块的 CornerRadius 则按右下、右上、左上、左下顺序) |
RoundedBox 是从几何上切出来的轮廓:角的平滑程度取决于段数,且不自带抗锯齿。要精确、与分辨率无关、带边框或渐变的圆角矩形,用 RectBlock。
旁边的两样东西
UDreamSelectableStyle:输入层的数据资产,挂在行为(UUISelectable::Style)上——一组可复用的状态色、状态刷子、动画时长和声音。selectable 上挂着它时,它压过控件推过来的颜色和声音。FDreamTextStyle:文字的描边、投影和发光,整个库共用一个结构体;FDreamRichTextStyle直接带着它,而不是自己再定义一份。
要换掉的不是颜色而是整棵树时,用控件的 Template 属性(在 Style 分类里):给一个里面有正确命名部件的 widget 蓝图,控件用它的树,行为和样式约定照旧。见一个控件是怎么搭起来的。