UDreamDialog
UDreamDialog
继承自 UDreamUIControl。
声明于 Public/Controls/DreamDialog.h。
一个层级由代码而非资源构成的对话框:一个遮罩、一个居中的面板、一个标题、一个带有消息的内容区域,以及一行按钮。
它不做什么,因为 UDreamUIModalSubsystem 已经做了。通过 ShowModal 打开时,对话框被挂到该子系统的模态 LAYER 下,该层本身就是遮罩(一个占满整个矩形的着色矩形块),携带 UUIEventBlocker 拦截所有指向下方世界的指针事件,排序在页面层带之上,并压入一个 UDreamUIModalScope,后者限制手柄焦点并赋予 Back 以“以 Back 结果关闭”的含义。这些都不在这里重新实现。分工是:SUBSYSTEM 拥有屏幕(变暗、输入拦截、焦点、一次一个的排队,以及将结果带回调用方);DIALOG 拥有面板(它说什么、提供哪些按钮、每个按钮意味着什么结果),并通过调用 CloseTopModal 结束模态。
因此,遮罩部分是为另一种受支持的安排而存在的——独立使用。作为普通控件放入 .dui 时(休眠,在需要提问时被唤醒),它的上方没有子系统层,所以对话框自身的遮罩是唯一让屏幕变暗的东西,它的 UUIEventBlocker 也是唯一阻止点击穿到背后的东西。当宿主本身已经在做遮罩时——检测方式是在父级链上任意位置存在一个拦截器,而这正是模态层所携带的——对话框会收起自己的遮罩,而不是让屏幕变暗两次。两种安排都受支持;两者之间的树结构没有任何变化。
按钮是真正的 Native.Button 实例,而不是手工构建的外观,因此项目只需为按钮设置一次样式,对话框按钮就会跟随。FDreamDialogStyle 专门为此携带了 Button 和 PrimaryButton,并且创建的按钮会被切换为 Inline 样式来源:对话框样式已经解析完成(表或实例),它指定的外观必须胜出,否则每个对话框按钮都会悄悄地重新解析为表中的普通按钮,那两个样式字段就毫无作用。
关于按钮列表和 .dui:该语言目前还没有数组字面量,正如 Native.Dropdown 的 Options 所诚实说明的那样。Buttons 仍然可以从 C++、从蓝图以及从细节面板填充——而且构造函数会预置 Cancel + OK(OK 为主按钮),所以常见的对话框完全不需要数组:
/Script/DreamGUIControls.DreamDialog Confirm {
Title = "删除存档"
Message = "这个操作不能撤销。"
OnDialogClosed -> HandleAnswer
}用枚举固定一对 OK/Cancel 按钮,对同样的情况并不会表达得更好,对三按钮的情况更是无从表达,这正是数组胜出的原因。
Properties
| Name | Type | Category | In the details panel | From Blueprint | Description |
|---|---|---|---|---|---|
Style | FDreamDialogStyle | Dialog | yes | SetStyle | 此实例自身的外观。当 StyleSource 如此指示且表中确实存在一个表时,项目表胜出;当项目中没有任何表时,这个值就是实际生效的外观——这就是为什么它保持可编辑,而不是受该枚举限制。 |
Title | FText | Dialog | yes | GetTitle / SetTitle | 为空时完全收起标题,而不是为它保留一个空行。 |
Message | FText | Dialog | yes | GetMessage / SetMessage | 内容区域的内置占用者。为空时将其收起;该区域保留给其他内容。 |
Buttons | TArray<FDreamDialogButton> | Dialog | yes | read only | 每个条目对应一个 Native.Button,从左到右。预置为 Cancel + OK;见类注释。 |
CancelResult | FName | Dialog | yes | SetCancelResult | 当对话框被取消而不是被作答时,Close 被调用时使用的结果——RequestCancel,以及项目将 Escape 或 Back 路由到的任何内容。 |
bFocusDefaultButton | bool | Dialog | yes | SetFocusDefaultButton | 当对话框出现时将焦点放在默认按钮上。 |
bCloseOnBack | bool | Dialog | yes | SetCloseOnBack | Back(Escape,或手柄的 B)以该对话框的取消结果关闭它。 |
bCloseOnDimmerClick | bool | Dialog | yes | SetCloseOnDimmerClick | 点击遮罩会以该对话框的取消结果关闭它——每个桌面对话框都有的“点击外部以关闭”。 |
bShowDimmer | bool | Dialog | yes | GetShowDimmer / SetShowDimmer | 此对话框自身是否让屏幕变暗。 |
DimmerNode | TObjectPtr<UDreamWidget> | Dialog | - | read only | 全屏遮罩。当宿主本身已经在做遮罩时处于休眠状态;见类注释。 |
PanelNode | TObjectPtr<UDreamWidget> | Dialog | - | read only | |
TitleNode | TObjectPtr<UDreamWidget> | Dialog | - | read only | |
BodyNode | TObjectPtr<UDreamWidget> | Dialog | - | read only | 中间层带上的空洞。为空是正常状态;宿主放在这里的内容会取代内置消息,后者正是因此才作为它的覆盖兄弟而非子级。 |
ContentNode | TObjectPtr<UDreamWidget> | Dialog | - | read only | 中间层带。存放 MessageNode,也是使用者自身内容的去处。 |
MessageNode | TObjectPtr<UDreamWidget> | Dialog | - | read only | |
ButtonRowNode | TObjectPtr<UDreamWidget> | Dialog | - | read only | |
ButtonWidgets | TArray<TObjectPtr<UDreamButton> > | Dialog | - | read only | 每个 Buttons 条目对应一个,按顺序。每当规格变化时重建。 |
BackScope | TObjectPtr<UDreamDialogScope> | Dialog | - | read only | 导航作用域,仅在独立使用时添加:它在对话框出现时接管焦点,在对话框关闭时归还焦点,在 bCloseOnBack 要求时响应 Back,并在对话框变暗期间将手柄和 Tab 保持在对话框内,无论 bCloseOnBack 怎么说。它属于该对话框的所有者玩家。见 UDreamDialogScope。 |
Functions
| 函数 | 类型 | 描述 |
|---|---|---|
void Close(FName InResult) | callable | 以 InResult 结束对话框。 |
void FocusDefaultButton() | callable | 立即将焦点放到默认按钮上。当 bFocusDefaultButton 开启时,对话框每次出现都会为你调用;公开是因为按钮在出现后被替换的对话框会有一个新的默认按钮。 |
TArray<FDreamDialogButton> GetButtons() | pure | 获取按钮 |
UDreamButton* GetDefaultButton() | pure | 主按钮,没有标记时则为最后一个,空行时为 null。 |
FText GetMessage() | pure | 获取消息 |
bool GetShowDimmer() | pure | 获取显示遮罩 |
FText GetTitle() | pure | 获取标题 |
void RequestCancel() | callable | 以该结果关闭。项目的 Escape 或 Back 处理程序所调用的,以及点击遮罩会调用的——此控件自身不路由这两者(见类注释)。 |
FName ResolveCancelResult() | pure | 对话框被取消而非回答时给出的结果:CancelResult(如果指定了的话),否则为按钮行自身的取消(见 CancelResult)。 |
void SetButtons(TArray<FDreamDialogButton> InButtons) | callable | 整体替换按钮行;控件会立即根据新规格重建。 |
void SetCancelResult(FName InCancelResult) | callable | Back 和点击遮罩所给出的结果。在关闭的那一刻读取。 |
void SetCloseOnBack(bool bInCloseOnBack) | callable | Back 是否关闭对话框。Back 作用域会相应地添加或释放,这就是它是个 setter 的原因。 |
void SetCloseOnDimmerClick(bool bInCloseOnDimmerClick) | callable | 点击外部是否关闭对话框。遮罩的按钮会相应地添加或解绑。 |
void SetFocusDefaultButton(bool bInFocusDefaultButton) | callable | 设置焦点默认按钮 |
void SetMessage(FText InMessage) | callable | 设置消息 |
void SetShowDimmer(bool bInShowDimmer) | callable | 此对话框是否自行使屏幕变暗,立即重新决定。 |
void SetStyle(FDreamDialogStyle InStyle) | callable | 替换外观并推送。直接写入变量只会改变一个之后不再被读取的结构体。 |
void SetTitle(FText InTitle) | callable | 设置标题 |
void SubmitDefaultButton() | callable | 像默认按钮那样回答——UMG 的“Enter 按下默认按钮”。 |
事件
| 事件 | 签名 | 描述 |
|---|---|---|
OnDialogClosed | void DreamDialogResultEvent__DelegateSignature(FName Result) | 对话框已关闭,无论以何种方式关闭。恰好触发一次,在模态宿主将其拆除之前。 |
OnButtonClicked | void DreamDialogResultEvent__DelegateSignature(FName Result) | 按钮所发出的内容,在控件上重新广播:消费者在此绑定,而不是绑定到某个按钮。 |