UE3:UIObject (UT3)

Object >> UIRoot >> UIScreenObject >> UIObject

Package: 

Engine

Base class for all UI widgets.

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

Constants

FIRST_DEFAULT_DATABINDING_INDEX

Value: 100

used to differentiate tooltip bindings from others

TOOLTIP_BINDING_INDEX

Value: 100

CONTEXTMENU_BINDING_INDEX

Value: 101

Properties

Property group 'Data'

ContextMenuData

Type: UIRoot.UIDataStoreBinding

Modifiers: private, editconst

Default value:

Member	Value
RequiredFieldType	DATATYPE_Collection

ToolTip

Type: UIRoot.UIDataStoreBinding

Modifiers: private

The tool tip for this widget; only relevant for widgets that implement the UIDataStoreSubscriber interface.

Property group 'Debug'

bDebugShowBounds

Type: bool

Set to true to render an outline marking the widget's RenderBounds.

DebugBoundsColor

Type: Object.Color

if bRenderBoundingRegion is TRUE, specifies the color to use for this widget.

Default value:

Member	Value
A	255
B	255
G	128
R	255

Property group 'Focus'

NavigationTargets

Type: UIRoot.UINavigationData

Controls which widgets are given focus when this widget receives an event that changes the currently focused widget.

TabIndex

Type: int

Allows the designer to specify where this widget occurs in the bound (i.e. tab, shift+tab) navigation network of this widget's parent.

Default value: -1

Property group 'Presentation'

DockTargets

Type: UIRoot.UIDockingSet

Modifiers: editconst

The widgets that this widget should be docked to. For the 'right' and 'bottom' faces, if the widget has no dock target, it is considered docked to the 'left' and 'top' faces, respectively.

Default value:

Member	Value
TargetFace[0]	INVALID
TargetFace[1]	INVALID
TargetFace[2]	INVALID
TargetFace[3]	INVALID

RenderBounds

Type: float

Array size: 4 (EUIWidgetFace.UIFACE_MAX)

Modifiers: editconst, private, const, transient

Represents the bounding region available for the widget to render itself in. Set through the docking system.

RenderBoundsVertices

Type: Object.Vector2D

Array size: 4 (EUIWidgetFace.UIFACE_MAX)

Modifiers: editconst, private, const, transient

Represents the location of the corners of the widget including any tranforms, in absolute pixels (pixel space). Starts at the upper-left corner of the widget and goes clockwise.

RenderOffset

Type: Object.Vector

Screenspace offset to apply to the widget's rendering.

Rotation

Type: UIRoot.UIRotation

Rotation of the widget.

Default value:

Member	Value
AnchorPosition	Member Value ScaleType[0] EVALPOS_PixelOwner ScaleType[1] EVALPOS_PixelOwner
AnchorType	RA_Center

WidgetTag

Type: name

Modifiers: editconst

Unique non-localized name for this widget which is used to reference the widget without needing to know its GUID

Internal variables

AnimationParent

Type: UIObject

Used as the parent in animation sequences

AnimationPosition

Type: Object.Vector

Modifiers: transient

- The following is used in UTGame's UI animation system. - It is subject to change at any time.

AnimStack

Type: array<UIAnimation.UIAnimSeqRef>

Modifiers: transient

This is the stack of animations currently being applied to this UIObject

bEnableActiveCursorUpdates

Type: bool

Modifiers: private

Indicates that this widget should receive a call each tick with the location of the mouse cursor while it's the active control (NotifyMouseOver) (caution: slightly degrades performance)

bSupportsPrimaryStyle

Type: bool

Modifiers: const

Temp hack to allow widgets to remove "Primary Style" from the styles listed in the context menu for that widget if they no longer use it. Will be removed once I am ready to deprecate the PrimaryStyle property.

Default value: True

Owner

Type: UIObject

Modifiers: const, private, duplicatetransient

the UIObject that contains this widget in its Children array

OwnerScene

Type: UIScene

Modifiers: const, private, duplicatetransient

The scene that owns this widget

PrimaryStyle

Type: UIRoot.UIStyleReference

Specifies the style data to use for this widget

Default value:

Member	Value
DefaultStyleTag	'DefaultComboStyle'

PrivateFlags

Type: int

Modifiers: private

Stores a bitmask of flags which modify/define which operations may be performed to this widget (such as renaming, reparenting, selecting, etc.).

Valid behavior flags are defined in UIRoot.uc, as consts which begin with PRIVATE_

StyleSubscribers

Type: array<UIStyleResolver>

Modifiers: transient

List of objects/components contained by this widget which contain their own style references. When this widget's style is resolved, each element in this list will receive a notification to resolve its style references as well.

Elements should be added to this list either from the native InitializeStyleSubscribers method [for native classes], the Initialized event [for non-native classes], or the native PostEditChange method (when e.g. components are created or removed using the UI editor's property window).

You should NEVER add elements to this array using defaultproperties, since interface properties will not be updated to point to the subobject/component instance when this widget is created.

WidgetID

Type: UIRoot.WIDGET_ID

Modifiers: noimport

Unique identifier for this widget

Default values

Property	Value
EventProvider	UIComp_Event'WidgetEventComponent'

Subobjects

WidgetEventComponent

Class: Engine.UIComp_Event

Property	Value
DefaultEvents[0]	Member Value EventTemplate UIEvent_Initialized'Engine.Default__UIObject:WidgetInitializedEvent'

Delegates

OnClicked

delegate bool OnClicked (UIScreenObject EventObject, int PlayerIndex)

Called when the widget is no longer being pressed. Not implemented by all widget types.

The difference between this delegate and the OnPressRelease delegate is that OnClick will only be called on the widget that received the matching key press. OnPressRelease will be called on whichever widget was under the cursor when the key was released, which might not necessarily be the widget that received the key press.

Parameters:

• EventObject - Object that issued the event.
• PlayerIndex - Player that performed the action that issued the event.

Returns:

return TRUE to prevent the kismet OnClick event from firing.

OnCloseContextMenu

delegate bool OnCloseContextMenu (UIContextMenu ContextMenu, int PlayerIndex)

Called when the system wants to close the currently active context menu.

Parameters:

• ContextMenu - the context menu that is going to be closed
• PlayerIndex - the index of the player that generated the request for the context menu to be closed.

Returns:

TRUE to allow the specified context menu to be closed; FALSE to prevent the context menu from being closed. Note that there are certain situations where the context menu will be closed regardless of the return value, such as when the scene which owns the context menu is being closed.

OnContextMenuItemSelected

delegate OnContextMenuItemSelected (UIContextMenu ContextMenu, int PlayerIndex, int ItemIndex)

Called when the user selects a choice from a context menu.

Parameters:

• ContextMenu - the context menu that called this delegate.
• PlayerIndex - the index of the player that generated the event.
• ItemIndex - the index [into the context menu's MenuItems array] for the item that was selected.

OnCreate

delegate OnCreate (UIObject CreatedWidget, UIScreenObject CreatorContainer)

Called when this widget is created

Parameters:

• CreatedWidget - the widget that was created
• CreatorContainer - the container that created the widget

OnDoubleClick

delegate OnDoubleClick (UIScreenObject EventObject, int PlayerIndex)

Called when the widget has received a double-click input event. Not implemented by all widget types.

Parameters:

• EventObject - Object that issued the event.
• PlayerIndex - Player that performed the action that issued the event.

OnOpenContextMenu

delegate bool OnOpenContextMenu (UIObject Sender, int PlayerIndex, out UIContextMenu CustomContextMenu)

Called when the user right-clicks (or whatever input key is configured to activate the ShowContextMenu UI input alias) this widget. Provides a way for widgets to customize the context menu that is used or prevent the context menu from being shown entirely.

For script customization of the context menu, a custom context menu object must be assigned to the CustomContextMenu variable. It is possible to provide data for the context menu without creating or modifying any existing data stores. First, get a reference to the scene's default context menu (GetScene()->GetDefaultContextMenu()). Add the desired elements to the scene's data store then bind the context menu to that data field.

Parameters:

• Sender - the widget that will be displaying the context menu
• PlayerIndex - index of the player that generated the input event that triggered the context menu display.
• CustomContextMenu - to provide a custom tooltip implementation, fill in in this value and return TRUE. The custom context menu will then be activated by native code.

Returns:

return FALSE to prevent a context menu from being shown, including any from parent widgets. Return TRUE to indicate that the context menu for this widget can be displayed; if a value is not provided for CustomContextMenu, the default context menu will be displayed, using this widget's context menu data binding to generate the items.

OnPressed

delegate OnPressed (UIScreenObject EventObject, int PlayerIndex)

Called when this widget is pressed. Not implemented by all widget types.

Parameters:

• EventObject - Object that issued the event.
• PlayerIndex - Player that performed the action that issued the event.

OnPressRelease

delegate OnPressRelease (UIScreenObject EventObject, int PlayerIndex)

Called when the widget is no longer being pressed. Not implemented by all widget types.

Parameters:

• EventObject - Object that issued the event.
• PlayerIndex - Player that performed the action that issued the event.

OnPressRepeat

delegate OnPressRepeat (UIScreenObject EventObject, int PlayerIndex)

Called when the widget been pressed and the user is holding the button down. Not implemented by all widget types.

Parameters:

• EventObject - Object that issued the event.
• PlayerIndex - Player that performed the action that issued the event.

OnQueryToolTip

delegate bool OnQueryToolTip (UIObject Sender, out UIToolTip CustomToolTip)

Called when this widget (or one of its children) becomes the ActiveControl. Provides a way for child classes or containers to easily override or short-circuit the standard tooltip that is normally shown. If this delegate is not assigned to any function, the default tool-tip will be displayed if this widget has a data store binding property named "ToolTipBinding" which is bound to a valid data store.

Parameters:

• Sender - the widget that will be displaying the tooltip
• CustomToolTip - to provide a custom tooltip implementation, fill in in this value and return TRUE. The custom tool tip object will then be activated by native code.

Returns:

return FALSE to prevent any tool-tips from being shown, including parents.

OnRefreshSubscriberValue

delegate bool OnRefreshSubscriberValue (UIObject Sender, int BindingIndex)

Called when this widget receives a call to RefreshSubscriberValue.

Parameters:

• Sender - the widget that is refreshing their value
• BindingIndex - optional parameter for indicating which data store binding is being refreshed, for those objects which have multiple data store bindings. How this parameter is used is up to the class which implements this interface, but typically the "primary" data store will be index 0, while values greater than FIRST_DEFAULT_DATABINDING_INDEX correspond to tooltips and context menus.

Returns:

TRUE to indicate that this widget is going to refresh its value manually.

OnUIAnimEnd

delegate OnUIAnimEnd (UIObject AnimTarget, int AnimIndex, UIAnimationSeq AnimSeq)

If set, this delegate is called whenever an animation is finished

OnValueChanged

delegate OnValueChanged (UIObject Sender, int PlayerIndex)

Called when the value of this UIObject is changed. Only called for widgets that contain data values.

Parameters:

• Sender - the UIObject whose value changed
• PlayerIndex - the index of the player that generated the call to this method; used as the PlayerIndex when activating UIEvents; if not specified, the value of GetBestPlayerIndex() is used instead.

Functions

Native functions

See UIObject native functions.

Events

ClearUIAnimation

event ClearUIAnimation (name AnimName, optional UIAnimationSeq AnimSeq)

Clears the animation from the stack. Stopping an animation (either naturally or by force) doesn't remove the effects. In those cases you need to clear the animation from the stack.

NOTE: This only affects position and rotation animations. All other animations are destructive and can't be easilly reset.

Parameters:

• AnimName - The Name of the animation to play
• AnimSeq - Optional sequence to use. In case you don't know the name

PlayUIAnimation

event PlayUIAnimation (name AnimName, optional UIAnimationSeq AnimSeqTemplate, optional float PlaybackRate, optional bool bLoop, optional float InitialPosition)

Play an animation on this UIObject

Parameters:

• AnimName - The Name of the Animation to play
• AnimSeq - Optional, A Sequence Template. If that's set, we use it instead
• PlaybackRate - Optional, How fast to play back the sequence
• InitialPosition - Optional, Where in the sequence should we start

StopUIAnimation

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

Stop an animation that is playing.

Parameters:

• AnimName - The Name of the animation to play
• AnimSeq - Optional sequence to use. In case you don't know the name
• bFinalize - If true, we will force the end frame

UIAnimEnd

event UIAnimEnd (int SeqIndex)

AnimEnd is always called when an animation stops playing either by ending, or when StopAnim is called on it. It's responsible for unsubscribing from the scene client and performing any housekeeping

Other instance functions

GetOwner

final function UIObject GetOwner ()

Returns the owner of this widget

GetParent

function UIScreenObject GetParent ()

Overrides: UIScreenObject.GetParent

Returns the scene or widget that contains this widget in its Children array.

GetScene

final function UIScene GetScene ()

Returns the scene that owns this widget

LogRenderBounds

function LogRenderBounds (int Indent)

OnSetDatastoreBinding

function OnSetDatastoreBinding (UIAction_SetDatastoreBinding Action)

Kismet Action Handlers