UDreamInputKeySelector
UDreamInputKeySelector
继承自 UDreamUIControl。
声明于 Public/Controls/DreamInputKeySelector.h 中。
一个标签为绑定的按键、并且被点击时监听下一个按键的按钮。
两个节点和一个行为,正是按钮的构造——按钮面就是根节点,按键名居中显示在其上——因为这就是这个控件的本质:一个承载值的按钮。点击它会将其置为待命状态(bIsListening),接下来告知它的按键就成为该值,然后它解除待命。
按键从何而来,直白地说,因为这个插件没有可以提供它的钩子,这个类也不假装有。这里存在的是:
- UDreamUIActionRouter,它从数据表路由具名动作。它把按键解析为一个动作并触发该动作的回调;它无法报告按键本身,而重绑定需要的是按键,不是含义。
- ADreamStandaloneInputEventSystemActor,它确实持有真实的 FKey——其 AnyKey 绑定就是它们到达的地方——但会直接将它们转发到导航和路由器,不广播任何内容。OnAnyKeyPressed 是私有的且非虚。
- UDreamUserWidget 的蓝图接口,涉及指针、拖拽、焦点和导航。没有按键。(UUITextInput 确实会捕获原始按键,方法是生成一个使用 AutoReceiveInput 的 actor 并在其上绑定每个按键。那是文本框的代价——每个活动文本框一个 actor,消费它所绑定的内容——而在一 个控件内部悄悄发明它的第二份副本,不是这个类会做的事。)
所以待命、状态、视觉呈现和值都在这里,而按键是被喂进来的:当它处于监听状态时,项目的输入层用玩家按下的任何按键调用 NotifyKeyPressed,当它接受该按键时返回 true。那一层就是项目已经能看到按键的地方——它的 PlayerController、一个 Enhanced Input 动作,或者一个覆写 BindActionRouting(正是为这类扩展而设为虚)的 ADreamStandaloneInputEventSystemActor 子类。SetSelectedKey 在不涉及监听的情况下写入值,用于设置界面恢复已保存的绑定。
UMG 对等性是 UInputKeySelector 的核心:SelectedChord(以 SelectedKey 作为其裸按键拼写)、bIsListening、OnKeySelected、OnIsSelectingKey——再加上本库的 OnValueChangedBP,因为按键就是一个值,<-> 会对其绑定。
/Script/DreamGUIControls.DreamInputKeySelector JumpBinding {
SelectedKey = (KeyName="SpaceBar")
OnKeySelected -> HandleJumpRebound
}Properties
| Name | Type | Category | In the details panel | From Blueprint | Description |
|---|---|---|---|---|---|
Style | FDreamInputKeySelectorStyle | Input Key Selector | yes | GetStyle / SetStyle | 此实例自身的外观。当 StyleSource 如此指示且确实存在样式表时,项目样式表优先;项目中没有任何样式表时,这个就是生效的外观——这就是为什么它保持可编辑,而不是由枚举来把关:旧的编辑条件恰恰把驱动该控件的那些值置灰了。 |
SelectedChord | FInputChord | Input Key Selector | yes | GetSelectedChord / SetSelectedChord | 绑定的按键及其修饰键——UMG 的 FInputChord,也是该控件的真实值。 |
SelectedKey | FKey | Input Key Selector | yes | GetSelectedKey / SetSelectedKey | 兼容性拼写:仅和弦的按键,丢弃其修饰键。保留为属性是因为现有的 .dui 会书写它(SelectedKey = (KeyName="SpaceBar"))并对其绑定,也因为 <-> 会解析属性;通过所有路径都与 SelectedChord 保持一致。两者被编写为不一致的地方见 ReconcileKeySpellings。 |
NoKeyText | FText | Input Key Selector | yes | GetNoKeyText / SetNoKeyText | 未绑定任何内容时显示。为空则保留内置文字,正如空画刷保留字形。 |
ListeningText | FText | Input Key Selector | yes | GetListeningText / SetListeningText | 处于待命状态时显示。为空则保留内置文字。 |
bEscapeCancels | bool | Input Key Selector | yes | GetEscapeCancels / SetEscapeCancels | Escape 解除待命而不是进行绑定。默认开启,原因与 UMG 保留其退出键相同:一个误打开它的玩家需要有一个保证能退出的按键,而一个会绑定任意按键的控件没有这样的按键。 |
EscapeKeys | TArray<FKey> | Input Key Selector | yes | GetEscapeKeys / SetEscapeKeys | 哪些按键是退出的方式——UMG 的 EscapeKeys,是一个列表,而不是这个控件过去保留的硬编码的单个 Escape。 |
bAllowModifierKeys | bool | Input Key Selector | yes | AllowModifierKeys / SetAllowModifierKeys | 捕获的按键是否连同按住的修饰键一起记录。 |
bAllowGamepadKeys | bool | Input Key Selector | yes | AllowGamepadKeys / SetAllowGamepadKeys | 手柄按键是否能成为绑定——UMG 的 bAllowGamepadKeys。 |
FaceNode | TObjectPtr<UDreamWidget> | Input Key Selector | - | read only | |
LabelNode | TObjectPtr<UDreamWidget> | Input Key Selector | - | read only | |
ButtonBehaviour | TObjectPtr<UUIButton> | Input Key Selector | - | read only | |
bIsListening | bool | Input Key Selector | - | read only | 是否处于待命状态。瞬态且只读,从不编写:待命是玩家片刻之前所做之事,一个能编写它的 .dui 会编写出一个吞掉所在界面下一个按键的控件。SetIsListening 是唯一的写入者。 |
bCaptureKeysWhileListening | bool | Input Key Selector | yes | GetCaptureKeysWhileListening / SetCaptureKeysWhileListening | 待命时是否也监听按键本身。 |
Functions
| 函数 | 种类 | 描述 |
|---|---|---|
bool AllowGamepadKeys() | pure | 允许游戏手柄按键 |
bool AllowModifierKeys() | pure | UMG 对 GetAllowModifierKeys 的拼写,也就是它自己的 getter 所携带的名称。 |
void BeginListening() | callable | 进入待命:下次喂给 NotifyKeyPressed 的按键就是新绑定。点击时执行的操作。 |
void CancelListening() | callable | 解除待命且不绑定任何内容。Escape 执行的操作,也是关闭界面时应执行的操作。 |
bool GetCaptureKeysWhileListening() | pure | 获取 监听时捕获按键 |
bool GetEscapeCancels() | pure | 获取 Escape 取消 |
TArray<FKey> GetEscapeKeys() | pure | 获取 Escape 按键 |
bool GetIsListening() | pure | 获取 是否监听中 |
bool GetIsSelectingKey() | pure | UMG 的 GetIsSelectingKey:待命状态在 UMG 中的名称。 |
FText GetListeningText() | pure | 获取 监听文本 |
FText GetNoKeyText() | pure | 获取 无按键文本 |
FInputChord GetSelectedChord() | pure | 获取 选中组合键 |
FKey GetSelectedKey() | pure | 获取 选中按键 |
FDreamInputKeySelectorStyle GetStyle() | pure | 获取 样式 |
bool NotifyChordPressed(FInputChord InChord) | callable | 组合键形态的孪生版本,适用于输入层知道按下了哪些修饰键的项目。NotifyKeyPressed 正是它不带修饰键的形式,因此两者不会产生不同含义:它转发到这里。 |
bool NotifyKeyPressed(FKey InKey) | callable | 向此选择器提供一个按键。类注释所说的入口点:本插件中没有任何地方调用它,项目自己的输入层才会调用。 |
void SetAllowGamepadKeys(bool bInAllowGamepadKeys) | callable | 设置 允许游戏手柄按键 |
void SetAllowModifierKeys(bool bInAllowModifierKeys) | callable | 设置 允许修饰键 |
void SetCaptureKeysWhileListening(bool bInCaptureKeysWhileListening) | callable | 在待命时将其关闭会立即释放捕获代理;无人能停止的捕获就是个陷阱。 |
void SetEscapeCancels(bool bInEscapeCancels) | callable | 设置 Escape 取消 |
void SetEscapeKeys(TArray<FKey> InKeys) | callable | 哪些按键是退出方式。空列表表示没有退出方式——参见该属性。 |
void SetKeySelectionText(FText InKeySelectionText) | callable | UMG 对待命期间显示提示文本的命名。 |
void SetListeningText(FText InListeningText) | callable | 设置 监听文本 |
void SetNoKeySpecifiedText(FText InNoKeySpecifiedText) | callable | UMG 对相同文本的命名。一个字段,两种拼写。 |
void SetNoKeyText(FText InNoKeyText) | callable | 在未绑定任何内容时立即重新标记,这是唯一会显示这些文本的状态。 |
void SetSelectedChord(FInputChord InChord) | callable | 整个绑定,包括修饰键。两种拼写都经由的同一个写入者。 |
void SetSelectedKey(FKey InKey) | callable | 写入值并重新标记;仅当绑定确实变化时才广播。从不监听。 |
void SetStyle(FDreamInputKeySelectorStyle InStyle) | callable | 一次性重新推送整个外观——包括跟随待命状态的表面颜色。 |
void SetTextBlockVisibility(EDreamWidgetVisibility InVisibility) | callable | 显示或隐藏表面上的文本——UMG 的 SetTextBlockVisibility。 |
事件
| 事件 | 签名 | 描述 |
|---|---|---|
OnKeySelected | void DreamInputKeySelectorKeyEvent__DelegateSignature(FKey SelectedKey) | 当按键被绑定时触发,来自监听或来自 SetSelectedKey。携带组合键的按键。 |
OnChordSelected | void DreamInputKeySelectorChordEvent__DelegateSignature(FInputChord SelectedChord) | 同一时刻,携带整个组合键。与 OnKeySelected 一同触发。 |
OnIsListeningChanged | void DreamInputKeySelectorListeningEvent__DelegateSignature(bool bIsListening) | 当待命状态变化时触发,以便界面可以在某个选择器待命时将其余部分变暗。 |
OnValueChangedBP | void DreamInputKeySelectorKeyEvent__DelegateSignature(FKey SelectedKey) | <-> 约定:双向绑定会针对这个确切的名称合成其反向路由,因此一个值控件会在其显式事件之外同时携带它。与它们一同触发。 |
与 UMG 对比
UMG 类中每个面向蓝图的成员,以及它们的去向。adopt:同名,同含义。map:在此处以另一个名称或在另一个类型上出现。reject:有意缺失,并附带原因。
| UMG | 成员 | 状态 | 此处 | 说明 |
|---|---|---|---|---|
UInputKeySelector | WidgetStyle | map | Style | FDreamInputKeySelectorStyle:按钮的五个状态颜色,加上此控件所需的第六个——监听中,也就是“现在按一个键”反馈的全部。 |
UInputKeySelector | TextStyle | map | Style | 标签的颜色和大小是 FDreamInputKeySelectorStyle::LabelColor 和 FontSize;本库不会将控件的外观拆分到按钮样式和文本样式中。 |
UInputKeySelector | SelectedKey | map | SelectedChord | UMG 的 SelectedKey 本身就是一个 FInputChord,因此组合键是忠实的映射。此控件还携带一个裸 FKey 的 SelectedKey 作为现有 .dui 作者所使用的兼容拼写,并通过每个写入者保持一致。 |
UInputKeySelector | Margin | map | FDreamInputKeySelectorStyle::ContentPadding | 按键名称周围的间距。属于外观,因此位于样式结构中。 |
UInputKeySelector | KeySelectionText | map | ListeningText | SetKeySelectionText 携带 UMG 名称并转发。为空时保留内置文本,因此项目可以覆盖提示而无需覆盖控件。 |
UInputKeySelector | NoKeySpecifiedText | map | NoKeyText | SetNoKeySpecifiedText 携带 UMG 名称并转发。 |
UInputKeySelector | bAllowModifierKeys | adopt | bAllowModifierKeys | 只有捕获路径会读取它:NotifyKeyPressed 和 NotifyChordPressed 由已经知道按下了什么的调用者提供。 |
UInputKeySelector | bAllowGamepadKeys | adopt | bAllowGamepadKeys | 默认开启,这也是捕获代理原本的行为。关闭时,手柄按键既不会被绑定也不会被消耗——它本是为别的东西准备的,吞掉它会导致选择器待命时手柄什么都不做。会先检查退出按键,因此手柄的 B 键仍是退出方式。 |
UInputKeySelector | EscapeKeys | adopt | EscapeKeys | 预置为 Escape 和手柄的 B 键。清空它是合法的,意味着点击是唯一的退出方式,头文件将其记录为陷阱。 |
UInputKeySelector | OnKeySelected | map | OnChordSelected | UMG 的携带一个 FInputChord,在此处是 OnChordSelected。此控件还在同一时刻以裸按键触发 OnKeySelected,供只关心哪个按键的消费者使用。 |
UInputKeySelector | OnIsSelectingKeyChanged | map | OnIsListeningChanged | 携带新状态,而 UMG 的什么都不携带——一个将屏幕其余部分变暗的处理程序需要知道它朝哪个方向变化了。 |
UInputKeySelector | SetSelectedKey | map | SetSelectedChord | UMG 的接受一个 FInputChord。此处也存在 SetSelectedKey 并接受裸 FKey,它会清除任何修饰键:“就绑定这个按键”正是按键形态 setter 调用者所表达的意思。 |
UInputKeySelector | SetKeySelectionText | adopt | SetKeySelectionText | 转发到 SetListeningText,它会立即重新标记。 |
UInputKeySelector | SetNoKeySpecifiedText | adopt | SetNoKeySpecifiedText | 转发到 SetNoKeyText。 |
UInputKeySelector | SetAllowModifierKeys | adopt | SetAllowModifierKeys | |
UInputKeySelector | SetAllowGamepadKeys | adopt | SetAllowGamepadKeys | |
UInputKeySelector | GetIsSelectingKey | adopt | GetIsSelectingKey | 待命状态在 UMG 中的名称;GetIsListening 是本库对同一标志自己的拼写。 |
UInputKeySelector | SetTextBlockVisibility | adopt | SetTextBlockVisibility | 接受 EDreamWidgetVisibility,即本库对同一问题的五个自有答案。仅限标签:表面保持其可见性,因此选择器仍可点击,这是从待命状态退出的已记录方式。 |
UInputKeySelector | SetEscapeKeys | adopt | SetEscapeKeys |