DreamGUI
类参考

UDreamListView

UDreamListView

继承自 UDreamListViewBase。

声明于 Public/Controls/DreamListView.h。

一个层级结构由代码而非资产定义的列表:行由来源构建,处于可滚动的视口中。

DreamGUI 风格下的 UMG ListView —— 并且刻意比它更小。没有需要实现的 entry-widget 协议,也没有需要编写的数据源:设计师真正会去使用的两个属性(一组条目,以及选中哪一个)都是 UPROPERTY,因此 .dui、设计器、蓝图以及 <-> 绑定都可以驱动它们,而无需任何人编写一行胶水代码。

关于树的形态、为何行是被放置而不是被排列、何时开始回收它们,以及 Native.List 如何与 each 语言特性并立,请参阅 UDreamListViewBase。

属性

名称类型类别在细节面板中来自蓝图描述
StyleFDreamListStyleList是GetStyle / SetStyle此实例自身的外观。只要 StyleSource 如此声明且确实存在样式表,项目样式表就胜出;当项目中没有任何样式表时,这个属性本身就是生效的外观——这就是为什么它保持可编辑,而不是被该枚举所门控。

函数

函数类型描述
FDreamListStyle GetStyle()pure按值而非按引用:UFUNCTION 的返回值必须是值,而样式是一个小结构体。
void SetStyle(FDreamListStyle InStyle)callable替换整个外观并重新推送它。行几何属于样式,因此这会重建各行。

与 UMG 对比

UMG 类中每一个面向蓝图的成员,以及它去了哪里。adopt:同名,同义。map:在此处换了一个名称或换到了另一种类型上。reject:刻意缺失,并附原因。

UMG成员状态在此处备注
UListViewGetListItemsadoptGetListItems一份副本:UFUNCTION 的返回值是值,而交出实时数组会让调用方调整每一行都作为索引目标的那个东西的大小。
UListViewAddItemadoptAddItem经由 SetItemObjects,它会针对即将消失的来源来安置选中项以及子类的按索引键控的状态。AddTextItem 对于仅文本来源是同一调用。
UListViewAddItemAtadoptAddItemAt并行的文本以相同索引放入,空白:对于文本未覆盖到的索引,GetItemLabel 会回退到对象名称,这在较短数组的末尾是正确的,而在数组中间则是错误的。
UListViewAddItemsadoptAddItems通过 FScopedRebuildSuppression 对整批只重建一次——它是一个计数器而非标志,因为各批量调用是以彼此为基础编写的。
UListViewAddItemsAtadoptAddItemsAt其他三个调用都是以它为基础编写的。
UListViewRemoveItemadoptRemoveItem会一并带上匹配的文本:这两个数组是并行的,只缩短其中一个会重新标记空洞之后的每一行。移除选中项会取消选中它,并在 OnSelectionChanged 上触发一次,正如 SListView::UpdateSelectionSet 在 UMG 下一次刷新时所做的那样(ESelectInfo::Direct);在这里,它发生在调用返回之前。
UListViewRemoveItemsadoptRemoveItems索引先被收集、排序,然后从后往前移除:每次移除都会移动其后的内容,因此升序会让第一个之后的每个索引都出错。
UListViewGetItemAtadoptGetItemAt
UListViewGetNumItemsadoptGetNumItems当存在对象时由对象决定计数;否则由文本决定。
UListViewGetIndexForItemadoptGetIndexForItem
UListViewClearListItemsadoptClearListItems清空两个来源并清除选中项——当原本存在选中项时,会在 OnSelectionChanged 上公告一次,就像任何带走选中项的来源编辑一样。
UListViewSetSelectionModeadoptSetSelectionModeEUIListSelectionMode,即 UUIListView 已经给出的四个答案。
UListViewSetScrollIntoViewAlignmentmapSetScrollIntoViewDestination一个四答案枚举而非 UMG 的浮点数:滚动框和滚动行为已经用 EDreamUIScrollDestination 回答了同一个问题,因此项目只需学一次。
UListViewSetEnableProximateEntryNavigationreject见 bEnableProximateEntryNavigation。
UListViewIsRefreshPendingreject此控件会同步重建——每一个移动来源的 setter 都会在返回前重建——因此永远不会有待处理的刷新可供通知。这是刻意的:正是它使列表在无头测试中和设计师的第一帧上都保持正确。
UListViewScrollIndexIntoViewadoptScrollIndexIntoView由行间距计算而来,因此它能针对行尚未被实例化的条目作答——这是回收期间唯一有意义的版本。
UListViewSetSelectedIndexadoptSetSelectedIndex
UListViewNavigateToIndexadoptNavigateToIndex选中并显示,因为一个在屏幕之外的选中项是没人能看见自己做出的选中项。
UListViewWidgetStylemapStyleFDreamListStyle,针对项目样式表解析。Get/SetStyle。
UListViewScrollBarStylemapFDreamListStyle::Bar列表的样式带有滚动条的整个样式,因此一次编辑即可同时装扮列表及其滚动条。
UListViewbEnableShadowBrushadoptbEnableShadowBrush两个叠加层位于视口内,而不是滚动的列中:一个随内容滚动的渐隐会是一条穿过列表的条纹。每一个都只在列表滚离该端时醒来,因此它表示的是“这边还有更多”,而不是永久的装饰。
UListViewShadowBrushStylemapShadowBrushFDreamUIFaceBrush 位于控件上,而非 FDreamListStyle 中:样式结构体是共享外观,并针对项目样式表解析,而渐隐是关于某一个列表边缘的逐屏幕决策。一个为每个列表同时开启它的样式表,不是任何人会故意做出的编辑。
UListViewOrientationadoptOrientationEDreamPanelOrientation,此库的两值写法。该控件以 MAIN/CROSS 轴术语重写,而不是按调用点分支:行间距、内容范围、窗口大小、装饰、放置、偏移、过度滚动和显示全都读取同一对辅助函数。垂直是默认值,因此现有内容不会移动。UDreamTreeView 拒绝它——树的缩进是跨其各行测量的,而 UMG 也没有水平树。
UListViewSelectionModeadoptSelectionMode
UListViewConsumeMouseWheeladoptConsumeMouseWheel与滚动框使用的同一枚举。
UListViewbClearSelectionOnClickmapSelectionModeSingleToggle 就是“第二次点击所选中行会清除它”。单独的标志会是对同一问题的第二个答案。
UListViewbIsFocusablemapUDreamWidget::bIsFocusable已经位于每个控件的基类上。
UListViewbClearScrollVelocityOnSelectionadoptbClearScrollVelocityOnSelection在选中路径的前端执行 EndInertialScrolling,这样玩家选中的行在点击仍在处理时不会从光标下滑走。
UListViewbReturnFocusToSelectionadoptbReturnFocusToSelection仅在焦点落在列表本身时起作用:已经到达某一行的焦点正是在做这个想要的事,重定向它会把玩家从他们刚刚导航到的行上拖走。FocusSelectedRow 是可调用的同一步操作,并在所选项没有已实现的行时如实返回 false。
UListViewbEnableProximateEntryNavigationreject到达列表时本就已经是几何上的最近邻——FDreamUINavigationScroll 和 UDreamWidgetNavigation 对每个控件都按矩形挑选最近的行——这正是该标志位在 UMG 中开启的行为,因此没有第二种模式可切换。一旦位于某一行上,按下按键会像 SListView::OnNavigation 那样按项步进(UDreamListRowButton 会先询问列表),只有当按下的按键在列表内部无路可去时才会回到扫描逻辑。到达不会选中;在 bSelectItemOnNavigation 开启时,步进会选中。
UListViewScrollIntoViewAlignmentmapScrollIntoViewDestination见 SetScrollIntoViewAlignment。
UListViewHorizontalEntrySpacingmapFDreamTileViewStyle::TileSpacing列表只有一列,因此横向行间间距只在平铺视图中有意义,而它正位于那里。
UListViewVerticalEntrySpacingmapFDreamListStyle::RowSpacing行下方的间隙,也就是沿列向下走一步在其高度之外所要付出的代价。
UListViewScrollBarPaddingmapFDreamScrollBarStyle::BarPadding位于滚动条的样式中,由 FDreamListStyle::Bar 承载——与滚动框读取的是同一个字段。
UListViewGetHorizontalEntrySpacingmapUDreamTileView::GetStyle从解析后的平铺样式读取;见属性行。
UListViewGetVerticalEntrySpacingmapGetStyle从解析后的列表样式读取;见属性行。
UListViewSetReturnFocusToSelectionadoptSetReturnFocusToSelection
UListViewBP_SetSelectedItemmapSetSelectedIndexSOURCE 中的一个索引,它能在折叠后依然有效,而逐行比较对象标识则不能。GetIndexForItem 可将对象转换为索引。
UListViewBP_SetItemSelectionmapSetItemSelection按索引;这是唯一能表达多选的调用。
UListViewBP_ClearSelectionmapClearSelection
UListViewBP_GetNumItemsSelectedmapGetNumItemsSelected
UListViewBP_GetSelectedItemsmapGetSelectedItems对于纯文本源会返回空,因为没有可供应答的对象;此时应询问的是 GetSelectedIndices。
UListViewBP_IsItemVisiblemapIsItemVisible当该项当前有代表它的行控件时为 true。
UListViewBP_NavigateToItemmapNavigateToIndex按索引;GetIndexForItem 可将对象转换为索引。
UListViewBP_ScrollItemIntoViewmapScrollItemIntoView按索引,并根据行间距计算得出,因此对未实现的行也能应答。
UListViewBP_CancelScrollIntoViewmapEndInertialScrolling缓动的显示是滚动行为上的补间动画;停止它就是停止正在移动内容的东西。
UListViewBP_SetListItemsmapSetItemObjects接受原始指针,因为 TArray<TObjectPtr<>> 不能作为 UFUNCTION 参数。
UListViewBP_GetSelectedItemmapGetSelectedItems另外用 GetSelectedIndex 获取锚点。单项 getter 不过是调用者本就能看到的集合的第一个元素。
UListViewBP_OnEntryInitializedmapOnRowInitialized在行控件生命周期中仅一次,位于子类自身的一次性钩子之后,因此使用者看到的是一个已经接线完毕的行。
UListViewBP_OnItemClickedmapOnItemClicked在选中项移动之后触发,因此询问 GetSelectedIndex 的处理程序会看到用户刚刚给出的答案。
UListViewBP_OnItemDoubleClickedmapOnItemDoubleClicked使用事件系统的 DoubleClickTime,因此列表和旁边的文本字段对间隔的认定是一致的。在第二次按下时发出,正如 UMG 的做法(Slate 将该次按下路由到 OnMouseButtonDoubleClick,而不是 OnMouseButtonDown);该次按下所结束的点击仍会跟随,OnItemClicked 仍会为它触发。
UListViewBP_OnItemDragDetectedmapOnItemDragDetected在操作仍可编辑时触发,因此使用者可以在其上放置自己的负载或标记。除了对象之外还携带 ITEM INDEX,因为纯文本源没有可用于标识行的对象。
UListViewBP_OnItemDragEntermapOnItemDragEnter任何拖拽,而不仅仅是此列表自身的拖拽。由行自身的放置目标转发,该目标自创建起就知道自己的池槽位——基类的 enter/leave 只携带操作,而在 leave 时搜索该行将不得不进行猜测,那时悬停标志已经落下。
UListViewBP_OnItemDragLeavemapOnItemDragLeave见 BP_OnItemDragEnter。
UListViewBP_OnItemAcceptDropmapOnItemAcceptDrop携带 EDreamItemDropZone——AboveItem、OntoItem、BelowItem——根据指针沿行的 MAIN 轴所处的位置解析得出,因此水平列表会将接缝解读为其左右边缘。列表不会自行重新排序:放置意味着什么由使用者决定,而一个移动自身源的列表将是在猜测只有数据所有者才能做出的编辑。
UListViewBP_OnItemDragCancelledmapOnItemDragCancelled当拖拽结束时没有任何东西接受时触发,依据 OPERATION 的 bDropWasHandled 判断——操作比行存续得更久,而被回收的行或关闭的屏幕可能在飞行途中销毁该行。
UListViewBP_OnListViewDraggingStateChangedmapOnDraggingStateChanged两端,来自设置该标志的同样两处位置。
UListViewBP_OnItemIsHoveredChangedmapOnItemIsHoveredChanged由行可选中项的状态驱动,这是唯一能区分静止指针与焦点的事物。报告 ITEM,因此在静止指针下重新绑定的行会宣告新的项。
UListViewBP_OnItemSelectionChangedmapOnSelectionChanged携带锚点索引;在 Multi 模式下 GetSelectedIndices 是完整的答案。为点击、导航步进、API,以及移除所选项的源编辑(每次编辑一次,一批算一次)触发——但不为仅随其项移动到新索引的选中触发,这在 UMG 中同样不算变化。
UListViewBP_OnItemScrolledIntoViewmapOnItemScrolledIntoViewEDGE:RefreshVisibleWindow 保留先前的已实现集合,并只宣告到达项,位于每次绑定之后而非循环内部,因此询问屏幕上还有什么内容的处理程序能得到完整答案。
UListViewBP_OnListViewScrolledmapOnListViewScrolled同时携带偏移量和可见比例,因为绘制自身位置指示器的使用者两者都需要,且无法自行算出任何一个。
UListViewBP_OnListViewFinishedScrollingmapOnListViewFinishedScrolling在第一次落地时已无物可承载它的移动中锁存:每次手势一次调用,而不是一次轻扫的每帧一次。
UListViewBP_OnListViewTouchStartmapOnListViewTouchStart从 UUIScrollView 的新的原生拖拽手势广播转发,该广播携带阶段以及是否是手指。从行为转发,而不是第二套指针订阅:行为才是决定手势能否到达这些行的东西,而单独监听的列表会为行为拒绝的拖拽宣告触摸。
UListViewBP_OnListViewTouchMovemapOnListViewTouchMove见 BP_OnListViewTouchStart。
UListViewBP_OnListViewTouchEndmapOnListViewTouchEnd见 BP_OnListViewTouchStart。
UListViewBP_OnIsItemSelectableOrNavigablemapOnIsItemSelectableOrNavigable单播,带布尔返回值,类似树的子项提供器:这是一个 QUESTION(问题),而两个答案是一种无法解决的歧义。在点击路径和导航路径上都会询问,否则两者对哪些行存在会产生分歧。取消选中永远不会被否决——一个被选中时变得不可选的行必须能够停止被选中。
UListViewEntrySpacingmapFDreamListStyle::RowSpacing条目之间的间隙属于外观,因此它位于列表的样式上而不是控件上:FDreamListStyle::RowSpacing,沿列表的主轴(垂直列表的行之间、水平列表的列之间)。
UListViewBaseGetDisplayedEntryWidgetsmapRowNodes池,按池顺序排列,RowSourceIndices 说明每个当前显示的内容。GetRealizedRowCount / GetRowWidget 是调用者通常想问的问题。
UListViewBaseGetScrollOffsetadoptGetScrollOffset
UListViewBaseGetIsDraggingListItemadoptGetIsDraggingListItem仅当拖拽的是本列表自己的行时才为真——从别处拖拽并悬停在其上的,不算本列表在拖拽。
UListViewBaseRegenerateAllEntriesmapRebuildRows丢弃这些行并重新从源构建,这正是 UMG 的做法。
UListViewBaseScrollToTopadoptScrollToTop
UListViewBaseScrollToBottomadoptScrollToBottom
UListViewBaseSetScrollOffsetadoptSetScrollOffset
UListViewBaseEndInertialScrollingadoptEndInertialScrolling转发给滚动行为。
UListViewBaseSetWheelScrollMultiplieradoptSetWheelScrollMultiplier列表的刻度单位是一个 ROW(行),因此该乘数缩放的是行间距;而滚动框缩放的是本地单位。名称相同、含义相同,但底层单位不同。
UListViewBaseSetScrollbarVisibilitymapSetScrollBarVisibility大写 B,这是本库各处的拼写方式。接受 EDreamScrollBoxScrollbarVisibility 而不是 ESlateVisibility。
UListViewBaseGetScrollbarVisibilitymapGetScrollBarVisibility参见 SetScrollbarVisibility。
UListViewBaseSetAllowOverScrollmapSetAllowOverscrollOverscroll 中小写 s,这是本库其余部分的拼写方式。
UListViewBaseGetOverscrolladoptGetOverscroll超出端点的有符号本地单位;在范围内为零,且过滚动关闭时也为零。
UListViewBaseSetIsPointerScrollingEnabledadoptSetIsPointerScrollingEnabledUUIScrollView::bIsPointerScrollingEnabled,在 AcceptsDragGesture 的 FRONT(前部)被询问,并与滚轮路径上的 ConsumeMouseWheel::Never 并列:滚轮和拖拽是同一组手势,一个视图只响应其中之一,意味着它的滚动条是唯一向下滚动的方式。
UListViewBaseSetIsTouchScrollingEnabledmapSetEnableTouchScrolling同一个开关,按滚动框的拼写方式,以使两个控件读起来一致。
UListViewBaseSetIsGamepadScrollingEnabledadoptSetIsGamepadScrollingEnabledUUIScrollView::bIsGamepadScrollingEnabled,由 FDreamUINavigationScroll 在 AnalogMouseWheelKey 之前询问。在那里拒绝意味着该手势无人接收:外层容器不是作者在内层关闭的开关的兜底。
UListViewBaseCancelListViewDragDropadoptCancelListViewDragDrop通过拖放子系统,而不是清除我们自己的标志:操作、可视元素和指针状态都是它的,一个只忘记自己那一半的列表会让屏幕上留下一个可视元素却没有任何东西来结束它。当子系统没有任何东西可取消时——无头测试、指针已消失——控件仍会清除自己的状态,否则之后的每次拖拽都会看起来像已经有一个在进行中。
UListViewBaseRequestRefreshmapRebuildRows此控件同步重建,因此没有待处理的请求可发:每个移动源的设置器在返回前都会重建,这正是无头测试和设计师第一帧都需要的。
UListViewBaseBP_OnEntryGeneratedmapOnRowGenerated每次 BIND 时触发,在回收时也就是每次行轮回绑定到新条目时。
UListViewBaseBP_OnEntriesGeneratedadoptOnRowsGenerated在 RebuildRows 返回前广播,这在此处就是批处理边界:此控件同步重建,因此没有待处理的请求留给后续帧来完成。
UListViewBaseEntryWidgetClassmapRowTemplateClass每个 POOL 行一个实例,填满该行;行的外观、高度、悬停和选中状态仍由控件管理。Null 即内置的标签行。
UListViewBaseWheelScrollMultiplieradoptWheelScrollMultiplier
UListViewBasebEnableScrollAnimationadoptbEnableScrollAnimation默认关闭:所有现有列表的显示都落在一帧内。推送到该行为体的动画滚轮开关。
UListViewBaseScrollingAnimationInterpolationSpeedadoptScrollingAnimationInterpolationSpeed列表上是 SPEED(速度),行为体上是 DURATION(持续时间)——同一个缓动参数化了两次。在推送时转换一次,作为倒数。
UListViewBasebInEnableTouchAnimatedScrollingadoptbEnableTouchAnimatedScrolling新增 UUIScrollView::bAnimateTouchScrolling:在拖拽结束时,甩动的预测落点被交给滚轮所用的同一滑行,并且速度被丢弃,以便物理不会继续推动补间已经在移动的内容。
UListViewBaseAllowOverscrolladoptbAllowOverscroll
UListViewBasebEnableRightClickScrollingadoptbEnableRightClickScrolling推送到 UUIScrollView::bAllowRightClickDragScrolling,这是滚动框对同一开关的拼写方式。
UListViewBasebEnableTouchScrollingadoptbEnableTouchScrolling
UListViewBasebIsPointerScrollingEnabledadoptbIsPointerScrollingEnabled参见 SetIsPointerScrollingEnabled。
UListViewBasebIsGamepadScrollingEnabledadoptbIsGamepadScrollingEnabled参见 SetIsGamepadScrollingEnabled。
UListViewBasebEnableFixedLineOffsetadoptbEnableFixedLineOffsetScrollItemIntoView 目标中的一个分支:该行被 PINNED(固定)在窗口的某个比例处,而不仅仅是带入窗口内。这正是光标驱动的菜单想要的——高亮行保持不动,列表在其下方移动。
UListViewBaseFixedLineScrollOffsetadoptFixedLineScrollOffset0 是近端,1 是远端,一半是中间。在范围两端仍会被钳制,因为两端没有多余的线可让。
UListViewBasebAllowDraggingadoptbAllowDragging关闭,且关闭是字面意义上的:关闭时不带任何行拖拽行为,因此现有列表没有任何可订阅的东西,也没有任何东西会改变在行上按下所代表的含义。开启会添加 UDreamListRowDragSource——本库自己的 UDreamUIDragSource 的子类,因此按下并移动测试、操作交接和拖拽结束通知都是其他所有可拖拽控件所用的那一套。
UListViewBasebAllowDragDropadoptbAllowDragDrop与 bAllowDragging 分开,且两个方向都有用:一个只被拖出而从不拖入的调色板想要单独的拖拽,一个从别处接收物品的装备列表想要单独的放置。本库添加了 UMG 的列表所没有的边缘滚动:在 bEnableDragEdgeScrolling 开启时(默认关闭),一个可接受的拖拽保持在视口两端 DragEdgeScrollBandSize 范围内,就会以 DragEdgeScrollSpeed 沿该方向滚动列表,在拖放子系统的悬停 tick 上步进。
UListViewBaseDragDropVisualPivotadoptDragDropVisualPivot在拖拽时合并进操作的单一 DragVisualOffset,因为枢轴是按可视化对象自身尺寸度量的偏移,而库的操作对两者只携带一个数值。需要行的尺寸,因此它发生在存在行的时候,而不是在行为上。
UListViewBaseDragDropVisualOffsetadoptDragDropVisualOffset叠加在枢轴之上,使用局部单位。X 向右,Y 向上。
UListViewBaseDragDropVisualEntryClassadoptDragDropVisualEntryClass为空时回退到 RowTemplateClass,这是无需编写的答案:光标下的东西应当看起来像它所来自的行,而列表早已知道如何创建一个。
UListViewBaseDragDropOperationClassadoptDragDropOperationClass默认为 UDreamDragDropOperation,它已经携带了载荷、标签、可视化类,以及比被回收的行存活更久的取消通知。
UListViewBaseDragVisualWidgetmapDragDropVisualEntryClass是类,而不是实例:列表会为每次拖拽创建一个可视化对象,而共享实例会是一个被两个同时进行的拖拽争抢的控件。实例一旦创建,就归操作所有。
UListViewBasebIsDraggingmapGetIsDraggingListItem私有状态,配有纯 getter 而非可写标志:它由拖拽开始设置、由拖拽结束清除,调用方写入它就等于对每个读取它的处理器撒谎。GetDraggedItemIndex 回答是哪一个行。
UListViewBasebSelectItemOnNavigationadoptbSelectItemOnNavigation两条路径上都为 True:一次步进到另一行的导航按下会选中它,正如 SListView 的 NavigationSelect 那样,而 NavigateToIndex 会选中它所揭示的内容。关闭时,两者都只移动焦点并揭示,选中项停留在玩家离开的位置——这是一个可以滚动浏览而不会丢失你所在行的列表。
UListViewBasebAllowKeepPreselectedItemsadoptbAllowKeepPreselectedItems与实时索引集合并存的停放索引集合:ReconcileSelection 会在源长到足以容纳停放索引的瞬间重新应用它,而不是丢弃它。一个在数据加载前就恢复“第 7 行曾被选中”的界面,否则就会静默地丢失它。关闭该开关会丢弃停放集合。
UListViewBaseBP_OnEntryReleasedmapOnRowReleased在新索引写入之前触发,因此询问 GetRowItemIndex 的处理器仍会被告知正在释放的那一个。
UListViewBaseNumDesignerPreviewEntriesreject仅设计时使用的行数。此控件没有世界、也没有布局过程,直接从编写的 Items 构建它的行,因此设计器已经看到真实的列表——没有什么需要预览计数来替代。

本页目录