Engine.UIScreenObject

/**
 * Base class for all UI entities which can appear onscreen
 *
 * Copyright 1998-2008 Epic Games, Inc. All Rights Reserved.
 */
class UIScreenObject extends UIRoot
	native(UIPrivate)
	HideCategories(Object)
	abstract
	placeable;
























































































































 



#linenumber 12

/** The location of this screen object */
var(Presentation)			UIScreenValue_Bounds	Position;

/**
 * Controls how the widget is sorted by the rendering code; higher values push the widget "away" from the screen,
 * while lower values bring the widget "closer" to the screen
 */
var(Presentation)				float				ZDepth;

/** Controls whether the screen object is visible */
var(Presentation) 	private{private}	bool		bHidden;

/**
 * Indicates whether this widget has been initialized.  Set from UUIScene/UUIObject::Initialize, immediately after the
 * base version of Initialized has been called, but before Initialize() has been called on the children of the widget.
 */
var transient bool									bInitialized;

/** list of UIObjects which are owned by this UIObject */
var	protected noimport		array<UIObject>			Children;

/**
 * The states that should exist in this widget's InactiveStates array by default.  When the widget is initialized, the
 * InactiveStates array is iterated through, and if there are no states in the InactiveStates array that have a class
 * matching a DefaultState, a new UIState object of that class is instanced and placed into the InactiveStates array.
 */
var	const				array<class<UIState> >		DefaultStates;

/**
 * Specifies the UIState that this widget will automatically enter when it is initialized.
 */
var						class<UIState>				InitialState;

/** list of states that this screen object can enter */
var(States) const	instanced	array<UIState>		InactiveStates;

/** stack of states this widget is currently using */
var	transient	const	array<UIState>				StateStack;

/**
 * The children of this widget that are in special states (i.e. focused control, last focused control, etc.)
 * Each element of this array corresponds to the player at the same array index in the Engine.GamePlayers array.
 */
var	transient	const	array<PlayerInteractionData>	FocusControls;

/**
 * Determines which children of this widget should receive focus when this widget receives focus.
 * Each element of this array corresponds to the player at the same array index in the Engine.GamePlayers array.
 */
var(Focus)	transient	array<UIFocusPropagationData>	FocusPropagation;

/**
 * Indicates that this widget should never become the focused control; does not prevent children of this widget from receiving focus (that must be done
 * by calling SetPrivateBehavior(PRIVATE_NotFocusable,true))
 */
var(Focus)	bool					bNeverFocus;

/**
 * A bitmask representing the player indexes that this control will process input for, where the value is generated by
 * left bitshifting by the index of the player.
 * A value of 255 indicates that this control will process input from all players.
 * A value of 1 << 1 indicate that only input from player at index 1 will be acccepted, etc.  So value of 3 means that this control
 * processes input from players at indexes 0 and 1.  Input from player indexes that do not match the mask will be ignored.
 */
var(Splitscreen)		byte						PlayerInputMask;

/** the opacity of the object */
var(Presentation)		float						Opacity;

/**
 * Indicates whether this widget uses 3D primitives.
 */
var	const				bool						bSupports3DPrimitives;

// ===============================================
// Components
// ===============================================
var	 					UIComp_Event				EventProvider;

// ===============================================
// Sounds
// ===============================================
/** this sound is played when this widget becomes the focused control */
var(Sound)				name						FocusedCue;

/** this sound is played when this widget becomes the active control */
var(Sound)				name						MouseEnterCue;

/** this sound is played when this widget has a navigate up event */
var(Sound)				name						NavigateUpCue;

/** this sound is played when this widget has a navigate down event */
var(Sound)				name						NavigateDownCue;

/** this sound is played when this widget has a navigate left event */
var(Sound)				name						NavigateLeftCue;

/** this sound is played when this widget has a navigate right event */
var(Sound)				name						NavigateRightCue;

// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)

/* == Delegates == */
/**
 * Called when the currently active skin has been changed.  Reapplies this widget's style and propagates
 * the notification to all children.
 *
 * @note: this delegate is only called if it is actually assigned to a member function.
 */
delegate NotifyActiveSkinChanged();

/**
 * 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.
 *
 * @param	EventParms	information about the input event.
 *
 * @return	TRUE to indicate that this input key was processed; no further processing will occur on this input key event.
 */
delegate bool OnRawInputKey( const out InputEventParameters EventParms );

/**
 * Provides a hook for unrealscript to respond to input using UI input aliases (i.e. Left, Tab, etc.)
 *
 * Called when an input axis event is received which this widget responds to and is in the correct state to process.  The
 * axis 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.
 *
 * @param	EventParms	information about the input event.
 *
 * @return	TRUE to indicate that this input key was processed; no further processing will occur on this input key event.
 */
delegate bool OnRawInputAxis( const out InputEventParameters EventParms );

/**
 * Provides a hook for unrealscript to respond to input using UI input aliases (i.e. Clicked, NextControl, 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 AFTER kismet is given a chance to process the input, but BEFORE any native code processes the input.
 *
 * @param	EventParms	information about the input event, including the name of the input alias associated with the
 *						current key name (Tab, Space, etc.), event type (Pressed, Released, etc.) and modifier keys (Ctrl, Alt)
 *
 * @return	TRUE to indicate that this input key was processed; no further processing will occur on this input key event.
 */
delegate bool OnProcessInputKey( const out SubscribedInputEventParameters EventParms );

/**
 * Provides a hook for unrealscript to respond to input using UI input aliases (i.e. Clicked, NextControl, etc.)
 *
 * Called when an input axis event is received which this widget responds to and is in the correct state to process.  The
 * axis and states widgets receive input for is managed through the UI editor's key binding dialog (F8).
 *
 * This delegate is called AFTER kismet is given a chance to process the input, but BEFORE any native code processes the input.
 *
 * @param	EventParms	information about the input event, including the name of the input alias associated with the
 *						current key name (Tab, Space, etc.), event type (Pressed, Released, etc.) and modifier keys (Ctrl, Alt)
 *
 * @return	TRUE to indicate that this input key was processed; no further processing will occur on this input key event.
 */
delegate bool OnProcessInputAxis( const out SubscribedInputEventParameters EventParms );

/**
 * Called whenever this object changes its position
 */
delegate NotifyPositionChanged( UIScreenObject Sender );

/**
 * Called when the viewport rendering this widget's scene is resized.
 *
 * @param	OldViewportSize		the previous size of the viewport
 * @param	NewViewportSize		the new size of the viewport
 */
delegate NotifyResolutionChanged( const out Vector2D OldViewportsize, const out Vector2D NewViewportSize );

/**
 * Called when a new UIState becomes the widget's currently active state, after all activation logic has occurred.
 *
 * @param	Sender					the widget that changed states.
 * @param	PlayerIndex				the index [into the GamePlayers array] for the player that activated this state.
 * @param	NewlyActiveState		the state that is now active
 * @param	PreviouslyActiveState	the state that used the be the widget's currently active state.
 */
delegate transient NotifyActiveStateChanged( UIScreenObject Sender, int PlayerIndex, UIState NewlyActiveState, optional UIState PreviouslyActiveState );

/**
 * Allows others to receive a notification when this widget's visibility status changes.
 *
 * @param	SourceWidget	the widget that changed visibility status
 * @param	bIsVisible		whether this widget is now visible.
 */
delegate NotifyVisibilityChanged( UIScreenObject SourceWidget, bool bIsVisible );

/** If set, this delegate will be called as directly before rendering */
delegate OnPreRenderCallBack();


/* == Natives == */

/**
 * Returns whether this screen object has been initialized.
 */
native final noexport function bool IsInitialized();

/**
 * 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.
 *
 * @param	PlayerIndex		the index [into the GamePlayers array] where the player was inserted
 * @param	AddedPlayer		the player that was added
 */
native final virtual function CreatePlayerData( int PlayerIndex, LocalPlayer AddedPlayer );

/**
 * Called when a player has been removed from the list of active players (i.e. split-screen players)
 *
 * @param	PlayerIndex		the index [into the GamePlayers array] where the player was located
 * @param	RemovedPlayer	the player that was removed
 */
native final virtual function RemovePlayerData( int PlayerIndex, LocalPlayer RemovedPlayer );

/**
 * 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.
 */
native final virtual function InitializePlayerTracking();

/**
 * Retrieves a reference to a LocalPlayer.
 *
 * @param	PlayerIndex		if specified, returns the player at this index in the GamePlayers array.  Otherwise, returns
 *							the player associated with the owner scene.
 *
 * @return	the player that owns this scene or is located in the specified index of the GamePlayers array.
 */
native final function LocalPlayer GetPlayerOwner( optional int PlayerIndex=INDEX_NONE );

/**
 * Plays the sound cue associated with the specified name; simple wrapper for UIInteraction.PlayUISound
 *
 * @param	SoundCueName	the name of the UISoundCue to play; should corresond to one of the values of the UISoundCueNames array.
 * @param	PlayerIndex		allows the caller to indicate which player controller should be used to play the sound cue.  For the most
 *							part, all sounds can be played by the first player, regardless of who generated the play sound event.
 *
 * @return	TRUE if the sound cue specified was found in the currently active skin, even if there was no actual USoundCue associated
 *			with that UISoundCue.
 *
 * @note: noexport because the native version is a static method of UUIScreenObject
 */
native static final noexport function bool PlayUISound( name SoundCueName, optional int PlayerIndex=0 );

/**
 * Utility function for encapsulating constructing a widget
 *
 * @param	Owner			the container for the widget.  Cannot be none
 * @param	WidgetClass		the class of the widget to create.  Cannot be none.
 * @param	WidgetArchetype	the template to use for creating the widget
 * @param	WidgetName		the name to use for the new widget
 */
native final function UIObject CreateWidget( UIScreenObject Owner, class<UIObject> WidgetClass, optional Object WidgetArchetype, optional name WidgetName );

/**
 * 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.
 *
 * @param	inOwnerScene	the scene to add this widget to.
 * @param	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.
 */
native final function virtual Initialize( UIScene inOwnerScene, optional UIObject inOwner );

/**
 * Insert a widget at the specified location
 *
 * @param	NewChild		the widget to insert
 * @param	InsertIndex		the position to insert the widget.  If not specified, the widget is insert at the end of
 *							the list
 * @param	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.
 *
 * @return	the position that that the child was inserted in, or INDEX_NONE if the widget was not inserted
 */
native function int InsertChild( UIObject NewChild, optional int InsertIndex = INDEX_NONE, optional bool bRenameExisting=true );

/**
 * Remove an existing child widget from this widget's children
 *
 * @param	ExistingChild	the widget to remove
 * @param	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.
 *
 * @return	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.
 */
native final noexport function bool RemoveChild( UIObject ExistingChild, optional array<UIObject> ExclusionSet );

/**
 * 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.
 *
 * @param	ChildrenToRemove	the list of child widgets to remove
 *
 * @return	a list of children that could not be removed; if the return array is emtpy, all children were successfully removed.
 */
native final function array<UIObject> RemoveChildren( array<UIObject> ChildrenToRemove );

/**
 * Replace an existing child widget with the specified widget.
 *
 * @param	ExistingChild	the widget to remove
 * @param	NewChild		the widget to replace ExistingChild with
 *
 * @return	TRUE if the ExistingChild was successfully replaced with the specified NewChild; FALSE otherwise.
 */
native final function bool ReplaceChild( UIObject ExistingChild, UIObject NewChild );

/**
 * Find a child widget with the specified name
 *
 * @param	WidgetName	the name of the child to find
 * @param	bRecurse	if TRUE, searches all children of this object recursively
 *
 * @return	a pointer to a widget contained by this object that has the specified name, or
 *			NULL if no widgets with that name were found
 */
native final function UIObject FindChild( name WidgetName, optional bool bRecurse ) const;

/**
 * Find a child widget with the specified GUID
 *
 * @param	WidgetID	the ID(GUID) of the child to find
 * @param	bRecurse	if TRUE, searches all children of this object recursively
 *
 * @return	a pointer to a widget contained by this object that has the specified GUID, or
 *			NULL if no widgets with that name were found
 */
native final function UIObject FindChildUsingID( WIDGET_ID WidgetID, optional bool bRecurse ) const;

/**
 * Find the index for the child widget with the specified name
 *
 * @param	WidgetName	the name of the child to find
 *
 * @return	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.
 */
native final function int FindChildIndex( name WidgetName ) const;

/**
 * Returns whether this screen object contains the specified child in its list of children.
 *
 * @param	Child		the child to look for
 * @param	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.
 *
 * @return	TRUE if Child is contained by this screen object
 */
native final function bool ContainsChild( UIObject Child, optional bool bRecurse=true ) const;

/**
 * Returns whether this screen object contains a child of the specified class.
 *
 * @param	SearchClass	the class to search for.
 * @param	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.
 *
 * @return	TRUE if Child is contained by this screen object
 */
native final function bool ContainsChildOfClass( class<UIObject> SearchClass, optional bool bRecurse=true ) const;

/**
 * Gets a list of all children contained in this screen object.
 *
 * @param	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.
 * @param	ExclusionSet	if specified, any widgets contained in this array will not be added to the output array.
 *
 * @return	an array of widgets contained by this screen object.
 *
 * @note: noexport because non-const optional arrays aren't exported correctly by the script compiler.
 */
native final noexport function array<UIObject> GetChildren( optional bool bRecurse, optional array<UIObject> ExclusionSet ) const;

/**
 * Returns the number of UIObjects owned by this UIScreenObject, recursively
 *
 * @return	the number of widgets (including this one) contained by this widget, including all
 *			child widgets
 */
native final function int GetObjectCount() const;

/**
 * Tell the scene that it needs to be udpated
 *
 * @param	bDockingStackChanged	if TRUE, the scene will rebuild its DockingStack at the beginning
 *									the next frame
 * @param	bPositionsChanged		if TRUE, the scene will update the positions for all its widgets
 *									at the beginning of the next frame
 * @param	bNavLinksOutdated		if TRUE, the scene will update the navigation links for all widgets
 *									at the beginning of the next frame
 * @param	bWidgetStylesChanged	if TRUE, the scene will refresh the widgets reapplying their current styles
 */
native final noexport function RequestSceneUpdate( bool bDockingStackChanged, bool bPositionsChanged, bool bNavLinksOutdated=FALSE, bool bWidgetStylesChanged=FALSE );

/**
 * Flag the scene to refresh all string formatting at the beginning of the next tick.
 */
native final noexport function RequestFormattingUpdate();

/**
 * 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.
 *
 * @param	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.
 * @param	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.
 */
native final noexport function RequestPrimitiveReview( bool bReinitializePrimitives, bool bReviewPrimitiveUsage );

/**
 * Immediately rebuilds the navigation links between the children of this screen object and recalculates the child that should
 * be the first & last focused control.
 */
native function RebuildNavigationLinks();

/**
 * 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.
 *
 * @param	out_ViewportOffset	[out] will be filled in with the delta between the viewport's actual origin and virtual origin.
 *
 * @return	TRUE if the viewport origin was successfully retrieved
 */
native final function bool GetViewportOffset( out Vector2D out_ViewportOffset ) const;

/**
 * Retrieves the scale factor for the viewport which renders this widget's scene.  Only relevant in the UI editor.
 */
native final function float GetViewportScale() 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.
 *
 * @param	out_ViewportOrigin	[out] will be filled in with the origin point for the viewport that
 *								owns this screen object
 *
 * @return	TRUE if the viewport origin was successfully retrieved
 */
native final function bool GetViewportOrigin( out Vector2D out_ViewportOrigin ) const;

/**
 * Retrieves the viewport size, accounting for split-screen.
 *
 * @param	out_ViewportSize	[out] will be filled in with the width & height of the viewport that
 *								owns this screen object
 *
 * @return	TRUE if the viewport size was successfully retrieved
 */
native final function bool GetViewportSize( out Vector2D out_ViewportSize ) const;

/**
 * Retrieves the width of the viewport this widget uses for rendering.
 */
native final function float GetViewportWidth() const;

/**
 * Retrieves the height of the viewport this widget uses for rendering.
 */
native final function float GetViewportHeight() const;

/**
 * Activate the event of the specified class.
 *
 * @param	PlayerIndex				the index of the player that activated this event
 * @param	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.
 * @param	InEventActivator		an optional object that can be used for various purposes in UIEvents
 * @param	bActivateImmediately	TRUE to activate the event immediately, causing its output operations to also be processed immediately.
 * @param	IndicesToActivate		Indexes into this UIEvent's Output array to activate.  If not specified, all output links
 *									will be activated
 * @param	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.
 */
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 );

/**
 * Finds UIEvent instances of the specified class.
 *
 * @param	EventClassToFind		specifies the event class to search for.
 * @param	out_EventInstances		an array that will contain the list of event instances of the specified class.
 * @param	LimitScope				if specified, only events contained by the specified state's sequence will be returned.
 * @param	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.
 */
native final function FindEventsOfClass( class<UIEvent> EventClassToFind, out array<UIEvent> out_EventInstances, optional UIState LimitScope, optional bool bExactClass );

/** State functions */

/**
 * Attempts to set the object to the enabled/disabled state specified.
 *
 * @param bEnabled		Whether to enable or disable the widget.
 * @param PlayerIndex	Player index to set the state for.
 *
 * @return TRUE if the operation was successful, FALSE otherwise.
 */
native function bool SetEnabled( bool bEnabled, int PlayerIndex=GetBestPlayerIndex() );

/**
 * Gets the current UIState of this screen object
 *
 * @param	PlayerIndex	the index [into the Engine.GamePlayers array] for the player that generated this call
 */
native final function UIState GetCurrentState( INT PlayerIndex=INDEX_NONE );

/**
 * Determine whether there are any active states of the specified class
 *
 * @param	StateClass	the class to search for
 * @param	PlayerIndex	the index [into the Engine.GamePlayers array] for the player that generated this call
 * @param	StateIndex	if specified, will be set to the index of the last state in the list of active states that
 *						has the class specified
 *
 * @return	TRUE if there is at least one active state of the class specified
 */
native final noexport function bool HasActiveStateOfClass( class<UIState> StateClass, int PlayerIndex, optional out int StateIndex );

/**
 * Adds the specified state to the screen object's StateStack.
 *
 * @param	StateToActivate		the new state for the widget
 * @param	PlayerIndex			the index [into the Engine.GamePlayers array] for the player that generated this call
 *
 * @return	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
 */
native final virtual function bool ActivateState( UIState StateToActivate, int PlayerIndex );
/**
 * Alternate version of ActivateState that activates the first state in the InactiveStates array with the specified class
 * that isn't already in the StateStack
 */
native final noexport function bool ActivateStateByClass( class<UIState> StateToActivate, int PlayerIndex, optional out UIState StateThatWasAdded );

/**
 * Removes the specified state from the screen object's state stack.
 *
 * @param	StateToRemove	the state to be removed
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated this call
 *
 * @return	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
 */
native final virtual function bool DeactivateState( UIState StateToRemove, int PlayerIndex );
/**
 * Alternate version of DeactivateState that deactivates the last state in the StateStack array that has the specified class.
 */
native final noexport function bool DeactivateStateByClass( class<UIState> StateToRemove, int PlayerIndex, optional out UIState StateThatWasRemoved );

/**
 * Propagates the enabled state of this widget to its child widgets, if the widget has the PRIVATE_PropageteState flag set.
 *
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated this call
 * @param	bForce			specify TRUE to propagate the enabled state even if this widget doesn't have the PropagateState flag set.
 *
 * @return	TRUE if child widget states were set successfully.
 */
native final virtual function bool ConditionalPropagateEnabledState( int PlayerIndex, optional bool bForce );

/**
* Returns TRUE if the player associated with the specified ControllerId is holding the Ctrl key
*
* @fixme - doesn't currently respect the value of ControllerId
*/
native final virtual function bool IsHoldingCtrl( 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
*/
native final virtual function bool IsHoldingAlt( 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
*/
native final virtual function bool IsHoldingShift( int ControllerId );

/** === Navigation === */
/**
 * Sets focus to the first focus target within this container.
 *
 * @param	Sender	the widget that generated the focus change.  if NULL, this widget generated the focus change.
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated the focus change.
 *
 * @return	TRUE if focus was successfully propagated to the first focus target within this container.
 */
native function bool FocusFirstControl( UIScreenObject Sender, optional int PlayerIndex=GetBestPlayerIndex() );

/**
 * Sets focus to the last focus target within this container.
 *
 * @param	Sender			the widget that generated the focus change.  if NULL, this widget generated the focus change.
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated the focus change.
 *
 * @return	TRUE if focus was successfully propagated to the last focus target within this container.
 */
native function bool FocusLastControl( UIScreenObject Sender, optional int PlayerIndex=GetBestPlayerIndex() );

/**
 * 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.
 *
 * @param	Sender			the widget to use as the base for determining which control to focus next
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated the focus change.
 *
 * @return	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.
 */
native function bool NextControl( UIScreenObject Sender, optional int PlayerIndex=GetBestPlayerIndex() );

/**
 * 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.
 *
 * @param	Sender			the widget to use as the base for determining which control to focus next
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated the focus change.
 *
 * @return	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.
 */
native function bool PrevControl( UIScreenObject Sender, optional int PlayerIndex=GetBestPlayerIndex() );

/**
 * 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.
 *
 * @param	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.
 * @param	Direction 		the direction to navigate focus.
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated the focus change.
 *
 * @return	TRUE if the next child widget in the navigation network for the specified direction successfully received focus.
 */
native function bool NavigateFocus( UIScreenObject Sender, EUIWidgetFace Direction, optional int PlayerIndex=GetBestPlayerIndex() );

/** === Focus Handling === */

/**
 * Getter for bNeverFocus
 */
native final function bool IsNeverFocused() const;

/**
 * Determines whether this widget can become the focused control.
 *
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player to check focus availability
 *
 * @return	TRUE if this widget (or any of its children) is capable of becoming the focused control.
 */
native function bool CanAcceptFocus( optional int PlayerIndex=GetBestPlayerIndex() ) const;

/**
 * Determines whether this widget is allowed to propagate focus chains to and from the specified widget.
 *
 * @param	TestChild	the widget to check
 *
 * @return	TRUE if the this widget is allowed to route the focus chain through TestChild.
 */
native final function bool CanPropagateFocusFor( UIObject TestChild ) const;

/**
 * Activates the focused state for this widget and sets it to be the focused control of its parent (if applicable)
 *
 * @param	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.
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated the focus change.
 */
native function bool SetFocus( UIScreenObject Sender, optional int PlayerIndex=GetBestPlayerIndex() );

/**
 * Sets focus to the specified child of this widget.
 *
 * @param	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.
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated the focus change.
 */
native function bool SetFocusToChild( optional UIObject ChildToFocus, optional int PlayerIndex=GetBestPlayerIndex() );

/**
 * Deactivates the focused state for this widget.
 *
 * @param	Sender			the control that called KillFocus.
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated the focus change.
 */
native function bool KillFocus( UIScreenObject Sender, optional int PlayerIndex=GetBestPlayerIndex() );

/**
 * Retrieves the child of this widget which is current focused.
 *
 * @param	bRecurse		if TRUE, returns the inner-most focused widget; i.e. the widget at the end of the focus chain
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated the focus change.
 *
 * @return	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.
 */
native final function UIObject GetFocusedControl( optional bool bRecurse, optional int PlayerIndex=GetBestPlayerIndex() ) const;

/**
 * Retrieves the child of this widget which last had focus.
 *
 * @param	bRecurse		if TRUE, returns the inner-most previously focused widget; i.e. the widget at the end of the focus chain
 * @param	PlayerIndex		the index [into the Engine.GamePlayers array] for the player that generated the focus change.
 *
 * @return	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
 */
native final function UIObject GetLastFocusedControl( optional bool bRecurse, optional int PlayerIndex=GetBestPlayerIndex() ) const;

/**
 * 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.
 */
native final function OverrideLastFocusedControl( int PlayerIndex, UIObject ChildToFocus );

/**
 * Returns TRUE if this widget has a UIState_Enabled object in its StateStack
 *
 * @param	PlayerIndex			the index of the player to check
 * @param	bCheckOwnerChain	by default, the owner chain is checked as well; specify FALSE to override this behavior.
 */
native final noexport function bool IsEnabled( optional int PlayerIndex=GetBestPlayerIndex(), optional bool bCheckOwnerChain=true ) const;

/**
 * Returns TRUE if this widget has a UIState_Focused object in its StateStack
 *
 * @param	PlayerIndex		the index of the player to check
 */
native final noexport function bool IsFocused( optional int PlayerIndex=GetBestPlayerIndex() ) const;

/**
 * Returns TRUE if this widget has a UIState_Active object in its StateStack
 *
 * @param	PlayerIndex		the index of the player to check
 */
native final noexport function bool IsActive( optional int  PlayerIndex=GetBestPlayerIndex() ) const;

/**
 * Returns TRUE if this widget has a UIState_Pressed object in its StateStack
 *
 * @param	PlayerIndex		the index of the player to check
 */
native final noexport function bool IsPressed( optional int PlayerIndex=GetBestPlayerIndex() ) const;

/**
 * Determines whether this widget can accept input from the player specified
 *
 * @param	PlayerIndex		the index of the player to check
 *
 * @return	TRUE if this widget's PlayerInputMask allows it to process input from the specified player.
 */
native final function bool AcceptsPlayerInput( int PlayerIndex ) const;

/**
 * Returns the number of active split-screen players.
 */
native static final noexport function int GetActivePlayerCount();

/**
 * 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.
 */
native final function int GetSupportedPlayerCount();

/**
 * 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.
 */
native final function int GetBestPlayerIndex() const;

/**
 * Changes this widget's position to the specified value for the specified face.
 *
 * @param	NewValue		the new value (in pixels or percentage) to use
 * @param	Face			indicates which face to change the position for
 * @param	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.
 * @param	bZeroOrigin		FALSE indicates that the value specified includes the origin offset of the viewport.
 */
native final function SetPosition( float NewValue, EUIWidgetFace Face, EPositionEvalType InputType=EVALPOS_PixelOwner, optional bool bZeroOrigin );

/**
 * @Returns the Position of a given face for this widget
 * @param	Face			indicates which face to change the position for
 * @param	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.
 *	@param	bIgnoreDockPadding
 *							used to prevent recursion when evaluting docking links
 */
native final function float GetPosition(EUIWidgetFace Face, EPositionEvalType OutputType=EVALPOS_None, optional bool bZeroOrigin, optional bool bIgnoreDockPadding ) const;

/**
 * Returns the width or height for this widget
 *
 * @param	Dimension			UIORIENT_Horizontal to get the width, UIORIENT_Vertical to get the height
 * @param	OutputType			indicates the format of the returnedvalue
 * @param	bIgnoreDockPadding	used to prevent recursion when evaluting docking links
 */
native final function float GetBounds(EUIOrientation Dimension, EPositionEvalType OutputType=EVALPOS_None, optional bool bIgnoreDockPadding) const;

/**
 * Returns this widget's absolute normalized screen position as a vector.
 *
 * @param	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.
 */
native final function vector GetPositionVector( optional bool bIncludeParentPosition=true ) const;

/**
 * Generates a list of all widgets which are docked to this one.
 *
 * @param	out_DockedWidgets	receives the list of widgets which are docked to this one
 * @param	SourceFace			if specified, only widgets which are docked to this one through the specified face will be considered
 * @param	TargetFace			if specified, only widgets which are docked to the specified face on this widget will be considered
 */
native final function GetDockedWidgets( out array<UIObject> out_DockedWidgets, optional EUIWidgetFace SourceFace=UIFACE_MAX, optional EUIWidgetFace TargetFace=UIFACE_MAX ) const;

/* === Conversion between coordinate systems === */
/*
There are two coordinate systems that are used by the UI system:

	Canvas (widget local space)
		- X/Y axis are aligned with the widget's top/left face
		- Range is 0,0 to SizeX,SizeY
		- Origin at 0,0 (transformed using the widget's transform matrix)

	Pixel (actual viewport pixel location)
		- X/Y axis are aligned with the screen's top/left edge
		- Range is 0,0 to SizeX,SizeY
		- Origin at 0,0 (top-left of screen)

	the intermediate coordinate systems are not used directly by the UI system, but are important when convertin between them:
	Screen (D3D device coordinates) / Camera (normalized device coordinates)
		- X/Y axis are aligned to the screen's left/top
		- Range is -1,1 to 1,-1 (normalized) or -SizeX/2,SizeY/2 to SizeX/2,-SizeY/2
		- Origin is at 0,0 (center of screen)

*/
/**
 * Converts a coordinate from this widget's local space (that is, tranformed by the widget's rotation) into a 2D viewport
 * location, in pixels.
 *
 * @param	CanvasPosition	a vector representing a location in widget local space.
 *
 * @return	a coordinate representing a point on the screen in pixel space
 */
native final function Vector Project( const out Vector CanvasPosition ) const;

/**
 * Converts an absolute pixel position into 3D screen coordinates.
 *
 * @param	PixelPosition	the position of the 2D point, in pixels
 *
 * @return	a position tranformed using this widget's rotation and the scene client's projection matrix.
 */
native final function Vector DeProject( const out Vector PixelPosition ) const;

/**
 * Transforms a vector from canvas (widget local) space into screen (D3D device) space
 *
 * @param	CanvasPosition	a vector representing a location in widget local space.
 *
 * @return	a vector representing that location in screen space.
 */
native final function Vector4 CanvasToScreen( const out Vector CanvasPosition ) const;

/**
 * Transforms a vector from screen (D3D device space) into pixel (viewport pixels) space.
 *
 * @param	ScreenPosition	a vector representing a location in device space
 *
 * @return	a vector representing that location in pixel space.
 */
native final function Vector2D ScreenToPixel( const out Vector4 ScreenPosition ) const;

/**
 * Transforms a vector from pixel (viewport pixels) space into screen (D3D device) space
 *
 * @param	PixelPosition	a vector representing a location in viewport pixel space
 *
 * @return	a vector representing that location in screen space.
 */
native final function Vector4 PixelToScreen( const out Vector2D PixelPosition ) const;

/**
 * Transforms a vector from screen (D3D device space) space into canvas (widget local) space
 *
 * @param	ScreenPosition	a vector representing a location in screen space.
 *
 * @return	a vector representing that location in screen space.
 */
native final function Vector ScreenToCanvas( const out Vector4 ScreenPosition ) 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.
 *
 * @param	PixelPosition	the position of the 2D point; a value from 0 - size of the viewport.
 *
 * @return	a 2D screen coordinate corresponding to where PixelPosition would be if this widget was not rotated.
 */
native final function Vector PixelToCanvas( const out Vector2D PixelPosition ) const;

// Same thing as Project
//native final function Vector2D CanvasToPixel( const out Vector CanvasPosition ) const;

/**
 * Returns a matrix which includes the scene client's CanvasToScreen matrix and this widget's tranform matrix.
 */
native final function matrix GetCanvasToScreen() const;

/**
 * Returns the inverse of the canvas to screen matrix.
 */
native final function Matrix GetInverseCanvasToScreen() const;

/**
 * Calculate the correct scaling factor to use for preserving aspect ratios in e.g. string and image formatting.
 *
 * @param	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.
 *
 * @param	a float representing the aspect ratio percentage to use for scaling fonts and images.
 */
native final function float GetAspectRatioAutoScaleFactor( optional Font BaseFont ) const;

/** == Debug == */

/**
 * Returns a string representation of this widget's hierarchy.
 * i.e. SomeScene.SomeContainer.SomeWidget
 */
native final noexport function string GetWidgetPathName();

/* == Events == */

/**
 * Called once this screen object has been completely initialized, before it has called Initialize on its children.
 */
event Initialized();


/**
 * Called after this screen object's children have been initialized
 */
event PostInitialize();

/**
 * Called immediately after a child has been added to this screen object.
 *
 * @param	WidgetOwner		the screen object that the NewChild was added as a child for
 * @param	NewChild		the widget that was added
 */
event AddedChild( UIScreenObject WidgetOwner, UIObject NewChild );

/**
 * Called immediately after a child has been removed from this screen object.
 *
 * @param	WidgetOwner		the screen object that the widget was removed from.
 * @param	OldChild		the widget that was removed
 * @param	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.
 */
event RemovedChild( UIScreenObject WidgetOwner, UIObject OldChild, optional array<UIObject> ExclusionSet );

/**
 * 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.
 *
 * @param	WidgetOwner		the screen object that this widget was removed from.
 */
event RemovedFromParent( UIScreenObject WidgetOwner );

/** @return Returns whether or not the player with the specified controller id is logged in */
event bool IsLoggedIn( optional int ControllerId=INDEX_NONE, optional bool bRequireOnlineLogin )
{
	if ( ControllerId == INDEX_NONE )
	{
		ControllerId = GetBestControllerId();
	}

	return class'UIInteraction'.static.IsLoggedIn(ControllerId, bRequireOnlineLogin);
}

/**
 * Changes this widget's visibility.  Do not change this method to be public - if you need to bypass overrides of SetVisibility,
 * use the Super/Super(UIScreenObject) syntax.
 *
 * @param	bVisible	specify FALSE to hide the widget.
 */
final private function PrivateSetVisibility( bool bVisible )
{
	local bool bCouldAcceptFocus;

	if ( bHidden == bVisible )
	{
		bCouldAcceptFocus = CanAcceptFocus(GetBestPlayerIndex());

		bHidden = !bVisible;
		NotifyVisibilityChanged(Self, bVisible);

		if ( IsFocused() )
		{
			KillFocus(None);
		}

		if ( bCouldAcceptFocus != CanAcceptFocus(GetBestPlayerIndex()) )
		{
			RequestSceneUpdate( false, false, true );
		}
	}
}

/**
 * Changes whether this widget is visible or not.  Should be overridden in child classes to perform additional logic or
 * abort the visibility change.
 *
 * @param	bIsVisible	TRUE if the widget should be visible; false if not.
 */
event SetVisibility( bool bIsVisible )
{
	PrivateSetVisibility(bIsVisible);
}

/**
 * Accessor for private variable
 *
 * @returns true if this object is visible
 */
final function bool IsVisible()
{
	return !bHidden;
}

/**
 * Accessor for private variable
 *
 * @returns true if this object is hidden
 */
final function bool IsHidden()
{
	return bHidden;
}

/**
 * Enables input processing in this widget for the player located at the specified index of the Engine.GamePlayers array.
 * If this control is not currently masking input (i.e. its PlayerInputMask is 255), the input mask will be set to only
 * allow input from the player index specified.
 *
 * @param	PlayerIndex		the index of the player that this control should now respond to input for.
 * @param	bRecurse		propagate the new input mask to all children of this control.
 */
final event EnablePlayerInput( byte PlayerIndex, optional bool bRecurse=true )
{
	local byte NewPlayerInputMask;

	if ( PlayerIndex >= 0 && PlayerIndex < MAX_SUPPORTED_GAMEPADS )
	{
		// a value of 255 allows this control to process input from all gamepads, so if the current value
		// is 255, we need to reset it first so that we now only respond to the gamepad index specified.
		if ( PlayerInputMask == 255 )
		{
			PlayerInputMask = 0;
		}

		NewPlayerInputMask = PlayerInputMask | (1 << PlayerIndex);
		SetInputMask(NewPlayerInputMask, bRecurse);
	}
}

/**
 * Disables input processing in this widget for the player located at the specified index of the Engine.GamePlayers array.
 * If this control is no longer masking any players (i.e. the new PlayerInputMask would be 0), the input mask will be reset
 * to allow input from any player.
 *
 * @param	GamepadIndex	the gamepad that this control should no longer respond to input for.
 * @param	bRecurse		propagate the new input mask to all children of this control.
 */
final event DisablePlayerInput( byte PlayerIndex, optional bool bRecurse=true )
{
	local byte NewPlayerInputMask;

	if ( PlayerIndex >= 0 && PlayerIndex < MAX_SUPPORTED_GAMEPADS )
	{
		NewPlayerInputMask = PlayerInputMask & ~(1 << PlayerIndex);

		// if we disabled input for all gamepads, it means that we don't want to mask out
		// any gamepads, so reset this control's input mask so that it will accept input
		// from any gamepad
		if ( NewPlayerInputMask == 0 )
		{
			NewPlayerInputMask = 255;
		}

		SetInputMask(NewPlayerInputMask, bRecurse);
	}
}

/**
 * Changes the player input mask for this control, which controls which players this control will accept input from.
 *
 * @param	NewInputMask	the new mask that should be assigned to this control
 * @param	bRecurse		if TRUE, calls SetInputMask on all child controls as well.
 */
event SetInputMask( byte NewInputMask, optional bool bRecurse=true )
{
	local int i;

	PlayerInputMask = NewInputMask;
	if ( bRecurse )
	{
		for ( i = 0; i < Children.Length; i++ )
		{
			Children[i].SetInputMask(NewInputMask, true);
		}
	}
}

/**
 * Allow Script to add UI Actions
 */
event GetSupportedUIActionKeyNames(out array<Name> out_KeyNames );

/* == Unrealscript == */

/**
 * Returns the scene or widget that contains this widget in its Children array.
 */
function UIScreenObject GetParent();

/** Kismet Action Handlers */
function OnChangeVisibility( UIAction_ChangeVisibility Action )
{
	SetVisibility(Action.bVisible);
}

/** wrapper for enabling/disabling widgets */
final function bool EnableWidget( int PlayerIndex )
{
	return SetEnabled(true, PlayerIndex);
}
final function bool DisableWidget( int PlayerIndex )
{
	return SetEnabled(false, PlayerIndex);
}

function OnConsoleCommand( UIAction_ConsoleCommand Action )
{
	local LocalPlayer PlayerOwner;

	PlayerOwner = GetPlayerOwner();
	if ( PlayerOwner != None && PlayerOwner.Actor != None )
	{
		PlayerOwner.Actor.ConsoleCommand(Action.Command);
	}
	else
	{
		LogInternal(Name$"::"$GetFuncName()@"Couldn't execute console command '" $ Action.Command $ "':" @ "PlayerOwner:"$(PlayerOwner!= None ? string(PlayerOwner.Name) : "None") @ (PlayerOwner != None ? "PlayerOwner.Actor:"$(PlayerOwner.Actor!= None ? string(PlayerOwner.Actor.Name) : "None") : ""));
	}
}

/**
 * @return	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.
 */
function int GetBestControllerId()
{
	local LocalPlayer LP;
	local int PlayerIndex, ControllerId;

	LP = GetPlayerOwner();
	if ( LP != None )
	{
		ControllerId = LP.ControllerId;
	}
	else
	{
		PlayerIndex = GetBestPlayerIndex();
		ControllerId = class'UIInteraction'.static.GetPlayerControllerId(PlayerIndex);
	}

	return ControllerId;
}

/** @return Returns the current login status for the specified controller id. */
function ELoginStatus GetLoginStatus(int ControllerId=INDEX_NONE)
{
	if ( ControllerId == INDEX_NONE )
	{
		ControllerId = GetBestControllerId();
	}

	return class'UIInteraction'.static.GetLoginStatus(ControllerId);
}

/** @return Returns the current status of the platform's network connection. */
function bool HasLinkConnection()
{
	return class'UIInteraction'.static.HasLinkConnection();
}

/** @return Returns whether or not the specified player can play online. */
function bool CanPlayOnline(int ControllerId=GetBestControllerId())
{
	return class'UIInteraction'.static.CanPlayOnline(ControllerId);
}

/**
 * Wrapper for getting the NAT type
 */
function ENATType GetNATType()
{
	return class'UIInteraction'.static.GetNatType();
}

/**
 * Displays the friends UI
 *
 * @param Action used to determine which player is requesting the action
 */
function OnShowFriendsUI(UIAction_ShowFriendsUI Action)
{
	local OnlineSubsystem OnlineSub;
	OnlineSub = class'GameEngine'.static.GetOnlineSubsystem();
	if (OnlineSub != None)
	{
		if (OnlineSub.PlayerInterface.ShowFriendsUI(class'UIInteraction'.static.GetPlayerControllerId(Action.PlayerIndex)) == false)
		{
			LogInternal("Failed to show the friends UI");
		}
	}
}

/**
 * Displays the players UI
 *
 * @param Action used to determine which player is requesting the action
 */
function OnShowPlayersUI(UIAction_ShowPlayersUI Action)
{
	local OnlineSubsystem OnlineSub;
	OnlineSub = class'GameEngine'.static.GetOnlineSubsystem();
	if (OnlineSub != None && OnlineSub.PlayerInterfaceEx != None)
	{
		// Show the recent players list for the requesting player
		if (OnlineSub.PlayerInterfaceEx.ShowPlayersUI(class'UIInteraction'.static.GetPlayerControllerId(Action.PlayerIndex)) == false)
		{
			LogInternal("Failed to show the players UI");
		}
	}
}

/**
 * Displays the achievements UI
 *
 * @param Action used to determine which player is requesting the action
 */
function OnShowAchievementsUI(UIAction_ShowAchievementsUI Action)
{
	local OnlineSubsystem OnlineSub;
	OnlineSub = class'GameEngine'.static.GetOnlineSubsystem();
	if (OnlineSub != None)
	{
		if (OnlineSub.PlayerInterfaceEx != None)
		{
			// Show them for the requesting player
			if (OnlineSub.PlayerInterfaceEx.ShowAchievementsUI(class'UIInteraction'.static.GetPlayerControllerId(Action.PlayerIndex)) == false)
			{
				LogInternal("Failed to show the achievements UI");
			}
		}
		else
		{
			LogInternal("OnlineSubsystem does not support the extended player interface");
		}
	}
}

/**
 * Displays the friends invite UI
 *
 * @param Action ignored
 */
function OnShowFriendInviteUI(UIAction_ShowFriendInviteUI Action)
{
	local OnlineSubsystem OnlineSub;
	local UniqueNetId Friend;
//@todo ronp -- remove this code once you are reading the id from somewhere. it just removes a warning
	Friend.Uid[0] = 0;
	OnlineSub = class'GameEngine'.static.GetOnlineSubsystem();
	if (OnlineSub != None && OnlineSub.PlayerInterfaceEx != None)
	{
//@todo ronp -- The Friend var needs to be filled with the UniqueId contained in the OnlineFriend structure for this friend
		if (OnlineSub.PlayerInterfaceEx.ShowFriendsInviteUI(class'UIInteraction'.static.GetPlayerControllerId(Action.PlayerIndex),Friend) == false)
		{
			LogInternal("Failed to show the friends invite UI");
		}
	}
}

/**
 * Displays the messages UI
 *
 * @param Action used to determine which player is requesting the action
 */
function OnShowMessagesUI(UIAction_ShowMessagesUI Action)
{
	local OnlineSubsystem OnlineSub;
	OnlineSub = class'GameEngine'.static.GetOnlineSubsystem();
	if (OnlineSub != None)
	{
		if (OnlineSub.PlayerInterfaceEx != None)
		{
			// Show the messages for the requesting player
			if (OnlineSub.PlayerInterfaceEx.ShowMessagesUI(class'UIInteraction'.static.GetPlayerControllerId(Action.PlayerIndex)) == false)
			{
				LogInternal("Failed to show the messages UI");
			}
		}
		else
		{
			LogInternal("OnlineSubsystem does not support the extended player interface");
		}
	}
}

/**
 * Displays the feedback UI
 *
 * @param Action used to determine which player is requesting the action
 */
function OnShowFeedbackUI(UIAction_ShowFeedbackUI Action)
{
	local OnlineSubsystem OnlineSub;
	local UniqueNetId Player;
//@todo ronp -- remove this code once you are reading the id from somewhere. it just removes a warning
	Player.Uid[0] = 0;
	OnlineSub = class'GameEngine'.static.GetOnlineSubsystem();
	if (OnlineSub != None)
	{
		if (OnlineSub.PlayerInterfaceEx != None)
		{
//@todo ronp -- The Player var needs to be filled with the UniqueId for this player
			if (OnlineSub.PlayerInterfaceEx.ShowFeedbackUI(class'UIInteraction'.static.GetPlayerControllerId(Action.PlayerIndex),Player) == false)
			{
				LogInternal("Failed to show the feedback UI");
			}
		}
		else
		{
			LogInternal("OnlineSubsystem does not support the extended player interface");
		}
	}
}

/**
 * Displays the gamercard UI
 *
 * @param Action used to determine which player is requesting the action
 */
function OnShowGamerCardUI(UIAction_ShowGamerCardUI Action)
{
	local OnlineSubsystem OnlineSub;
	local UniqueNetId Player;
//@todo ronp -- remove this code once you are reading the id from somewhere. it just removes a warning
	Player.Uid[0] = 0;
	OnlineSub = class'GameEngine'.static.GetOnlineSubsystem();
	if (OnlineSub != None)
	{
		if (OnlineSub.PlayerInterfaceEx != None)
		{
//@todo ronp -- The Player var needs to be filled with the UniqueId for this player
			if (OnlineSub.PlayerInterfaceEx.ShowGamerCardUI(class'UIInteraction'.static.GetPlayerControllerId(Action.PlayerIndex),Player) == false)
			{
				LogInternal("Failed to show the gamercard UI");
			}
		}
		else
		{
			LogInternal("OnlineSubsystem does not support the extended player interface");
		}
	}
}

/**
 * Displays the marketplace UI
 *
 * @param Action used to determine which player is requesting the action
 */
function OnShowContentMarketplaceUI(UIAction_ShowContentMarketplaceUI Action)
{
	local OnlineSubsystem OnlineSub;
	OnlineSub = class'GameEngine'.static.GetOnlineSubsystem();
	if (OnlineSub != None)
	{
		if (OnlineSub.PlayerInterfaceEx != None)
		{
			if (OnlineSub.PlayerInterfaceEx.ShowContentMarketplaceUI(class'UIInteraction'.static.GetPlayerControllerId(Action.PlayerIndex)) == false)
			{
				LogInternal("Failed to show the marketplace UI");
			}
		}
		else
		{
			LogInternal("OnlineSubsystem does not support the extended player interface");
		}
	}
}

/**
 * Displays the marketplace UI
 *
 * @param Action used to determine which player is requesting the action
 */
function OnShowMembershipMarketplaceUI(UIAction_ShowMembershipMarketplaceUI Action)
{
	local OnlineSubsystem OnlineSub;
	OnlineSub = class'GameEngine'.static.GetOnlineSubsystem();
	if (OnlineSub != None)
	{
		if (OnlineSub.PlayerInterfaceEx != None)
		{
			if (OnlineSub.PlayerInterfaceEx.ShowMembershipMarketplaceUI(class'UIInteraction'.static.GetPlayerControllerId(Action.PlayerIndex)) == false)
			{
				LogInternal("Failed to show the marketplace UI");
			}
		}
		else
		{
			LogInternal("OnlineSubsystem does not support the extended player interface");
		}
	}
}

/**
 * Handler function for the SetControllerId action.
 */
function OnSetControllerId( UIAction_SetControllerId Action )
{
	local LocalPlayer PlayerOwner;

	if ( Action != None && Action.GamepadID >= 0 && Action.GamepadID < MAX_SUPPORTED_GAMEPADS )
	{
		// get the player that owns this scene
		PlayerOwner = GetPlayerOwner();
		if ( PlayerOwner != None )
		{
			PlayerOwner.SetControllerId(Action.GamepadID);

			// update the action's PlayerIndex so that it still corresponds to the correct player
			Action.PlayerIndex = class'UIInteraction'.static.GetPlayerIndex(PlayerOwner.ControllerId);
		}
	}
}

//Debug
function LogCurrentState( int Indent )
{

	local int i;
    local string IndentString;
	local UIState CurrentState;

	for ( i = 0; i < Indent; i++ )
	{
		IndentString $= " ";
	}

	CurrentState = GetCurrentState();
	LogInternal(IndentString $ "'" $ Name $ "':" @ CurrentState.Name);;
	for ( i = 0; i < Children.Length; i++ )
	{
		Children[i].LogCurrentState(Indent + 3);
	}

}

defaultproperties
{
   Position=(Value[2]=1.000000,Value[3]=1.000000,ScaleType[0]=EVALPOS_PercentageOwner,ScaleType[1]=EVALPOS_PercentageOwner,ScaleType[2]=EVALPOS_PercentageOwner,ScaleType[3]=EVALPOS_PercentageOwner)
   DefaultStates(0)=Class'Engine.UIState_Enabled'
   DefaultStates(1)=Class'Engine.UIState_Disabled'
   InitialState=Class'Engine.UIState_Enabled'
   PlayerInputMask=255
   Opacity=1.000000
   FocusedCue="Focused"
   NavigateUpCue="NavigateUp"
   NavigateDownCue="NavigateDown"
   NavigateLeftCue="NavigateLeft"
   NavigateRightCue="NavigateRight"
   Name="Default__UIScreenObject"
   ObjectArchetype=UIRoot'Engine.Default__UIRoot'
}