UI Editor User Guide

Document Summary: Guide to using the UnrealUI Editor suite for working with scenes and widgets.

Created by Amitt Mahajan^?. Maintained by Richard Nalezynski.

Introduction

This document describes how to use the major features of the Unreal UI Editor.

Terminology

Scene The outermost container for a group of widgets. Scenes contain a collection of widgets, and the relationship between scenes and widgets is very similar to the relationship between a map and the actors placed in that map, in that all widgets must be contained by a Scene.

Widget A Scene placeable object with specific behavior, appearance, states, and available events, or actions.

Event An Event is a signal that a widget can respond to. It could be an input event such as a button press, or a system event such as receiving data from a remote system. Events are generally not bound to a particular type of widget; programmers choose which events are available to widgets, and artists decide which events to implement.

Action Actions perform tasks for widgets, in response to some external event. Actions are created by programmers and are bound to widget events by designers using the UI editor.

State Defines the behavior, appearance, available events, or actions for a single widget or scene. Every widget has at last two states - enabled and disabled, but can have as many as necessary. Other common widget states might be focused, active (i.e. mouse-over), pressed, dragging (i.e. drag-n-drop), or selected.

Sequence A set of events and associated actions (i.e. logic) within the scope of a widget/scene state. Event logic will go in and out of scope as a widget/scene enters and leaves its states.

Style Contains information about how to present and format a widget's appearance.

Skin Represents a collection of Styles.

When a style is created, it is assigned a persistent STYLE_ID. All styles for a particular widget are stored in a single unreal package file. The root object for this package is a UISkin object. The resources required by the style may also be stored in the skin file, or they might be located in another package.

A game UI is required to have at least one UISkin package that will serve as the default skin. Only one UISkin can be active at a time, and all custom UISkins are based on the default UISkin. Custom UISkins may decide to override a style completely by creating a new style that has the same STYLE_ID as the skin to be replaced, and placing that skin into the StyleLookupTable under that STYLE_ID. Any styles which aren't specifically overridden in the custom UISkin are inherited from the default skin.

By default, widgets will automatically be mapped to the customized version of the UIStyle contained in the custom UISkin, but the user may choose to assign a completely different style to a particular widget. This only changes the style of that widget for that skin set and any UISkin that is based on the custom UISkin. Custom UISkins can be hierarchical, in that custom UISkins can be based on other custom UISkins.

Data Store A data store is how the UI references data in the game. Data stores allow the UI to reference game data in a safe manner, since they encapsulate lifetime management. A data store can be either persistent, in which case it is attached directly to the UI Interaction object and is available to all widgets, or it can be temporary, in which case it is attached to the current scene and is only accessible to the widgets contained by that scene. Persistent data stores might track information such as UI data for all gametypes or characters. Temporary data stores might track stuff like the name that was entered into some UI value widget. Data stores can provide static information, such as the names of all gametypes, or dynamic information, such as the name of the current gametype.

Bound Navigation Bound navigation refers navigating between widgets that does not adhere to the Focus Chain for the scene. Bound navigation occurs as a result of input that is bound to the NextControl and PreviousControl Input Event Aliases.

Unbound Navigation Unbound navigation refers to navigation between widgets that does adhere to the behavior defined by the Focus Chain for the scene. Unbound navigation occurs as a result of input that is bound to the NavFocusLeft, NavFocusRight, NavFocusUp and NavFocusDown Input Event Aliases.

Using the Scene Editor

Creating a Scene

Within the UnrealEd Generic Browser select the menu item File > New, enter/select a package name, enter a scene name, select UIScene as the Factory setting, and then select OK.

Opening the Scene Editor

Using the left mouse button, click on the package name under the Packages tree in the UnrealEd Generic Browser . Double-click the scene within the Generic Browser using the left mouse button.

NOTE: It may be useful to filter by the UI Scenes resource type.

Scene Editor Overview

Scenes are constructed within the UIScene Editor.

Editor Layout

1. Scene Viewport	The Viewport is the canvas for your scene layout.
2. Scene Menu Bar and Tool Bar	The Menu Bar and Tool Bar allow for quick access to the settings and tools used while building your scene.
3. Scene Properties	The Properties of currently selected items within the scene.
4. Scene Tools	The Tools available to the artist for scene widget organization, data store binding, and style editing.

Menu Bar

File

Close Closes the Scene Editor.

Edit

Undo:

Redo:

Cut

Copy

Paste

Paste As Child

Rename Selected Widgets

Delete Selected Widgets

Bind selected widgets to datastore

Data Store Browser

Modify Default UI Event Alias Key Bindings...

View

Reset View

Center On Selected Widgets

Draw Background

Draw Grid

Draw Wireframe

Viewport Outline

Container Outline

Selection Outline

Show Dock Handles

Draw Title Safe Regions

Skin

Save Selected Skin

Edit Selected Skin

Load Existing Skin

Create New Skin

Scene

Refresh Scene

Window

Properties Shows the Properties Pane.

Positioning Shows the Positioning Pane

Docking Shows the Docking Pane.

Scene Tools Shows the Scene Tools Pane.

Tool Bar

Alignment Tools

The Alignment toolbar provides tools used to align scene elements. To use an alignment tool, select an object and then click the desired alignment tool.



The Alignment toolbar contains the following tools (in order from left to right).

• Align to Viewport: Top
  • Align the top edge of selected object with the top edge of the viewport.
• Align to Viewport: Center Vertically
  • Align the center of selected object to its vertical coordinate.
• Align to Viewport: Bottom
  • Align the bottom edge of selected object with the bottom edge of the viewport.
• Align to Viewport: Left
  • Align the left edge of selected object with the leftmost edge of the viewport.
• Align to Viewport: Center Horizontally
  • Align the center of selected object to its horizontal coordinate.
• Align to Viewport: Right
  • Align the right edge of selected object with the rightmost edge of the viewport.

Controls

Mouse Controls

Keyboard Controls

Ctrl+Up	Reorder Widget (Selected in the Scene tab of the Scene Tools panel)
Ctrl+Down	Reorder Widget (Selected in the Scene tab of the Scene Tools panel)

Hot Keys

Working with Widgets

Creating a Widget

Widgets can be created in a scene by three different approaches.

The first approach is to utilize the widget creation tools that are available from the Scene Toolbar button panel at the top of the UIScene editor window. Creating a specific widget is as simple as selecting the appropriate widget tool and clicking and dragging in the scene window.

Widgets can also be created by right clicking in the scene window and selecting Place Widget from the contex menu or by right clicking on the UI Scene's icon () in the Scene tab of the Scene Tools panel and selecting Place Widget from the context menu. Both of the approaches that utilize context menus have the disadvantage of not being able to dictate the widgets size upon creation. However, the advantage is that you will be able to select from more widget types, other than the default ones in the toolbar.

Moving a Widget

Once created, a widget can be moved by simply selecting it with the selection tool () and clicking and dragging the widget's edge anywhere between the resize handles. The mouse cursor will change to a cross () and the outer edge of the widget will change color when the mouse cursor is hovering over an appropriate area to grab and move the selected widget.

Resizing a Widget

The resizing of a widget is done by selecting a widget with the selection tool () and clicking and dragging one of its square resize handles that are located at every corner and in the center of each edge. Moving the mouse cursor over a resize handle will change the cursor into a double headed arrow icon to indicate that it is positioned over a resize handle.

Advanced Widget Editing

The following editing windows are available from the Window submenu on the main menu bar in the Scene editor.

Properties

Widget-specific properties such as presentation and sound can be found in the Properties editor.

Positioning and Scaling

Fine tuned control of widget position and scaling can be found in the Positioning editor. The Positioning editor provides the functionality to adjust the position of the four faces of a widget or an entire scene independently via numerical values. The scene or widget's width and height in pixels can also be adjusted through the Positioning editor.

It is worth noting that the relationship between a scene and its widgets or a widget and its child widgets can result in the propagation of position and scale changes. In an example with a widget that has a child widget, adjusting the position of one of the parent widget's faces will not only result in scaling the widget in the direction that the face was moved. It will also result in scaling the child widget in the same direction by an equal percentage. The relationship is the same between a widget and a scene being that all widgets in a given scene are children of that scene.

 

The numeric representation of the selected scene's or widget's faces can be interpreted in six different ways that can be selected from the drop down menu provided under the Scale Type caption that is present for each face. These six representations are actually a result of interpreting three primary representations, Viewport, Scene and Object in terms of both pxiels and percentages. Both pixel and percentage representations are available to provide the option to maintain either a finite pixel offset or a relative percentage based ratio depending upon what the situation may require. Choosing any of these Scale Types will redefine what the value listed under the Face Value caption means for the face that it corresponds to. The following Scale Types are available.

PixelViewport

The value of the Face Value using this Scale Type is equal to the absolute pixel value of the given face in relation to the viewport's origin (0,0) in the upper lefthand corner of the viewport. The viewport frame defines the extent of the viewport area and is visible as the blue rectangle in the scene viewport.

PixelScene

The Face Value of the top and left faces using this Scale Type is equal to the absolute pixel value of the given face in relation to the scene's origin (0,0) in the upper left corner of the scene. The Face Value of the right and bottom faces is equal to the pixel distance from their opposite faces which is the same as the width and height of the widget. The scene frame defines the extent of the scene's area and is visible as the green rectangle in the scene viewport. By default, a scene's frame will be the same dimensions as the viewport frame and may be covered by the blue rectangle of viewport frame as a result.

PixelOwner

The Face Value of the top and left faces using this Scale Type is equal to the absolute pixel value of the given face of the widget in relation to its parent's upper left corner. The Face Value of the right and bottom faces is equal to the pixel distance from their opposite faces which is the same as the width and height of the widget. If the selected widget has no parent widget then its parent will be the scene in which case this Scale Type will be equal to the PixelScene type.

PercentageViewport

The value of the Face Value using this Scale Type is equal to the percentage of the given face's absolute pixel offset from the viewport's upper left corner divided by the viewport's width or height depending upon the face. For example, a Face Value of zero for the left face of a widget will have the widget's left face exactly aligned with the viewport's left face. In the same scenario, a value of one would have the widget's left face aligned exactly with the right face of the viewport since a value of one implies an offset of 100% of the viewport's width.

PercentageScene

The value of the Face Value using this Scale Type is equal to the percentage of the given face's absolute pixel offset from the scene's upper left corner divided by the scene's width or height depending upon the face. For example, a Face Value of zero for the left face of a widget will have the widget's left face exactly aligned with the scene's left face. In the same scenario, a value of one would have the widget's left face aligned exactly with the right face of the scene since a value of one implies an offset of 100% of the scene's width.

PercentageOwner

The value of the Face Value using this Scale Type is equal to the percentage of the given face's absolute pixel offset from its parent's upper left corner divided by the its parent's width or height depending upon the face. For example, in a scenario with a widget that is a child of another widget, a Face Value of zero for the left face will have the widget's left face exactly aligned with its parent's left face. In the same scenario, a value of one would have the widget's left face aligned exactly with the right face of its parent since a value of one implies an offset of 100% of its parent's width.

Docking

Different widgets in a scene have the ability to dock to each other. The term docking is use to describe a relationship between the edges of two or more widgets. In an scenario with two widgets, if an edge of widget one is docked to an edge of widget two, any changes made to the position of the docked edge of widget two will be propagated to the docked edge of widget one. This relationship can be best explained through example.

Setting up a docking relationship requires at least two or more widgets in the scene as well as being selected on the selection tool () that is available from the button panel at the top of the UIScene editor window. Upon selecting a widget that is placed in a scene, four circles will become apparent in the center of each edge. Each of these circles is a docking handle for the edge that it is closest to. By clicking and dragging one of these handles a link will be drawn between the handle and the mouse cursor. This link can be dragged over another widget in the scene which will trigger this second widget's docking handles to be drawn. Dragging the link over one of the second widget's docking handles and releasing will dock the two edges of these widgets.



Now when the second widget's docked edge is dragged in a direction, the first widge's dock edge is moved the corresponding amount. Padding between the position of the first widget's docked edge and the second widget's docked edge can be modified through the docking editor. The docking editor can be accessed by right clicking on the first widget in the relationship and selecting docking editor from the contextual menu. The padding values that can be defined through the docking editor indicate the amount of offset between the two docked edges' positions. The docking relationship can be removed by simply right clicking in the circle from where the docking relationship originated and selecting Break Docking Link.

Scene Tools

Styles

Styles control how a widget is displayed. A style might contain information about how to render a texture (scaled, stretched, etc.), and it may also contain information for drawing a string (font, color, attributes, etc.). The look of a widget can be changed from state to state by modifying its style. Different widgets may require different types of styles (currently there are text, image, and combo). A user can create one style and then apply it to many widgets in the scene so they share the same properties. All the styles live in a container called a Skin which is saved as a separate package file. There has to be at least one Skin file for the complete game UI. You can add, remove, edit styles in the particular skin through the Styles browser located in the Scene Tools Panel

Style Hierarchy

When creating a new style, you can base it on an existing style by choosing a template for it. New style will then appear as a child node of the existing style in the tree hierarchy and it will also create a special bond between them. The relationship between styles in the hierarchy is very similar to relationship between archetypes and archetype instances. When a new style is created based on an existing style, the existing style will become an archetype for the new style. From now on, whenever you modify any property of the parent style, that change will be automatically propagated to the child styles if that property wasn't overridden in the child style, just like in case of archetypes and archetype instances. This propagation process happens on a state by state basis which means that changes made to the Enabled state in the parent style will be propagated only to the Enabled states of children styles.

Creating a New Style

To create a new style in the current skin right click on an item in the style browser and choose Create New Style. Then you will get a window asking for the style type, unique tag, name and template. Template indicates which style you want to base the new one on, and will insert the new style as a child of the existing style. After you click OK, new style will be created, and immediately a style editor window will be displayed.

 

Editing a Style

You can edit a style through a style editor. You can open in a few ways, one: selecting "Edit Style" from the styles browser, two: right clicking on the widget and selecting Edit Style from widget's pop up menu. Style editor window will also pop up automatically when creating a new style. Here is an example of one style editor window explaining different areas of it. This editor displays properties of a text style, style editor will look differently based on what type of style you are editing.

1. Common Properties	Contains some common properties that apply to all types of styles and also lets you choose/edit specific states of the style. If the checkbox next to a state is blank, this means that this style's values for this state will be inherited from the same state in the parent style. So you must check the box next to the state if you want to override any of the parent style's properties for this state
2. Custom Properties	Shows properties specific to style type you are currently editing, it will be different for text styles and image styles.
3. Preview Window	Shows a preview of how the current property values will affect the widgets.

Assigning a Style to a Widget

Right click on a widget to bring up its pop up menu. Then choose Select Style and you will get a list of styles available to assign. Style currently assigned to the widget will have a checkmark next to it. Pick style you want and widget will update itself with the new style.

Skins

The UI system supports the idea of skins, creating custom skins for scenes, and reusing skins for multiple scenes. A skin is a container for styles. The complete game UI is required to have at least one skin package that will serve as the default skin package. The default skin will contain base versions of styles that can be applied to all the scene widgets in the game. Users can add, edit, and remove styles from the skins.

Custom Skins

Users can create custom skins, but they need to be based directly or indirectly on one default skin package. In addition to adding, editing and removing styles, users can also override or replace the styles derived from the default skin package. When a new custom skin is created it doesn't contain any styles directly, but it imlicitly contains references to the parent skin styles. You can replace these references with actual custom copies of a style. If you replace a style reference instead of creating a new style, then base skin style will become an archetype for the replaced copy and changes done to the archetype will propagate automatically to style replaced in custom skin. In addition these two styles will have the same underlying ID which means you can change skins from the default skin to the custom skin and the overridden styles will automatically apply onto widgets which used the original style version in the base skin. This allows to quickly change the skins between scenes without changing the underlying widget styles manually. You may still choose to assign a completely different style to a particular widget, but this only changes the style of that widget for that skin and any skin that is based on the custom skin. Custom skins can be hierarchical, in that custom skin sets can be based from other custom skin sets.

Using a custom skin in-game

To tell the engine to use your custom skin, you need to add the following line to your Game's DefaultUI.ini:

[Engine.UIInteraction]
UISkinName="MyPackageName.MySkinName"

Creating a Custom Skin Set

To create a custom skin set based on an existing skin go to the Styles Browser located in the Scene Tools panel in the UI Editor. Next to the box displaying current skin name is a button with an exclamation mark ( ). Click on it and select Create New Skin. Then you will be prompted to enter the following information: Package Name - name of the package file where the new skin will be saved, Skin Name - name of the new custom skin. Then click OK and the new custom skin will be created. If you now select to use the new skin it will appear empty, but since it was based on another skin it implicitly contains references to styles from the base skin. This means you can still apply the same styles to widgets as if you were using the base skin. At this point you can either create new styles in the custom skin or override the base skin styles. Note If you specified a name of the package which does not exist, it will be created for you, but it may not automatically appear in the generic browser unless you refresh the view.

Overriding Base Styles in the Custom Skin Set

Once you have created a custom skin you can proceed to override any styles from its base skin. To do that you must open your custom skin in the Skin Editor. Go to the Generic Browser in the Unreal Editor, open the package where you saved the custom skin, and double click on the custom skin with the left mouse button. You should then see a Skin browser window where you can view the skin hierarchy, override base skin styles in the custom skin, and also add, edit, and remove custom styles. The list of styles displayed in the Styles tab may contain items which are displayed in italics. This means that the particular style is not actually present in this custom skin, but it is present in the parent skin, and the custom skin implicitly contains a reference to it. You can override or replace this reference with a custom version of the style by right clicking on an item displayed in italics and selecting Replace Style Style Name In Current Skin. You will notice that item's font will lose the italics and at this point the custom skin will contain its own copy of the style.
 

Changing Skins

To change the skin that is used for your scene, first make sure that the package with your skin has been loaded in the generic browser. Then go to the drop down box located in the Styles tab of the Scene Tools panel and select the appropriate skin.

Data Stores

The data that a widget visual presents is typically controlled by the Style that it is using and its properties, while the data a widget can manipulate is usually defined through logic in the UI Kismet editor. The functionality that Styles and Kismet provide is described later in the guide, however Data Stores also provide a source for data that widgets can present and modify. Currently, Data Store functionality is limited to presentation of string data, but in future Data Stores will provide widgets with image data as well as game state and game settings data that can be displayed, modified and communicated back to the game.

Using Data Stores for string data requires the creation of a widget that has the ability to present string data such as a label or a label button. Once the widget is created, simply select the widget with the selection tool () and then navigate to the Data Stores tab which can be found on the Scene Tools panel. Within the Data Stores tab two viewports will be visible. The top viewport displays a listing of available data store categories. The lower viewport labeled Data Store Tags displays a listing of available data stores in the category that is selected in the categories viewport above. The Data Store Tags viewport will only populate if the selected category does not have any sub-categories.

A list of string categories can be made visible by expanding the Strings selection in the categories viewport. Expanding the Strings selection will reveal additional listing of string categories. These sub-categories of strings can be expanded further. Selecting a category at the bottom of a given branch will populate the Data Stores Tags viewport with a listing of available strings. Binding one of the strings to the selected widget is done by right clicking on the desired string. A contextual menu will be presented with the option to Bind selected widgets to the given string which when selected will change the widgets label to the value of the selected string.

 

1. Categories Viewport	The data store category viewport displays a list of all available data store categories.
2. Tags Viewport	The data store tags viewport displays a list of the individual data stores in the selected category.

Focus Chain

In a scene, traditionally a widget that is in the Focused state is the widget that receives the user's input. This will be the case by default for most widgets, though this behavior can be redefined through the Modify Default UI Event Key Bindings editor under the Edit menu. The functionality provided by Modify Default UI Event Key Bindings editor will be discussed in more depth in the Input Handling section. For the purpose of describing the Focus Chain system the assumption will be made that the widget that is in the Focused state will be the widget that is receiving input.

The Focus Chain system is the way that the designer can define which widget will transition into the Focused state when the widget that is currently in the Focused state receives a NavFocus event via relevant user input. The relevant input that will trigger this change of focus from the current widget is defined by which keys will trigger a NavFocus event. Information about event key bindings will be discussed further in the Input section. The term Focus Chain stems from the concept that the designer can define a system of links between widgets in a UI scene or a chain that will represent where the focus will move between widgets. It should be noted that the input that generates the NavFocus events which trigger the behavior defined by the Focus Chain is know as "unbound navigation". Conversely, "bound navigation" is that which generates NextControl and PreviousControl events which results in focus changing behavior that does not adhere to the focus chain, but instead simply cycles through widgets in a linear fashion. The NextControl and PreviousControl events are bound to the Tab key by default.

Creating a Focus Chain for widgets in a UI scene is done by selecting the Focus Chain Tool () from the button panel at the top of the UIScene editor window. Upon clicking on a widget after selecting the tool, the selected widget will display diamonds in the middle of each edge of the widget. Each of these diamonds corresponds to a given event NavFocus event. For example, the diamond in the middle of the right edge corresponds to where focus will go upon the widget receiving a NavFocusRight event that could be triggered when the user presses the right arrow key. Like the Docking tool, the designer can click and drag one of these diamonds to create a link that can then be dragged to another widget in the scene. A focus link or chain between the two widgets will be created upon releasing the mouse button over the desired widget. Links between widgets can be removed by right clicking on the diamond and selecting Break Focus Chain.



You may have noticed that after selecting a widget with the Focus Chain Tool () that focus links between the widgets in the scene had already been created. This is because whenever a widget is placed in a scene with other widgets, the UI system will atempt to auto-generate focus links between the new widget and its surrounding widgets based upon where it was originally positioned in the scene.

Input

The Unreal UI tool allows designers to assign and modify the key bindings associated with widgets on a state basis.

Opening Modifying Default Key Bindings

We can modify the key bindings set by default on widgets using the Bind UI Event Key Defaults window. This window can be accessed by selecting Modifying Default Key Bindings from the Edit menu in the Scene Editor or by just pressing F8.

Modifying Default Key Bindings Overview

Using the functionality of the Bind UI Event Key Defaults window global changes can be made to the way all widgets of a certain type respond to user input. This means that if we change the key binding for the Clicked Input Event Aliases on the button widget, the change will propagate to all button widgets in our package. The behavior of an individual widget can also be changed via a method that is desribed in the Binding Keys to Individual Widgets section. The process of interpreting the data proivded by the Bind UI Event Key Defaults window can best be described through an example. Lets look at the Clicked Input Event Alias for the button widget.



Notice we have 3 bound keys associated with this Input Event Alias. Lets look a bit deeper into the bound keys section of the menu.

Here we see a table with the keys bound to the Clicked Input Event Alias and in which states this event will be triggered when the key is pressed. The first column on the table is the name of the key. The remaining columns are the different states that will be listening for the key press. In this case LeftMouseButton uses the Active state, indicating that the mouse cursor needs to be hovering over the button widget when the key press occurs for the Input Event Alias to be triggered. In the case of Enter and SpaceBar the button widget must be in the Focus state for the Clicked event to be triggered.

We can add as many key bindings as we want to any particular event. We can also remove bindings, but keep in mind these changes are global for all widgets of the type you are changing.

Adding Key Bindings to An Input Event Alias

Adding Key Bindings to An Input Event Alias is done by first selecting the type of widget you wish to modify in the Bind UI Event Key Defaults window. Then the Input Event Alias we want to add a key binding to should be selected followed by selecting the key we wish to bind to the Input Event Alias from the Available Keys list. Once these selections have been made, simply click the button. After this is done the new key binding will appear in the Bound Keys table and we can then modify the states that this key will be processed in.



You can also remove key bindings by selecting the key binding to be removed from the Bound Keys table and pressing the button.

NOTE: Double check that you've actually assigned keys to the input aliases for the widget in the UI input alias dialog. This is the most common reason why an input key is not processed (via ProcessInputKey) for widgets.

Enabling and Disabling Input Event Aliases

In addition to defining which keys are bound to which Input Event Aliases, it is also possible to enable or disable which Input Event Aliases an individual widget will respond to. Editing the Input Event Aliases a given widget will respond to is done through the Edit Widget Events dialogue. This dialogue is opened by right clicking on the widget in the Scene editor viewport and selecting Enable/Disable Widget Events from the contextual menu that appears. Within the Edit Widgets Events dialogue Input Event Aliases can be checked or unchecked to enable or disable the event alias for the selected widget. The Bind UI Event Key Defaults window, that is described in the Modifying Default Key Bindings Overview section, can also be opened from the Edit Widget Events dialogue should the key bindings for an Input Event Alias need to be changed.

Binding Keys to Individual Widgets

Previously we learned how to change key bindings for widget Input Event Aliases for all widgets of a given type. This meant that if we changed the key binding for a given Input Event Alias the changes would propagate throughout all the widgets of that particular type. However, it is more than likely that we would want to change the key bindings of a particular widget rather than all widgets of a given type. This can be done through the use of Kismet Events. For the purpose of this topic we will only discus the aspects of Kismet that are peritnant to input. For more information of Kismet in UnrealUI visit the Kismet section.

To access the Kismet editor for a given widget right click on the widget in Scene Viewport of the Scene editor and select Kismet from the contextual menu. Once in the Kismet editor you will need to select the sequence that corresponds to the state you wish to modify the key bindings in.



Upon selecting a sequence the Sequence Editor should display a State Input Event. This Kismet event acts as a key bindings editor that is local to this specific widget in the current state. Each state that the widget has a Kismet sequence for will have a State Input Event created for it by default. It is through this Kismet event that we can add our custom bindings for this specific widget. This is done by double clicking on the State Input Events event to open Bind Event Keys window.



Within the Bind Event Keys window there is an interface to bind keys to this widget for the given state that is similar to the binding interface in the Default Key Bindings window. It is worth noting that the Availble Keys window within the Bind Event Keys window offers the additional functionality to bind key presses, releases and repeats rather than just the presses like the Bind UI Event Key Defaults window in the Scene editor. To add a key binding we select it form the available keys list and click on the button.



New key bindings that are created through the Bind Event Keys window will be represented by new output handles on the State Input Event. These output handles can be used to trigger Kismet behaviors on their specified key presses. An explaination of Kismet behaviors can be found in the Kismet section.

Override Default Bindings for an Individual Widget

Using the method described in the Binding Keys to Individual Widgets sections it is also possible to rebind keys for an individual widget that have already been bound via Bind UI Event Key Defaults window in the Scene editor. This means that using the functionality provided by the State Input Event it is possible to not just add new key bindings to an individual widget, but also redefine the key bindings that are defaults for any widget of its type.

Whenever a key that is bound to an Input Event Alias by default is rebound by the Kismet State Input Event the word OVERRIDE will appear next to that input key's output handle as depicted below.

 

Using Sound Cues

The ClickedCue property of a Widget is referring to the name of a UISoundCue. UISoundCues are similar to the input alias system by allowing you to separate the actual resource being used from the logical action you want to perform.

It takes a couple of steps to set up SoundCues for Widgets so that you could have different sounds associated with the same sound cue name in different skins. For example, the sounds used in your game's front-end skin have could a lot more detail, etc., but have your in-game skin use sounds that take as little memory as possible.

Configuration

Open your game's DefaultUI.ini file and you should see a list of UISoundCueNames in the [Engine.UIInteraction] section. (The section name might be different if your game is using a custom interaction class - most games do.) That list defines the available names that are valid for UI sound properties (like the ClickedCue property of the UIButton).

Skins

Now find your UIskin in the Generic Browser and double-click it to open the Skin Editor. Select your game's skin in the left pane, then click the Sound Cue tab in the right pane. Right-click in the right pane and select Add Sound Cue. The dialog that's shown will allow you to link those sound cue names with an actual sound cue.

Using Kismet

Unreal Engine 3's UnrealKismet^? tool is a very flexible and powerful tool that allows non-programmers to script complex gameplay flow in level. The UnrealUI System utilizes the foundation of the UnrealKismet^? system to allow non-programmers to script complex user interface behavior. It works by allowing a designer to connect simple functional Sequence Objects to form complex sequences just like Kismet does for gameplay.

Opening the Kismet Editor

The UI Kismet Editor can be opened by right clicking in the scene window and selecting Kismet Editor from the contextual menu or by right clicking on the UI Scene's icon () in the Scene tab of the Scene Tools panel and selecting Kismet Editor from the contextual menu.

Kismet Overview

Kismet Editor Layout

1. Sequence Browser	The sequence browser shows state sequences in a state folder under the scene and each widget name in the tree.
2. Sequence Editor	Selecting a node in the sequence browser will select it in the editor graphic view.
3. Properties	The properties of currently selected item within the editor.

Working with Sequences

Sequences

The overall concept of a sequence in UnrealUI Kismet has not changed not from UnrealKismet^?. A sequence is still a collection of Sequence Objects that can interact with each other to achieve various complex behaviors. However the ability to build complex hierarchies of sub-sequences has changed. In the context of UnrealUI sub-sequences are not created by the designer, but instead exist in terms of scenes, widgets and states. Every widget and scene that is created will inherently have a Global Sequence in addition to a variable number of sequences that are associated with a given state that the widget supports. Sequence Objects that exist in the Global Sequence are active all of the time, however Sequence Objects that exist in the state sequences are only active when the widget is in that state.

Sequence Objects

Sequence Objects are the fundamental building block of a Kismet sequence. The functionality provided by the various objects is what provides the ability to script complex behaviors for scenes and widgets. There are four types of Sequence Objects which include Events, Conditions, Actions, and Variables. These objects are defined below.

Events

These are objects that create an input to your sequence to trigger Conditions and Actions. They are denoted by a red diamond that will have an output of the right side and possibly an activator variable on the bottom that is used to indicate which widget triggered the event. Events can be triggered by a number of catalysts varying from user input to scene or widget state changes. Upon being triggered, events will provide output that can be used as input for Actions or Conditions. For a complete list of the Events that are currently available see the UI Sequence Object reference.

Conditions

These are objects that act as flow control for the sequence. They are denoted by a blue rectangle that will have inputs on the left side, outputs on the right side and the relevant variables on the bottom. Conditions basically act as a way to redirect input into a sequence based upon the state of some variable. For a complete list of the Conditions that are currently available see the UI Sequence Object reference.

Actions

These are objects that perform some action on the widgets in your scene or the scene itself. They are denoted by a pink rectangle with inputs on the left, outputs on the right and variable connections on the bottom. Actions are triggered by some input which usually takes the form of the output of an Event or an Action. For a complete list of the Actions that are currently available see the UI Sequence Object reference.

Variables

These objects simply store information of a particular type for use by an Event, Action or Condition. They are denoted by a circle that will vary in color depending upon the type of Variable. The information that a Variable Sequence Object stores can be local to the sequence or it can pertain to global data outside of the Kismet sequence like a widget. Creating a Variable that is associated with a widget in a scene is done by selecting the widget in the Scene Editor and then right clicking in the Sequence Editor of Kismet or on a given sequence in the Sequence Browser. The contextual menu that is used for creating any Sequence object will appear with the additional selection of New Object Var Using "Widget Name" where widget name is the name of the selected widget in the Scene Editor.

Creating Sequence Objects

Creating Sequence Objects in a given sequence can be done in two ways. The first approach requires that the sequence the object will be added to be selected in the Sequence Browser. Next, simply right click in the Sequence Editor and select the desired new object from the contextual menu. The second approach is to right click on a sequence in the Sequence Browser and select a new object from the contextual menu.

Creating Behaviors

Creating a useful sequence in Kismet requires a basic overview of creating relationships between Sequence Objects. The various types of Sequence Objects that can be placed in a sequence all have contain some input and output handles. Connections can be made between an object's outputs handles and another object's inputs. These input and output handles will usually have certain restrictions upon what they can be connected or linked to. Some of these restrictions are implicit like the requirement that inputs only accept links to outputs. Others restrictions are displayed through color coding like in the example below where the Activate UI State Action will only modify Object Variables which are denoted by the color pink.

The images below display a basic example of a Kismet behavior involving an Event that acts as input for an Action that affects a Variable. Creating the link between the Scene Opened Event and the Activate UI State action is done by clicking and dragging the output handle of the Event to the input handle of the Action. If a link can be established then the destination handle will change color at which point releasing the mouse button result in a link being created. In the case of Variables, the entire circle that denotes the Variable acts as a handle that can be connected to.

Sequence Object Reference

The following reference defines Kismet Events, Conditions, Actions and Variables that are unique to the UnrealUI's implementation of Kismet. The functionality of all other Kismet sequence objects is carried over from UnrealKismet^? and can be referenced in the UnrealKismetReference.

Events

Data Submitted

Submit Text

This event is triggered as a result of the Widget Input Alias Event by the same name, Submit Text. This event can have two variables associated with it and results in one output. The first variable is an object variable called an activator. The activator's behavior is explained in the event description of the Sequence Object section. The second variable is a string variable that will be set to the contents of the text buffer of the widget that fired the event.

UI

Enter State

This event is triggered when the owner of the sequence it resides in enters a new state. This event can have one variable associated with it and results in one output. The variable is an object variable called an activator. The activator's behavior is explained in the event description of the Sequence Object section.

Initialized

This event is triggered when the owner of the sequence it resides in is initialized. This event can have one variable associated with it and results in one output. The variable is an object variable called an activator. The activator's behavior is explained in the event description of the Sequence Object section.

Leave State

This event is triggered when the owner of the sequence it resides in leaves its current state. This event can have one variable associated with it and results in one output. The variable is an object variable called an activator. The activator's behavior is explained in the event description of the Sequence Object section.

On Click

This event is triggered when the owner of the sequence receives input that is bound to the Clicked Input Event Alias for the current state. This event can have one variable associated with it and results in one output. The variable is an object variable called an activator. The activator's behavior is explained in the event description of the Sequence Object section.

Scene Closed

This event is triggered when the current scene is closed. This event can have one variable associated with it and results in one output. The variable is an object variable called an activator. The activator's behavior is explained in the event description of the Sequence Object section.

Scene Opened

This event is triggered when the current scene is opened. This event can have one variable associated with it and results in one output. The variable is an object variable called an activator. The activator's behavior is explained in the event description of the Sequence Object section.

State Input Event

This event is triggered whenever key input that is bound to it occurs. This event has no variables and it can have a number of different outputs. Each output corresponds to an input key that has been bound to it. For more information on the use and configuration of the State Input Event see the Binding Keys to Individual Widgets section.

Value Changed

Checkbox Value

This event is triggered when the checkbox widget that owns the sequence that this event resides in changes value. This event can have two variables associated with it and results in two outputs. The first variable is an object variable called an activator. The activator's behavior is explained in the event description of the Sequence Object section. The second variable is a bool variable that will set to the value of the checkbox widget after the event occurred. The two outputs are True and False. The output that is used will depend on the value of the checkbox widget after the event was triggered.

Editbox Value

This event is triggered when the editbox widget that owns the sequence that this event resides in changes value. This event can have two variables associated with it and results in one output. The first variable is an object variable called an activator. The activator's behavior is explained in the event description of the Sequence Object section. The second variable is a string variable that will set to the value of the editbox widget's text entry buffer after the event occurred.

Slider Value

Todo.

Conditions

All conditions in UnrealUI Kismet function the same as in UnrealKismet^?. See UnrealKismetReference for details.

Actions

Misc

Console Command

See UnrealKismetReference for details.

Set Value

Set Bool Value

See UnrealKismetReference for details.

Set Label Text

This action will set the label text of a label widget or a label button widget. This action has one input, one output and two variables. Upon receiving an input the action will set the label text of the widget that is specified through the object variable to the value of the string that is specific through the string variable. After performing this behavior the action will provide an output that can be used to trigger other actions or conditions.

UI

Activate Initial State

This action is used to set a widget into its initial state. This action has one input, one output and one variable. The variable is an object variable that specifies the widget that will be returned to its initial state. After performing this behavior the action will provide an output that can be used to trigger other actions or conditions.

Activate UI State

This action is used to change a widget's state. This action has one input, one output and one variable. The variable is an object variable that specifies the widget whose state will be changed. The state that the widget will enter is specified in the StateType property. After performing this behavior this action will provide an output via either the Successful or Failed outputs depending upon whether the action was successful. The action can fail if the specified widget does not support the state that is specified by the action.

Change Visibility

This action is used to change a widget's visibility. This action has one input, one output and one variable. The variable is an object variable that specifies the widget whose visibility will be changed. The visibility of the widget, either true or false, is specified in the bVisible property. After performing this behavior the action will provide an output that can be used to trigger other actions or conditions.

Close Scene

This action is used to close a scene. This action has one input, one output and one variable. The variable is an object variable that specifies the scene that will be closed. After performing this behavior this action will provide an output via either the Successful or Failed outputs depending upon whether the action was successful. The action can fail if the specified scene is in a scenario where it cannot be closed.

Deactivate UI State

Todo

Open Scene

This action is used to open a scene. This action has one input, one output and one variable. The variable is an object variable that specifies the scene that will be opened. After performing this behavior this action will provide an output via either the Successful or Failed outputs depending upon whether the action was successful. The action can fail if the specified scene is in a scenario where it cannot be opened.

Set Focus

This action is used to set focus to a widget in a scene. This action has one input, one output and one variable. The variable is an object variable that specifies the widget that will enter the Focus state. The widget that is specified can be in a different scene or a scene that is not loaded. In such a case, the scene that the widget resides in will become active and it will be loaded if necessary. After performing this behavior this action will provide an output via either the Successful or Failed outputs depending upon whether the action was successful. The action can fail if the specified widget is in a scenario where it cannot enter the Focus state.

Variables

All variables in UnrealUI Kismet function the same as in Kismet^?. See the Kismet Reference^? page for details.

Archetypes

For more information on working with Archetypes, see the Using Archetypes page.

---

Widget Reference

Widget Input Event Aliases

Widget Input Event Aliases are how the UI system maps platform specific input keys to platform independant input events. Input events can be thought of as behaviors that are necessary for various features of specific widgets and the UI system in general. These input events are common to any platform, be it PC, Xbox360 or PS3, so Input Event Aliases act as a way of associating common input events with platform specifc input keys. These Input Event Aliases should not be confused with Kismet events.

Consume

Any input bound to this event alias will be deleted and will not trigger any other event alias it may be bound to. The input will also not be propagated to other widgets in the scene.

NextControl

Input that is bound to this event alias is considered "bound navigation" because it triggers a focus change between widgets, but does not adhere to the Focus Chain. This event alias will result in focus being passed to the next widget in the list of scene widgets.

PreviousControl

Input that is bound to this event alias is considered "bound navigation" because it triggers a focus change between widgets, but does not adhere to the Focus Chain. This event alias will result in focus being passed to the previous widget in the list of scene widgets.

NavFocusUp

Input that is bound to this event alias is considered "unbound navigation" because it triggers a focus change between widgets that does correspond to the Focus Chain. This event alias will result in focus being passed to the widget that is linked to the current widgets top Focus Chain handle if a link exists.

NavFocusDown

Input that is bound to this event alias is considered "unbound navigation" because it triggers a focus change between widgets that does correspond to the Focus Chain. This event alias will result in focus being passed to the widget that is linked to the current widgets bottom Focus Chain handle if a link exists.

NavFocusLeft

Input that is bound to this event alias is considered "unbound navigation" because it triggers a focus change between widgets that does correspond to the Focus Chain. This event alias will result in focus being passed to the widget that is linked to the current widgets left Focus Chain handle if a link exists.

NavFocusRight

Input that is bound to this event alias is considered "unbound navigation" because it triggers a focus change between widgets that does correspond to the Focus Chain. This event alias will result in focus being passed to the widget that is linked to the current widgets right Focus Chain handle if a link exists.

Clicked

Input that is bound to this event alias will result in the Kismet event OnClicked as well as transitioning the widget that receives it into the Pressed state if the widget supports that state.

SubmitText

Input that is bound to this event alias will result in the Kismet event Submit Text as well as transitioning the widget that receives it into the Pressed state. The Submit Text Kismet event includes a parameter that contains whatever text was in the widget's text entry buffer at the time of the input. This is applicable for widgets that support a text buffer such as the Editbox.

Char

Input that is bound to this event alias will be added to the widget's text entry buffer in the form of the character that the input key corresponds to. The character will be added at the text cursor's position in the buffer. This is applicable for widgets that support a text buffer such as the Editbox. Note that in order for classes like the edit box to properly handle input, the key "Character" needs to be added to the Char event.

BackSpace

Input that is bound to this event alias result in the character before the text buffer's cursor to be removed from the widget's text buffer. This is applicable for widgets that support a text buffer such as the Editbox.

DeleteCharacter

Input that is bound to this event alias result in the character after the text buffer's cursor to be removed from the widget's text buffer. This is applicable for widgets that support a text buffer such as the Editbox.

MoveCursorLeft

Input bound to this event alias will cause the text buffer cursor to move one character to the left in the widget's text buffer. This is applicable for widgets that support a text buffer such as the Editbox.

MoveCursorRight

Input bound to this event alias will cause the text buffer cursor to move one character to the right in the widget's text buffer. This is applicable for widgets that support a text buffer such as the Editbox.

MoveCursorToLineStart

Input bound to this event alias will cause the text buffer cursor to move to the beginning of the current line in the widget's text buffer. This is applicable for widgets that support a text buffer such as the Editbox.

MoveCursorToLineEnd

Input bound to this event alias will cause the text buffer cursor to move to the end of the current line in the widget's text buffer. This is applicable for widgets that support a text buffer such as the Editbox.

DragSlider

Input that is bound to this event alias will result in relative mouse cursor movement being added or subtracted to a slider widget's current value.

IncrementSliderValue

Input that is bound to this event alias will increment a slider widget's current value by the nudge value defined in the slider's properties. This alias is only applicable to slider widgets.

DecrementSliderValue

Input that is bound to this event alias will decrement a slider widget's current value by the nudge value defined in the slider's properties. This alias is only applicable to slider widgets.

IncrementNumericValue

Input that is bound to this event alias will increment a numeric editbox widget's current value by the nudge value defined in the numeric editbox's properties. This alias is only applicable to numeric editbox widgets.

DecrementNumericValue

Input that is bound to this event alias will decrement a numeric editbox widget's current value by the nudge value defined in the numeric editbox's properties. This alias is only applicable to numeric editbox widgets.

Widget States

A Widget State is a condition that a widget can be put into that can contain specific user input settings, Kismet logic, and style data. The listing below outlines the default behavior of the different Widget States, however most of the widget properties in a given Widget State can be modified.

Active

A widget will enter the active state when the mouse cursor is over the given widget.

Disabled

A widget in this state cannot be put in the Focus state via the Focus Chain system or NextControl and PreviousControl Input Event Aliases. A widget in the Disable state cannot change its own state. The children of a widget that is put into the Disabled state will also be set to the Disabled state.

Enabled

A widget that is in the Enabled state can receive focus through the Focus Chain system or NextControl and PreviousControl Input Event Aliases.

Focused

A widget will be put into this state when another widget sets its state to Focused via the Focus Chain or NextControl and PreviousControl Input Event Aliases. A widget that is in the Focus state will receive user input.

Pressed

A widget will enter this state when it is in the Focus state and receives user input that is bound to the Input Event Alias Clicked.

Widgets

• Panel - The primary purpose for this widget is to act as a container for other widgets. Any other widget can be made a child of a panel creating a relationship that will propagate any position or scale changes made to the panel to its child widgets. This widget is capable of displaying a texture via the style it is using or by explicitly setting its PanelBackground property in the image category of it properties.
  • Widget Input Event Aliases - Consume, NextControl, PreviousControl, NavFocusUp, NavFocusDown, NavFocusLeft, NavFocusRight.
  • Widget States - Active, Disabled, Enabled, Focused.

• Label - This widget acts as a simple method for displaying text. The text this widget displays can be bound to a Data Store or input into the Markup String field of its Data Source property which is listed under the Data category of its properties.
  • Widget Input Event Aliases - Consume, NextControl, PreviousControl, NavFocusUp, NavFocusDown, NavFocusLeft, NavFocusRight.
  • Widget States - Active, Enabled, Disabled.

• Button - The primary purpose of a button is to trigger events when it is clicked or activated by user input or other state changing events. This widget is capable of displaying a texture via the style it is using or by explicitly setting its ButtonBackground property in the image category of it properties.
  • Widget Input Event Aliases - Consume, NextControl, PreviousControl, NavFocusUp, NavFocusDown, NavFocusLeft, NavFocusRight, Clicked.
  • Widget States - Active, Disabled, Enabled, Focused, Pressed.

• Label Button - This widget behaves the same as a Button with the addition functionality of a Label.
  • Widget Input Event Aliases - Consume, NextControl, PreviousControl, NavFocusUp, NavFocusDown, NavFocusLeft, NavFocusRight, Clicked.
  • Widget States - Active, Disabled, Enabled, Focused, Pressed.

• Image - This widget acts as a simple method for displaying a texture. The image that this widget displays can be bound in the style editor or through its image property in the image category of its properties.
  • Widget Input Event Aliases - Consume, NextControl, PreviousControl, NavFocusUp, NavFocusDown, NavFocusLeft, NavFocusRight.
  • Widget States - Active, Disabled, Enabled.

• Checkbox - This widget behaves the same as a Button with the exception that it will toggle in or out of the pressed state upon user input rather than only remaining in the pressed state while the input key is depressed. This widget can be set to default to the pressed state by checking the bIsChecked property under the Value category of its properties. This widget is capable of displaying a texture via the style it is using or by explicitly altering the properties in the image category of its properties.
  • Widget Input Event Aliases - Consume, NextControl, PreviousControl, NavFocusUp, NavFocusDown, NavFocusLeft, NavFocusRight, Clicked.
  • Widget States - Active, Disabled, Enabled, Focused, Pressed.

• Editbox - The primary purpose of this widget is to act as a text entry field for keyboard input. Upon gaining focus the widget will display alphanumeric keyboard input within the bounds of the widget. The number of characters this widget will allow can be changed by setting the MaxCharacters property under the Text category of its properties. Properties for the setting the initial value and whether the editbox is editable or read only can also be found in the Text category of this widget's properties. The acceptable character set can also be changed through the character set property to restrict input characters.
  • Widget Input Event Aliases - Consume, NextControl, PreviousControl, NavFocusUp, NavFocusDown, NavFocusLeft, NavFocusRight, SubmitText, Char, BackSpace, DeleteCharacter, MoveCursorLeft, MoveCursorRight, MoveCursorToLineStart, MoveCursorToLineEnd.
  • Widget States - Active, Disabled, Enabled, Focused, Pressed.

• Numeric Editbox - The primary purpose of this widget is to act as a numeric text entry field for keyboard input. Upon gaining focus the widget will display numeric keyboard input within the bounds of the widget. It also contains two buttons that are used to increment and decrement its numeric value. The numeric editbox has all of the properties of the editbox widget with the addition of properties to specify the number of decimal places to display, the amount to increase or decrease the its value by upon input (nudge) and the maximum and minimum values accepted.
  • Widget Input Event Aliases - Consume, NextControl, PreviousControl, NavFocusUp, NavFocusDown, NavFocusLeft, NavFocusRight, SubmitText, Char, BackSpace, DeleteCharacter, MoveCursorLeft, MoveCursorRight, MoveCursorToLineStart, MoveCursorToLineEnd, IncrementNumericValue, DecrementNumericValue.
  • Widget States - Active, Disabled, Enabled, Focused, Pressed.

• Slider - This widget is designed to act as an interface for allowing the user to select a value between a certain range. This widget has a number of properties that are listed in the Slider category of its properties. These properties allow for the customizing of the maximum value, minimum value and current value of the value range. The amount the slider will increment through its value range upon a user input is also defined in properties as the nudge value. The visual indicator of the slider's value or marker can be customized via the marker height and marker width sections of the properties.
  • Widget Input Event Aliases - Consume, NextControl, PreviousControl, NavFocusUp, NavFocusDown, NavFocusLeft, NavFocusRight, Clicked, DragSlider, DecrementSliderValue, IncrementSliderValue.
  • Widget States - Active, Disabled, Enabled, Focused, Pressed.

• List - This widget is used for displaying table views of data. The List will only work when bound to data fields which have a type of Collection or ProviderCollection (the field type is shown in the data store browser's right pane when you click on a data provider in the left pane). Once the List widget is bound to a valid data field, you can add/insert/remove columns through the context menu (there should be a UIList menu item when right-clicking on the widget). Some data fields do not support more than one column, so there is only one item in the Add Column submenu, that data field doesn't support multiple columns.
• Combo Box - This widget consists of an Edit Box and a List. It sends two events: one when the text is changed in its Edit Box, and one when an element is selected in its List. Data for the Combo Box is handled by its List - select the Combo Box's list and bind it to a Data Store as you would any other List. While the Edit Box can be bound to a Data Store as well, the Edit Box's value is managed by the Combo Box, so any value pulled from a Data Store will be overwritten when the list is initialized or an item is selected.