DreamGUI
类参考

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

属性

名称类型分类在细节面板中来自蓝图说明
StyleFDreamRingMenuStyleRing Menu是SetStyle此实例自身的外观。当 StyleSource 指示如此且确实存在样式表时,项目样式表优先;如果项目中没有样式表,那么这就是实际生效的外观——这就是为什么它保持可编辑,而不是根据枚举进行限制。
ItemsTArray<FDreamRingMenuItem>Ring Menu是SetItems轮盘。顺序为从样式的 StartAngle 顺时针方向。
SelectedIndexint32Ring Menu是SetSelectedIndex已提交的项。-1 表示无,这是无人选择过的菜单的静止状态。
HitAreaEDreamRingHitAreaRing Menu是GetHitArea / SetHitArea参见 EDreamRingHitArea。
SliceHitRadiusScalefloatRing Menu是GetSliceHitRadiusScale / SetSliceHitRadiusScaleSlice 的触及范围,以圆环外半径的倍数表示。Ring 会忽略此项。
DeadZoneRadiusfloatRing Menu是GetDeadZoneRadius / SetDeadZoneRadius指针在此半径之内不会选中任何东西,以圆环为单位。零(默认值)表示样式的 InnerRadius,即中心枢纽的边缘,也是十有八九的答案;一个想要比其中心枢纽更大的"在此松开以取消"中间区域的 Slice 菜单可以在此指定一个值。
StickDeadZonefloatRing Menu是SetStickDeadZone摇杆必须推动多远,HighlightByDirection 才会选中任何东西,以向量的模长表示——轴对本身已经归一化,因此这是 0 到 1,与圆环半径无关。它可以防止静止摇杆的抖动每帧都选中一个项目。
LabelFacingEDreamRingLabelFacingRing Menu是GetLabelFacing / SetLabelFacing参见 EDreamRingLabelFacing。
bSelectOnHighlightboolRing Menu是SetSelectOnHighlight高亮一个项目即提交它,无需点击——即武器轮盘,其中指针的方向就是选择,松开按键就是确认。
bAllowDeselectboolRing Menu是SetAllowDeselect点击已经选中的项目会清除选择,而不是重新选择它。
bShowLabelsboolRing Menu是GetShowLabels / SetShowLabels关闭后楔块只保留其图标。一个只含符号的轮盘是再普通不过的需求。
bHubFollowsHighlightboolRing Menu是SetHubFollowsHighlight中心枢纽显示高亮项目的标签(回退到选中项目的标签,再回退到 HubText)。关闭后保持 HubText 不变,这样中心枢纽就成了一个静态标题。
HubTextFTextRing Menu是SetHubText没有任何高亮时中心枢纽显示的内容。空即为空的中心枢纽。
WedgeTemplateClassTSubclassOf<UDreamUserWidget>Ring Menu是SetWedgeTemplateClass楔块的内容,在别处创作:每个楔块控件内都会创建一个此类的实例,内置图标和标签则让位。该实例以内置框原本所在的位置为中心——位于切片的中线上、样式的 ContentRadius 处(该值为 0 时,即圆环两边之间的中点)——尺寸为其类的根控件创作时的尺寸(根控件拉伸时,为样式的 ContentWidth,呈正方形),并按 LabelFacing 的指示旋转。楔块的形状、命中扇区、高亮和点击仍归控件所有,因此模板只需绘制一个项目。
RingNodeTObjectPtr<UDreamWidget>Ring Menu-只读所有内容所依附的节点,也是 Open 和 Close 缩放与淡入淡出的对象。
BackdropNodeTObjectPtr<UDreamWidget>Ring Menu-只读楔块背后的完整圆环,填充它们之间的间隙。
WedgeRootNodeTObjectPtr<UDreamWidget>Ring Menu-只读楔块的父节点——其中也包括模板。
WedgeTemplateNodeTObjectPtr<UDreamWidget>Ring Menu-只读楔块复制自的对象——只创作一次,处于非活动状态,自身从不绘制。公开是因为它是"交给它一个模板"这一说法的另一半。
HubNodeTObjectPtr<UDreamWidget>Ring Menu-只读圆环内部的圆盘。
HubLabelNodeTObjectPtr<UDreamWidget>Ring Menu-只读
WedgeNodesTArray<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切换打开

事件

事件签名描述
OnHighlightChangedvoid DreamRingMenuIndexEvent__DelegateSignature(int32 Index)指针所在的位置。两条路线都会触发——扇区的悬停和 HighlightByAngle。
OnSelectionChangedvoid DreamRingMenuIndexEvent__DelegateSignature(int32 Index)已提交的项发生了移动。
OnValueChangedBPvoid DreamRingMenuIndexEvent__DelegateSignature(int32 Index)<-> 约定:双向绑定会针对这个确切的名称合成其反向路线,因此值控件会将其与它明确声明的事件一同携带。在 OnSelectionChanged 时触发。
OnItemActivatedvoid DreamRingMenuActivatedEvent__DelegateSignature(int32 Index, FName Tag)某个项被选择了——通过点击,或通过 ActivateHighlighted 确认。每次都会触发,包括所选的就是已选中项的情况,因为菜单项是一条命令,而“再做一次”必须能够被表达。标签会随之传递,因此处理程序永远不需要根据索引进行分支判断。
OnWedgeGeneratedvoid DreamRingMenuWedgeEvent__DelegateSignature(int32 Index, UDreamWidget* Wedge)每个扇区一个,每当它被绑定到某个项时触发。这是为那些扇区内容比“图标加标签”更丰富、但又不想编写整个类的使用方准备的钩子:扇区下的所有内容都可以从这里通过显示名称访问,而在第一次重建之前添加到 WedgeTemplateNode 下的任何内容都会随每次复制一并带入。
OnOpenedvoid DreamRingMenuIndexEvent__DelegateSignature(int32 Index)Open 和 Close,各自携带当时的选择——这正是“按住打开、松开选择”输入希望从关闭中得到的全部内容。
OnClosedvoid DreamRingMenuIndexEvent__DelegateSignature(int32 Index)

本页目录