DreamGUI
类参考

UDreamDropdown

UDreamDropdown

继承自 UDreamUIControl。

声明于 Public/Controls/DreamDropdown.h。

一个层级结构是代码而非资源的下拉框。

预设蓝图里最大的那个——十六个控件——被削减到 UUIDropdown 真正读取的内容:一个带标题的脸面、一个由 Show() 定位并做动画的列表根节点,以及其中容纳一个模板行的内容列。行为会按选项复制该行,因此模板只编写一次,处于非激活状态,且自身从不被绘制。

该行承载了本库反复得出的切换布局:悬停为行自身的脸面着色,选中标记是独立的视觉元素,因为一个视觉无法承载两种过渡。

此处的选项是纯文本,而非行为中的文本+笔刷对:这是常见情形,而该控件的职责就是应对常见情形。需要为每个选项提供图标的调用者应直接与 DropdownBehaviour 交互。

当没有补间管理器来淡入淡出列表时——比如没有游戏实例的世界,也就是设计器预览和无头测试——它会立即以其结束不透明度打开和关闭,而不是等待一个永远不会运行的淡入淡出。

属性

名称类型类别在细节面板中来自蓝图描述
StyleFDreamDropdownStyleDropdownyesGetStyle / SetStyle此实例自身的外观。当 StyleSource 如此指示且项目中确实存在样式表时,项目样式表优先;如果项目中没有样式表,那么这就是实际生效的外观——正因如此它保持可编辑而非被枚举所限制:旧的编辑条件恰恰把驱动控件的那几个值灰掉了。
OptionsTArray<FText>DropdownyesGetOptions / SetOptions使用 BlueprintReadOnly 而非一对 BlueprintSetter,原因与 UDreamDialog::Buttons 相同:选项是打开列表所依据的构建来源,因此蓝图就地写入此数组只会改变数据而让列表仍然显示旧副本。SetOptions 才是入口。设计器和 .dui 仍然直接编写它,此时 PostEditChangeProperty 会重新推送。
SelectedIndexint32DropdownyesGetSelectedIndex / SetSelectedIndex编写时的选中项;对应行为的输出镜像。-1 表示无。
MaxVisibleItemsint32DropdownyesGetMaxVisibleItems / SetMaxVisibleItems打开列表最多显示多少行。列表的高度始终恰好等于其可见行数——行数乘以行高,不多不少——超过此数量后其余行滚动:上限是一个计数,因为设计师就是这样考虑下拉框的,而不是以像素计。
OptionIconsTArray<TObjectPtr<UObject> >DropdownyesSetOptionIcons每个选项一张图片,与 Options 按索引对应——与 TabLabels 和 TabEnabled 使用相同的并行数组惯用法,原因也相同:为每个选项定义一个结构体会让常见情形(完全没有图标)付出该语言无法书写的数组字面量代价。
bHasDownArrowboolDropdownyesGetHasDownArrow / SetHasDownArrow脸面是否绘制自己的箭头字形——即 UMG 的 HasDownArrow。关闭适用于以其他方式表示“打开我”的脸面(自身图标、边框)。
bTabCommitsHighlightedRowboolDropdownyesGetTabCommitsHighlightedRow / SetTabCommitsHighlightedRow在打开列表中按 Tab 或 Shift+Tab 会选择玩家当前所在的行,然后列表关闭,Tab 继续越过下拉框移动——这正是 HTML select 的行为。关闭时,Tab 只关闭列表而不做任何选择。Tab 从不遍历行:那是方向键和手柄的职责。
ItemTemplateClassTSubclassOf<UDreamUserWidget>DropdownyesGetItemTemplateClass / SetItemTemplateClass选项行的内容,在别处编写:该类的实例会在每个项目控件内创建并填充它,而内置标签则让位。行的脸面、其复选标记、其悬停和选中始终保持为控件的,因此模板只需绘制一个选项。
FaceNodeTObjectPtr<UDreamWidget>Dropdown-read only
CaptionNodeTObjectPtr<UDreamWidget>Dropdown-read only
ArrowNodeTObjectPtr<UDreamWidget>Dropdown-read only
ListNodeTObjectPtr<UDreamWidget>Dropdown-read only
ItemTemplateNodeTObjectPtr<UDreamWidget>Dropdown-read only
DropdownBehaviourTObjectPtr<UUIDropdown>Dropdown-read only

函数

函数类型描述
void AddOption(FText InOption)callable选项列表,一次调用一个——UMG 的组合框 API,这正是根据游戏数据构建其选项的界面实际使用的。
void ClearOptions()callable选项及其图标,两者皆是。选中项是 ClearSelection 的职责,而非此函数的。
void ClearSelection()callable完全不选择任何项——索引 -1,这正是该控件已经用来表示“无”的方式。
int32 FindOptionIndex(FText InOption)pure按含义比较(FText::EqualTo),因此本地化的选项可以跨文化匹配。-1 表示无。
bool GetHasDownArrow()pure获取是否有下箭头
TSubclassOf<UDreamUserWidget> GetItemTemplateClass()pure获取项目模板类
int32 GetMaxVisibleItems()pure获取最大可见项目数
FText GetOptionAtIndex(int32 InIndex)pure对于没人提供的索引返回空文本,而不是越界读取。
int32 GetOptionCount()pure获取选项数量
TArray<FText> GetOptions()pure获取选项
int32 GetSelectedIndex()pure获取选中索引
FText GetSelectedOption()pure所选选项的文本,未选中任何项时为空。
FDreamDropdownStyle GetStyle()pure获取样式
bool GetTabCommitsHighlightedRow()pure获取 Tab 是否提交高亮行
bool IsOpen()pure列表是否处于打开状态。它是从行为自身的可见性接缝镜像而来,而非由打开它的人所保持,因此被别处点击关闭的列表在这里不会仍显示为“打开”。
void RefreshOptions()callable根据当前选项重建各行。供就地编辑了数组的调用者使用。
bool RemoveOption(FText InOption)callable当没有选项匹配时返回 false,与 UMG 的返回值一致。会一并移除匹配的图标。
void SetHasDownArrow(bool bInHasDownArrow)callable设置是否有下箭头
void SetItemTemplateClass(TSubclassOf<UDreamUserWidget> InItemTemplateClass)callable重建各行:行究竟是什么来自此类,因此单纯写入不会改变任何东西。
void SetMaxVisibleItems(int32 InMaxVisibleItems)callable打开列表最多显示多少行,立即重新推送。
void SetOptionIcons(TArray<UObject*> InIcons)callable替换每个选项的图片并重新推送列表,使已打开的列表在指针下即刻改变。
void SetOptions(TArray<FText> InOptions)callable替换选项:打开的列表会立即重建并重新定位,关闭的列表则在下次打开时处理。
void SetSelectedIndex(int32 InIndex)callable设置选中索引
void SetSelectedOption(FText InOption)callable选择具有该文本的选项。没人提供的选项不会改变任何东西。
void SetStyle(FDreamDropdownStyle InStyle)callable此实例的完整外观,替换并推送。注意事项见 UDreamButton::SetStyle。
void SetTabCommitsHighlightedRow(bool bInTabCommitsHighlightedRow)callable参见 bTabCommitsHighlightedRow。立即推送到行为,因此打开的列表会依据它来响应下一次 Tab。

事件

事件签名描述
OnSelectionChangedvoid DreamDropdownChangedEvent__DelegateSignature(int32 SelectedIndex)从 behaviour 重新广播,因此消费者绑定到控件本身,而不是它的某个部分。
OnOpeningvoid DreamDropdownSimpleEvent__DelegateSignature()列表正在打开——即 UMG 的 OnOpening,也是刷新选项的时机。
OnClosedvoid DreamDropdownSimpleEvent__DelegateSignature()列表已关闭,无论是因为做出了选择,还是在别处点击。
OnValueChangedBPvoid DreamDropdownChangedEvent__DelegateSignature(int32 SelectedIndex)<-> 约定:双向绑定会针对这个确切的名称合成其反向路由,因此值控件在携带其显式事件的同时也携带它。与它们一同触发。
OnItemGeneratedvoid DreamDropdownItemEvent__DelegateSignature(int32 ItemIndex, UDreamWidget* Item)构建列表时,每个选项行触发一次。这是为那些选项比一个词更丰富、但又不想专门编写一个完整类的消费者准备的钩子:行下面的所有内容都可以从这里通过显示名称访问。这是下拉框对应列表 OnRowGenerated 的接口。

与 UMG 对比

UMG 类中所有面向蓝图的成员,以及它们去了哪里。adopt:同名、同义。map:在这里换了个名字,或换到了另一种类型上。reject:被有意省略,并说明原因。

UMG成员状态这里说明
UComboBoxStringDefaultOptionsmapOptions一个数组,而不是两个。UMG 将 DefaultOptions 与运行时列表并列保存,是因为它的组合框会从 Slate 控件自身的副本重建;而在这里,行会在每次推送时根据 Options 构建,所以编辑的数组就是活动数组。
UComboBoxStringSelectedOptionmapSelectedIndex索引才是编辑时的真相,选项文本由它推导而来(GetSelectedOption / SetSelectedOption)。同一次选择有两种编辑写法,正是数组编辑导致二者不一致的原因。
UComboBoxStringWidgetStylemapStyleFDreamDropdownStyle:表面的五种状态颜色和笔刷、列表背景、行、对勾标记以及标题。
UComboBoxStringItemStylemapFDreamDropdownStyle::ItemBrush行的外观是下拉框自身样式的一部分,而不是单独的表行样式:旁边的 ItemBrush、ItemHeight、ItemHovered、ItemFocused、ItemDisabled 和 CheckColor。
UComboBoxStringScrollBarStylereject没有需要设置样式的滚动条。这个下拉框的打开列表高度正好是 MaxVisibleItems,通过滚轮和拖拽滚动,不绘制滚动条——一个按行数封顶的列表始终是它看起来的大小,这正是滚动条并非缺失而是多余的原因。该系列的滚动条样式是 FDreamScrollBarStyle,其控件是 Native.ScrollBar;想要滚动条的列表应该用 Native.ScrollBox,而不是组合框。
UComboBoxStringContentPaddingmapFDreamDropdownStyle::ContentPadding位于样式中,其默认值正是该控件一直以来精确排布的数字(左边十,右边二十四以避开箭头)。将其显式声明出来,可以让更宽的表面、或没有箭头的表面成为项目表单能够回答的事情。
UComboBoxStringMaxListHeightmapMaxVisibleItems是行数而不是像素高度,因为设计师就是这么思考下拉框的;打开列表的高度正好是行数乘以 ItemHeight,其余部分滚动。
UComboBoxStringHasDownArrowmapbHasDownArrow使用此代码库的布尔前缀命名。
UComboBoxStringEnableGamepadNavigationModereject两种行为之间的开关,而这里只存在其中一种——正是该标志开启的那一种。打开列表中的行是普通可选项:方向键移动焦点,在行被激活之前不提交任何内容,这正是 UMG 的手柄导航模式。关闭状态——即在关闭的控件上按方向键不打开它就改变值——在这里没有对应实现,也不应该添加:一个会吞掉左右键的关闭控件,正是 UUISlider::RequiresControllerLock 存在以防止一整行控件陷入的陷阱。
UComboBoxStringFontmapFDreamDropdownStyle::FontSize是一个尺寸,而不是 FSlateFontInfo:字体来自文本视觉自身的设置(UDreamText),下拉框的样式决定的是其标题和行有多大。
UComboBoxStringForegroundColormapFDreamDropdownStyle::TextColor标题和行的颜色。旁边的 FDreamUIStateFaces 为希望其标题随指针变化的表面携带了每种状态的前景色。
UComboBoxStringbIsFocusablemapUDreamWidget::bIsFocusable这里的每个控件都携带它。
UComboBoxStringOnGenerateWidgetEventmapItemTemplateClass是一个类而不是每行的委托,并且为每一行触发 OnItemGenerated 来填充它。与 UDreamListViewBase::RowTemplateClass 相同的取舍:类是可以被 .dui 和设计师命名的东西,而委托不是。
UComboBoxStringOnSelectionChangedmapOnSelectionChanged携带索引。UMG 的第二个参数 ESelectInfo 没有对应物:behaviour 无论是什么改变了值都只引发一个值变更接缝,所以“谁改变了它”不是这个控件能够诚实回答的问题。
UComboBoxStringOnOpeningadoptOnOpening从 behaviour 的 Show 触发,在放置行之前——因此从处理程序写入的选项正是玩家看到的。OnClosed 是 UMG 没有给出名称的对应项。
UComboBoxStringAddOptionadoptAddOption是 FText 而不是 FString:选项是玩家阅读的东西,而这个框架一路都使用 FText。
UComboBoxStringRemoveOptionadoptRemoveOption会一并处理与索引匹配的图标。
UComboBoxStringFindOptionIndexadoptFindOptionIndex按含义比较(FText::EqualTo),因此本地化选项可以跨区域文化匹配。
UComboBoxStringGetOptionAtIndexadoptGetOptionAtIndex对于无人提供的索引,返回空文本。
UComboBoxStringClearOptionsadoptClearOptions选项和图标;选择是 ClearSelection 的职责,与 UMG 中一样。
UComboBoxStringClearSelectionadoptClearSelection索引 -1,这正是该控件已经用来表示“无”的方式。
UComboBoxStringRefreshOptionsadoptRefreshOptions适用于就地编辑了数组的调用方。
UComboBoxStringSetSelectedOptionadoptSetSelectedOption无人提供的选项不会改变任何内容,而不是清除选择。
UComboBoxStringSetSelectedIndexadoptSetSelectedIndex
UComboBoxStringGetSelectedOptionadoptGetSelectedOption
UComboBoxStringGetSelectedIndexadoptGetSelectedIndex
UComboBoxStringGetOptionCountadoptGetOptionCount
UComboBoxStringIsOpenadoptIsOpen从 behaviour 的可见性接缝镜像而来,因此在别处点击关闭的列表在这里不会仍然是打开的。
UComboBoxStringSetStyleadoptSetStyle在 UComboBoxString 上不是 UFUNCTION(其 Setter 元数据为其命名);在这里添加,以便外观可以在运行时替换。

本页目录