UDreamToggle
UDreamToggle
继承自 UDreamUIControl。
声明于 Public/Controls/DreamToggle.h。
一个层级结构由代码而非资源构成的开关。
BP_Toggle 拥有的同样四个节点——一个方框、其中有一个勾选标记、旁边有一个标签——在 NativeOnInitialized 中构建,而不是从模板实例化而来。这样做的收益在于,该控件不可能处于半成品状态:BP_Button 发布了数月却没有在其上挂载 UIButton,而没有任何人指出这一点,而一个总是添加自身行为的类不可能遭遇这种情况。
代价则是一棵没人能打开的树。作者原本必须深入层级结构去修改的一切,在这里都必须成为属性,这就是 FDreamToggleStyle 的意义所在,而一旦某个项目希望其所有开关保持一致,这就不再足够了。
它无需任何语言改动即可组合进 .dui,因为类路径本身就已经是一个节点标签:
Native.Toggle Mute {
Style.TickChecked = #FF3355
OnToggleChanged -> HandleMute
}刻意不带标签:复选框就是一个方块和它的标记,旁边的文字属于使用方的布局。在屏幕所需的任意行中,将它和一个 Text 节点搭配使用。
在 API 层面,它沿用 UMG 的复选框:CheckedState(Unchecked/Checked/Undetermined)以及 GetCheckedState/SetCheckedState、IsChecked/SetIsChecked 和 OnCheckStateChanged。bIsOn 连同 GetIsOn/SetIsOn 和 OnToggleChanged 是两态子集的兼容写法,并且完全可绑定;这两种写法在每条路径上互为镜像,而当作者填写的值出现分歧时,CheckedState 胜出(参见 ReconcileCheckSpellings)。
第三个状态是控件自身所有的。其下的行为仍为两态,并且在 Undetermined 成立期间停驻于未选中;勾选标记会把对勾换成 TickChecked 颜色的一条横杠。一次点击会以变为未选中的方式离开 Undetermined,正如 UMG 的 SCheckBox 那样。
属性
| 名称 | 类型 | 类别 | 在细节面板中 | 来自蓝图 | 描述 |
|---|---|---|---|---|---|
Style | FDreamToggleStyle | 开关 | 是 | GetStyle / SetStyle | 此实例自身的外观。当 StyleSource 如此指示且项目中确实存在样式表时,项目样式表胜出;项目中没有任何样式表时,这里就是实际生效的外观——这就是为什么它保持可编辑,而不是被该枚举所门控:旧的编辑条件恰恰把正在驱动控件的那些值置灰了。 |
ClickMethod | EDreamUIClickMethod | 开关 | 是 | GetClickMethod / SetClickMethod | 勾选标记何时翻转,按输入类型区分——UMG 的三个枚举,在控件上暴露的方式与 UDreamButton 完全一致,原因也相同:它们位于底层的可选中控件上,而一个从不声明它们的控件会让桌面上的每个复选框都停留在 DownAndUp。 |
TouchMethod | EDreamUITouchMethod | 开关 | 是 | GetTouchMethod / SetTouchMethod | |
PressMethod | EDreamUIPressMethod | 开关 | 是 | GetPressMethod / SetPressMethod | |
AcceptedMouseButtons | int32 | 开关 | 是 | GetAcceptedMouseButtons / SetAcceptedMouseButtons | 哪些鼠标按键会按下并翻转此复选框——一个基于 EDreamUIMouseButtonType 的位掩码,默认仅左键,这是 UMG 的规则:SCheckBox 仅在左键上切换,其他按键都不行,因此右键点击既不会按下也不会翻转它,而是继续传递给其后方的内容。 |
CheckedState | EDreamCheckState | 开关 | 是 | GetCheckedState / SetCheckedState | 作者设定的状态,采用 UMG 的拼写并带有 UMG 的第三个值。点击对其的移动方式与 UMG 的复选框一致:从未选中到选中,从已选中或未确定到未选中——混合状态会被点击清除,绝不会被勾选。它是属性而非仅有一对 getter/setter,因为仅有那一对是不可见的:.dui 写入属性,设计器列出属性,绑定解析属性——因此一个仅作为两个 UFUNCTION 存在的旋钮,是 C++ 之外任何东西都无法转动的旋钮。 |
bIsOn | bool | 开关 | 是 | GetIsOn / SetIsOn | 兼容性拼写:以布尔值表示的 CheckedState。选中映射为 true;未选中和未确定映射为 false。保留为属性是因为现有的 .dui 对其做双向绑定(bIsOn <-> ...),而绑定解析的是属性;通过每条路径(作者推送、用户点击、程序化设置)都与 CheckedState 保持同步。新代码应使用 CheckedState。 |
BoxNode | TObjectPtr<UDreamWidget> | 开关 | - | 只读 | 各个部件,以框架其余部分期望找到它们的形态呈现。 |
TickNode | TObjectPtr<UDreamWidget> | 开关 | - | 只读 | |
MarkNode | TObjectPtr<UDreamWidget> | 开关 | - | 只读 | 图像标记——仅当当前状态的画刷包含图像时激活。 |
ToggleBehaviour | TObjectPtr<UUIToggle> | 开关 | - | 只读 |
函数
| 函数 | 类型 | 描述 |
|---|---|---|
int32 GetAcceptedMouseButtons() | 纯函数 | 获取可接受的鼠标按键 |
EDreamCheckState GetCheckedState() | 纯函数 | 完整状态。对于它能保持的两个状态,行为体才是真相;未确定是控件自身所有的,并从这里读取。 |
EDreamUIClickMethod GetClickMethod() | 纯函数 | 获取点击方式 |
bool GetIsOn() | 纯函数 | IsChecked() 的兼容性拼写:行为体存在后返回其布尔值,之前返回 bIsOn。 |
EDreamUIPressMethod GetPressMethod() | 纯函数 | 获取按压方式 |
FDreamToggleStyle GetStyle() | 纯函数 | 获取样式 |
EDreamUITouchMethod GetTouchMethod() | 纯函数 | 获取触摸方式 |
bool IsChecked() | 纯函数 | UMG 的便捷写法:恰好等于 GetCheckedState() == Checked。 |
bool IsPressed() | 纯函数 | 指针是否正按住该方框——即 UMG 的 IsPressed,复选框拥有它的原因与按钮相同。向行为体询问,而不是在此处记忆:第二份“是否按下”的副本,会在某次按压结束于本控件听不到的位置时第一次变得过时。 |
void SetAcceptedMouseButtons(int32 InAcceptedMouseButtons) | 可调用 | 写入位掩码,并如同三个方式设置器一样立即将其推送到行为体上。 |
void SetCheckedState(EDreamCheckState InCheckedState) | 可调用 | 设置三种状态中的任意一种。选中/未选中通过行为体并带通知处理,即点击所走的路径;未确定将行为体停留在未选中且不发通知,并保存在控件上(见类注释)。 |
void SetClickMethod(EDreamUIClickMethod InMethod) | 可调用 | 以下四个设置器各自写入字段并重新将其推送到行为体上。 |
void SetIsChecked(bool bInIsChecked) | 可调用 | UMG 对 SetIsOn 的便捷拼写。 |
void SetIsOn(bool bInIsOn) | 可调用 | SetCheckedState(Checked/Unchecked) 的兼容性拼写。 |
void SetPressMethod(EDreamUIPressMethod InMethod) | 可调用 | 设置按压方式 |
void SetStyle(FDreamToggleStyle InStyle) | 可调用 | 此实例的完整外观,替换后推送。注意事项见 UDreamButton::SetStyle。 |
void SetTouchMethod(EDreamUITouchMethod InMethod) | 可调用 | 设置触摸方式 |
事件
| 事件 | 签名 | 描述 |
|---|---|---|
OnToggleChanged | void DreamToggleChangedEvent__DelegateSignature(bool bIsOn) | 由底层的开关触发,并在此处重新广播,使消费者永远不必深入部件内部。OnCheckStateChanged 的兼容性拼写:每当该状态的布尔投影发生变化时触发(因此未选中 <-> 未确定的变动在这里是静默的)。 |
OnCheckStateChanged | void DreamCheckStateChangedEvent__DelegateSignature(EDreamCheckState CheckedState) | UMG 对同一时刻的拼写,携带完整状态。每当 CheckedState 变化时触发——当布尔投影也移动时,与 OnToggleChanged 一同触发。 |
OnValueChangedBP | void DreamToggleChangedEvent__DelegateSignature(bool bIsOn) | <-> 约定:双向绑定依据这个确切名称合成其反向路径,因此值控件会将其与自身对外声明的事件一同携带。与它们一同触发。 |
OnPressed | void DreamToggleSimpleEvent__DelegateSignature() | 四个指针时刻,与值变化完全一样地从行为体重新广播。 |
OnReleased | void DreamToggleSimpleEvent__DelegateSignature() | |
OnHovered | void DreamToggleSimpleEvent__DelegateSignature() | |
OnUnhovered | void DreamToggleSimpleEvent__DelegateSignature() |
与 UMG 的对比
UMG 类中每一个面向蓝图的成员,以及它们去向何处。adopt:相同名称,相同含义。map:在这里以另一个名称或位于另一个类型上。reject:有意缺失,并附原因。
| UMG | 成员 | 状态 | 此处 | 备注 |
|---|---|---|---|---|
UCheckBox | CheckedState | adopt | CheckedState | EDreamCheckState,相同的三个值。bIsOn 是双状态兼容性拼写并与之镜像。 |
UCheckBox | WidgetStyle | map | Style | FDreamToggleStyle。其 CheckedBrush / UncheckedBrush / UndeterminedBrush 是 UMG 的三个标记图像;StateFaces 是框体按指针状态的绘制。 |
UCheckBox | HorizontalAlignment | reject | 此控件是一个框体及其标记,完全没有内容槽位——复选框旁边的文本在这里是使用者自己的布局。没有任何可供对齐的东西。 | |
UCheckBox | ClickMethod | adopt | ClickMethod | EDreamUIClickMethod;被推送到底层的可选择对象上。 |
UCheckBox | TouchMethod | adopt | TouchMethod | |
UCheckBox | PressMethod | adopt | PressMethod | |
UCheckBox | IsFocusable | map | UDreamWidget::bIsFocusable | 这里的每个控件都携带它;控件级的副本会遮蔽基类成员。 |
UCheckBox | OnCheckStateChanged | adopt | OnCheckStateChanged | 携带完整状态。OnToggleChanged 是布尔投影并与之同时触发。只有 AcceptedMouseButtons 中的鼠标按键才会按下并翻转框体——默认仅左键,这是 SCheckBox 的规则;AcceptedMouseButtons 是此控件自己的旋钮,如同 UDreamButton 上的一样。双击会翻转框体两次,正如 SCheckBox 那样:第二次按下以双击形式到达,切换将其作为自身的按下处理(SCheckBox::OnMouseButtonDoubleClick 即 OnMouseButtonDown)。 |
UCheckBox | IsPressed | adopt | IsPressed | 询问行为的选中状态,而不是在控件上记忆。 |
UCheckBox | IsChecked | adopt | IsChecked | |
UCheckBox | GetCheckedState | adopt | GetCheckedState | |
UCheckBox | SetIsChecked | adopt | SetIsChecked | |
UCheckBox | SetCheckedState | adopt | SetCheckedState | Undetermined 将双状态行为停在未选中并存在于控件上;一次点击通过变为 UNCHECKED 来离开它,正如 UMG 那样(SCheckBox::ToggleCheckedState:Checked 或 Undetermined 变为 Unchecked,Unchecked 变为 Checked)。 |
UCheckBox | SetClickMethod | adopt | SetClickMethod | |
UCheckBox | SetTouchMethod | adopt | SetTouchMethod | |
UCheckBox | SetPressMethod | adopt | SetPressMethod | |
UCheckBox | SetStyle | adopt | SetStyle | 不是 UCheckBox 上的 UFUNCTION(其 Setter meta 如此命名);在此添加是因为一个运行时无法替换的样式是只有设计者才能更改的外观。 |