UI

UI Screens are defined in text files which define the objects and actions of UI screens. They are made up for 2 main sections, animations and objects. Animations are defined first in the file, followed by objects. Animations are not required for the correct operation of most UI screens.

Objects

All objects are defined by a minimal data chunk of the form:

[<objectName>]
TYPE <type>
X <x>
Y <y>
WIDTH <w>
HEIGHT <h>

the different types of UI objects and their capabilities, defined using additional tags in the chunk, are described below. All x,y and width, height values are assumed to be based on a 1024x768 screen.

The Parent Object

The first object defined in a file is assumed to be the screen parent object.  
Any other object in the file without an explicit PARENT definition is assumed to be a child of the screen parent object.  
The screen parent object has a number of unique tags which can be set.

HANDLER <handlerName>   // handler tags hook in to the code and so should be used with caution.
                        //In most cases you will want to keep handler values as they are already set in existing/equivalent files.
MODAL                   // if set, this says that the screen is modal and prevents interaction with any screens below it in the display stack.
LEVEL <level>           // each screen is created at a fixed level in the screen layers.  It is the order in which screens are displayed.

There can be a hierarchy of parent / child objects below the screen parent object indicated by the PARENT tag on the child.  
Child objects are drawn in front of their parents and some properties (for example visibility) of a parent will automatically propagate to their children.  
When two sibling objects overlap visually, the object appearing first in the layout is drawn in front.

Additional Common Tags

DRAGGABLE <size>        // denotes that an object is draggable.  Size is the height of draggable top border.
FOCUS                   // can this object have focus (be moused over, clicked on, etc).  Some objects (e.g. buttons) are always focus-able.
SFXFOCUS <id>           // play the sound (based on the position in the sound list) when the object is moused over.
ALWAYSTOOL              // always display the tooltip text at the bottom of the object
ALWAYSTOOLX <offset>    // x display offset for ALWAYSTOOL display
ALWAYSTOOLY <offset>    // y display offset for ALWAYSTOOL display
CLIPPING                // 
DX <x>                  // horizontal position relative to parent (overrides X)
DY <y>                  // vertical position relative to parent (overrides Y)
PARENT <parentName>     // see The Parent Object

Object Types

Map Display

The Map Display control allows the use of 3D heightmapped maps which can be scrolled and broken into territories. For details see the detailed documentation. Map Display Documentation

Core Object Types

OBJECT
This is a generic UI object. It is neither visible nor interactable.

IMAGE
An image object is simply a displayed texture. Valid tags are:

FILE <filename>            // the filename of the texture. The root path is DATA\UI\TEXTURES.

You can show just a portion of a texture by using the additional tags below:

IMAGELEFT <value>
IMAGETOP <value>
IMAGEWIDTH <value>
IMAGEHEIGHT <value>

These values are in pixels, so if the texture is resized, they will need to be re-evaluated.

ANIMSPEED <speed>
ANIMFADE <value>
COLOUR <colour>        // anywhere colours are specified, they may either be ARGB hex values (ex. ffff0000) or named colours specified in the COLOURDICTIONARY chunk of DATA/UISETTINGS.TXT
KEEPSQUARE <0/1>       // keep the object aspect ratio from the layout when scaling to non 4:3 resolutions, default 0
BACKDROP               // when the screen aspect ratio is below 21:9, the texture will be cropped horizontally (ie if a 21:9 background texture is displayed in a 1024 by 768 IMAGE object with BACKDROP, it will fill the screen and maintain the correct aspect ratio at all screen ratios up to 21:9, with the left and right edges of the image removed as required)

DISPLAY

A display object is a non interactive display. It draws a simple window using a window template texture.

Valid tags:
FILE <filename>        // texture filename

The window template is laid as as follows (generally it is assumed the texture will be 256x256). The corner 1/16ths of the texture are the corners of the window - these are drawn at 64x64. The top and bottom and left and right center halves are the frames (these are stretched to size) and then the middle of the texture is stretch to cover the remaining center of the window.

STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>

Used to display a window title when used.

BUTTON

Button objects are displayed using a texture file. This file must contain 4 versions of the button. These are arranged as follows:

Normal  - top left
Moused Over  - top right
Pressed  - bottom left
Inactive (greyed)  - bottom right

Valid tags:
FILE <filename>    // texture name
STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>
IMAGEU <u>
IMAGEV <v>
GROUP <group> // the number of the group this button belongs to (for use with Get/SetUIGroupSelection commands)
GROUPINDEX <groupIndex> // the index within a group for this button (for use with Get/SetUIGroupSelection commands)
SIMPLEIMAGE <0/1> // treat the FILE as a single image rather than the 4 images described above
TEXTLEFT <x> // placement values for the text within the button (absolute if object is placed absolutely, relative to self if object is placed relatively)
TEXTTOP <y>
TEXTWIDTH <w>
TEXTHEIGHT <h>
KEEPSQUARE <0/1> // keep the object aspect ratio from the layout when scaling to non 4:3 resolutions, default 1

TEXT

A static text object used to display information to the user.

Valid tags:
STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>
CENTER        // Causes the text to be centered horizontally in the rectangle.
WINDOWEDBACK
RESCALE
FILE <filename>
TEXTLEFT <value>
TEXTTOP <value>
TEXTWIDTH <value>
TEXTHEIGHT <value>
Screen placement values for the actual text list within the main object window.
SCROLLING <filename> // adds a scrollbar to the text of needed, filename is the name for the scrolling control texture (equivalent to CONTROLTEX on a LISTBOX)
BARSIZE <size> // this size of the scrollbar is a SCROLLING control texture is specified

LISTBOX

A listbox allowing the user to scroll through and select lines. 

Valid tags:
CONTROLTEX <filename>
Required, contains all the various listbox controls. The texture is laid out as follows:
Up scroll arrow - top left
Down scroll arrow - bottom right
Scrollbar  - bottom left (this is stretched to the height of the listbox)
Scroll nub  - bottom right

FRAMETEX <filename> - used for the listbox frame
SELTEX <filename> - selection display, this is stretched across the width of the selection box
BUTTONTEX <filename> - applied to element in the listbox, texture layout is the same as a BUTTON type

TEXTLEFT <value>
TEXTTOP <value>
TEXTWIDTH <value>
TEXTHEIGHT <value>
Screen placement values for the actual text list, absolute if list is placed absolutely, relative to list if object is placed relatively

FONT <fontname> - the font of the listbox item text
COLOUR <colour> - the colour of the listbox item text.
BARSIZE <value> - Sets the size of the scrollbar. Default value is 32.
ITEMSPACING <value> - spacing between listbox items (vertical or horizontal depending on type of listbox), default value is 0
ITEMSIZE <value> - the size of the listbox items (vertical or horizontal depending on type of listbox), default is the height of one line of text for vertical listboxes and the max width to fit all items for horizontal listboxes
HORIZONTAL - causes the items to be displayed horizontally across the listbox, only the arrow elements of CONTROLTEX are used (and rotated) for left/right scrolling

EDITBOX

A single line text entry box.

Valid tags:
FONT <fontname>
COLOUR <colour>
MAXCHARS <count>
Defines the display of the listbox item text.

REGIONMAP

A specialist control for representing a map of distinct regions.

Valid Tags
FILE <texture>

The texture for the region map must be crafted in a specific way.  It should be a 4 channel TGA file.  The channels in the file are used in the following way:

R - a monochrome image layer.  A region is coloured with its owning sides colour modulated with this channel.
G - selected layer.  The currently selected region has this layer coloured with the defined selection colour and blended with the normal map pixels.
B - currently unused
A - region layer.  The alpha value of each pixel denotes which region the pixel belongs to.  Value 255 is a special value for invalid pixels which belong to no region.

You can also provide a .DAT file (with the same name as the texture file) to define the owner and selection colours.  These are of the format:

SELECT <hexcolour>
COL0 <hexcolour>
COL1 <hexcolour>
...

e.g.

SELECT FFFF00
COL0 FFFFFF
COL1 FF00FF

Enhanced Graphics
You can also provide enhanced graphical files if you desire.  There are two ways of doing this, which all interoperate correctly.

You can provide a single drawn image by using the tag in the global chunk

HANDDRAWN <texture>

This image is used in place of the monochrome channel from the main texture file.  The alpha channel determines how the side colours are blended with the image colour, with zero meaning that the image colours are fully modulated with the side colour, and other values blending the modulated colour with the original image.

You can also provide pre-created images for each side.  That is, when a side owns an area then if an image for that side exists, the system will display that section of the drawn image with no colouration or other changes.  These are defined by the tag in the global chunk 

DRAWN<N> <texture>

e.g.

DRAWN0 side0.tga

sets the texture to be shown when an area is owned by side zero.

Per-Area Data
You can also set up data for each area in their own chunk.  Valid tags are:

X <x>
Y <y>
DATA <a> [<b> <c> <d>]

Where X and Y are the region map image pixel coordinates of the center point of the area (retrieved in script as 1024x768 coordinates using the RegionMapGetX/Y functions).  DATA can be used for preset data on each area to be used in the script.  There can be up to 4 data elements in the list.
NOTE: While there are both Get and Set functions (RegionMapGetData/RegionMapSetData) it is important to note that this region data is NOT saved as part of a save game and so the Set function should only be used for data which can be rebuilt when the screen is activated etc.

e.g.

[44]        // chunk header should contain the index of the area
X 100
Y 300
DATA 100 4 5        // unset data is initialised to zero

VARIABLEEDIT

This is a control specially built to enable quick and simple editing of data stored in a script structure.  The UI file itself only contains the basic positioning details of the control, with scripting being used to set up the structure type to be edited and any custom layout functionality.

The default behaviour is to list all the structure elements arranged to fill the control area, or centered horizontally if all elements will fit.  The logic attempts to ensure the same layout irrespective of resolution.

Valid Tags

FONT <fontname>

The commands used to set up and control a VariableEdit control are

//set up a variable edit control with the structure you want to edit. The customFilename points to a file which allows setup of custom entry positioning/fonts and other details.
VariableEditSetStruct(objectName, structName, [customFilename])

//fill the edit control with the values from the given variable.  Requires the variable name string, not the variable itself.
VariableEditSetVariable(objectName, variableName)

//use the edit control to set the values of a given variable.  Requires the variable name string, not the variable itself.
VariableEditGetVariable(objectName, variableName)

The custom layout file has a syntax as below

<elementName> I
<elementName> R <x> <y> <width> <height> [<editbox width>]
<elementName> C <hexColour>
<elementName> F <fontname>
<elementName> B<sizePercent>:<buttonTextureName>

The elementName can be either an explicit name, a wildcard string name, or apply to all members of an array, as follows

type I		// ignore the type element of the structure
type* I		// ignore the type element and any other elements which start with type
type? I		// ignore all array entries for the type element

Examples of usage are

type R 10 10 100 40	
// all in 1024x768 coordinate space

type C FFFF00FF
// magenta fully opaque
type F smallFont

type B50:plain_button.tga
// rather than an edit box, have a button taking up 50% of the width of the area

By default the edit boxes are set up to only accept numeric input.


TABSET

Creates a set of buttons which automatically enable or disable other objects in the screen based on which is currently active.

Valid tags

FONT <fontname>
COLOUR <hex colour>
MAXWIDTH <maximum button width>
FILE <button texture filename>

The control creates a button for each of its direct child objects.  The button order is the reverse of the order the objects are defined in the UI file.

The text on the buttons defaults to the name of the UI object, but you can add a text file entry of the form

TAB_<objectname> 

and this will be used.

3DVIEW

Creates a 3D viewport into which you can load 3D models for viewing.  The COLOUR tag for this control sets the background clear colour (use zero for a transparent background, FF000000 for black).

Script commands to control this are:

//if filename starts with # then defaults to standard unit loading paths.
UIObject3DLoad(objectName, filename, [texturePath])

//automatically set the zoom and camera origin to the size of the currently loaded object
UIObject3DAuto(objectName)

//set the origin position and vertical angle of the camera.
SetUIObject3DCamera(objectName, x,y,z,angle,[zoom])

//set the options for the view.  0 for off, nonzero for on.
SetUIObject3DOptions(objectName, allowZoom, allowHorizontalRotate, allowVerticalRotate)

Object Commands

All objects can have one or more commands attached to them.  Commands are inbuilt UI commands to allow for simple actions to occur.  While any object can have a command attached to it, not all are able to trigger nor respond to them.
Available commands are:

COMMAND ENABLE <screen>
COMMAND DISABLE <screen>
COMMAND PRESS <UIObject>
COMMAND SHOWBOX <stringID>
COMMAND CLOSEGAMEANDOPENLINK <url>
COMMAND CUSTOM <value>            // send a custom value to a code-defined handler in the game
COMMAND KEY <key>        // simulate a key press.  Can be any alphanumeric key value, or the special TAB value for the tab key.

for example

COMMAND ENABLE MAINMENU
COMMAND DISABLE POPUP
COMMAND PRESS POPUPOKBUTTON
COMMAND SHOWBOX IDS_HELPFUL_MESSAGE
COMMAND CLOSEGAMEANDOPENLINK someurlonslitherine.html
COMMAND CUSTOM 55
COMMAND KEY F

All commands are checked for validity (that is, that the objects they reference are defined) during UI system loading.  Screens are defined by the name of the root objects defined in them.

Current command triggers are:

BUTTON - commands triggered on press
EDITBOX - commands triggered on RETURN key

Animations

Animations are defined at the top of a UI file, and their chunks all start with a # symbol as shown below.  An animation with the name #START will be played whenever the screen is activated.  Other named animations can be triggered from scripts etc.  All animation commands work on a tick-based timer which is always reset to zero when an animation is played.

[#<name>]
ANIM PLACE <object> <time> <x> <y>
// place the object at the given coordinates on the given tick
ANIM MOVE <object> <time> <x> <y> <steps>
// move the object from its current position to a new set of coordinates over a given number of steps
ANIM SCROLL <object> <time> <dx> <dy> <startx> <starty> <endx> <endy> <loop>
// move an object from one point to another in steps of dx,dy.  If loop is not zero then it will loop indefinitely.
ANIM BOUNCE <object> <time> <startScale> <endScale> <steps>
// cause the object to 'bounce' scale up in size and then back over time.  The scales are in 1000ths, so to bounce an object without changing its size, you would use 1000 1000.
ANIM OFF <object>
// disable an screen via its parent object name.  Only works on top level objects.
ANIM SFX <object> <time> <soundID> [<bank>]
// play a UI SFX at the given time.  The soundID is the position in the sound list.
ANIM TIME <object> <time> <delta>
// change the 'time' for a given object.  Each object can have its own flow of time, and this allows (e.g.) a single object on a screen to execute its animations over and over (if delta is <0, moving time back and allowing an object to execute its animations again.
ANIM FADE <object> <time> <startColour> <endColour> <steps>
// change the colour (including alpha) of an object over time.  Colours should be defined as hex values in AARRGGBB order, e.g. FFFFFFFF for fully opaque white.

Strings

To allow for localization, strings displayed in UIs are referenced by IDs corresponding to entries in string files, typically DATA/TEXT/TEXT#.TXT or TEXT#.TXT in the current campaign directory. Text may also be assigned to UI components at runtime by scripts.

Some formatting of strings is possible using tags embedded in strings, similar to HTML.

• <b>bold</b>
• <i>italics</i>
• line break: <br> or \n
• <h1>heading</h1>
• <colour=0xffffff>colour (red)</colour>
• inline image: <img=filename.tga>
• a double quote character in a string file must be escaped with a additional double quote, ex. "Please use the ""Show preview"" button"

UI Scripting

You can attach a script to any UI control using the SCRIPT tag. Events propagate up the UI object hierarchy to any attached script. Generally you will use root object level scripts for general screen logic, and child-object scripts for more specific rendering components.

The hook functions for UI scripts are:

FUNCTION UI_OBJ_INIT()

Called once when the screen is loaded.

FUNCTION UI_OBJ_ACTIVATE(id)

Called when a screen is activated (shown) by the game.

FUNCTION UI_OBJ_DEACTIVATE(id)

Called when a screen is deactivated (hidden) by the game.

FUNCTION UI_OBJ_RENDER(x,y,width,height,pass, name)

Called to allow scripts to do additional rendering on a control. All screen params are in 1024x768 space. The function is called twice each time the control is rendered, with the pass value set to 0 when called prior to default object rendering, and 1 when called after.

FUNCTION UI_OBJ_HANDLE(data, event, id, name)

Receives events from controls when they are actioned. The data parameter varies depending upon the control type, e.g. it is the region clicked in Region Map controls, or the clicked item in a list in a Listbox control. The event varies, but is generally 0 for a left mouse action, 1 for a right. The id is the id of the actioned control. Use the IsUIObject system function to map this to a specific object name. The name is the name of the owning object (e.g. the object to which the script is attached).

FUNCTION UI_OBJ_UPDATE(mousex, mousey, buttons, over, dragging, flags)

Called on the object update, and providing information on the current mouse position, button states, object the mouse is over, and any object being dragged. The mouse coordinates are in 1024x768. The buttons value is a bitmask, with bit 0 being the left button state, and bit 1 being the right. The over and dragging values are object IDs as per the UI_OBJ_HANDLE function. The flags value can be one of the following values:

0 - normal per tick update 1 - the dragging object has just been dropped

FUNCTION UI_OBJ_EVENT(id, event, data)

This is called when a script uses the UIEvent command to trigger and event on another control. This can be used for inter-control communication.