UE3:UITabControl (UT3)

Object >> UIRoot >> UIScreenObject >> UIObject >> UITabControl

Package: 

Engine

Direct subclass:

UTUITabControl

This class in other games:

UDK

This widget manages a collection of panels. Only one panel can be active at a time. Each panel is associated with a tab, which is displayed in a row across one edge of the tab control. Users select the tab corresponding to the panel they wish to interact with by clicking with the mouse or using the keyboard/gamepad to activate neighboring panels.

A UITabControl is composed of two main areas - the "tab region" and the "client region". The tab region is where the tabs are rendered, while the client region is where the currently active panel is rendered.

Copyright 2007 Epic Games, Inc. All Rights Reserved

Properties

Property group 'Presentation'

bAllowPagePreviews

Type: bool

Modifiers: config

Controls whether tab buttons are allowed to enter the targeted state

Default value: True

TabButtonPadding

Type: UIRoot.UIScreenValue_Extent

Array size: 2 (EUIOrientation.UIORIENT_MAX)

The amount of padding to apply to each button's text. The specified value will be evenly distributed to each sides of the button's caption.

Default value, index 0:

Member	Value
ScaleType	UIEXTENTEVAL_PercentOwner
Value	0.02

Default value, index 1:

Member	Value
Orientation	UIORIENT_Vertical
ScaleType	UIEXTENTEVAL_PercentOwner
Value	0.02

TabButtonSize

Type: UIRoot.UIScreenValue_Extent

The size to use for the tab buttons along the orientation of the TabDockFace (i.e. if tabs are docked at top or bottom, this determines the height of the tabs)

Default value:

Member	Value
Orientation	UIORIENT_Vertical
ScaleType	UIEXTENTEVAL_PercentOwner
Value	0.02

TabDockFace

Type: UIRoot.EUIWidgetFace

Controls which face of this UITabControl the tab buttons will be docked to

Todo: ronp - currently only top and bottom are properly supported. In order to support left & right, we'll probably need to rotate the buttons, but first need to figure out what the docking relationship should be in that case.

Default value: UIFACE_Top

TabSizeMode

Type: EUITabAutosizeType

The mode to use for sizing the tab buttons

Default value: TAST_Auto

Property group 'Sound'

ActivateTabCue

Type: name

this sound is played when a new tab is activated

Property group 'UITabControl'

ActivePage

Type: UITabPage

Modifiers: editconst, editinline, transient

Reference to the currently active page

Pages

Type: array<UITabPage>

Modifiers: protected, editinline, editfixedsize, editconst

the list of tab pages managed by this UITabControl

PendingPage

Type: UITabPage

Modifiers: editconst, editinline, transient

Reference to the page which is about to become active.

Internal variables

bUpdateLayout

Type: bool

Modifiers: transient

set to indicate that the tab control should layout the buttons and panels during the next tick

TabButtonBackgroundStyle

Type: UIRoot.UIStyleReference

Modifiers: private

The style to use for the tab button background image

Default value:

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

TabButtonCaptionStyle

Type: UIRoot.UIStyleReference

Modifiers: private

The style to use for the tab button labels

Default value:

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

Default values

Property	Value
OnRawInputKey	ProcessInputKey
bSupportsPrimaryStyle	False
DefaultStates[2]	Class'Engine.UIState_Focused'
DefaultStates[3]	Class'Engine.UIState_Pressed'
DefaultStates[4]	Class'Engine.UIState_Active'

Subobjects

WidgetEventComponent

Class: Engine.UIComp_Event

Inherits from: UIObject.WidgetEventComponent

No new values.

Enums

EUITabAutosizeType

Different ways to adjust the sizes of tab buttons used in this control.

TAST_Manual 

No autosizing; the size for each tab button will be set manually.

TAST_Fill 

all tab buttons will be the same width, and will be expanded to fill the entire width of this control

TAST_Auto 

Standard autosizing; all tab buttons will be resized to fit their captions

Delegates

OnPageActivated

delegate OnPageActivated (UITabControl Sender, UITabPage NewlyActivePage, int PlayerIndex)

Called when a new page is activated.

Parameters:

• Sender - the tab control that activated the page
• NewlyActivePage - the page that was just activated
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this event.

OnPageInserted

delegate OnPageInserted (UITabControl Sender, UITabPage NewPage, int PlayerIndex)

Called when a new page is added to this tab control.

Parameters:

• Sender - the tab control that added the page
• NewPage - the page that was just added
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this event.

OnPageRemoved

delegate OnPageRemoved (UITabControl Sender, UITabPage OldPage, int PlayerIndex)

Called when a page is removed from this tab control.

Parameters:

• Sender - the tab control that removed the page
• OldPage - the page that was removed
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this event.

Functions

Native functions

CreateTabPage

native function UITabPage CreateTabPage (class<UITabPage> TabPageClass, optional UITabPage PagePrefab)

Creates a new UITabPage of the specified class as well as its associated tab button.

Parameters:

• TabPageClass - the class to use for creating the tab page.
• PagePrefab - if specified, the prefab to use for creating this tab page.

Returns:

a pointer to a new instance of the specified UITabPage class

FindTargetedTab

native final function UITabButton FindTargetedTab (int PlayerIndex) const

Returns a reference to the tab button which is currently in the Targeted state, or NULL if no buttons are in that state.

GetPageAtIndex

native final function UITabPage GetPageAtIndex (int PageIndex) const

Returns a reference to the page at the specified index.

GetPageCount

native final function int GetPageCount () const

Returns the number of pages in this tab control.

RequestLayoutUpdate

native final function RequestLayoutUpdate ()

Enables the bUpdateLayout flag and triggers a scene update to occur during the next frame.

Events

ActivateNextPage

event bool ActivateNextPage (int PlayerIndex, optional bool bFocusPage, optional bool bAllowWrapping)

Activates the page immediately after the currently active page. If the currently active page is the last one, activates the first page.

Parameters:

• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this event.
• bFocusPage - specify FALSE if the tab control itself should maintain focus.
• bAllowWrapping - specify false to prevent the first page from being activated if the currently active page is the last page in the stack.

Returns:

TRUE if the next page was successfully activated.

ActivatePage

event bool ActivatePage (UITabPage PageToActivate, int PlayerIndex, optional bool bFocusPage)

Attempts to activate the specified tab page.

Parameters:

• PageToActivate - the tab page that should be become the active page
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player to activate this tab for.
• bFocusPage - specify FALSE if the tab control itself should maintain focus.

Returns:

TRUE if the specified page was successfully activated.

ActivatePreviousPage

event bool ActivatePreviousPage (int PlayerIndex, optional bool bFocusPage, optional bool bAllowWrapping)

Activates the page immediately before the currently active page. If the currently active page is the first one, activates the last page.

Parameters:

• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this event.
• bFocusPage - specify FALSE if the tab control itself should maintain focus.
• bAllowWrapping - specify false to prevent the first page from being activated if the currently active page is the last page in the stack.

Returns:

TRUE if the previous page was successfully activated.

AddedChild

event AddedChild (UIScreenObject WidgetOwner, UIObject NewChild)

Overrides: UIScreenObject.AddedChild

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

This version hooks up the OnClicked delegate for the newly added button.

Parameters:

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

EnableTabPage

event bool EnableTabPage (UITabPage PageToEnable, int PlayerIndex, bool bEnablePage, optional bool bActivatePage, optional bool bFocusPage)

Enables/disables a tab page and its associated tab button.

Parameters:

• PageToEnable - the page to enable/disable.
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this event.
• bEnablePage - controls whether the page should be enabled or disabled.
• bActivatePage - if true, the page will also be activated (only relevant if bEnablePage is true).
• bFocusPage - specify FALSE if the new page should not become the focused control (only relevant if bActivatePage is true)

Returns:

TRUE if the page was successfully enabled/disabled.

InsertPage

event bool InsertPage (UITabPage PageToInsert, int PlayerIndex, int InsertIndex, optional bool bActivateImmediately)

Inserts a page at the specified location.

Parameters:

• PageToInsert - the tab page to insert
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this action.
• InsertIndex - location to insert the page in the Pages array. If not specified, page is inserted at the end.
• bActivateImmediately - if TRUE, immediately activates the page and gives it focus

Returns:

TRUE if the page was successfully added to this tab control

PostInitialize

event PostInitialize ()

Overrides: UIScreenObject.PostInitialize

Called after this screen object's children have been initialized

PrivateActivatePage

protected event PrivateActivatePage (UITabPage PageToActivate, int PlayerIndex)

Worker method for setting a new active page. Handles deactivating the previously active page and firing the appropriate notifications.

Parameters:

• PageToActivate - the tab page that should be become the active page
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player to activate this tab for.

Returns:

TRUE if the specified page was successfully activated.

RemovePage

event bool RemovePage (UITabPage PageToRemove, int PlayerIndex)

Removes the specified page from this tab control's list of pages.

Parameters:

• PageToRemove - the tab page to remove
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this action.

Returns:

TRUE if the page was successfully removed from the pages array.

ReplacePage

event bool ReplacePage (UITabPage ExistingPage, UITabPage NewPage, int PlayerIndex, optional bool bFocusPage)

Replaces one tab page with another one.

Parameters:

• ExistingPage - the tab page to replace; must be a page that is currently in this tab control's Pages array.
• NewPage - the tab page that will replace the existing one.
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player that generated this action.
• bFocusPage - if TRUE, immediately activates the page and gives it focus

Returns:

TRUE if the page was successfully replaced.

Other instance functions

ActivateBestTab

function bool ActivateBestTab (int PlayerIndex, optional bool bFocusPage, optional int StartIndex)

Chooses the best tab to activate and activates it.

Parameters:

• PlayerIndex - the index [into the Engine.GamePlayers array] for the player to activate this tab for.
• bFocusPage - specify FALSE if the tab control itself should maintain focus.
• StartIndex - if specified, starts the iteration at this index when searching for a new tab to activate.

Returns:

TRUE if a tab was successfully activated.

ActivatePageByCaption

function bool ActivatePageByCaption (string PageCaption, int PlayerIndex, optional bool bFocusPage)

Attempts to activate the specified tab page.

Parameters:

• PageToActivate - the tab page that should be become the active page
• PlayerIndex - the index [into the Engine.GamePlayers array] for the player to activate this tab for.
• bFocusPage - specify FALSE if the tab control itself should maintain focus.

Returns:

TRUE if the specified page was successfully activated.

FindPageIndexByButton

function int FindPageIndexByButton (UITabButton SearchButton)

Returns the index [into the Pages array] for the page which has the specified button.

Returns:

INDEX_NONE if no page was found with the specified button.

FindPageIndexByCaption

function int FindPageIndexByCaption (string PageCaption, optional bool bMarkupString)

Returns the index [into the Pages array] for the page which has a button with the specified caption.

Parameters:

• PageCaption - the caption to use for searching for the page
• bMarkupString - if TRUE, searches for the button that has PageCaption as its data store binding.

Returns:

INDEX_NONE if no page was found with the specified caption.

FindPageIndexByPageRef

function int FindPageIndexByPageRef (UITabPage SearchPage)

Returns the index [into the Pages array] for the specified page.

Returns:

INDEX_NONE if the specified was None or isn't in the Pages array.

ProcessInputKey

function bool ProcessInputKey (const out UIRoot.InputEventParameters EventParms)

Provides a hook for unrealscript to respond to input using actual input key names (i.e. Left, Tab, etc.)

Called when an input key event is received which this widget responds to and is in the correct state to process. The keys and states widgets receive input for is managed through the UI editor's key binding dialog (F8).

This delegate is called BEFORE kismet is given a chance to process the input.

Allows the user to use the left/right arrow keys to preview other panels if this widget is the globally focused control

Parameters:

• EventParms - information about the input event.

Returns:

TRUE to indicate that this input key was processed; no further processing will occur on this input key event.

TabButtonClicked

function bool TabButtonClicked (UIScreenObject EventObject, int PlayerIndex)

Called when the user clicks on a tab button and releases the mouse. Begins activating the associated tab page.

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.