类参考
UDreamUIWidgetLibrary
UDreamUIWidgetLibrary
继承自 UBlueprintFunctionLibrary。
声明于 Public/DreamUIWidgetLibrary.h。
从蓝图中查找控件、驱动拖拽以及构建图像画刷——即 UMG 的 UWidgetBlueprintLibrary 中在本框架里具有实际意义的那部分内容。
不具备实际意义的部分已在对照表中连同原因一并列出,而这些原因归根结底是同一条:UMG 的该函数库有一半是 Slate 的底层管线。FEventReply、OnPaint 绘制上下文以及 Slate 的输入事件结构体描述的是 SWidget 与 Slate 之间的对话,而 DreamGUI 控件从不会有这种对话——它的输入以 UDreamPointerEventData 的形式来自事件系统,其像素则来自自身的网格体。
函数
| 函数 | 类型 | 描述 |
|---|---|---|
bool BeginDragWithOperation(UDreamPointerEventData* InPointerEvent, UDreamDragDropOperation* InOperation) | callable | 立即在控件上开始一次拖拽,来自一个已经按在它上面的指针——即 UMG 的 DetectDragIfPressed,去掉了“如果已按下”的判断,因为调用方手中已经拿到了已按下指针的事件数据,这一步已然满足。 |
bool CancelDragDrop(UObject* WorldContextObject) | callable | 结束所有正在进行中的拖拽且不产生放置——即 Escape 所做的事。若确实有可取消的拖拽则返回 true。 |
UDreamDragDropOperation* CreateDragDropOperation(TSubclassOf<UDreamDragDropOperation> InOperationClass) | callable | 创建一个拖拽操作,交给正在开始的拖拽使用——即 UMG 的 CreateDragDropOperation。 |
int32 DismissAllMenus(UObject* WorldContextObject) | callable | 关闭此世界中任意位置所有打开的菜单锚点——即 UMG 的 DismissAllMenus。 |
bool EqualEqual_DreamUIImageBrush(FDreamUIImageBrush A, FDreamUIImageBrush B) | pure | 两个画刷是否为同一个画刷?即 UMG 的 EqualEqual_SlateBrush,针对本框架的画刷类型。 |
void GetAllWidgetsOfClass(UObject* WorldContextObject, TSubclassOf<UDreamWidget> InWidgetClass, TArray<UDreamWidget*>& OutFoundWidgets, bool bTopLevelOnly) | callable | 世界中任意位置某个类的所有存活控件。 |
void GetAllWidgetsWithInterface(UObject* WorldContextObject, TSubclassOf<UInterface> InInterface, TArray<UDreamWidget*>& OutFoundWidgets, bool bTopLevelOnly) | callable | 其类实现了某个接口的所有存活控件。不搜索行为(Behaviour),只搜索控件。 |
UObject* GetBrushResource(FDreamUIImageBrush InBrush) | pure | 获取画刷资源 |
UMaterialInterface* GetBrushResourceAsMaterial(FDreamUIImageBrush InBrush) | pure | 获取画刷资源为材质 |
UTexture2D* GetBrushResourceAsTexture2D(FDreamUIImageBrush InBrush) | pure | 获取画刷资源为纹理 2D |
UDreamDragDropOperation* GetDragDroppingContent(UObject* WorldContextObject, int32 InPointerID) | pure | 指针正在携带的操作,若无则为 null。指针 0 为鼠标。 |
UMaterialInstanceDynamic* GetDynamicMaterial(FDreamUIImageBrush& InBrush) | callable | 将画刷的材质作为可设置其参数的对象——即 UMG 的 GetDynamicMaterial。 |
bool GetSafeZonePadding(UObject* WorldContextObject, FVector4& OutSafePadding, FVector2D& OutSafePaddingScale) | pure | 平台的标题安全区域内边距(以像素为单位),以及同一内边距占视口的比例。 |
bool IsDragDropping(UObject* WorldContextObject) | pure | 当前是否有任意指针正在携带拖拽操作? |
FDreamUIImageBrush MakeBrushFromAsset(UObject* InResource, int32 InWidth, int32 InHeight) | pure | 一个显示该资产本身内容的图像画刷——纹理、材质、精灵或图集皆可。 |
FDreamUIImageBrush MakeBrushFromMaterial(UMaterialInterface* InMaterial, int32 InWidth, int32 InHeight) | pure | 一个显示材质的图像画刷。 |
FDreamUIImageBrush MakeBrushFromTexture(UTexture2D* InTexture, int32 InWidth, int32 InHeight) | pure | 一个显示纹理的图像画刷。即 UMG 的 MakeBrushFromTexture;尺寸为零表示使用纹理自身的尺寸。 |
FDreamUIImageBrush NoResourceBrush() | pure | 一个不绘制任何内容的画刷。即 UMG 的 NoResourceBrush。 |
void SetBrushResourceToMaterial(FDreamUIImageBrush& InBrush, UMaterialInterface* InMaterial) | callable | 将画刷资源设置为材质 |
void SetBrushResourceToTexture(FDreamUIImageBrush& InBrush, UTexture2D* InTexture) | callable | 将画刷资源设置为纹理 |
void SetFocusToGameViewport() | callable | 将键盘焦点交还给游戏视口——即 UMG 的 SetFocusToGameViewport。 |
bool SetMousePosition(APlayerController* InPlayer, FVector2D InPosition) | callable | 将光标放到某个位置——即 UMG 的 SetMousePosition,去掉了它原本内建的 FEventReply。 |
与 UMG 的对比
UMG 该类中所有面向蓝图的成员,以及它们的去向。adopt:名称相同、含义相同。map:在此处以另一名称或位于另一类型上。reject:有意不提供,并附原因。
| UMG | 成员 | 状态 | 此处 | 备注 |
|---|---|---|---|---|
UWidgetBlueprintLibrary | Create | map | UDreamUIBPLibrary::CreateDreamWidgetOfClass | 与 UMG 标记 Create 一样为 BlueprintInternalUseOnly:Create Dream Widget 节点在图表中代表它,正如 UMG 的 Create Widget 节点代表 Create 一样——每个 Expose on Spawn 属性对应一个引脚,在控件初始化之前而非 Create 之后进行赋值。AddWidgetOfClassToViewport 则是“创建并显示”这一对组合。 |
UWidgetBlueprintLibrary | CreateDragDropOperation | adopt | CreateDragDropOperation | 与 UMG 一样,其 Outer 为瞬态包:操作的生命周期长于创建它的控件,而拖拽中途列表行被回收是常见情况。 |
UWidgetBlueprintLibrary | SetInputMode_UIOnlyEx | map | UDreamUIInputModeLibrary::SetInputModeUIOnly | 通过 DreamGUI 用户索引而非原始控制器来定位,因此分屏无需重新发现某个菜单属于哪个玩家。需要将 UDreamGameViewportClient 作为游戏视口客户端:引擎的仅 UI 模式会在客户端处忽略输入,而 DreamGUI 的输入正是经过该客户端传入的,此客户端会在该模式持续期间放行输入。 |
UWidgetBlueprintLibrary | SetInputMode_GameAndUIEx | map | UDreamUIInputModeLibrary::SetInputModeGameAndUI | |
UWidgetBlueprintLibrary | SetInputMode_GameOnly | map | UDreamUIInputModeLibrary::SetInputModeGameOnly | |
UWidgetBlueprintLibrary | SetFocusToGameViewport | adopt | SetFocusToGameViewport | 这是一次 Slate 焦点变更,而非 DreamGUI 的。UDreamWidget::ClearKeyboardFocus 是框架层面的对应项,二者通常需要一起使用。 |
UWidgetBlueprintLibrary | DrawBox | reject | UMG 的 Draw* 系列会写入交给蓝图 OnPaint 重写的 FPaintContext。此处没有即时模式的绘制过程:DreamGUI 控件通过拥有网格体来绘制,因此任何被绘制的东西都是一个带有可视表现的控件,而不是绘制过程内部的一次调用。 | |
UWidgetBlueprintLibrary | DrawSpline | reject | 参见 DrawBox。 | |
UWidgetBlueprintLibrary | DrawLine | reject | 参见 DrawBox。 | |
UWidgetBlueprintLibrary | DrawLines | reject | 参见 DrawBox。 | |
UWidgetBlueprintLibrary | DrawTextFormatted | reject | 参见 DrawBox。 | |
UWidgetBlueprintLibrary | Handled | reject | FEventReply 是 Slate 的回复对象,由处理程序构建并返回给 Slate。DreamGUI 的处理程序返回一个表示“让此事继续冒泡”的布尔值(IDreamPointer* 接口),因此没有需要构建的回复对象。 | |
UWidgetBlueprintLibrary | Unhandled | reject | 参见 Handled。 | |
UWidgetBlueprintLibrary | CaptureMouse | reject | 无需进行捕获:已按下指针的 PressWidget 已经会接收每一次拖拽,并在指针移动到的任意位置接收释放事件。UDreamWidget::HasMouseCapture 会报告该状态。 | |
UWidgetBlueprintLibrary | ReleaseMouseCapture | reject | 参见 CaptureMouse。 | |
UWidgetBlueprintLibrary | LockMouse | map | UDreamUIInputModeLibrary::SetMouseLockMode | 在那里有意与输入模式分离:为了仅更改锁定而重新设置整个输入模式,正是项目让自己的菜单失去焦点的原因。 |
UWidgetBlueprintLibrary | UnlockMouse | map | UDreamUIInputModeLibrary::SetMouseLockMode | EMouseLockMode::DoNotLock。 |
UWidgetBlueprintLibrary | SetUserFocus | map | UDreamWidget::SetUserFocus | 是控件上的一个动作,而非在处理程序内部构建的回复对象。 |
UWidgetBlueprintLibrary | ClearUserFocus | map | UDreamWidget::ClearKeyboardFocus | |
UWidgetBlueprintLibrary | SetMousePosition | map | SetMousePosition | 是一个动作,而非 UMG 的 FEventReply 构建器。使用视口像素,与 GetMousePositionOnViewport 所报告的空间以及几何体的绝对坐标所在空间相同,因此“将光标移到该控件上”只需一次转换而非两次。 |
UWidgetBlueprintLibrary | DetectDrag | reject | UMG 让处理程序为某个键启用拖拽检测。此处指针管线会依据距离和按住阈值(UDreamEventSystem 的拖拽设置)自行检测拖拽,因此处理程序没有什么可启用的——来源所提供的,是拖拽的“含义”,即 CreateDragDropOperation 加上 BeginDragWithOperation。 | |
UWidgetBlueprintLibrary | DetectDragIfPressed | reject | 参见 DetectDrag。 | |
UWidgetBlueprintLibrary | EndDragDrop | reject | 管线会在指针释放时结束拖拽;处理程序没有可用于结束它的回复对象。CancelDragDrop 是提前结束拖拽的动作。 | |
UWidgetBlueprintLibrary | IsDragDropping | adopt | IsDragDropping | |
UWidgetBlueprintLibrary | GetDragDroppingContent | adopt | GetDragDroppingContent | 按指针区分,因为触摸屏上多根手指可以同时拖动;指针 0 是鼠标。 |
UWidgetBlueprintLibrary | CancelDragDrop | adopt | CancelDragDrop | |
UWidgetBlueprintLibrary | MakeBrushFromAsset | adopt | MakeBrushFromAsset | 接受笔刷能够绘制的任何资源,在这里包括精灵和图集以及纹理和材质。 |
UWidgetBlueprintLibrary | MakeBrushFromTexture | adopt | MakeBrushFromTexture | 宽度或高度为零时保留笔刷自身的尺寸,而不是将其折叠。 |
UWidgetBlueprintLibrary | MakeBrushFromMaterial | adopt | MakeBrushFromMaterial | |
UWidgetBlueprintLibrary | GetBrushResource | adopt | GetBrushResource | |
UWidgetBlueprintLibrary | GetBrushResourceAsTexture2D | adopt | GetBrushResourceAsTexture2D | |
UWidgetBlueprintLibrary | GetBrushResourceAsMaterial | adopt | GetBrushResourceAsMaterial | |
UWidgetBlueprintLibrary | SetBrushResourceToTexture | adopt | SetBrushResourceToTexture | |
UWidgetBlueprintLibrary | SetBrushResourceToMaterial | adopt | SetBrushResourceToMaterial | |
UWidgetBlueprintLibrary | NoResourceBrush | adopt | NoResourceBrush | |
UWidgetBlueprintLibrary | GetDynamicMaterial | adopt | GetDynamicMaterial | 此框架笔刷上的同名操作:持有材质的 FDreamUIImageBrush 会被改写为持有该材质的动态实例,并返回该实例;已经持有实例的则原样返回;纹理或精灵笔刷返回 null。笔刷是一个值,因此调用方需要将它交还给图像(UDreamImage::SetBrush)。这与矩形块的材质不同,后者属于绘制调用,且刻意不向外提供(见 Border.json)。 |
UWidgetBlueprintLibrary | DismissAllMenus | adopt | DismissAllMenus | 遍历世界中的菜单锚点并关闭已打开的锚点,跳过类默认值和原型。采用遍历而非维护一份已打开锚点的注册表:被其他任何途径关闭的锚点必须记得从这样的注册表中移除自己,而忘记移除的那个就会留下一个幽灵。返回它关闭了多少个,这样调用方就能区分“本来就是空的”和“什么都没做”。 |
UWidgetBlueprintLibrary | GetAllWidgetsOfClass | adopt | GetAllWidgetsOfClass | 读取 UDreamUIManagerWorldSubsystem 的已注册控件数组,这是唯一可靠的来源:控件是以控件树为 Outer 的 UObject,因此 Actor 迭代器看不到它们,而 Object 迭代器还会把原型、设计器预览和其他世界一并扫进来。 |
UWidgetBlueprintLibrary | GetAllWidgetsWithInterface | adopt | GetAllWidgetsWithInterface | 仅限控件类;实现该接口的行为通过控件的 GetComponentByInterface 查找。 |
UWidgetBlueprintLibrary | GetInputEventFromKeyEvent | reject | FKeyEvent 及其同类是 Slate 的输入结构体,会递交给 SWidget 处理程序。在这里,输入以 UDreamPointerEventData 或 UDreamKeyEventData 的形式从事件系统到达,因此没有 Slate 事件可供解包。 | |
UWidgetBlueprintLibrary | GetKeyEventFromAnalogInputEvent | reject | 参见 GetInputEventFromKeyEvent。 | |
UWidgetBlueprintLibrary | GetInputEventFromCharacterEvent | reject | 参见 GetInputEventFromKeyEvent。 | |
UWidgetBlueprintLibrary | GetInputEventFromPointerEvent | reject | 参见 GetInputEventFromKeyEvent。 | |
UWidgetBlueprintLibrary | GetInputEventFromNavigationEvent | reject | 参见 GetInputEventFromKeyEvent。 | |
UWidgetBlueprintLibrary | GetSafeZonePadding | adopt | GetSafeZonePadding | 当 Slate 未运行时返回 false,因此“不需要内边距”和“无法询问”不会都表现为零。不返回 UMG 的 SpillOverPadding:这里没有任何绘制内容会超出视口矩形从而溢出到其上。 |
UWidgetBlueprintLibrary | SetColorVisionDeficiencyType | reject | 一个引擎范围的渲染器模拟开关,恰好位于 UMG 的库中。它不是控件框架需要关心的事,而且引擎已经将其公开;DreamGUI 再包装一层就等于在同一全局量上开了第二扇门。 | |
UWidgetBlueprintLibrary | SetHardwareCursor | reject | 向平台注册光标“形状”。DreamGUI 的 Cursor 属性在项目已注册的形状中进行选择,并不拥有该注册表。 | |
UWidgetBlueprintLibrary | SetWindowTitleBarState | reject | 游戏窗口的标题栏属于 Slate 窗口的范畴。DreamGUI 绘制在视口内部,没有自己的窗口装饰。 | |
UWidgetBlueprintLibrary | RestorePreviousWindowTitleBarState | reject | 参见 SetWindowTitleBarState。 | |
UWidgetBlueprintLibrary | SetWindowTitleBarOnCloseClickedDelegate | reject | 参见 SetWindowTitleBarState。 | |
UWidgetBlueprintLibrary | SetWindowTitleBarCloseButtonActive | reject | 参见 SetWindowTitleBarState。 |