UDreamRingMenu
UDreamRingMenu
继承自 UDreamUIControl。
声明于 Public/Controls/DreamRingMenu.h。
一种层级结构由代码而非资产定义的环形菜单:围绕中心枢纽的扇形楔块,按方向选取。
每个动作游戏都有、却没有哪个 UI 框架提供的径向菜单,用 DreamGUI 的方式实现。项目是一个 UPROPERTY 数组,因此 .dui、设计器、蓝图以及 <-> 绑定都能驱动它,无需任何黏合代码;外观来自项目样式表,和其他所有控件一样。
楔块就是一个矩形
这里没有新的视觉元素,也没有新的着色器。UDreamRectBlock 已经能绘制带边框、径向填充遮罩、渐变和阴影的圆角矩形——而圆环扇区恰恰就是这样一个矩形:圆角半径为 100%,主体关闭(因此边框就是圆环),遮罩设为该切片。UDreamProgressBar 的 Radial 形状发现了这其中的前半部分;后半部分在于遮罩的起始和扫过角度是按项设置的,而不是一个百分比。因此每个楔块都能免费继承渐变、内外阴影和柔和边缘,想要更花哨圆环的项目只需给这个矩形设置样式,而不用等待新功能。
代价是实实在在的,值得说明:每个楔块都是一个和整个圆环同样大小的正方形,着色器只保留其中一个切片。因此每个楔块都与其他所有楔块重叠,而矩形命中测试会把整个圆形都交给最上层的那个—— 这就是为什么命中形状是 UDreamRingSectorRaycast 而非默认形状。
为什么命中测试是自定义射线检测而不是逐帧 Tick
显而易见的做法是做一个每帧读取指针并算出角度的控件。这个控件不是那样做的,而且区别不在于风格:用精确的扇区作为每个楔块的命中形状,整套既有事件管线就都能正常工作——进入、离开、按下、点击、可选中项的四种状态转换、事件冒泡、模态层、拖拽阈值。一个逐帧 Tick 的控件将不得不重新实现其中每一项,而且仍然会搞不清指针究竟位于两个重叠菜单中的哪一个。角度计算只存在于一个地方,即射线检测中,游戏手柄路径(HighlightByDirection)调用的是同样的两个静态函数,而不是第二份副本。
楔块之间的间隙仅仅是绘制出来的。如果它也属于命中形状,那么拖拽穿过间隙时就会离开一个楔块而进入不了任何楔块,高亮就会在每对项目之间闪烁消失。
高亮和选中是两回事
高亮是指针(或摇杆)所在的位置;选中是已经提交的结果。菜单会将二者分开——先悬停,再点击—— 而武器轮盘则不会,这只是一个布尔值(bSelectOnHighlight),而不是两个控件。两者都可读取,都能触发,并且每次提交时 OnItemActivated 都会触发,即使同一项被选择了两次,因为 "再次调用此命令"是菜单必须能够表达的事情。
Native.RingMenu Wheel {
HitArea = Slice
bSelectOnHighlight = true
Style.SweepAngle = 360
Items = [{ "Lamp", Tag: Lamp }, { "Door", Tag: Door, bEnabled: false }]
OnItemActivated -> HandleWheelPick属性
| 名称 | 类型 | 分类 | 在细节面板中 | 来自蓝图 | 说明 |
|---|---|---|---|---|---|
Style | FDreamRingMenuStyle | Ring Menu | 是 | SetStyle | 此实例自身的外观。当 StyleSource 指示如此且确实存在样式表时,项目样式表优先;如果项目中没有样式表,那么这就是实际生效的外观——这就是为什么它保持可编辑,而不是根据枚举进行限制。 |
Items | TArray<FDreamRingMenuItem> | Ring Menu | 是 | SetItems | 轮盘。顺序为从样式的 StartAngle 顺时针方向。 |
SelectedIndex | int32 | Ring Menu | 是 | SetSelectedIndex | 已提交的项。-1 表示无,这是无人选择过的菜单的静止状态。 |
HitArea | EDreamRingHitArea | Ring Menu | 是 | GetHitArea / SetHitArea | 参见 EDreamRingHitArea。 |
SliceHitRadiusScale | float | Ring Menu | 是 | GetSliceHitRadiusScale / SetSliceHitRadiusScale | Slice 的触及范围,以圆环外半径的倍数表示。Ring 会忽略此项。 |
DeadZoneRadius | float | Ring Menu | 是 | GetDeadZoneRadius / SetDeadZoneRadius | 指针在此半径之内不会选中任何东西,以圆环为单位。零(默认值)表示样式的 InnerRadius,即中心枢纽的边缘,也是十有八九的答案;一个想要比其中心枢纽更大的"在此松开以取消"中间区域的 Slice 菜单可以在此指定一个值。 |
StickDeadZone | float | Ring Menu | 是 | SetStickDeadZone | 摇杆必须推动多远,HighlightByDirection 才会选中任何东西,以向量的模长表示——轴对本身已经归一化,因此这是 0 到 1,与圆环半径无关。它可以防止静止摇杆的抖动每帧都选中一个项目。 |
LabelFacing | EDreamRingLabelFacing | Ring Menu | 是 | GetLabelFacing / SetLabelFacing | 参见 EDreamRingLabelFacing。 |
bSelectOnHighlight | bool | Ring Menu | 是 | SetSelectOnHighlight | 高亮一个项目即提交它,无需点击——即武器轮盘,其中指针的方向就是选择,松开按键就是确认。 |
bAllowDeselect | bool | Ring Menu | 是 | SetAllowDeselect | 点击已经选中的项目会清除选择,而不是重新选择它。 |
bShowLabels | bool | Ring Menu | 是 | GetShowLabels / SetShowLabels | 关闭后楔块只保留其图标。一个只含符号的轮盘是再普通不过的需求。 |
bHubFollowsHighlight | bool | Ring Menu | 是 | SetHubFollowsHighlight | 中心枢纽显示高亮项目的标签(回退到选中项目的标签,再回退到 HubText)。关闭后保持 HubText 不变,这样中心枢纽就成了一个静态标题。 |
HubText | FText | Ring Menu | 是 | SetHubText | 没有任何高亮时中心枢纽显示的内容。空即为空的中心枢纽。 |
WedgeTemplateClass | TSubclassOf<UDreamUserWidget> | Ring Menu | 是 | SetWedgeTemplateClass | 楔块的内容,在别处创作:每个楔块控件内都会创建一个此类的实例,内置图标和标签则让位。该实例以内置框原本所在的位置为中心——位于切片的中线上、样式的 ContentRadius 处(该值为 0 时,即圆环两边之间的中点)——尺寸为其类的根控件创作时的尺寸(根控件拉伸时,为样式的 ContentWidth,呈正方形),并按 LabelFacing 的指示旋转。楔块的形状、命中扇区、高亮和点击仍归控件所有,因此模板只需绘制一个项目。 |
RingNode | TObjectPtr<UDreamWidget> | Ring Menu | - | 只读 | 所有内容所依附的节点,也是 Open 和 Close 缩放与淡入淡出的对象。 |
BackdropNode | TObjectPtr<UDreamWidget> | Ring Menu | - | 只读 | 楔块背后的完整圆环,填充它们之间的间隙。 |
WedgeRootNode | TObjectPtr<UDreamWidget> | Ring Menu | - | 只读 | 楔块的父节点——其中也包括模板。 |
WedgeTemplateNode | TObjectPtr<UDreamWidget> | Ring Menu | - | 只读 | 楔块复制自的对象——只创作一次,处于非活动状态,自身从不绘制。公开是因为它是"交给它一个模板"这一说法的另一半。 |
HubNode | TObjectPtr<UDreamWidget> | Ring Menu | - | 只读 | 圆环内部的圆盘。 |
HubLabelNode | TObjectPtr<UDreamWidget> | Ring Menu | - | 只读 | |
WedgeNodes | TArray<TObjectPtr<UDreamWidget> > | Ring Menu | - | 只读 | 楔块控件,与 Items 平行。 |
函数
| 函数 | 类型 | 描述 |
|---|---|---|
void ActivateHighlighted() | callable | 提交当前高亮的项:即“松开按键以选择”输入所调用的内容。 |
void Close() | callable | 将其隐藏,并在退出时清除高亮。焦点位于某个扇区上——或从环形菜单中未指向任何位置——的玩家,会在淡出开始前恢复其打开时聚焦的内容。 |
float GetDeadZoneRadius() | pure | 获取死区半径 |
int32 GetHighlightedIndex() | pure | 获取高亮索引 |
EDreamRingHitArea GetHitArea() | pure | 获取命中区域 |
int32 GetItemCount() | pure | 获取项数 |
float GetItemMidAngle(int32 InIndex) | pure | 某个项扇区的中点,也是其图标和标签所在的位置。 |
float GetItemStartAngle(int32 InIndex) | pure | 某个项扇区的起始位置,以从十二点方向顺时针计的度数表示。 |
float GetItemSweepAngle(int32 InIndex) | pure | 某个项扇区的宽度,以度数表示——即按权重计算的、它在样式扫描角度中所占的份额。 |
EDreamRingLabelFacing GetLabelFacing() | pure | 获取标签朝向 |
int32 GetSelectedIndex() | pure | 获取选中索引 |
bool GetShowLabels() | pure | 获取显示标签 |
float GetSliceHitRadiusScale() | pure | 获取扇区命中半径缩放 |
UDreamWidget* GetWedgeWidget(int32 InIndex) | pure | 代表某个项的扇区,若不存在则为 null。 |
void HighlightByAngle(float InAngleDegrees) | callable | 高亮拥有该角度(以从十二点方向顺时针计的度数表示)的项。 |
void HighlightByDirection(FVector2D InDirection) | callable | 高亮拥有该方向的项——即手柄路线。 |
int32 IndexAtAngle(float InAngleDegrees) | pure | 哪个项拥有某个角度;若扫描范围未覆盖该角度,则为 -1。 |
bool IsOpen() | pure | 是否打开 |
void Open() | callable | 显示环形菜单,在有世界可供补间时对它进行缩放和淡入。首先记录每位玩家的焦点。 |
void RebuildItems() | callable | 再次将几何信息交给各扇区;若项数发生变化,则先扩大或缩小池。由 ApplyStyle 为你调用——扇区几何信息本身就是样式——以及由 SetItems 调用。 |
void SetAllowDeselect(bool bInAllowDeselect) | callable | 设置允许取消选择 |
void SetDeadZoneRadius(float InRadius) | callable | 设置死区半径 |
void SetHighlightedIndex(int32 InIndex) | callable | 移动高亮。-1 或已禁用的项会将其清除。 |
void SetHitArea(EDreamRingHitArea InHitArea) | callable | 下面这五个 setter 各自写入字段,然后执行读取该字段所需的推送——这就是 BlueprintSetter 在这一体系上带来的全部内容。命中形状三件套(HitArea、扇区的作用范围、死区)是在指针到达时由射线检测重载查询的,而不是烘焙进任何绘制内容中,因此这三者完全不需要重新设置样式;而决定扇区显示内容的两者则需要。 |
void SetHubFollowsHighlight(bool bInHubFollowsHighlight) | callable | 中心是否显示高亮项的标签。中心会立即被重新读取。 |
void SetHubText(FText InHubText) | callable | 当没有其他内容占用时中心所显示的内容。中心会立即被重新读取。 |
void SetItems(TArray<FDreamRingMenuItem> InItems) | callable | 替换轮盘并重建它。 |
void SetLabelFacing(EDreamRingLabelFacing InFacing) | callable | 重新调整每个扇区标签的朝向,这是样式推送所写入的几何信息。 |
void SetSelectedIndex(int32 InIndex) | callable | 移动选择并触发两个选择事件。超出范围则不选择任何内容。 |
void SetSelectedIndexWithoutNotify(int32 InIndex) | callable | 相同的移动,但静默进行:用于推入某个已编写的值,这不属于用户选择。 |
void SetSelectOnHighlight(bool bInSelectOnHighlight) | callable | 设置高亮时选择 |
void SetShowLabels(bool bInShowLabels) | callable | 唤醒或休眠每个扇区的标签,这由样式推送决定。 |
void SetSliceHitRadiusScale(float InScale) | callable | 设置扇区命中半径缩放 |
void SetStickDeadZone(float InStickDeadZone) | callable | 摇杆在被推离多远之后才会指向任何内容,0..1。每次采样摇杆时都会读取。 |
void SetStyle(FDreamRingMenuStyle InStyle) | callable | 替换外观并推送它。 |
void SetWedgeTemplateClass(TSubclassOf<UDreamUserWidget> InWedgeTemplateClass) | callable | 已编写的扇区内容。在构建时实例化到每个扇区中,因此更换新类意味着重建。 |
void StepHighlight(int32 InDelta) | callable | 让高亮绕环形菜单步进,跳过已禁用的项。在完整轮盘上会循环,在半轮盘上会停在两端——半环有第一个和最后一个项,假装不是这样,正是键盘用户最终落到屏幕外某个地方的原因。 |
void ToggleOpen() | callable | 切换打开 |
事件
| 事件 | 签名 | 描述 |
|---|---|---|
OnHighlightChanged | void DreamRingMenuIndexEvent__DelegateSignature(int32 Index) | 指针所在的位置。两条路线都会触发——扇区的悬停和 HighlightByAngle。 |
OnSelectionChanged | void DreamRingMenuIndexEvent__DelegateSignature(int32 Index) | 已提交的项发生了移动。 |
OnValueChangedBP | void DreamRingMenuIndexEvent__DelegateSignature(int32 Index) | <-> 约定:双向绑定会针对这个确切的名称合成其反向路线,因此值控件会将其与它明确声明的事件一同携带。在 OnSelectionChanged 时触发。 |
OnItemActivated | void DreamRingMenuActivatedEvent__DelegateSignature(int32 Index, FName Tag) | 某个项被选择了——通过点击,或通过 ActivateHighlighted 确认。每次都会触发,包括所选的就是已选中项的情况,因为菜单项是一条命令,而“再做一次”必须能够被表达。标签会随之传递,因此处理程序永远不需要根据索引进行分支判断。 |
OnWedgeGenerated | void DreamRingMenuWedgeEvent__DelegateSignature(int32 Index, UDreamWidget* Wedge) | 每个扇区一个,每当它被绑定到某个项时触发。这是为那些扇区内容比“图标加标签”更丰富、但又不想编写整个类的使用方准备的钩子:扇区下的所有内容都可以从这里通过显示名称访问,而在第一次重建之前添加到 WedgeTemplateNode 下的任何内容都会随每次复制一并带入。 |
OnOpened | void DreamRingMenuIndexEvent__DelegateSignature(int32 Index) | Open 和 Close,各自携带当时的选择——这正是“按住打开、松开选择”输入希望从关闭中得到的全部内容。 |
OnClosed | void DreamRingMenuIndexEvent__DelegateSignature(int32 Index) |