DreamGUI
类参考

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

NameTypeCategoryIn the details panelFrom BlueprintDescription
StyleFDreamInputKeySelectorStyleInput Key SelectoryesGetStyle / SetStyle此实例自身的外观。当 StyleSource 如此指示且确实存在样式表时,项目样式表优先;项目中没有任何样式表时,这个就是生效的外观——这就是为什么它保持可编辑,而不是由枚举来把关:旧的编辑条件恰恰把驱动该控件的那些值置灰了。
SelectedChordFInputChordInput Key SelectoryesGetSelectedChord / SetSelectedChord绑定的按键及其修饰键——UMG 的 FInputChord,也是该控件的真实值。
SelectedKeyFKeyInput Key SelectoryesGetSelectedKey / SetSelectedKey兼容性拼写:仅和弦的按键,丢弃其修饰键。保留为属性是因为现有的 .dui 会书写它(SelectedKey = (KeyName="SpaceBar"))并对其绑定,也因为 <-> 会解析属性;通过所有路径都与 SelectedChord 保持一致。两者被编写为不一致的地方见 ReconcileKeySpellings。
NoKeyTextFTextInput Key SelectoryesGetNoKeyText / SetNoKeyText未绑定任何内容时显示。为空则保留内置文字,正如空画刷保留字形。
ListeningTextFTextInput Key SelectoryesGetListeningText / SetListeningText处于待命状态时显示。为空则保留内置文字。
bEscapeCancelsboolInput Key SelectoryesGetEscapeCancels / SetEscapeCancelsEscape 解除待命而不是进行绑定。默认开启,原因与 UMG 保留其退出键相同:一个误打开它的玩家需要有一个保证能退出的按键,而一个会绑定任意按键的控件没有这样的按键。
EscapeKeysTArray<FKey>Input Key SelectoryesGetEscapeKeys / SetEscapeKeys哪些按键是退出的方式——UMG 的 EscapeKeys,是一个列表,而不是这个控件过去保留的硬编码的单个 Escape。
bAllowModifierKeysboolInput Key SelectoryesAllowModifierKeys / SetAllowModifierKeys捕获的按键是否连同按住的修饰键一起记录。
bAllowGamepadKeysboolInput Key SelectoryesAllowGamepadKeys / SetAllowGamepadKeys手柄按键是否能成为绑定——UMG 的 bAllowGamepadKeys。
FaceNodeTObjectPtr<UDreamWidget>Input Key Selector-read only
LabelNodeTObjectPtr<UDreamWidget>Input Key Selector-read only
ButtonBehaviourTObjectPtr<UUIButton>Input Key Selector-read only
bIsListeningboolInput Key Selector-read only是否处于待命状态。瞬态且只读,从不编写:待命是玩家片刻之前所做之事,一个能编写它的 .dui 会编写出一个吞掉所在界面下一个按键的控件。SetIsListening 是唯一的写入者。
bCaptureKeysWhileListeningboolInput Key SelectoryesGetCaptureKeysWhileListening / SetCaptureKeysWhileListening待命时是否也监听按键本身。

Functions

函数种类描述
bool AllowGamepadKeys()pure允许游戏手柄按键
bool AllowModifierKeys()pureUMG 对 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()pureUMG 的 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)callableUMG 对待命期间显示提示文本的命名。
void SetListeningText(FText InListeningText)callable设置 监听文本
void SetNoKeySpecifiedText(FText InNoKeySpecifiedText)callableUMG 对相同文本的命名。一个字段,两种拼写。
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。

事件

事件签名描述
OnKeySelectedvoid DreamInputKeySelectorKeyEvent__DelegateSignature(FKey SelectedKey)当按键被绑定时触发,来自监听或来自 SetSelectedKey。携带组合键的按键。
OnChordSelectedvoid DreamInputKeySelectorChordEvent__DelegateSignature(FInputChord SelectedChord)同一时刻,携带整个组合键。与 OnKeySelected 一同触发。
OnIsListeningChangedvoid DreamInputKeySelectorListeningEvent__DelegateSignature(bool bIsListening)当待命状态变化时触发,以便界面可以在某个选择器待命时将其余部分变暗。
OnValueChangedBPvoid DreamInputKeySelectorKeyEvent__DelegateSignature(FKey SelectedKey)<-> 约定:双向绑定会针对这个确切的名称合成其反向路由,因此一个值控件会在其显式事件之外同时携带它。与它们一同触发。

与 UMG 对比

UMG 类中每个面向蓝图的成员,以及它们的去向。adopt:同名,同含义。map:在此处以另一个名称或在另一个类型上出现。reject:有意缺失,并附带原因。

UMG成员状态此处说明
UInputKeySelectorWidgetStylemapStyleFDreamInputKeySelectorStyle:按钮的五个状态颜色,加上此控件所需的第六个——监听中,也就是“现在按一个键”反馈的全部。
UInputKeySelectorTextStylemapStyle标签的颜色和大小是 FDreamInputKeySelectorStyle::LabelColor 和 FontSize;本库不会将控件的外观拆分到按钮样式和文本样式中。
UInputKeySelectorSelectedKeymapSelectedChordUMG 的 SelectedKey 本身就是一个 FInputChord,因此组合键是忠实的映射。此控件还携带一个裸 FKey 的 SelectedKey 作为现有 .dui 作者所使用的兼容拼写,并通过每个写入者保持一致。
UInputKeySelectorMarginmapFDreamInputKeySelectorStyle::ContentPadding按键名称周围的间距。属于外观,因此位于样式结构中。
UInputKeySelectorKeySelectionTextmapListeningTextSetKeySelectionText 携带 UMG 名称并转发。为空时保留内置文本,因此项目可以覆盖提示而无需覆盖控件。
UInputKeySelectorNoKeySpecifiedTextmapNoKeyTextSetNoKeySpecifiedText 携带 UMG 名称并转发。
UInputKeySelectorbAllowModifierKeysadoptbAllowModifierKeys只有捕获路径会读取它:NotifyKeyPressed 和 NotifyChordPressed 由已经知道按下了什么的调用者提供。
UInputKeySelectorbAllowGamepadKeysadoptbAllowGamepadKeys默认开启,这也是捕获代理原本的行为。关闭时,手柄按键既不会被绑定也不会被消耗——它本是为别的东西准备的,吞掉它会导致选择器待命时手柄什么都不做。会先检查退出按键,因此手柄的 B 键仍是退出方式。
UInputKeySelectorEscapeKeysadoptEscapeKeys预置为 Escape 和手柄的 B 键。清空它是合法的,意味着点击是唯一的退出方式,头文件将其记录为陷阱。
UInputKeySelectorOnKeySelectedmapOnChordSelectedUMG 的携带一个 FInputChord,在此处是 OnChordSelected。此控件还在同一时刻以裸按键触发 OnKeySelected,供只关心哪个按键的消费者使用。
UInputKeySelectorOnIsSelectingKeyChangedmapOnIsListeningChanged携带新状态,而 UMG 的什么都不携带——一个将屏幕其余部分变暗的处理程序需要知道它朝哪个方向变化了。
UInputKeySelectorSetSelectedKeymapSetSelectedChordUMG 的接受一个 FInputChord。此处也存在 SetSelectedKey 并接受裸 FKey,它会清除任何修饰键:“就绑定这个按键”正是按键形态 setter 调用者所表达的意思。
UInputKeySelectorSetKeySelectionTextadoptSetKeySelectionText转发到 SetListeningText,它会立即重新标记。
UInputKeySelectorSetNoKeySpecifiedTextadoptSetNoKeySpecifiedText转发到 SetNoKeyText。
UInputKeySelectorSetAllowModifierKeysadoptSetAllowModifierKeys
UInputKeySelectorSetAllowGamepadKeysadoptSetAllowGamepadKeys
UInputKeySelectorGetIsSelectingKeyadoptGetIsSelectingKey待命状态在 UMG 中的名称;GetIsListening 是本库对同一标志自己的拼写。
UInputKeySelectorSetTextBlockVisibilityadoptSetTextBlockVisibility接受 EDreamWidgetVisibility,即本库对同一问题的五个自有答案。仅限标签:表面保持其可见性,因此选择器仍可点击,这是从待命状态退出的已记录方式。
UInputKeySelectorSetEscapeKeysadoptSetEscapeKeys

本页目录