This article has been re-structured and can be found in its new format here: User Interface
The UI Action system allows to setup and control any Flash UI element using flowgraph.
For this purpose every Flash asset can be defined in an XML file with all events, functions, and variables that need to be available in the flowgraphs.
How to setup materials for flash use can be found here: UI Elements as Dynamic Textures.
Setup XML files for Flash assets
The Flash UI system reads all XML files located in
Game/Libs/UI/UIElements and creates flownodes to control the Flash assets.
Open an existing XML file or create a new one to define a new UI element.
Basic definition of a Flash asset:
Functions that should be callable from outside need to be defined in the <functions> list of the element.
e.g. an actionscript function to set a health bar:
can be defined in the xml as:
where name="..." is the name of the function that is visible in the flowgraph and funcname="..." is the real name of the function in the actionscript.
The system will automatically create a node for the flowgraph to call this function.
Note: It is also possible to define functions that are not in the rootspace of the Flash file, e.g.
To get notification about some user interaction, e.g. if a button was pressed, events can be defined in the <events> list. To trigger an event in your actionscript code you have to call fscommand("commandString"). These fscommands are handled by the engine.
e.g. in the onPress function of a button you can call fscommand with the string "onMyButtonPressed" and some arguments.
To handle this event add a <event> tag into the <events> list
The system creates a node to handle this event.
Variables, Arrays and MovieClips
Access to an array or a variable can also be defined in the xml file.
Just add a <variable> tag into the <variables> list, an <array> tag to the <arrays> list or a <movieclip> tag into the <movieclips> list.
To get or set a variable select the variable in the dropdown list of the UI:Variable:Var or UI:Variable:Array flownode.
Note: Arrays are comma separated strings.
You can also access your defined MovieClips via FlowNodes.
Display / hide and setup gfx files
To show or hide a Flash asset use the UI:Display:Display node. You can select the element in the dropdown list.
To setup the behavior and the constraints use the UI:Display:Constraints and UI:Display:Config nodes.
It is also possible to initialize all of those settings in the xml file.
0=disable, 1=enabled, if enabled mouse events are send to the Flash file (mouse-clicks and movement)
0=disabled, 1=enabled, if enabled a hardware mouse cursor is visible while the Flash element is displayed.
0=disabled, 1=enabled, if enabled keyevents are send to the Flash element.
0=disabled, 1=enabled, if enabled the controller works as a mouse on console (thumb-stick). Only if mouseevents are enabled.
0=diabled, 1=enabled, if enabled a hardware cursor is displayed on console as well. Only if cursor is enabled.
0 to n, defines in which order the elements are displayed (if more than one Flash element is visible).
0 to 1, the background alpha of the Flash element.
There are three modes to place the asset on the screen:
in this mode the Flash asset is displayed on a fixed position, defined by a top, left, width and height value.
this mode aligns the asset on anchors. For vertical alignment it is possible to align the Flash element at the "top", "center" or "bottom", for horizontal alignment to the "left", "center" or "right" of the screen.
If scale is "1" it tries to scale the element to the maximum without deforming the aspect ratio. If scale is set to "0", it will not scale the Flash asset.
If max is set to "1" it will maximize the element so that 100% of the screen is covered (this might cause that some parts of the element are cut-off) otherwise the asset will fit to the screen with maybe some uncovered space on the left/right or top/bottom side.
In this mode the viewport of the asset is same as the render viewport. If scale is set to "1" the asset is stretched to fit the complete screen, otherwise not.
Instantiation of Elements
Each node has the "InstanceID" port. With this instance ID you can have more than one instance of any Flash asset. The "InstanceID" port of any UI node defines which instance should be affected by this node. If you use a node with a new instance ID it will automaticly create the new instance of this Flash asset. If you use "-1" as the instance ID, the node will affect all instances of this Flash element.
There are some special actionscript functions that are automatically called by the UI system.
These functions can be defined in the rootspace of your actionscript and don't need to be defined in the xml file.
If this function exists, it is called once the gfx/swf file is loaded by the engine.
If this function exists, it is called once the gfx/swf file is shown up.
If this function exists, it is called once the gfx/swf file is hided.
If this function exists, it is called once the resolution of the engine has changed.
If this function exists, it is called once if the player pressed the back button on the controller.
This function is called if the "RequestHide" port was triggered on the UI:Display:Display Node (or via code / Lua). Can be used to fade out elements.
There are some fscommand strings that can be called within your actionscript.
If a fscommand is executed with this string, it tells the UI System to hide the element.
Fade UI Element in / out.
You can now fade in/out the element by triggering the port show / requestHide if the UI:Display:Display Node.
To create a new flowgraph for the UI just open the Flowgraph and choose "File->New UI Action...".
All UI Actions are located in the Flow Graphs list and the xml files needs to be saved in
Note: All UI actions are saved separate from the level. They need to be saved via File->Save in the flowgraph menu. Make sure to save every time you did some changes!
You find all flownodes for the UI in the component list unter UI.
This example shows a simple flowgraph to show/hide a loading screen and setup the level name and a progress value.
The associated element is defined in
Sometimes it is helpful to trigger a complex UI Action several times without rebuilding the whole graph every time.
For this purpose it is possible to create UI Actions with a "UI:Action:Start" and "UI:Action:End" node. You will find this nodes under UI:Action.
The Name of the Flowgraph defines the Name of the Action.
The "UI:Action:Control" node allows to start an UI Action and receive notifications if an action was started or stopped.
It is also possible to pass several arguments to an UIAction via the "UI:Action:Control" node.
As an example the UIAction to display a USM Video file:
This action can be used e.g. to play a movie on enter a proximity trigger:
Note: You can control any UI action from any flowgraph. If you disable an UI Action, the complete flowgraph will be disabled (not only the Nodes between the start and end node). It is also possible to use the StartAction and EndAction notes more than once per flowgraph. Every StartAction node will be triggered if the action is started and the first reached EndAction node will trigger the OnEnd port of any UI:Action:Control node which is listening to the flowgraph.
Lua and Flash UI System
It is also possible to control the UI System via Lua. See also: List of Lua functions.
Communication between C++ and UI flowgraph
You can just create your own custom flownodes and use them to trigger/receive UI functions/events. More information in the Creating a New Flow Node topic.
UI Event System
The UI System comes with an event system which can also used to communicate between C++ and the UI flowgraph.
The event system provides an easy way to define function and event nodes and handle them in C++.
Function nodes are available to all flowgraphs and provide an easy way to call C++ code.
Create a new .h file and name it UIFunctions.h
Create a new .cpp file and name it UIFunctions.cpp
Open Game.h, forward declare your class and add a private member to CGame:
Open Game.cpp init m_pUIFunctions with NULL in the construcor, delete m_pUIFunctions in the deconstructor and create the CUIFunction object at the end of the init function.
Note: It is important to create all your classes that uses the UI event system before CompleteInit is called.
This code will result in two new nodes UI:Functions:Game:Foo and UI:Functions:Game:Bar.
If the port "send" is triggered, it will call the C++ code in UIFunctions.cpp.
Event nodes are very similar to Function nodes. They are used to send events from C++ to any UI flowgraph.
e.g. you can create a singleton class to call events from everywhere of your code.
Create a .h file UIGameEvents.h
Create a .cpp file UIGameEvents.cpp
Open Game.cpp, include "UIGameEvents.h" and add to the end of the Init function:
The code will create two nodes for the flowgraph:
Now you can call from everywhere in your code the SendEvent function to trigger e.g. the UI:Events:Game:Bar Node: