UE3:UIList (UDK)

Object >> UIRoot >> UIScreenObject >> UIObject >> UIList

Package: 

Engine

Implemented interfaces: 

UIDataStorePublisher

Known classes within UIList:

UIComp_ListComponentBase, UIComp_ListElementSorter, UIComp_ListPresenter, UIComp_ListPresenterBase, UIComp_ListPresenterCascade, UIComp_ListPresenterTree, UIComp_UTUIMenuListPresenter, UIListString

Direct subclasses:

UIContextMenu, UINavigationList, UIObjectList, UTUIList

This class in other games:

UT3

The "container" component of the UI system's list functionality, which is composed fo three components: data source, container widget, and formatter.

The UIList acts as the conduit for list data to the UI. UIList knows nothing about the type of data it contains. It is responsible for tracking the number of elements it has, the size of each cell, handling input (including tracking which elements are selected, changing the selected element, etc.), adding and removing elements from the list, and passing data back and forth between the data source and the presenter components.

Constants

ResizeBufferPixels

Value: 5

how many pixels wide the region is that is used for resizing a column/row

Properties

Property group 'Appearance'

bEnableMultiSelect

Type: bool

Determines whether more than one item can be selected at the same time.

Todo: not yet implemented

bForceFullPageDisplay

Type: bool

Modifiers: private

Controls what happens when the end of the list is reached and the number of remaining items is less than the number of visible items. Set to FALSE to prevent the list's TopIndex from being adjusted to display a full page.

Default value: True

bHoverStateOverridesSelected

Type: bool

Modifiers: private

For lists with bUpdateItemUnderCursor=TRUE, controls whether the selected item enters the hover state when mouse over.

bUpdateItemUnderCursor

Type: bool

Modifiers: private

Controls whether the item currently under the cursor should be drawn using a different style.

CellLinkType

Type: ECellLinkType

Controls how the cells are mapped to elements. If CellLinkType is not LINKED_None, the data provider for this list must be capable of supplying multiple data fields for a single item.

Todo: once this functionality is exposed through the UI, this variable should no longer be editable

Default value: LINKED_Columns

CellPadding

Type: UIRoot.UIScreenValue_Extent

Amount of spacing to use inside each cell.

CellSpacing

Type: UIRoot.UIScreenValue_Extent

Amount of spacing to use between each element in the list.

ColumnAutoSizeMode

Type: ECellAutoSizeMode

Controls how columns are auto-sized.

Default value: CELLAUTOSIZE_Uniform

ColumnCount

Type: int

Modifiers: protected

Number of columns to display in the list. How this is set is dependent on the value of CellLinkType.

LINKED_None: Whatever value designer specifies is used. Either the width of the list or the column widths must be dynamic. LINKED_Rows: always the same value as MaxVisibleItems. LINKED_Columns: determined by the number of cells which are bound to data providers.

Default value: 1

ColumnWidth

Type: UIRoot.UIScreenValue_Extent

Default width for cells in the list. A value of 0 indicates that the cell widths are dynamic. Dynamic behavior is as follows: Linked columns: columns are expanded to fill the width of the list Non-linked columns: columns widths will be adjusted to fit the largest string in the list

If columns are linked, this value is only applied to cells that have a value of 0 for CellSize.

Default value:

Member	Value
Value	100.0

HeaderCellPadding

Type: UIRoot.UIScreenValue_Extent

Amount of spacing to use inside the cells of the column headers.

HeaderElementSpacing

Type: UIRoot.UIScreenValue_Extent

Amount of spacing to place between the column header and the first element.

MaxVisibleItems

Type: int

Modifiers: editconst, transient, duplicatetransient

Maximum number of items that can be visible at one time in the list. Calculated using the current size of the list and the list's cells.

MinColumnSize

Type: UIRoot.UIScreenValue_Extent

Minimum size a column is allowed to be resized to.

Default value:

Member	Value
Value	0.5

RowAutoSizeMode

Type: ECellAutoSizeMode

Controls how rows are auto-sized

Default value: CELLAUTOSIZE_Constrain

RowCount

Type: int

Modifiers: protected

Number of rows to display in the list. How this is set is dependent on the value of CellLinkType.

LINKED_None: Whatever value designer specifies is used. Either the height of the list or the column heights must be dynamic. LINKED_Rows: determined by the number of cells which are bound to data providers. LINKED_Columns: always the same value as MaxVisibleItems.

Default value: 4

RowHeight

Type: UIRoot.UIScreenValue_Extent

Default height for cells in the list. A value of 0 indicates that the cell heights are dynamic.

If rows are linked, this value is only applied to cells that have a value of 0 for CellSize.

Default value:

Member	Value
Value	16.0

WrapType

Type: EListWrapBehavior

Controls the wrapping behavior of the list, or what happens when the use attempts to scroll past the last element

Property group 'Components'

BackgroundImageComponent

Type: UIComp_DrawImage

Modifiers: editinline

Component for rendering an optional list background

CellDataComponent

Type: UIComp_ListPresenterBase

Modifiers: editinline

Handles the interaction between the list and the list's elements. Encapsulates any special behavior associated with a particular type of list data and controls how the list formats its data.

Default value: UIComp_ListPresenter'ListPresentationComponent'

SortComponent

Type: UIComp_ListElementSorter

Modifiers: editinline

Determines how to sort the list's elements.

Property group 'Controls'

bEnableVerticalScrollbar

Type: bool

Determines if this list will display scrollbars

Default value: True

Property group 'Data'

DataSource

Type: UIRoot.UIDataStoreBinding

The data store that this list is bound to

Default value:

Member	Value
RequiredFieldType	DATATYPE_Collection

Property group 'Interaction'

bAllowColumnResizing

Type: bool

Controls whether the user is allowed to resize the columns in this list.

Default value: True

bAllowDisabledItemSelection

Type: bool

Controls whether items which are "disabled" can be selected.

bSingleClickSubmission

Type: bool

Controls how many clicks are required in order to submit the list selected item (triggers the kismet Submit List Selection event). FALSE to require a double-click on an item; FALSE to require only a single click;

Property group 'Sound'

DecrementIndexCue

Type: name

this sound is played when the user decreases the list's index

Default value: 'ListUp'

IncrementIndexCue

Type: name

this sound is played when the user increases the list's index

Default value: 'ListDown'

SortAscendingCue

Type: name

this sound is played when the user sorts the list in ascending order

Default value: 'SortAscending'

SortDescendingCue

Type: name

this sound is played when the user sorts the list in descending order

Default value: 'SortDescending'

SubmitDataFailedCue

Type: name

this sound is played when the user clicks or presses A on an item that is disabled

Default value: 'GenericError'

SubmitDataSuccessCue

Type: name

this sound is played when the user clicks or presses A on an item that is enabled

Default value: 'ListSubmit'

Property group 'ZDebug'

bDisplayDataBindings

Type: bool

Modifiers: transient

if TRUE, the schema fields assigned to each column/row will be rendered, rather than the actual data. Used primarily by the UI edtitor.

Internal variables

bInitializeScrollbars

Type: bool

Modifiers: transient

set to indicate that the scrollbars need to be initialized after in the ResolveFacePosition call

bSortingList

Type: bool

Modifiers: const, transient

TRUE if the user clicks on a column header - prevents the OnClick delegate from being fired

ColumnHeaderBackgroundStyle

Type: UIRoot.UIStyleReference

Array size: 3 (EColumnHeaderState.COLUMNHEADER_MAX)

The style to use for column header background images, if this list uses them. The CellDataComponent also needs valid values for its ColumnHeaderBackground variable.

Default value, index 0:

Member	Value
RequiredStyleClass	Class'Engine.UIStyle_Image'

Default value, index 1:

Member	Value
RequiredStyleClass	Class'Engine.UIStyle_Image'

Default value, index 2:

Member	Value
RequiredStyleClass	Class'Engine.UIStyle_Image'

ColumnHeaderStyle

Type: UIRoot.UIStyleReference

The style to use for the list's column header text. The string portion of the style is applied to text; the image portion of the style is applied to images embedded in the column header text (NOT the column header's background). If not valid, the GlobalCellStyle for the normal cell state will be used instead

Default value:

Member	Value
DefaultStyleTag	'DefaultColumnHeaderStyle'
RequiredStyleClass	Class'Engine.UIStyle_Combo'

DataProvider

Type: UIListElementProvider

Modifiers: const, transient

the list element provider referenced by DataSource

GlobalCellStyle

Type: UIRoot.UIStyleReference

Array size: 4 (EUIListElementState.ELEMENT_MAX)

The cell styles that are applied to any cells which do not have a custom cell style configured.

Default value, index 0:

Member	Value
DefaultStyleTag	'DefaultCellStyleNormal'
RequiredStyleClass	Class'Engine.UIStyle_Combo'

Default value, index 1:

Member	Value
DefaultStyleTag	'DefaultCellStyleActive'
RequiredStyleClass	Class'Engine.UIStyle_Combo'

Default value, index 2:

Member	Value
DefaultStyleTag	'DefaultCellStyleSelected'
RequiredStyleClass	Class'Engine.UIStyle_Combo'

Default value, index 3:

Member	Value
DefaultStyleTag	'DefaultCellStyleHover'
RequiredStyleClass	Class'Engine.UIStyle_Combo'

Index

Type: int

Modifiers: transient

Index into the Items array for currently active item. In most cases, the active item will be the same as the selected item. Active item does not imply selected, however. A good example of this is a multi-select list that has no selected items, but which has focus - corresponds to the item that would be selected if the user pressed 'space' or 'enter'.

ItemOverlayStyle

Type: UIRoot.UIStyleReference

Array size: 4 (EUIListElementState.ELEMENT_MAX)

The style to apply to the overlay textures for each cell state.

Default value, index 0:

Member	Value
DefaultStyleTag	'ListItemBackgroundNormalStyle'
RequiredStyleClass	Class'Engine.UIStyle_Image'

Default value, index 1:

Member	Value
DefaultStyleTag	'ListItemBackgroundActiveStyle'
RequiredStyleClass	Class'Engine.UIStyle_Image'

Default value, index 2:

Member	Value
DefaultStyleTag	'ListItemBackgroundSelectedStyle'
RequiredStyleClass	Class'Engine.UIStyle_Image'

Default value, index 3:

Member	Value
DefaultStyleTag	'ListItemBackgroundHoverStyle'
RequiredStyleClass	Class'Engine.UIStyle_Image'

Items

Type: array<int>

Modifiers: const, transient

The elements of the list. Corresponds to the array indexes of the whichever array this list's data comes from.

ResizeColumn

Type: int

Modifiers: const, transient

The column currently being resized, or INDEX_NONE if no columns are being resized.

SelectedItems

Type: array<int>

Modifiers: transient, public

The items which are currently selected. The int values are the array indexes of the whichever array this list's data comes from.

Todo: not yet implemented

SetIndexMutex

Type: int

Modifiers: private, transient

If this value is greater than 0, SetIndex() will not do anything.

TopIndex

Type: int

Modifiers: transient

The index of the element which is located at the beginning of the visible region.

ValueChangeNotificationMutex

Type: int

Modifiers: private, transient

If this value is more than 0, the OnValueChanged delegate will not be called.

VerticalScrollbar

Type: UIScrollbar

The UIScrollbar object which is allows the UIList to be scrolled up/down

Default value: UIScrollbar'Engine.Default__UIList:VertScrollbarTemplate'

Default values

Property	Value
bSupportsFocusHint	True
bSupportsPrimaryStyle	False
Children[0]	UIScrollbar'Engine.Default__UIList:VertScrollbarTemplate'
DebugBoundsColor	Member Value A 255 B 255 G 255 R 255
DefaultStates[2]	Class'Engine.UIState_Focused'
DefaultStates[3]	Class'Engine.UIState_Active'
DefaultStates[4]	Class'Engine.UIState_Pressed'
PrimaryStyle	Member Value DefaultStyleTag 'DefaultListStyle' RequiredStyleClass Class'Engine.UIStyle_Combo'
PrivateFlags	1024

Subobjects

ListPresentationComponent

Class: Engine.UIComp_ListPresenter

Property	Value
ListItemOverlay[0]	UITexture'Engine.Default__UIList:ListPresentationComponent.NormalOverlayTemplate'
ListItemOverlay[1]	UITexture'Engine.Default__UIList:ListPresentationComponent.ActiveOverlayTemplate'
ListItemOverlay[2]	UITexture'Engine.Default__UIList:ListPresentationComponent.SelectionOverlayTemplate'
ListItemOverlay[3]	UITexture'Engine.Default__UIList:ListPresentationComponent.HoverOverlayTemplate'

WidgetEventComponent

Class: Engine.UIComp_Event

Inherits from: UIObject.WidgetEventComponent

No new values.

Enums

ECellAutoSizeMode

Different ways to auto-size list cells

CELLAUTOSIZE_None 

(None in UnrealEd) Auto-sizing not enabled

CELLAUTOSIZE_Uniform 

(Uniform Fill in UnrealEd) Cells will be uniformly sized so that all cells can be displayed within the bounds of the list. The configured

cell size is ignored, and the bounds of the list are not adjusted.

CELLAUTOSIZE_Constrain 

(Best Fit in UnrealEd) Cells will be sized to fit their contents. The configured cell size is ignored, and the bounds of the list are

not adjusted.

CELLAUTOSIZE_AdjustList 

(Adjust List Bounds in UnrealEd) Cells will be sized to fit their contents. The configured cell size is ignored, and the bounds of the list are

adjusted to display all cells

ECellLinkType

Determines how the cells in this list are linked.

LINKED_None 

(Disabled in UnrealEd) no linking - one to one mapping between cells and elements

LINKED_Rows 

(Span Rows in UnrealEd) rows are linked; each column in the list will represent a single element; not yet implemented

LINKED_Columns 

(Span Columns in UnrealEd) columns are linked; each row in the list represents a single element

EListWrapBehavior

Determines how list elements are wrapped

LISTWRAP_None 

no wrapping (default); when the end of the list is reached, the user will not be able to scroll further

LISTWRAP_Smooth 

Smooth wrapping; if space is available after rendering the last element, starts over at the first element and

continues rendering elements until no more space is available.

Todo: not yet implemented

LISTWRAP_Jump 

Jump wrapping; list stops rendering at the last element, but if the user attempts to scroll past the end of the

list, the index jumps back to the opposite side of the list.

Structs

CellHitDetectionInfo

Modifiers: native, transient

Provides information about which cells the mouse is currently hovering over.

int HitColumn 

the column that was hit; INDEX_NONE if the location did not correspond to a valid column

int HitRow 

the row that was hit; INDEX_NONE if the location did not correspond to a valid row

int ResizeColumn 

if the hit location was within the region used for resizing a column, indicates the column that will be resized;

int ResizeRow 

if the hit location was within the region used for resizing a column, indicates the column that will be resized;

Delegates

OnListElementsSorted

delegate OnListElementsSorted (UIList Sender)

Called anytime this list's elements are sorted.

Parameters:

• Sender - the list that just sorted its elements.

OnOverrideListElementState

delegate UIRoot.EUIListElementState OnOverrideListElementState (UIList Sender, int ElementIndex, UIRoot.EUIListElementState CurrentState, UIRoot.EUIListElementState NewElementState)

Provides a way for users to override the cell state being assigned to a list element.

Parameters:

• Sender - the list calling the delegate
• ElementIndex - the index [into the list's Items array] for the element being set; Items[ElementIndex] would be the index into the source data provider's collection.
• CurrentState - the element's current cell state.
• NewElementState - the cell state that is being set on the element.

Returns:

the cell state that should be set on the element.

OnSubmitSelection

delegate OnSubmitSelection (UIList Sender, optional int PlayerIndex)

Called when the user presses Enter (or any other action bound to UIKey_SubmitListSelection) while this list has focus.

Parameters:

• Sender - the list that is submitting the selection

ShouldDisableElement

delegate bool ShouldDisableElement (UIList Sender, int ElementIndex)

Allows the widget to force specific elements to be disabled. If not implemented, or if the return value is false, the list's data provider will then be given an opportunity to disable the item.

Parameters:

• Sender - the list calling the delegate
• ElementIndex - the index [into the data store's list of items] for the item to query

Returns:

TRUE if the specified element should be disabled.

Functions

Native functions

See UIList native functions.

Events

AllMutexesDisabled

final event bool AllMutexesDisabled ()

Returns:

TRUE if all mutexes are disabled.

DecrementAllMutexes

final event DecrementAllMutexes (optional bool bDispatchUpdates)

Decrements all mutexes

Parameters:

• bDispatchUpdates - specify TRUE to refresh the list's index, formatting, and states.

DisableSetIndex

final event DisableSetIndex ()

Disable calls to SetIndex(); useful when adding lots of items to avoid flicker.

DisableValueChangeNotification

final event DisableValueChangeNotification ()

Disable calls to NotifyValueChanged(); useful when adding lots of items to avoid flicker.

EnableSetIndex

final event EnableSetIndex ()

Enable calls to SetIndex(); useful when adding lots of items to avoid flicker.

EnableValueChangeNotification

final event EnableValueChangeNotification ()

Enable calls to NotifyValueChanged(); useful when adding lots of items to avoid flicker.

IncrementAllMutexes

final event IncrementAllMutexes ()

Increments all mutexes

Initialized

event Initialized ()

Overrides: UIScreenObject.Initialized

Sets up the scroll activity delegates in the scrollbars

Todo: this is a fix for the issue where delegates don't seem to be getting set properly in defaultproperties blocks.

IsSetIndexEnabled

final event bool IsSetIndexEnabled ()

Returns:

TRUE if calls to SetIndex() will be executed.

IsValueChangeNotificationEnabled

final event bool IsValueChangeNotificationEnabled ()

Returns:

TRUE if calls to NotifyValueChanged() will be executed.

PostInitialize

event PostInitialize ()

Overrides: UIScreenObject.PostInitialize

Propagate the enabled state of this widget.

Other instance functions

ClickedScrollZone

function ClickedScrollZone (UIScrollbar Sender, float PositionPerc, int PlayerIndex)

Handler for the vertical scrollbar's OnClickedScrollZone delegate. Scrolls the list by a full page (MaxVisibleItems).

Parameters:

• Sender - the scrollbar that was clicked.
• PositionPerc - a value from 0.0 - 1.0, representing the location of the click within the region between the increment and decrement buttons. Values closer to 0.0 means that the user clicked near the decrement button; values closer to 1.0 are nearer the increment button.
• PlayerIndex - Player that performed the action that issued the event.

EnableColumnHeaderRendering

final function EnableColumnHeaderRendering (bool bShouldRenderColHeaders)

Changes whether this list renders colum headers or not. Only applicable if the owning list's CellLinkType is LINKED_Columns

OnStateChanged

final function OnStateChanged (UIScreenObject Sender, int PlayerIndex, UIState NewlyActiveState, optional UIState PreviouslyActiveState)

Called when a new UIState becomes the widget's currently active state, after all activation logic has occurred.

Parameters:

• Sender - the widget that changed states.
• PlayerIndex - the index [into the GamePlayers array] for the player that activated this state.
• NewlyActiveState - the state that is now active
• PreviouslyActiveState - the state that used the be the widget's currently active state.

ShouldRenderColumnHeaders

final function bool ShouldRenderColumnHeaders ()

Returns whether this list should render column headers