UE3:UIScene (UT3)

Object >> UIRoot >> UIScreenObject >> UIScene

Package: 

Engine

Direct subclasses:

UIPrefabScene, UIScriptConsoleScene, UTUIScene

This class in other games:

UDK

Outermost container for a group of widgets. The relationship between UIScenes and widgets is very similar to the relationship between maps and the actors placed in a map, in that all UIObjects must be contained by a UIScene. Widgets cannot be rendered directly.

Copyright 1998-2008 Epic Games, Inc. All Rights Reserved.

Properties

Property group 'Flags'

bAlwaysRenderScene

Type: bool

Overrides the setting of bRenderParentScenes for any scenes higher in the stack

bCloseOnLevelChange

Type: bool

Indicates whether the the scene should close itself when the level changes. This is useful for when you have a main menu and want to make certain it is closed when ever you switch to a new level.

Default value: True

bDisableWorldRendering

Type: bool

Displayed as: Disable World Rendering

TRUE to disable world rendering while this scene is active

bDisplayCursor

Type: bool

Controls whether the cursor is shown while this scene is active. Interactive scenes such as menus will generally want this enabled, while non-interactive scenes, such as the HUD generally want it disabled.

Todo: this bool may be unnecessary, since we can establish whether a scene should process mouse input by looking at the input events for the widgets of this scene; if any process any of the mouse keys (MouseX, MouseY, RMB, LMB, MMB, etc.) or if the scene can be a drop target, then this scene needs to process mouse input, and should probably display a cursor.... hmmm need to think about this assumption a bit more before implementing this

Default value: True

bEnableSceneDepthTesting

Type: bool

Controls whether depth testing is enabled for this scene. If TRUE then the 2d ui items are depth tested against the 3d ui scene

bEnableScenePostProcessing

Type: bool

Controls whether post-processing is enabled for this scene.

bExemptFromAutoClose

Type: bool

If true this scene is exempted from Auto closuer when a scene above it closes

bFlushPlayerInput

Type: bool

Displayed as: Flush Input

TRUE to flush all player input when this scene is opened.

Default value: True

bMenuLevelRestoresScene

Type: bool

TRUE indicates that this scene can be automatically reopened when the user returns to the main front-end menu.

bPauseGameWhileActive

Type: bool

Indicates whether the game should be paused while this scene is active.

Default value: True

bRenderParentScenes

Type: bool

Controls whether the scenes underneath this scene are rendered.

bRequiresNetwork

Type: bool

TRUE to indicate that this scene requires a valid network connection in order to be opened. If no network connection is available, the scene will be closed.

bRequiresOnlineService

Type: bool

Set to TRUE to indicate that the user must be signed into an online service (for example, Windows live) in order to view this scene. If the user is not signed into an online service, the scene will be closed.

bSaveSceneValuesOnClose

Type: bool

Indicates whether the scene should have its widgets save their values to the datastore on close.

Default value: True

Property group 'Overlays'

DefaultContextMenuClass

Type: class<UIContextMenu>

Modifiers: const

The UIContextMenu class to use for the StandardContextMenu

Default value: Class'Engine.UIContextMenu'

DefaultToolTipClass

Type: class<UIToolTip>

Modifiers: const

The UIToolTip class to use for the StandardToolTip

Default value: Class'Engine.UIToolTip'

Property group 'Sound'

SceneClosedCue

Type: name

this sound is played when this scene is deactivated

Default value: 'SceneClosed'

SceneOpenedCue

Type: name

this sound is played when this scene is activated

Default value: 'SceneOpened'

Property group 'Splitscreen'

SceneInputMode

Type: UIRoot.EScreenInputMode

Controls how this scene responds to input from multiple players.

Default value: INPUTMODE_Locked

SceneRenderMode

Type: UIRoot.ESplitscreenRenderMode

Controls how this scene will be rendered when split-screen is active.

Default value: SPLITRENDER_PlayerOwner

Property group 'UIScene'

MouseBounds

Type: UIRoot.UIMouseBounds

The boundaries with which to restrict mouse movement in this scene

Default value:

Member	Value
bFullscreenOnly	True
Value[2]	1.0
Value[3]	1.0

SceneTag

Type: name

Semi-unique non-localized name for this scene which is used to reference the scene from unrealscript. For scenes which are gametype specific, each scene may wish to use the same SceneName (for example, if each game had a single scene which represented the HUD for that gametype, all of the HUD scenes might use "HUDScene" as their SceneName, so that the current game's HUD scene can be referenced using "HUDScene" regardless of which type of hud it is)

Internal variables

ActiveContextMenu

Type: UIContextMenu

Modifiers: const, transient, private

The context menu currently being displayed or pending display.

ActiveToolTip

Type: UIToolTip

Modifiers: const, transient, private

The tool tip currently being displayed or pending display.

bIssuedPreRenderCallback

Type: bool

Modifiers: transient

This flag is used to detect whether or not we are updating the scene for the first time, if it is FALSE and update scene is called, then we issue the PreRenderCallback for the scene so widgets have a chance to 'initialize' their positions if desired.

bMouseBoundsSet

Type: bool

Modifiers: const

Used to determine whether or not the mouse boundaries have been set

bRefreshStringFormatting

Type: bool

Modifiers: transient

Indicates that all strings contained in this scene should be reformatted.

bRefreshWidgetStyles

Type: bool

Modifiers: transient

Indicates that the Widgets displayed need to be redrawn. Once this is set to true, RefreshWidgets() will be called on the next Tick()

bResolvingScenePositions

Type: bool

Modifiers: transient, const

Indicates that the scene is currently resolving positions for widgets in this scene

bUpdateDockingStack

Type: bool

Modifiers: transient

Indicates that the docking stack should be rebuilt on the next Tick()

bUpdateNavigationLinks

Type: bool

Modifiers: transient

Indicates that the navigation links between the widgets owned by this scene are no longer up to date. Once this is set to true, RebuildNavigationLinks() will be called on the next Tick()

bUpdatePrimitiveUsage

Type: bool

Modifiers: transient

Indicates that the value of bUsesPrimitives is potentially out of date. Normally set when a child is added or removed from the scene. When TRUE, UpdatePrimitiveUsage will be called during the next tick.

bUpdateScenePositions

Type: bool

Modifiers: transient

Indicates that the widgets owned by this scene should re-evaluate their screen positions into absolute pixels on the next Tick().

bUsesPrimitives

Type: bool

Modifiers: transient, const

Indicates that one or more widgets in this scene are using 3D primitives. Set to TRUE in Activate() if any children of this scene have true for UIScreenObject.bSupports3DPrimitives

CurrentViewportSize

Type: Object.Vector2D

The current aspect ratio for this scene's viewport. For scenes modified in the UI editor, this will be set according to the value of the resolution drop-down control. In game, this will be updated anytime the resolution is changed.

Default value:

Member	Value
X	1024.0
Y	768.0

DockingStack

Type: array<UIRoot.UIDockingNode>

Modifiers: const, transient, native, private

Tracks the docking relationships between widgets owned by this scene. Determines the order in which the UIObject.Position values for each widget in the sceen are evaluated into UIObject.RenderBounds

Note: this variable is not serialized (even by GC) as the widget stored in this array will be serialized through the Children array.

InputSubscriptions

Type: Object.Map_Mirror{TMap< FName, TArray<struct FInputEventSubscription> >}

Modifiers: const, transient, native

Tracks the widgets owned by this scene which are currently eligible to process input. Maps the input keyname to the list of widgets that can process that event.

Note: this variable is not serialized (even by GC) as the widgets stored in this map will be serialized through the Children array

LastPlayerIndex

Type: int

Modifiers: transient

The index for the player that this scene last received input from.

PlayerOwner

Type: LocalPlayer

Modifiers: const, transient

The LocalPlayer which owns this scene. NULL if this scene is global (i.e. not owned by a player)

RenderStack

Type: array<UIObject>

Modifiers: const, transient, private

Tracks the order in which widgets were rendered, for purposes of hit detection.

SceneClient

Type: UISceneClient

Modifiers: const, transient

the client for this scene - provides all global state information the scene requires for operation

SceneData

Type: SceneDataStore

Modifiers: const, instanced

The data store that provides access to this scene's temporary data

SceneLayerRoot

Type: UILayerBase

Modifiers: editoronly, const, private, transient

The root of the layer hierarchy for this scene; only loaded in the editor.

Todo: ronp - temporarily marked this transient until I can address the bugs in layer browser which are holding references to deleted objects (also commented out the creation of the layer browser).

ScenePreview

Type: Texture2D

Modifiers: editoronly

Preview thumbnail for the generic browser.

StandardContextMenu

Type: UIContextMenu

Modifiers: const, transient, private

This context menu will be used as the context menu for widgets which do not provide their own

StandardToolTip

Type: UIToolTip

Modifiers: const, transient, private

This tooltip widget will be used to display tooltips for widgets which do not provide custom tool-tip widgets.

Default values

Property	Value
DefaultStates[2]	Class'Engine.UIState_Focused'
DefaultStates[3]	Class'Engine.UIState_Active'
EventProvider	UIComp_Event'SceneEventComponent'

Subobjects

SceneEventComponent

Class: Engine.UIComp_Event

Property	Value
DefaultEvents[0]	Member Value EventTemplate UIEvent_Initialized'Engine.Default__UIScene:SceneInitializedEvent'
DefaultEvents[1]	Member Value EventTemplate UIEvent_SceneActivated'Engine.Default__UIScene:SceneActivatedEvent'
DefaultEvents[2]	Member Value EventTemplate UIEvent_SceneDeactivated'Engine.Default__UIScene:SceneDeactivatedEvent'
DefaultEvents[3]	Member Value EventTemplate UIEvent_OnEnterState'Engine.Default__UIScene:EnteredStateEvent'
DefaultEvents[4]	Member Value EventTemplate UIEvent_OnLeaveState'Engine.Default__UIScene:LeftStateEvent'

Delegates

GetSceneInputMode

delegate UIRoot.EScreenInputMode GetSceneInputMode ()

Returns the screen input mode configured for this scene

OnSceneActivated

delegate OnSceneActivated (UIScene ActivatedScene, bool bInitialActivation)

Allows others to be notified when this scene becomes the active scene. Called after other activation methods have been called and after focus has been set on the scene

Parameters:

• ActivatedScene - the scene that was activated
• bInitialActivation - TRUE if this is the first time this scene is being activated; FALSE if this scene has become active as a result of closing another scene or manually moving this scene in the stack.

OnSceneDeactivated

delegate OnSceneDeactivated (UIScene DeactivatedScene)

Allows others to be notified when this scene is closed. Called after the SceneDeactivated event, after the scene has published its data to the data stores bound by the widgets of this scene.

Parameters:

• DeactivatedScene - the scene that was deactivated

OnTopSceneChanged

delegate OnTopSceneChanged (UIScene NewTopScene)

This notification is sent to the topmost scene when a different scene is about to become the topmost scene. Provides scenes with a single location to perform any cleanup for its children.

Parameters:

• NewTopScene - the scene that is about to become the topmost scene.

Note: this delegate is called while this scene is still the top-most scene.

ShouldModulateBackgroundAlpha

delegate bool ShouldModulateBackgroundAlpha (out float AlphaModulationPercent)

Provides scenes with a way to alter the amount of transparency to use when rendering parent scenes.

Parameters:

• AlphaModulationPercent - the value that will be used for modulating the alpha when rendering the scene below this one.

Returns:

TRUE if alpha modulation should be applied when rendering the scene below this one.

Functions

Native functions

ForceImmediateSceneUpdate

native final noexport function ForceImmediateSceneUpdate ()

Triggers an immediate full scene update (rebuilds docking stacks if necessary, resolves scene positions if necessary, etc.); scene updates normally occur at the beginning of each scene's Tick() so this function should only be called if you must change the positions and/or formatting of a widget in the scene after the scene has been ticked, but before it's been rendered.

Note: noexport because this simply calls through to the C++ UpdateScene().

GetActiveContextMenu

native final function UIContextMenu GetActiveContextMenu () const

Returns the scene's currently active context menu, if there is one.

GetActiveToolTip

native final function UIToolTip GetActiveToolTip () const

Returns the scene's currently active tool-tip, if there is one.

GetDefaultContextMenu

native final function UIContextMenu GetDefaultContextMenu ()

Returns the scene's default context menu widget, creating one if necessary.

GetDefaultToolTip

native final function UIToolTip GetDefaultToolTip ()

Returns the scene's default tooltip widget, creating one if necessary.

GetPreviousScene

native final function UIScene GetPreviousScene (bool bRequireMatchingPlayerOwner)

Returns the scene that is below this one in the scene client's stack of active scenes.

Parameters:

• bRequireMatchingPlayerOwner - TRUE indicates that only a scene that has the same value for PlayerOwner as this scene may be considered the "previous" scene to this one

GetSceneDataStore

native final function SceneDataStore GetSceneDataStore ()

Gets the data store for this scene, creating one if necessary.

GetWorldInfo

native function WorldInfo GetWorldInfo ()

Returns the current WorldInfo

IsSceneActive

native final function bool IsSceneActive (optional bool bTopmostScene) const

Wrapper for easily determining whether this scene is in the scene client's list of active scenes.

Parameters:

• bTopmostScene - specify TRUE to check whether the scene is also the scene client's topmost scene.

LoadSceneDataValues

native final function LoadSceneDataValues ()

Notifies all children that are bound to readable data stores to retrieve their initial value from those data stores.

RebuildDockingStack

native final function RebuildDockingStack ()

Clears and rebuilds the complete DockingStack. It is not necessary to manually rebuild the DockingStack when simply adding or removing widgets from the scene, since those types of actions automatically updates the DockingStack.

ResetMouseBounds

native final function ResetMouseBounds ()

Reset the 'MouseBounds' struct to its default values

ResolveDataStore

native final function UIDataStore ResolveDataStore (name DataStoreTag, optional LocalPlayer InPlayerOwner)

Find the data store that has the specified tag. If the data store's tag is SCENE_DATASTORE_TAG, the scene's data store is returned, otherwise searches through the global data stores for a data store with a Tag matching the specified name.

Parameters:

• DataStoreTag - A name corresponding to the 'Tag' property of a data store
• InPlayerOwner - The player owner to use for resolving the datastore. If NULL, the scene's playerowner will be used instead.

Returns:

a pointer to the data store that has a Tag corresponding to DataStoreTag, or NULL if no data were found with that tag.

ResolveScenePositions

native final function ResolveScenePositions ()

Iterates through the scene's DockingStack, and evaluates the Position values for each widget owned by this scene into actual pixel values, then stores that result in the widget's RenderBounds field.

SaveSceneDataValues

native final function SaveSceneDataValues (optional bool bUnbindSubscribers)

Notifies all children of this scene that are bound to writable data stores to publish their values to those data stores.

Parameters:

• bUnbindSubscribers - if TRUE, all data stores bound by widgets and strings in this scene will be unbound.

SetActiveContextMenu

native final function bool SetActiveContextMenu (UIContextMenu NewContextMenu, int PlayerIndex)

Changes the scene's ActiveContextMenu to the one specified.

Parameters:

• NewContextMenu - the new context menu to activate, or NULL to clear any active context menus.
• PlayerIndex - the index of the player to display the context menu for.

Returns:

TRUE if the scene's ActiveContextMenu was successfully changed to the new value.

SetActiveToolTip

native final function bool SetActiveToolTip (UIToolTip NewToolTip)

Changes the scene's ActiveToolTip to the one specified.

SetMouseBounds

native final function SetMouseBounds (UIRoot.EUIWidgetFace Face, optional float Value, optional bool bPixelValue, optional UIObject BoundaryObject)

Modifies the scenes mouse boundaries during runtime.

Parameters:

• Face - the side of the scene which the boundary will be applied to
• Value - the value (in either pixels or percentage) of the current boundary
• bPixelValue - if true, 'Value' will be interpreted as a raw pixel value
• BoundaryObject - if set, Value/bPixelValue will be ignored and the mouse boundaries will be set based upon the input object

SetSceneInputMode

native final function SetSceneInputMode (UIRoot.EScreenInputMode NewInputMode)

Changes the screen input mode for this scene.

UnbindSubscribers

native final function UnbindSubscribers ()

Makes all the widgets in this scene unsubscribe from their bound datastores.

Events

CalculateInputMask

final event CalculateInputMask ()

Determines the appropriate PlayerInput mask for this scene, based on the scene's input mode.

LogDockingStack

event LogDockingStack ()

SceneActivated

event SceneActivated (bool bInitialActivation)

Called just after the scene is added to the ActiveScenes array, or when this scene has become the active scene as a result of closing another scene.

Parameters:

• bInitialActivation - TRUE if this is the first time this scene is being activated; FALSE if this scene has become active as a result of closing another scene or manually moving this scene in the stack.

SceneDeactivated

event SceneDeactivated ()

Called just after this scene is removed from the active scenes array

SetInputMask

event SetInputMask (byte NewInputMask, optional bool bRecurse)

Overrides: UIScreenObject.SetInputMask

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.

SetVisibility

event SetVisibility (bool bIsVisible)

Overrides: UIScreenObject.SetVisibility

Changes whether this widget is visible or not. Should be overridden in child classes to perform additional logic or abort the visibility change.

Parameters:

• bIsVisible - TRUE if the widget should be visible; false if not.

Other instance functions

AnimEnd

function AnimEnd (UIObject AnimTarget, int AnimIndex, UIAnimationSeq AnimSeq)

CloseScene

function bool CloseScene (UIScene SceneToClose, optional bool bSkipKismetNotify, optional bool bSkipAnimation)

Closes the specified scene.

Parameters:

• SceneToClose - Scene that we want to close.
• bSkipKismetNotify - Whether or not to close the kismet notify for the scene.
• bSkipAnimation - Whether or not to skip the close animation for this scene.

LogCurrentState

function LogCurrentState (int Indent)

Overrides: UIScreenObject.LogCurrentState

LogRenderBounds

function LogRenderBounds (int Indent)

NotifyGameSessionEnded

function NotifyGameSessionEnded ()

Called when the current map is being unloaded. Cleans up any references which would prevent garbage collection.

NotifyLinkStatusChanged

function NotifyLinkStatusChanged (bool bConnected)

Called when the status of the platform's network connection changes.

NotifyOnlineServiceStatusChanged

function NotifyOnlineServiceStatusChanged (OnlineSubsystem.EOnlineServerConnectionStatus NewConnectionStatus)

Notification that the player's connection to the platform's online service is changed.

OpenScene

function UIScene OpenScene (UIScene SceneToOpen, optional bool bSkipAnimation, optional delegate<OnSceneActivated> SceneDelegate)

Opens a UI Scene given a reference to a scene to open.

Parameters:

• SceneToOpen - Scene that we want to open.
• bSkipAnimation - specify TRUE to indicate that opening animations should be bypassed.
• SceneDelegate - if specified, will be called when the scene has finished opening.

SceneCreated

function SceneCreated (UIScene CreatedScene)

Default handler for the OnCreateScene delegate