UE3:UIScreenObject native functions (UDK)

Object >> UIRoot >> UIScreenObject (native functions)

UIScreenObject native functions in other games:

UT3

Native functions

ClearUIAnimationLoop

native event ClearUIAnimationLoop (int SequenceIndex, optional int TrackTypeMask)

Disables the looping for an animation, without affecting the animation itself.

Parameters:

• SequenceIndex - the index of the sequence to clear the looping for; can be retrieved using FindAnimationSequenceIndex().
• TypeMask - a bitmask representing the type of animation tracks to affect. The bitmask should be generated by left shifting 1 by the values of the EUIAnimType enum.

IsAnimating

native event bool IsAnimating (optional name AnimationSequenceName)

Accessor for checking whether this widget is currently animating.

Parameters:

• AnimationSequenceName - if specified, checks whether an animation sequence with this name is currently active.

Returns:

TRUE if this widget is animating and if the named animation sequence is active.

PlayUIAnimation

native event PlayUIAnimation (name AnimName, optional UIAnimationSeq AnimSeqTemplate, optional UIAnimation.EUIAnimationLoopMode OverrideLoopMode, optional float PlaybackRate, optional float InitialPosition, optional bool bSetAnimatingFlag)

Play an animation on this UIObject

Parameters:

• AnimName - name of the animation sequence to activate; only necessary if no value is provided for AnimSeq
• AnimSeq - the animation sequence to activate for this widget; if specified, overrides the value of AnimName.
• OverrideLoopMode - if specified, overrides the animation sequence's default looping behavior
• PlaybackRate - if specified, affects how fast the animation will be executed. 1.0 is 100% speed.
• InitialPosition - if specified, indicates an alternate starting position (in seconds) for the animation sequence
• bSetAnimatingFlag - specify FALSE to prevent this function from marking this widget (and its parents) as bAnimating.

StopUIAnimation

native event StopUIAnimation (name AnimName, optional UIAnimationSeq AnimSeq, optional bool bFinalize, optional int TrackTypeMask)

Stop an animation that is playing.

Parameters:

• AnimName - name of the animation sequence to stop; only necessary if no value is provided for AnimSeq
• AnimSeq - the animation sequence to deactivate for this widget; if specified, overrides the value of AnimName.
• bFinalize - indicates whether the widget should apply the final frame of the animation (i.e. simulate the animation completing)
• TypeMask - a bitmask representing the type of animation tracks to stop. The bitmask should be generated by left shifting 1 by the values of the EUIAnimType enum.

AcceptsPlayerInput

native final function bool AcceptsPlayerInput (int PlayerIndex) const

Determines whether this widget can accept input from the player specified

Parameters:

• PlayerIndex - the index of the player to check

Returns:

TRUE if this widget's PlayerInputMask allows it to process input from the specified player.

ActivateEventByClass

native final noexport function ActivateEventByClass (int PlayerIndex, class<UIEvent> EventClassToActivate, optional Object InEventActivator, optional bool bActivateImmediately, optional array<int> IndicesToActivate, optional out array<UIEvent> out_ActivatedEvents)

Activate the event of the specified class.

Parameters:

• PlayerIndex - the index of the player that activated this event
• EventClassToActivate - specifies the event class that should be activated. If there is more than one instance of a particular event class in this screen object's list of events, all instances will be activated in the order in which they occur in the event provider's list.
• InEventActivator - an optional object that can be used for various purposes in UIEvents
• bActivateImmediately - TRUE to activate the event immediately, causing its output operations to also be processed immediately.
• IndicesToActivate - Indexes into this UIEvent's Output array to activate. If not specified, all output links will be activated
• out_ActivatedEvents - filled with the event instances that were activated.

Note: noexport because non-const optional arrays aren't exported correctly by the script compiler.

ActivateState

native final virtual function bool ActivateState (UIState StateToActivate, int PlayerIndex)

Adds the specified state to the screen object's StateStack.

Parameters:

• StateToActivate - the new state for the widget
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this call

Returns:

TRUE if the widget's state was successfully changed to the new state. FALSE if the widget couldn't change to the new state or the specified state already exists in the widget's list of active states

ActivateStateByClass

native final noexport function bool ActivateStateByClass (class<UIState> StateToActivate, int PlayerIndex, optional out UIState StateThatWasAdded)

Alternate version of ActivateState that activates the first state in the InactiveStates array with the specified class that isn't already in the StateStack

Anim_GetValue

native final virtual function bool Anim_GetValue (UIAnimation.EUIAnimType AnimationType, out UIAnimation.UIAnimationRawData out_CurrentValue) const

Retrieves the current value for some data currently being interpolated by this widget.

Parameters:

• AnimationType - the type of animation data to retrieve
• out_CurrentValue - receives the current data value; animation type determines which of the fields holds the actual data value.

Returns:

TRUE if the widget supports the animation type specified.

Anim_SetValue

native final virtual function bool Anim_SetValue (UIAnimation.EUIAnimType AnimationType, const out UIAnimation.UIAnimationRawData NewValue)

Updates the current value for some data currently being interpolated by this widget.

Parameters:

• AnimationType - the type of animation data to set
• out_CurrentValue - contains the updated data value; animation type determines which of the fields holds the actual data value.

Returns:

TRUE if the widget supports the animation type specified.

AnimGetCurrentPPSettings

native final noexport function bool AnimGetCurrentPPSettings (out PostProcessVolume.PostProcessSettings CurrentSettings)

Accessor for retrieving the PostProcessSettings struct used for interpolating PP effects.

Parameters:

• CurrentSettings - receives the current PostProcessSettings that should be used for PP effect animation.

Returns:

TRUE if this widget supports animation of post-processing and filled in the value of CurrentSettings.

CanAcceptFocus

native function bool CanAcceptFocus (optional int PlayerIndex, optional bool bIncludeParentVisibility) const

Determines whether this widget can become the focused control.

Parameters:

• PlayerIndex - the index [into the Engine.GamePlayers array] for the player to check focus availability
• bIncludeParentVisibility - indicates whether the widget should consider the visibility of its parent widgets when determining whether it is eligible to receive focus. Only needed when building navigation networks, where the widget might start out hidden (such as UITabPanel).

Returns:

TRUE if this widget (or any of its children) is capable of becoming the focused control.

CanPropagateFocusFor

native final function bool CanPropagateFocusFor (UIObject TestChild) const

Determines whether this widget is allowed to propagate focus chains to and from the specified widget.

Parameters:

• TestChild - the widget to check

Returns:

TRUE if the this widget is allowed to route the focus chain through TestChild.

CanvasToScreen

native final function Object.Vector4 CanvasToScreen (const out Object.Vector CanvasPosition) const

Transforms a vector from canvas (widget local) space into screen (D3D device) space

Parameters:

• CanvasPosition - a vector representing a location in widget local space.

Returns:

a vector representing that location in screen space.

ConditionalPropagateEnabledState

native final virtual function bool ConditionalPropagateEnabledState (int PlayerIndex, optional bool bForce)

Propagates the enabled state of this widget to its child widgets, if the widget has the PRIVATE_PropageteState flag set.

Parameters:

• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this call
• bForce - specify TRUE to propagate the enabled state even if this widget doesn't have the PropagateState flag set.

Returns:

TRUE if child widget states were set successfully.

ContainsChild

native final function bool ContainsChild (UIObject Child, optional bool bRecurse) const

Returns whether this screen object contains the specified child in its list of children.

Parameters:

• Child - the child to look for
• bRecurse - whether to search child widgets for the specified child. if this value is FALSE, only the Children array of this screen object will be searched for Child.

Returns:

TRUE if Child is contained by this screen object

ContainsChildOfClass

native final function bool ContainsChildOfClass (class<UIObject> SearchClass, optional bool bRecurse) const

Returns whether this screen object contains a child of the specified class.

Parameters:

• SearchClass - the class to search for.
• bRecurse - indicates whether to search child widgets. if this value is FALSE, only the Children array of this screen object will be searched for instances of SearchClass.

Returns:

TRUE if Child is contained by this screen object

CreatePlayerData

native final virtual function CreatePlayerData (int PlayerIndex, LocalPlayer AddedPlayer)

Called when a new player has been added to the list of active players (i.e. split-screen join) after the scene has been activated.

Parameters:

• PlayerIndex - the index [into the GamePlayers array] where the player was inserted
• AddedPlayer - the player that was added

CreateWidget

native final function UIObject CreateWidget (UIScreenObject Owner, class<UIObject> WidgetClass, optional Object WidgetArchetype, optional name WidgetName)

Utility function for encapsulating constructing a widget

Parameters:

• Owner - the container for the widget. Cannot be none
• WidgetClass - the class of the widget to create. Cannot be none.
• WidgetArchetype - the template to use for creating the widget
• WidgetName - the name to use for the new widget

DeactivateState

native final virtual function bool DeactivateState (UIState StateToRemove, int PlayerIndex)

Removes the specified state from the screen object's state stack.

Parameters:

• StateToRemove - the state to be removed
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this call

Returns:

TRUE if the state was successfully removed, or if the state didn't exist in the widget's list of states; false if the state overrode the request to be removed

DeactivateStateByClass

native final noexport function bool DeactivateStateByClass (class<UIState> StateToRemove, int PlayerIndex, optional out UIState StateThatWasRemoved)

Alternate version of DeactivateState that deactivates the last state in the StateStack array that has the specified class.

DeProject

native final function Object.Vector DeProject (const out Object.Vector PixelPosition) const

Converts an absolute pixel position into 3D screen coordinates.

Parameters:

• PixelPosition - the position of the 2D point, in pixels

Returns:

a position tranformed using this widget's rotation and the scene client's projection matrix.

FindAnimationSequenceIndex

native final function int FindAnimationSequenceIndex (name SequenceName) const

Find the index [into this widget's AnimStack array] for the animation sequence that has the specified name.

Parameters:

• SequenceName - the name of the sequence to find.

Returns:

the index of the sequence, or INDEX_NONE if it's not currently active.

FindChild

native final function UIObject FindChild (name WidgetName, optional bool bRecurse) const

Find a child widget with the specified name

Parameters:

• WidgetName - the name of the child to find
• bRecurse - if TRUE, searches all children of this object recursively

Returns:

a pointer to a widget contained by this object that has the specified name, or NULL if no widgets with that name were found

FindChildIndex

native final function int FindChildIndex (name WidgetName) const

Find the index for the child widget with the specified name

Parameters:

• WidgetName - the name of the child to find

Returns:

the index into the array of children for the widget that has the specified name, or -1 if there aren't any widgets with that name.

FindChildUsingID

native final function UIObject FindChildUsingID (UIRoot.WIDGET_ID WidgetID, optional bool bRecurse) const

Find a child widget with the specified GUID

Parameters:

• WidgetID - the ID(GUID) of the child to find
• bRecurse - if TRUE, searches all children of this object recursively

Returns:

a pointer to a widget contained by this object that has the specified GUID, or NULL if no widgets with that name were found

FindEventsOfClass

native final function FindEventsOfClass (class<UIEvent> EventClassToFind, out array<UIEvent> out_EventInstances, optional UIState LimitScope, optional bool bExactClass)

Finds UIEvent instances of the specified class.

Parameters:

• EventClassToFind - specifies the event class to search for.
• out_EventInstances - an array that will contain the list of event instances of the specified class.
• LimitScope - if specified, only events contained by the specified state's sequence will be returned.
• bExactClass - if TRUE, only events that have the class specified will be found. Otherwise, events of that class or any of its child classes will be found.

FocusFirstControl

native function bool FocusFirstControl (UIScreenObject Sender, optional int PlayerIndex)

Sets focus to the first focus target within this container.

Parameters:

• Sender - the widget that generated the focus change. if NULL, this widget generated the focus change.
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated the focus change.

Returns:

TRUE if focus was successfully propagated to the first focus target within this container.

FocusLastControl

native function bool FocusLastControl (UIScreenObject Sender, optional int PlayerIndex)

Sets focus to the last focus target within this container.

Parameters:

• Sender - the widget that generated the focus change. if NULL, this widget generated the focus change.
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated the focus change.

Returns:

TRUE if focus was successfully propagated to the last focus target within this container.

GetAspectRatio

native final function float GetAspectRatio () const

Retrieves the ratio of the viewport's width to its height.

GetAspectRatioAutoScaleFactor

native final function float GetAspectRatioAutoScaleFactor (optional Font BaseFont) const

Calculate the correct scaling factor to use for preserving aspect ratios in e.g. string and image formatting.

Parameters:

• BaseFont - if specified, a font which can provide a "base" resolution for the scale; otherwise, uses the values of the DFEAULT_SIZE_X/Y consts as the base resolution.
• a - float representing the aspect ratio percentage to use for scaling fonts and images.

GetBestControllerId

native final function int GetBestControllerId () const

Returns:

the ControllerId for this widget's owner scene's PlayerOwner, or the player that the owning scene last received input from. If the owning scene is NULL, the PlayerOwner is NULL, and no input has been received, returns INDEX_NONE.

GetBestPlayerIndex

native final function int GetBestPlayerIndex () const

Returns:

the index [into the Engine.GamePlayers array] for the player that this widget's owner scene last received input from, or INDEX_NONE if the scene is NULL or hasn't received any input from players yet.

GetBounds

native final function float GetBounds (UIRoot.EUIOrientation Dimension, UIRoot.EPositionEvalType OutputType, optional bool bIgnoreDockPadding) const

Returns the width or height for this widget

Parameters:

• Dimension - UIORIENT_Horizontal to get the width, UIORIENT_Vertical to get the height
• OutputType - indicates the format of the returnedvalue
• bIgnoreDockPadding - used to prevent recursion when evaluting docking links

GetCanvasToScreen

native final function Object.Matrix GetCanvasToScreen () const

Returns a matrix which includes the scene client's CanvasToScreen matrix and this widget's tranform matrix.

GetChildren

native final noexport function array<UIObject> GetChildren (optional bool bRecurse, optional array<UIObject> ExclusionSet) const

Gets a list of all children contained in this screen object.

Parameters:

• bRecurse - if FALSE, result will only contain widgets from this screen object's Children array if TRUE, result will contain all children of this screen object, including their children.
• ExclusionSet - if specified, any widgets contained in this array will not be added to the output array.

Returns:

an array of widgets contained by this screen object.

Note: noexport because non-const optional arrays aren't exported correctly by the script compiler.

GetCurrentState

native final function UIState GetCurrentState (int PlayerIndex)

Gets the current UIState of this screen object

Parameters:

• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this call

GetDockClients

native final noexport function int GetDockClients (optional out array<UIObject> DockClients, optional bool bDirectDockClientsOnly, optional UIRoot.EUIWidgetFace TargetFace, optional UIRoot.EUIWidgetFace SourceFace) const

Returns all objects which are docked to this one.

Parameters:

• DockClients - If specified, receives the list of objects docked to this one. Do not pass a value if you only wish to know the number of objects docked to this one.
• bDirectDockClientsOnly - by default, only returns widgets that are docked to this widget directly; Specify FALSE to also include widgets which are docked to this widget indirectly (i.e. through more than one docking link. Caution: this can cause a performance hit if there are a large number of widgets in the scene.
• TargetFace - if specified, returns only those widgets that are docked to the specified face on this widget.
• SourceFace - if specified, returns only those widgets that have the specified face docked to this widget.

Returns:

the number of widgets docked to this one.

Note: noexport so that the script thunk can handle the optional array parm correctly

GetDockedWidgets

native final function GetDockedWidgets (out array<UIObject> out_DockedWidgets, optional UIRoot.EUIWidgetFace SourceFace, optional UIRoot.EUIWidgetFace TargetFace) const

Generates a list of all widgets which are docked to this one.

Parameters:

• out_DockedWidgets - receives the list of widgets which are docked to this one
• SourceFace - if specified, only widgets which are docked to this one through the specified face will be considered
• TargetFace - if specified, only widgets which are docked to the specified face on this widget will be considered

GetFocusedControl

native final function UIObject GetFocusedControl (optional bool bRecurse, optional int PlayerIndex) const

Retrieves the child of this widget which is current focused.

Parameters:

• bRecurse - if TRUE, returns the inner-most focused widget; i.e. the widget at the end of the focus chain
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated the focus change.

Returns:

a pointer to the child (either direct or indirect) widget which is in the focused state and is the focused control for its parent widget, or NULL if this widget doesn't have a focused control.

GetInputMask

native final noexportheader function byte GetInputMask (optional bool bInheritedMaskOnly, optional bool bOverrideMaskOnly) const

Gets the value of this widget's PlayerInputMask.

Parameters:

• bInheritedMaskOnly - specify TRUE to return only the mask that was set by this widget's owner scene.
• bOverrideMaskOnly - specify TRUE to return only the mask that was set manually for this widget.

GetInverseCanvasToScreen

native final function Object.Matrix GetInverseCanvasToScreen () const

Returns the inverse of the canvas to screen matrix.

GetLastFocusedControl

native final function UIObject GetLastFocusedControl (optional bool bRecurse, optional int PlayerIndex) const

Retrieves the child of this widget which last had focus.

Parameters:

• bRecurse - if TRUE, returns the inner-most previously focused widget; i.e. the widget at the end of the focus chain
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated the focus change.

Returns:

a pointer to the child (either direct or indirect) widget which was previously the focused control for its parent, or NULL if this widget doesn't have a LastFocusedControl

GetObjectCount

native final function int GetObjectCount () const

Returns the number of UIObjects owned by this UIScreenObject, recursively

Returns:

the number of widgets (including this one) contained by this widget, including all child widgets

GetPlayerOwner

native final function LocalPlayer GetPlayerOwner (optional int PlayerIndex)

Retrieves a reference to a LocalPlayer.

Parameters:

• PlayerIndex - if specified, returns the player at this index in the GamePlayers array. Otherwise, returns the player associated with the owner scene.

Returns:

the player that owns this scene or is located in the specified index of the GamePlayers array.

GetPlayerOwnerIndex

native final function int GetPlayerOwnerIndex (optional bool bRequireValidIndex) const

Get the index [into the Engine's GamePlayers array] for the player that owns this scene. Different from GetBestPlayerIndex() in that the index will always be that of the scene's owning player, and never the player that the scene last received input from.

Parameters:

• if - the scene doesn't have a player owner, specifying TRUE for this parameter will return the result of GetBestPlayerIndex().

Returns:

the index for the scene's owning player, or INDEX_NONE if the scene has no PlayerOwner and bRequireValidIndex is FALSE.

GetPosition

native final function float GetPosition (UIRoot.EUIWidgetFace Face, UIRoot.EPositionEvalType OutputType, optional bool bIncludeOrigin, optional bool bIgnoreDockPadding) const

Parameters:

• Face - indicates which face to change the position for
• OutputType - indicates the format of the returnedvalue EVALPOS_None: NewValue will be considered to be in whichever format is configured as the ScaleType for the specified face EVALPOS_PercentageOwner: EVALPOS_PercentageScene: EVALPOS_PercentageViewport: Indicates that return value is between 0.0 and 1.0, which represents the percentage of the corresponding base's actual size. EVALPOS_PixelOwner EVALPOS_PixelScene EVALPOS_PixelViewport Indicates that return value is an actual pixel value, relative to the corresponding base.
• bIncludeOrigin - specify TRUE to indicate that the viewport's origin should be included in the result (for retrieving absolute screen locations)
• bIgnoreDockPadding - used to prevent recursion when evaluting docking links

Returns:

the Position of a given face for this widget

GetPositionVector

native final function Object.Vector GetPositionVector (optional bool bIncludeParentPosition) const

Returns this widget's absolute normalized screen position as a vector.

Parameters:

• bIncludeParentPosition - if TRUE, coordinates returned will be absolute (relative to the viewport origin); if FALSE returned coordinates will be relative to the owning widget's upper left corner, if applicable.

GetSupportedPlayerCount

native final function int GetSupportedPlayerCount ()

Returns the maximum number of players that could potentially generate input for this scene. If the owning scene's input mode is INPUTMODE_Free, will correspond to the maximum number of simultaneous gamepads supported by this platform; otherwise, the number of active players.

GetViewportHeight

native final function float GetViewportHeight () const

Retrieves the height of the viewport this widget uses for rendering.

GetViewportOffset

native final function bool GetViewportOffset (out Object.Vector2D out_ViewportOffset) const

Retrieves the virtual viewport offset for the viewport which renders this widget's scene. Only relevant in the UI editor; non-zero if the user has panned or zoomed the viewport.

Parameters:

• out_ViewportOffset - out] will be filled in with the delta between the viewport's actual origin and virtual origin.

Returns:

TRUE if the viewport origin was successfully retrieved

GetViewportOrigin

native final function bool GetViewportOrigin (out Object.Vector2D out_ViewportOrigin) const

Retrieves the virtual origin of the viewport that this widget is rendered within. See additional comments in UISceneClient

In the game, this will be non-zero if Scene is for split-screen and isn't for the first player. In the editor, this will be equal to the value of the gutter region around the viewport.

Parameters:

• out_ViewportOrigin - out] will be filled in with the origin point for the viewport that owns this screen object

Returns:

TRUE if the viewport origin was successfully retrieved

GetViewportScale

native final function float GetViewportScale () const

Retrieves the scale factor for the viewport which renders this widget's scene. Only relevant in the UI editor.

GetViewportSize

native final function bool GetViewportSize (out Object.Vector2D out_ViewportSize) const

Retrieves the viewport size, accounting for split-screen.

Parameters:

• out_ViewportSize - out] will be filled in with the width & height of the viewport that owns this screen object

Returns:

TRUE if the viewport size was successfully retrieved

GetViewportWidth

native final function float GetViewportWidth () const

Retrieves the width of the viewport this widget uses for rendering.

GetWidgetPathName

native final noexport function string GetWidgetPathName ()

Returns a string representation of this widget's hierarchy. i.e. SomeScene.SomeContainer.SomeWidget

GetZDepth

native final noexportheader function float GetZDepth () const

Accessor for private variable.

Returns:

the current value of ZDepth for this widget.

HasActiveStateOfClass

native final noexport function bool HasActiveStateOfClass (class<UIState> StateClass, int PlayerIndex, optional out int StateIndex)

Determine whether there are any active states of the specified class

Parameters:

• StateClass - the class to search for
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this call
• StateIndex - if specified, will be set to the index of the last state in the list of active states that has the class specified

Returns:

TRUE if there is at least one active state of the class specified

Initialize

native final function virtual Initialize (UIScene inOwnerScene, optional UIObject InOwner)

Perform all initialization for this widget. Called on all widgets when a scene is opened, once the scene has been completely initialized. For widgets added at runtime, called after the widget has been inserted into its parent's list of children.

Parameters:

• inOwnerScene - the scene to add this widget to.
• inOwner - the container widget that will contain this widget. Will be NULL if the widget is being added to the scene's list of children.

InitializePlayerTracking

native final virtual function InitializePlayerTracking ()

Sets up the focus, input, and any other arrays which contain data that tracked uniquely for each active player. Ensures that the arrays responsible for managing focus chains are synched up with the Engine.GamePlayers array.

InsertChild

native function int InsertChild (UIObject NewChild, optional int InsertIndex, optional bool bRenameExisting)

Insert a widget at the specified location

Parameters:

• NewChild - the widget to insert
• InsertIndex - the position to insert the widget. If not specified, the widget is insert at the end of the list
• bRenameExisting - controls what happens if there is another widget in this widget's Children list with the same tag as NewChild. if TRUE, renames the existing widget giving a unique transient name. if FALSE, does not add NewChild to the list and returns FALSE.

Returns:

the position that that the child was inserted in, or INDEX_NONE if the widget was not inserted

InstanceUIPrefab

native final function UIPrefabInstance InstanceUIPrefab (UIPrefab SourcePrefab, optional name PrefabInstanceName, optional const out Object.Vector2D PlacementLocation, optional int InsertIndex, optional bool bRenameExisting)

Creates an instance of a UIPrefab and inserts it into this widget's Children array.

Parameters:

• SourcePrefab - the prefab to instance
• PrefabInstanceName - the name to use for the new prefab instance
• PlacementLocation - the screen location [in pixels, relative to 0,0 in canvas space] to place the UIPrefabInstance.
• InsertIndex - the position to insert the widget. If not specified, the widget is insert at the end of the list
• bRenameExisting - controls what happens if there is another widget in this widget's Children list with the same name as the new prefab (only relevant when specifying a value for PrefabInstanceName). if TRUE, renames the existing widget giving a unique transient name. if FALSE, does not add NewChild to the list and returns None.

Returns:

a UIPrefabInstance created from the specified UIPrefab.

InvalidateAllPositions

native final noexportheader function InvalidateAllPositions (optional bool bIgnoreDockedFaces)

Marks the position for all faces as out of sync with the RenderBounds values

Parameters:

• bIgnoreDockedFaces - indicates whether faces that are docked should be skipped

InvalidatePosition

native final noexportheader function InvalidatePosition (UIRoot.EUIWidgetFace Face)

Marks the position for the specified face as out of sync with the corresponding RenderBounds, as well as any faces in this or other widgets which are dependent on this face.

Parameters:

• Face - the face to modify; value must be one of the EUIWidgetFace values.

IsActive

native final noexport function bool IsActive (optional int PlayerIndex) const

Returns TRUE if this widget has a UIState_Active object in its StateStack and the state has been activated for the specified PlayerIndex.

Parameters:

• PlayerIndex - the index of the player to check

IsAnimationPaused

native final function bool IsAnimationPaused () const

Accessor for checking whether animations are currently paused.

Returns:

TRUE if animations are paused for this widget.

IsDisabled

native final noexport function bool IsDisabled (optional int PlayerIndex, optional bool bCheckOwnerChain) const

Returns TRUE if this widget has a UIState_Disabled object in its StateStack and the state has been activated for the specified PlayerIndex.

Parameters:

• PlayerIndex - the index of the player to check
• bCheckOwnerChain - by default, the owner chain is checked as well; specify FALSE to override this behavior.

IsEnabled

native final noexport function bool IsEnabled (optional int PlayerIndex, optional bool bCheckOwnerChain) const

Returns TRUE if this widget has a UIState_Enabled object in its StateStack and the state has been activated for the specified PlayerIndex.

Parameters:

• PlayerIndex - the index of the player to check
• bCheckOwnerChain - by default, the owner chain is checked as well; specify FALSE to override this behavior.

IsFocused

native final noexport function bool IsFocused (optional int PlayerIndex) const

Returns TRUE if this widget has a UIState_Focused object in its StateStack and the state has been activated for the specified PlayerIndex.

Parameters:

• PlayerIndex - the index of the player to check

IsHidden

native final noexportheader function bool IsHidden (optional bool bIncludeParents)

Accessor for private variable

Parameters:

• bIncludeParents - specify TRUE to check the visibility of parent widgets as well

Returns:

true if this object is hidden

IsHoldingAlt

native final virtual function bool IsHoldingAlt (int ControllerId)

Returns TRUE if the player associated with the specified ControllerId is holding the Alt key

Fixme: doesn't currently respect the value of ControllerId

IsHoldingCtrl

native final virtual function bool IsHoldingCtrl (int ControllerId)

Returns TRUE if the player associated with the specified ControllerId is holding the Ctrl key

Fixme: doesn't currently respect the value of ControllerId

IsHoldingShift

native final virtual function bool IsHoldingShift (int ControllerId)

Returns TRUE if the player associated with the specified ControllerId is holding the Shift key

Fixme: doesn't currently respect the value of ControllerId

IsInitialized

native final noexport function bool IsInitialized ()

Returns whether this screen object has been initialized.

IsNeverFocused

native final function bool IsNeverFocused () const

Getter for bNeverFocus

IsPressed

native final noexport function bool IsPressed (optional int PlayerIndex) const

Returns TRUE if this widget has a UIState_Pressed object in its StateStack and the state has been activated for the specified PlayerIndex.

Parameters:

• PlayerIndex - the index of the player to check

IsRuntimeInstance

native final noexportheader function bool IsRuntimeInstance () const

Determines whether this widget is contained a scene that has been instanced at runtime.

Retun: FALSE if this widget is contained in a scene from a content package; TRUE if this widget is contained within a scene that has been created from scratch or opened at runtime.

IsVisible

native final noexportheader function bool IsVisible (optional bool bIncludeParents)

Accessor for private variable

Parameters:

• bIncludeParents - specify TRUE to check the visibility of parent widgets as well

Returns:

true if this object is visible

KillFocus

native function bool KillFocus (UIScreenObject Sender, optional int PlayerIndex)

Deactivates the focused state for this widget.

Parameters:

• Sender - the control that called KillFocus.
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated the focus change.

NavigateFocus

native function bool NavigateFocus (UIScreenObject Sender, UIRoot.EUIWidgetFace Direction, optional int PlayerIndex, optional out byte bFocusChanged)

Sets focus to the widget bound to the navigation link for specified direction of the Sender. This function is used for navigation between controls in scenes that support unbound (i.e. any direction) navigation.

Parameters:

• Sender - Control that called NavigateFocus. Possible values are: - if NULL is specified, it indicates that this is the first step in a focus change. The widget will attempt to set focus to its most eligible child widget. If there are no eligible child widgets, this widget will enter the focused state and start propagating the focus chain back up through the Owner chain by calling SetFocus on its Owner widget. - if Sender is the widget's owner, it indicates that we are in the middle of a focus change. Everything else proceeds the same as if the value for Sender was NULL. - if Sender is a child of this widget, it indicates that focus has been successfully changed, and the focus is now being propagated upwards. This widget will now enter the focused state and continue propagating the focus chain upwards through the owner chain.
• Direction - the direction to navigate focus.
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated the focus change.
• bFocusChanged - will be set to true if we should play a sound as a result of this navigation; false otherwise.

Returns:

TRUE if the navigation event was handled successfully.

NextControl

native function bool NextControl (UIScreenObject Sender, optional int PlayerIndex)

Sets focus to the next control in the tab order (relative to Sender) for widget. If Sender is the last control in the tab order, propagates the call upwards to this widget's parent widget.

Parameters:

• Sender - the widget to use as the base for determining which control to focus next
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated the focus change.

Returns:

TRUE if we successfully set focus to the next control in tab order. FALSE if Sender was the last eligible child of this widget or we couldn't otherwise set focus to another control.

OverrideLastFocusedControl

native final function OverrideLastFocusedControl (int PlayerIndex, UIObject ChildToFocus)

Manually sets the last focused control for this widget; only necessary in cases where a particular child should be given focus but this widget (me) doesn't currently have focus. Setting the last focused control to the ChildToFocus will make it so that ChildToFocus is given focus the next time this widget does.

PauseAnimations

native final function PauseAnimations (bool bPauseAnimation)

Changes the value of bAnimationPaused

Parameters:

• bPauseAnimation - the new value for

PixelToCanvas

native final function Object.Vector PixelToCanvas (const out Object.Vector2D PixelPosition) const

Transforms a 2D screen coordinate into this widget's local space in canvas coordinates. In other words, converts a screen point into what that point would be on this widget if this widget wasn't rotated.

Parameters:

• PixelPosition - the position of the 2D point; a value from 0 - size of the viewport.

Returns:

a 2D screen coordinate corresponding to where PixelPosition would be if this widget was not rotated.

PixelToScreen

native final function Object.Vector4 PixelToScreen (const out Object.Vector2D PixelPosition) const

Transforms a vector from pixel (viewport pixels) space into screen (D3D device) space

Parameters:

• PixelPosition - a vector representing a location in viewport pixel space

Returns:

a vector representing that location in screen space.

PrevControl

native function bool PrevControl (UIScreenObject Sender, optional int PlayerIndex)

Sets focus to the previous control in the tab order (relative to Sender) for widget. If Sender is the first control in the tab order, propagates the call upwards to this widget's parent widget.

Parameters:

• Sender - the widget to use as the base for determining which control to focus next
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated the focus change.

Returns:

TRUE if we successfully set focus to the previous control in tab order. FALSE if Sender was the first eligible child of this widget or we couldn't otherwise set focus to another control.

Project

native final function Object.Vector Project (const out Object.Vector CanvasPosition) const

Converts a coordinate from this widget's local space (that is, tranformed by the widget's rotation) into a 2D viewport location, in pixels.

Parameters:

• CanvasPosition - a vector representing a location in widget local space.

Returns:

a coordinate representing a point on the screen in pixel space

RebuildNavigationLinks

native final virtual function bool RebuildNavigationLinks ()

Immediately rebuilds the navigation links between the children of this screen object and recalculates the child that should be the first & last focused control.

Returns:

TRUE if navigation links were created between any children of this widget.

RemoveChild

native final noexport function bool RemoveChild (UIObject ExistingChild, optional array<UIObject> ExclusionSet)

Remove an existing child widget from this widget's children

Parameters:

• ExistingChild - the widget to remove
• ExclusionSet - used to indicate that multiple widgets are being removed in one batch; useful for preventing references between the widgets being removed from being severed.

Returns:

TRUE if the child was successfully removed from the list, or if the child was not contained by this widget FALSE if the child could not be removed from this widget's child list.

Note: noexport because non-const optional arrays aren't exported correctly by the script compiler.

RemoveChildren

native final function array<UIObject> RemoveChildren (array<UIObject> ChildrenToRemove)

Removes a group of children from this widget's Children array. All removal notifications are delayed until all children have been removed; useful for removing a group of child widgets without destroying the references between them.

Parameters:

• ChildrenToRemove - the list of child widgets to remove

Returns:

a list of children that could not be removed; if the return array is emtpy, all children were successfully removed.

RemovePlayerData

native final virtual function RemovePlayerData (int PlayerIndex, LocalPlayer RemovedPlayer)

Called when a player has been removed from the list of active players (i.e. split-screen players)

Parameters:

• PlayerIndex - the index [into the GamePlayers array] where the player was located
• RemovedPlayer - the player that was removed

ReparentChild

native final function bool ReparentChild (UIObject CurrentChild, UIScreenObject NewParent, optional int InsertIndex)

Wrapper for removing a child from this widget in order to add it as a child of another widget in this scene

Parameters:

• CurrentChild - the widget that is being reparented
• NewParent - the widget that will be the new parent of the child
• InsertIndex - the position to insert the widget. If not specified, the widget is insert at the end of the list

Returns:

TRUE if reparented successfully. FALSE if any input parameters were invalid, or if the new parent wasn't in the same scene.

ReparentChildren

native final function bool ReparentChildren (array<UIObject> ChildrenToReparent, UIScreenObject NewParent, optional int InsertIndex)

Wrapper for removing a collection of children from this widget in order to add to another widget's children in this scene

Parameters:

• ChildrenToReparent - the widgets that are being reparented
• NewParent - the widget that will be the new parent of the child
• InsertIndex - the position to insert the widget. If not specified, the widget is insert at the end of the list

Returns:

TRUE if reparented successfully. FALSE if any input parameters were invalid, or if the new parent wasn't in the same scene.

ReplaceChild

native final function bool ReplaceChild (UIObject ExistingChild, UIObject NewChild)

Replace an existing child widget with the specified widget.

Parameters:

• ExistingChild - the widget to remove
• NewChild - the widget to replace ExistingChild with

Returns:

TRUE if the ExistingChild was successfully replaced with the specified NewChild; FALSE otherwise.

RequestFormattingUpdate

native final noexport function RequestFormattingUpdate ()

Flag the scene to refresh all string formatting at the beginning of the next tick.

RequestPrimitiveReview

native final noexport function RequestPrimitiveReview (bool bReinitializePrimitives, bool bReviewPrimitiveUsage)

Notifies the owning UIScene that the primitive usage in this scene has changed and sets flags in the scene to indicate that 3D primitives have been added or removed.

Parameters:

• bReinitializePrimitives - specify TRUE to have the scene detach all primitives and reinitialize the primitives for the widgets which have them. Normally TRUE if we have ADDED a new child to the scene which supports primitives.
• bReviewPrimitiveUsage - specify TRUE to have the scene re-evaluate whether its bUsesPrimitives flag should be set. Normally TRUE if a child which supports primitives has been REMOVED.

RequestSceneInputMaskUpdate

native final noexportheader function RequestSceneInputMaskUpdate ()

Flag the scene to recalculate its PlayerInputMask at the beginning of the next tick.

RequestSceneUpdate

native final noexport function RequestSceneUpdate (bool bDockingStackChanged, bool bPositionsChanged, bool bNavLinksOutdated, bool bWidgetStylesChanged)

Tell the scene that it needs to be udpated

Parameters:

• bDockingStackChanged - if TRUE, the scene will rebuild its DockingStack at the beginning the next frame
• bPositionsChanged - if TRUE, the scene will update the positions for all its widgets at the beginning of the next frame
• bNavLinksOutdated - if TRUE, the scene will update the navigation links for all widgets at the beginning of the next frame
• bWidgetStylesChanged - if TRUE, the scene will refresh the widgets reapplying their current styles

ScreenToCanvas

native final function Object.Vector ScreenToCanvas (const out Object.Vector4 ScreenPosition) const

Transforms a vector from screen (D3D device space) space into canvas (widget local) space

Parameters:

• ScreenPosition - a vector representing a location in screen space.

Returns:

a vector representing that location in screen space.

ScreenToPixel

native final function Object.Vector2D ScreenToPixel (const out Object.Vector4 ScreenPosition) const

Transforms a vector from screen (D3D device space) into pixel (viewport pixels) space.

Parameters:

• ScreenPosition - a vector representing a location in device space

Returns:

a vector representing that location in pixel space.

SetEnabled

native function bool SetEnabled (bool bEnabled, int PlayerIndex)

Attempts to set the object to the enabled/disabled state specified.

Parameters:

• bEnabled - Whether to enable or disable the widget.
• PlayerIndex - Player index to set the state for.

Returns:

TRUE if the operation was successful, FALSE otherwise.

SetFocus

native function bool SetFocus (UIScreenObject Sender, optional int PlayerIndex)

Activates the focused state for this widget and sets it to be the focused control of its parent (if applicable)

Parameters:

• Sender - Control that called SetFocus. Possible values are: - if NULL is specified, it indicates that this is the first step in a focus change. The widget will attempt to set focus to its most eligible child widget. If there are no eligible child widgets, this widget will enter the focused state and start propagating the focus chain back up through the Owner chain by calling SetFocus on its Owner widget. - if Sender is the widget's owner, it indicates that we are in the middle of a focus change. Everything else proceeds the same as if the value for Sender was NULL. - if Sender is a child of this widget, it indicates that focus has been successfully changed, and the focus is now being propagated upwards. This widget will now enter the focused state and continue propagating the focus chain upwards through the owner chain.
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated the focus change.

SetFocusToChild

native function bool SetFocusToChild (optional UIObject ChildToFocus, optional int PlayerIndex)

Sets focus to the specified child of this widget.

Parameters:

• ChildToFocus - the child to set focus to. If not specified, attempts to set focus to the most elibible child, as determined by navigation links and FocusPropagation values.
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated the focus change.

SetInputMask

native final noexportheader function SetInputMask (byte NewInputMask, optional bool bRecurse, optional bool bForcedOverride)

Changes the player input mask for this control, which controls which players this control will accept input from.

Parameters:

• NewInputMask - the new mask that should be assigned to this control
• bRecurse - if TRUE, calls SetInputMask on all child controls as well.
• bForcedOverride - indicates that the specified input mask should override any input mask inherited from the owning scene

SetPosition

native final function SetPosition (float NewValue, UIRoot.EUIWidgetFace Face, UIRoot.EPositionEvalType InputType, optional bool bIncludesViewportOrigin, optional bool bResolveChange)

Changes this widget's position to the specified value for the specified face.

Parameters:

• NewValue - the new value (in pixels or percentage) to use
• Face - indicates which face to change the position for
• InputType - indicates the format of the input value EVALPOS_None: NewValue will be considered to be in whichever format is configured as the ScaleType for the specified face EVALPOS_PercentageOwner: EVALPOS_PercentageScene: EVALPOS_PercentageViewport: Indicates that NewValue is a value between 0.0 and 1.0, which represents the percentage of the corresponding base's actual size. EVALPOS_PixelOwner EVALPOS_PixelScene EVALPOS_PixelViewport Indicates that NewValue is an actual pixel value, relative to the corresponding base.
• bIncludesViewportOrigin - TRUE indicates that the value is relative to the 0,0 on the screen (or absolute position); FALSE to indicate the value is relative to the viewport's origin.
• bResolveChange - indicates whether a scene update should be requested if NewValue does not match the current value.

SetZDepth

native final function SetZDepth (float NewZDepth, optional bool bPropagateToChildren)

Accessor for changing the value of ZDepth.

Parameters:

• NewZDepth - the ZDepth value to use.
• bPropagateToChildren - specify TRUE to set ZDepth on all child widgets to this value as well.

TickAnimations

native function TickAnimations (float DeltaTime)

Iterate over the AnimStack and tick each active sequence

Parameters:

• DeltaTime - How much time since the last call