UE3:UICalloutButtonPanel (UDK)

Object >> UIRoot >> UIScreenObject >> UIObject >> UIContainer >> UICalloutButtonPanel

Package: 

Engine

Container for a list of UICalloutButtons which handle navigation between scenes as well as activating special functionality in the scene. Each button is associated with a particular key or alias; the button's associated key is used to lookup the display text and optionally an image of the keyboard or gamepad key required to activate the button.

There are two ways to add buttons to a callout panel - via the panel's CalloutButtonAliases array, and adding new buttons dynamically at runtime. Any buttons added from code dynamically in the editor will be automatically published to the persistent tag array (CalloutButtonAliases) and will be part of the button panel anytime an instance of one is created.

The UIButtonCalloutPanel provides methods for adding, removing, positioning, or modifying the associated key for any button.

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

Properties

Property group 'Appearance'

ButtonBarOrientation

Type: UIRoot.EUIOrientation

Determines whether the button bar lays out its buttons vertically or horizontally.

ButtonLayout

Type: ECalloutButtonLayoutType

Determines how the buttons will be positioned within this panel

Default value: CBLT_DockRight

ButtonPadding

Type: UIRoot.UIScreenValue_Extent

Array size: 2 (EUIOrientation.UIORIENT_MAX)

The amount of padding to apply to this panel's buttons.

Default value, index 1:

Member	Value
Orientation	UIORIENT_Vertical

Property group 'Interaction'

bSupportsButtonRepeat

Type: bool

Indicates that the buttons in the panel should react to button press and repeat events, rather than release events

Property group 'ZDebug'

bRefreshButtonDocking

Type: bool

Modifiers: private, transient

Indicates that the panel should recalculate the docking between all buttons before the next tick.

ButtonTemplate

Type: UICalloutButton

Modifiers: editinline, editconst, duplicatetransient

the button template to use when creating child button instances for this panel

Default value: UICalloutButton'Engine.Default__UICalloutButtonPanel:CalloutButtonTemplate'

CalloutButtons

Type: array<UICalloutButton>

Modifiers: editinline, editconst, transient

The list of all buttons currently contained by this callout panel, whether generated based on this object's data store binding, or added dynamically at runtime. Although the buttons would be in the panel's Children array, this separate array provides quick and easy access to the buttons without the need for casting to UICalloutButton everywhere.

Internal variables

bGeneratingInitialButtons

Type: bool

Modifiers: transient

Prevents the ConfigureChildButton function from calling SetupDockingRelationships. Used when populating the initial list of buttons from the CalloutButtonAliases array (since we want to wait until all buttons have been added before setting up docking).

ButtonInputKeyMappings

Type: Map{FName,FName}

Modifiers: native, const, transient

Runtime mapping of input key name => button alias name; updated when buttons call Un/SubscribeToInputProxy; used to quickly lookup the button input alias associated with an input key when an input event occurs.

Fixme: doesn't support multiple players correctly

CalloutButtonAliases

Type: array<name>

Modifiers: config

The array of button string aliases used for generating the buttons in this panel.

Default values

Property	Value
bNeverFocus	True
DockTargets	Member Value bLockHeightWhenDocked True bLockWidthWhenDocked True
Position	Member Value Value[1] 0.95 Value[3] 0.05
PrimaryStyle	Member Value DefaultStyleTag 'DefaultImageStyle' RequiredStyleClass Class'Engine.UIStyle_Image'
PrivateFlags	1024

Subobjects

WidgetEventComponent

Class: Engine.UIComp_Event

Inherits from: UIContainer.WidgetEventComponent

No new values.

Enums

ECalloutButtonLayoutType

Different button layout types

CBLT_None 

buttons are auto-sized to fit their contents, but button positions are not adjusted unless they overlap

CBLT_DockLeft 

(Dock Left in UnrealEd) button are auto-sized to fit their contents, and docked to the left side of the panel

CBLT_DockRight 

(Dock Right in UnrealEd) button are auto-sized to fit their contents, and docked to the right side of the panel

CBLT_Centered 

(Centered in UnrealEd) buttons are auto-sized to fit their contents, then centered in the panel

CBLT_Justified 

(Spaced Evenly in UnrealEd) buttons are evenly spaced out in the panel

Functions

Native functions

CreateCalloutButton

native function UICalloutButton CreateCalloutButton (name ButtonInputAlias, optional name ButtonName, optional bool bInsertChild)

Create a new callout button and give it the specified input alias tag.

Parameters:

• ButtonInputAlias - the input alias to assign to the button (i.e. Accept, Cancel, Conditional1, etc.); this tag will be used to generate the button's data store markup.
• ButtonName - allows the caller to specify a name to use when creating the button.
• bInsertChild - if TRUE is specified, the newly created button will also be added to this panel's Children array, using the index provided by calling GetBestInsertionIndex().

Returns:

an instance of a new UICalloutButton which has ButtonInputAlias as its InputAliasTag.

FindBestInsertionIndex

native function int FindBestInsertionIndex (UICalloutButton ButtonToInsert, optional bool bSearchChildrenArray)

Finds the most appropriate position to insert the specified button, based on its InputAliasTag. Only relevant if this button's InputAliasTag is contained in the CalloutButtonAliases array.

Parameters:

• ButtonToInsert - the button that will be inserted into the panel
• bSearchChildren - specify TRUE to search for the best insertion index into the Children array, rather than the CalloutButtonAliases array.

Returns:

index [into the Children or CalloutButtons array] for the position to insert the button, or INDEX_NONE if the button's InputAliasTag is not contained in the CalloutButtonAliases array (meaning that it's a dynamic button)

GetAvailableCalloutButtonAliases

native final function GetAvailableCalloutButtonAliases (out array<name> AvailableAliases, optional LocalPlayer PlayerOwner)

Retrieves the list of callout button input aliases which are available for use in the specified button panel.

Parameters:

• AvailableAliases - receives the list of callout button aliases which aren't in use by this button panel.
• PlayerOwner - specifies the player that should be used for looking up the ButtonCallouts datastore; relevant when one player is using a gamepad and another is using a keyboard, for example.

GetCalloutInputProxy

native final function UIEvent_CalloutButtonInputProxy GetCalloutInputProxy (optional bool bCreateIfNecessary)

Returns a reference to the input proxy for this button's scene.

Parameters:

• bCreateIfNecessary - specify TRUE to have an input proxy created for you if it doesn't exist. Future calls to this function would then return that proxy.

Returns:

a reference to the button bar input proxy used by this button's owner scene.

RequestButtonDockingUpdate

native final function RequestButtonDockingUpdate (optional bool bImmediately)

Request that the docking relationships between the panel's buttons be updated at the beginning of the next scene update. Calling this method will trigger a scene update as well.

Parameters:

• bImmediately - specify TRUE to have the docking updated immediately rather than waiting until the next scene update. A scene update will then only be triggered if any docking relationships changed.

Events

AddedChild

event AddedChild (UIScreenObject WidgetOwner, UIObject NewChild)

Overrides: UIScreenObject.AddedChild

Called immediately after a child has been added to this screen object.

Parameters:

• WidgetOwner - the screen object that the NewChild was added as a child for
• NewChild - the widget that was added

CanButtonAcceptFocus

event bool CanButtonAcceptFocus (name InputAliasTag, optional int PlayerIndex)

Wrapper for easily determining whether the specified button should be able to process input.

Parameters:

• InputAliasTag - the input alias tag (i.e. Conditional1, Accept, Cancel, etc.) used by the button to be found.
• PlayerIndex - index into the Engine.GamePlayers array; unless the scene is configured to allow any player to interact with any widget, filters out any buttons which are associated with players other than the one indicated by this value.

Returns:

TRUE if the specified button is visible and enabled; FALSE if this panel doesn't contain the button or it isn't currently able to accept focus

ContainsButton

event bool ContainsButton (name ButtonInputAlias)

Wrapper for easily determining whether this panel contains a button associated with the specified input key.

Parameters:

• ButtonInputAlias - the input alias tag (i.e. Conditional1, Accept, Cancel, etc.) used by the button to be found.

Returns:

TRUE if this panel contains the specified button.

EnableButton

event bool EnableButton (name ButtonInputAlias, optional int PlayerIndex, optional bool bEnableButton, optional bool bUpdateButtonVisibility)

Wrapper for changing the enabled state of the specified button

Parameters:

• ButtonInputAlias - the input alias tag (i.e. Conditional1, Accept, Cancel, etc.) used by the button to be found.
• bEnableButton - indicates whether the button should be enabled or disabled.
• bUpdateButtonVisibility - indicates that the button's visibility should be updated (if being enabled, show the button; if being disabled, hide the button).

Returns:

TRUE if the button's enabled state was set successfully.

FindButton

event UICalloutButton FindButton (name ButtonInputAlias)

Returns a reference to the button associated with the input key.

Parameters:

• ButtonInputAlias - the input alias tag (i.e. Conditional1, Accept, Cancel, etc.) used by the button to be found.

Returns:

the button assocated with the specifed input key, or None if no buttons are associated with that input key.

FindButtonIndex

event int FindButtonIndex (name ButtonInputAlias)

Find the index [into the CalloutButtons array] for the specified button.

Parameters:

• ButtonInputAlias - the input alias tag (i.e. Conditional1, Accept, Cancel, etc.) used by the button to be found.

Returns:

the index for the button assocated with the specifed input key, or INDEX_NONE if no buttons are associated with that input key.

InsertButton

event int InsertButton (UICalloutButton NewButton)

Adds a new button to this callout panel.

Parameters:

• NewButton - the button to add

Returns:

the index where the button was actually inserted, or INDEX_NONE if it couldn't be inserted. not yet implemented (possible that this method will be changed to take the button's input key rather than a reference to the button itself).

PostInitialize

event PostInitialize ()

Overrides: UIScreenObject.PostInitialize

Called after this screen object's children have been initialized. While the Initialized event is only called when a widget is initialized for the first time, PostInitialize() will be called every time this widget receives a call to Initialize(), even if the widget was already initialized. Examples would be reparenting a widget.

RemoveAllButtons

event bool RemoveAllButtons ()

Remove all buttons from the button bar.

Returns:

TRUE if all buttons were successfully removed.

RemoveButton

event bool RemoveButton (UICalloutButton ButtonToRemove)

Removes the specified button from the CalloutButtons array (as well as the Children array).

Parameters:

• ButtonToRemove - reference to the button that should be removed.

Returns:

TRUE if the button was successfully removed.

Todo: should we provide an option for allowing the user to control whether this button's alias is removed from the CalloutButtonAliases map?

RemoveButtonByAlias

event bool RemoveButtonByAlias (name ButtonInputAlias)

Removes the specified button from the CalloutButtons array (as well as the Children array).

Parameters:

• ButtonInputAlias - the input alias tag (i.e. Conditional1, Accept, Cancel, etc.) used by the button to be found.

Returns:

TRUE if the button was successfully removed.

Todo: should we provide an option for allowing the user to control whether this button's alias is removed from the CalloutButtonAliases map?

RemovedChild

event RemovedChild (UIScreenObject WidgetOwner, UIObject OldChild, optional array<UIObject> ExclusionSet)

Overrides: UIScreenObject.RemovedChild

Called immediately after a child has been removed from this screen object.

Parameters:

• WidgetOwner - the screen object that the widget was removed from.
• OldChild - the widget that was removed
• 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. NOTE: If a value is specified, OldChild will ALWAYS be part of the ExclusionSet, since it is being removed.

RemovedFromParent

event RemovedFromParent (UIScreenObject WidgetOwner)

Overrides: UIScreenObject.RemovedFromParent

Notification that this widget's parent is about to remove this widget from its children array. Allows the widget to clean up any references to the old parent.

Parameters:

• WidgetOwner - the screen object that this widget was removed from.

SetButtonCallback

event bool SetButtonCallback (name ButtonInputAlias, delegate<UIObject.OnClicked> NewClickHandler)

Wrapper method for changing the function assigned to the specified button's OnClicked delegate.

Parameters:

• ButtonInputAlias - the input alias tag (i.e. Conditional1, Accept, Cancel, etc.) used by the button to be found.
• NewClickHandler - the function or delegate value to assign to the button's OnClicked delegate.

Returns:

TRUE if the button's OnClicked delegate was set successfully.

SetButtonCaption

event bool SetButtonCaption (name ButtonInputAlias, string NewButtonCaption)

Wrapper for changing a button's caption. Not yet implemented as this should be coming from the data store.

SetButtonInputAlias

event bool SetButtonInputAlias (name ButtonInputAlias, coerce name NewButtonInputAlias)

Wrapper method for changing a button's assigned input alias.

Parameters:

• ButtonInputAlias - the input alias tag (i.e. Conditional1, Accept, Cancel, etc.) used by the button to be found.
• NewButtonInputAlias - the new input alias tag to apply to the button.

Returns:

TRUE if the button's input alias tag was changed successfully.

ShowButton

event bool ShowButton (name ButtonInputAlias, optional bool bShowButton)

Wrapper for changing the visibility of the specified button

Parameters:

• ButtonInputAlias - the input alias tag (i.e. Conditional1, Accept, Cancel, etc.) used by the button to be found.
• bShowButton - whether the show or hide the button.

Returns:

TRUE if the button's visiblity was set successfully.

SynchronizeInputAliases

event SynchronizeInputAliases ()

Ensures that the CalloutButtonAliases array matches

Other instance functions

ConfigureChildButton

function ConfigureChildButton (UICalloutButton ChildButton)

Configures the button with all the appropriate settings to operate correctly in this callout panel (docking links, auto-size settings, etc.)

Parameters:

• ChildButton - the button to configure

InitializeInputProxy

function InitializeInputProxy ()

Creates CalloutButtonInputProxy object for the scene (if necessary) and register the input keys for all buttons in the panel.

OnButtonVisibilityChanged

function OnButtonVisibilityChanged (UIScreenObject SourceWidget, bool bIsVisible)

Handler for the NotifyVisibilityChanged delegate in the buttons contained by this panel.

Parameters:

• SourceWidget - the widget that changed visibility status
• bIsVisible - whether this widget is now visible.

PopulateCalloutButtonArray

function PopulateCalloutButtonArray ()

Iterates over the Children array, adding any child UICalloutButtons to the CalloutButtons array. Safe to call multiple times.