UI

Introduction

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.

You can include other files in UI files. Note this should be used with care as objects with the same names are still prohibited. Lines must be of the form

#include "file.txt"

or

include "file.txt"

You can also add a prefix to an include line. The prefix is applied to all chunk strings in the file, as well as all PARENT entries. So an include of the form

#include "file.txt" Prefix

would cause all the chunks in the include file to be parsed as

[PrefixChunkName]

and any PARENT entries as

PARENT PrefixParentName

This allows for reuse of UI controls in multiple screens (with some careful naming).

Include files must be in the same folder as the UI file (in which case you should NOT use a .txt extension unless you are sure the system will not try and load the include file as a normal UI file (as would happen in CORE/UI or DATA/UI for example) or in DATA/UI/TEMPLATES. Files are searched for in this order. Also, you cannot next includes, i.e. included files cannot have #include statements in them.

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.
TOOLTIP <stringID>
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
ATTACH <tags>           // attach an object to a screen edge, with an optional (unscaled) offset. See below.
KEEPONSCREEN <flags>    // keep the object onscreen.  Values for flags are 1 (ignore vertical), 2 (ignore horizontal), 4 (do both vertical and horizontal)
SQUAREASPECT            // see below

SQUAREASPECT tells controls to maintain their aspect, along with all their children. This differs from the KEEPSQUARE logic in that the actual positioning of child objects will retain a constant aspect (rather than just their control dimensions, as with KEEPSQUARE). Effectively, setting SQUAREASPECT on a control will cause it to be centered around it's usual position, with all its children positions as they would have been in their 1024x768 defined coordinates. So a popup (for example) will have the same look and layout all screen resolutions, but will scale uniformly to the appropriate size. Note that while it is possible to turn off SQUAREASPECT on child objects of SQUAREASPECT parents, the results will likely be undesired.

Attach takes a single composited string using LRTB for the left, right, top, and bottom screen edges respectively. An optional offset can be included. E.g.

ATTACH RB        // attach to the bottom right of the screen
ATTACH R20B10    // attach to the bottom right, with a 20 pixel offset from the right, and 10 up from the bottom.

Object Types

Map Display [DEPRECATED]

This UI object is currently not supported 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)
MODULATE              // use a modulate blend when rendering, multiplying (darkening) the screen based on the source image colours
SLICED <pixels> <size> // use a 9-sliced setup for the image. pixels is the size in pixels of a corner slice in the texture. size is the 1024-space size of a corner in the UI Image onscreen

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
MULTILINE <0/1> // allow wrapped, multiline text on the button, default 0
CENTER <0/1> // horizontally center text on the button, default 1
VCENTER <0/1> // vertically center text on the button, default 1
HOTKEY <key> // define a key which will also trigger the button. See below for more details.
CHECKBOX <0,1> // render this button as a checkbox.  Should be paired with CHECKBOXTICK
CHECKBOXTICK <filename> // the name of the image containing the tick used when drawing a checkbox-style button
MARQUEE <0,1> // if text is too long for button, scroll horizontally over time (cannot be used with MULTILINE)

For hotkeys, valid key values are A-Z and 0-9 as well as TAB, SPACE, RETURN, BACKSPACE, ESC, LEFT, RIGHT, UP, DOWN, F1 - F12. You can also add required modifiers using +SHIFT and/or +CTRL. If using both must be +SHIFT+CTRL. No whitespace allowed in definition. You can automatically show hotkey definitions as tooltips (added in a new line after any defined tooltip). To enable this either add

SHOWHOTKEYS 1

To the UI settings file for the given flavour, or you can add SHOWHOTKEY to the specific object definition in its UI file. When showing these tooltip additions you can define a number of strings, all are optional:

IDS_SYS_SHIFT_KEY,"string for SHIFT",
IDS_SYS_CONTROL_KEY,"string for CTRL",
IDS_SYS_SHOW_HOTKEY,"Prefix for the hotkey string",
IDS_SYS_SHOW_HOTKEY_POST,"postfix for the hokey string",
IDS_SYS_KEY_<key code>,"string for a given key"

As an example you would use IDS_SYS_KEY_A for the A key, or IDS_SYS_KEY_RETURN for the return/enter key. The end tag must match the tag used in the hotkey definition.

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.
VCENTER       // causes the text to be vertically centered in the rectangle
WINDOWEDBACK
RESCALE
RESCALEMAX <value> // Sets the maximum height for RESCALE. If used in conjunction with SCROLLING, the text object will start to Scroll when it reaches the set maximum height.
RESCALELOCK <byte value>  // lock growth direction for RESCALE. 0 centered (default), 1 grow down, 2 grow up.
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 (default 16)
SCROLLBOUNCE <0/1> // bounce when scrolling to the limit of the text (default 1)

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 - top 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 1/3 the horizontal resolution of the CONTROLTEX texture. -ve value causes it to scale with any SQUAREASPECT scaling on the listbox
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
ITEMKEEPSQUARE - causes the scaling of ITEMSPACING and ITEMSIZE to maintain the item layout aspect ratio at non-4:3 resolutions
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
MULTISELECT - allows multiselection in list with standard Ctrl and Shift click modifiers, use IsUIListboxItemSelected to test selections
AUTOSCROLL - scroll to the bottom of the list when new items are added
MAXSCROLL <value> - limit on the number of lines scrolled by the mouse wheel
TEXTMODE - mode for showing multiline text entries

MULTILINE <0/1> - allow wrapped, multiline text in listbox items, default 0 (note, this is different than a TEXTMODE listbox, 
                  you will likely need to adjust ITEMSIZE to actually make room to display multiple lines in a single item)
CENTER <0/1> - horizontally center text on listbox items, default 0 unless a BUTTONTEX is also given
VCENTER <0/1> - vertically center text on listbox items, default 0 unless a BUTTONTEX is also given
AUTOTOOLTIP <0/1> - if an item is too wide to display in the listbox using standard drawing and no tooltip is given, 
                    automatically show the item string as the tooltip
TABLE <headerID> - Draw the listbox as a table with a header and aligned columns. Item strings (and optionally, their tooltips) and the 
                   string referenced by headerID are treated as tab (\t) delimited rows. Behaviour may also be activated or updated 
                   using the SetUIListboxTable command.
LISTALIGN <alignment> - when there are not enough items to fill the visible listbox, align the items to the "CENTER" or "BOTTOM" (or 
                        "RIGHT") of the listbox
MARQUEE <0,1> - if text is too long for item, scroll horizontally over time (cannot be used with MULTILINE)
TEXTINSET <value> - inset the item text horizontally by a given value (in addition to restrictions set by TEXTLEFT, TEXTWIDTH)
COLUMNS <value> - use more than one column in the list box.  The items are displayed left to right then top to bottom.  Does not work for horizontal listboxes.

You can also define a custom item rendering callback

FUNCTION UI_OBJ_RENDER_ITEM(x,y,width,height,pass,flags, item, name)

which operates for each listbox item. The flags param has bits set for selection (bit 0) and mouseover (bit 1), item is the index of the item in the listbox, name is the UI object name, pass is zero prior to default rendering, and 1 after. Returning non-zero will prevent default item rendering.

In the case of wanting to block a list box selection event use

FUNCTION UI_LISTBOX_SELECTION_VALIDATE(data, event, id, name)

If the function returns 0 the select event will not be passed. Good for disabled buttons and states which shouldn't be selected with custom rendering.

EDITBOX

A single line text entry box.

Valid tags:

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

PROGRESS BAR

Progress bar and slider control. Note the common COLOUR tag changes the bar colour, not the text (which has its own tag as below).

BARTEXTURE <filename> // required
BARLEFT <xcoord>
BARTOP <ycoord>
BARWIDTH <width>
BARHEIGHT <height>
TEXTCOLOUR <colour>
NUB <nub image file>
NUBWIDTH <width>  // defaults to 32
WHOLETEXTURE   // boolean that denotes whether the texture is to be shown full sized across the progress bar.

The WHOLETEXTURE tag means that whichever portion of the progress bar is shown, that will be the proportion of the texture shown. So any details on (the visible part of) the texture will remain in the same place as the progress value changes.

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, selection, and other colours.  These are of the format:

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

HIGHLIGHT <highlightcolour>
// you can have as many of the HIGHLIGHTIGNORE tags as you need, each tells the code to not highlight a given region value
HIGHLIGHTIGNORE <region>

// this allows you to take the owner details from another channel in the texture. Values are generally 0, 8, 16, or 24.
OWNERCHANNELSHIFT <shift>
...

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.  Optionally change the zoom. xyz are in 100ths
SetUIObject3DCamera(objectName, x,y,z,angle,[zoom])

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

//set the rotation angle for the 3D view
SetUIObject3DRotation(objectName, angle)

//set the zoom for the given 3D view
SetUIObject3DZoom(objectName, zoom)

//play an animation, which must be set up in the standard text file. If index then it will play a specific anim (if it exists) otherwise random. Loops if loop is != 0, defaults on
SetUIObject3DAnim(objectName, animName, [loop, index])

BARCHART

A vertical bar graph.

Tags:

FILE <filename> - background image, windowed (optional)
BARTEX <filename> - texture for the bars of the graph (optional, otherwise will be drawn in a solid colour)
TILED <0/1> - if 1, BARTEX will be tiled vertically on the bars, otherwise it will be stretched (default 0)
COLOUR - the colour for the text and axis lines
BORDER - the colour for the text outline and bar outlines
STRING - the title of the graph
HLABEL - the label for the horizontal axis of the graph
VLABEL - the label for the vertical axis of the graph
STACKED <0/1> - if 1, multiple bars within a category will be drawn stacked vertically, otherwise they will be placed beside each other (default 0)
MAXBARWIDTH - limit on the width of bars
COLOUR0 to COLOUR9 - the colours used for bars within a category
KEY0 to KEY9 - the descriptions of the bars within a category displayed in the key (if there are multiple bars) and tooltip

Special commands:

//add or update data to a BARCHART UI object, multiple values can be given to show multiple bars in a category, category name is taken from UI string 0
SetUIChartData(objectName, value, [valueN], ...)

//set the colour for the bar within a category of a BARCHART UI, the text description of the bar is taken from string 0
SetUIChartColours(objectName, index, colour)

//set the title, horizontal label, and vertical label for a chart
SetUIChartLabels(objectName, titleStringTag, horizLabelStringTag, vertLabelStringTag)

//sort existing data in a BARCHART UI by category. direction: 0 ascending (default), 1 descending. numeric: 0 sort category names alphabetically (default), 1 treat category names as numbers (ie "2" < "10")
SortUIChartData(objectName, [direction], [numeric])

//clear data from a BARCHART UI object
ClearUIChartData(objectName)

PIECHART

A pie chart.

Tags:

FILE <filename> - background image, windowed (optional)
COLOUR - the colour for the text
BORDER - the colour for the text outline and slice outlines
STRING - the title of the graph
COLOUR0 to COLOUR15 - the colours used for slices (more colours can be set from script after data is added)

Special commands:

//add or update data for a PIECHART UI object, category name is taken from UI string 0, returns the index of the slice, 
//optional value# parameters not relevant to pie charts
SetUIChartData(objectName, value, [valueN], ...)

//set the colour for the slice of a PIECHART UI by index
SetUIChartColours(objectName, index, colour)

//sort existing data in a PIECHAT UI by category. direction: 0 ascending (default), 1 descending. 
//numeric: 0 sort category names alphabetically (default), 1 treat category names as numbers (ie "2" < "10")
SortUIChartData(objectName, [direction], [numeric])

//clear data from a PIECHART UI object
ClearUIChartData(objectName)

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.
ANIM SCALE <object> <time> <startH> <startV> <endH> <endV> <steps>
// change the scale of an object over time.
ANIM ROTATE <object> <time> <startRot> <endRot> <steps> <loop>
// rotate an object over time
ANIM SHOW <object> <time> <show>
// set the visiblity of an object. show == 0 will hide the object, otherwise it will be shown 

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>
• <h1>heading</h1>
• <colour=0xffffff>colour (red)</colour>
• <colour=0xffffff|0xff00ff>colour (red with a border colour)</colour>
• inline image: <img=filename.tga> If you place a # ahead of the filename it will scale the output to match the image's aspect ratio rather than being square
• tinted inline image: <img=filename.tga colour=0xff0000>
• inline image with backdrop: <img=filename.tga|backdrop.tga> Note the backdrop is always rendered to the same rect as the main image
• <c>small caps string</c>
• <fN>another font</f> The numeric value N is the (base zero) index of the font in the fonts file, e.g. <f12>
• <a>This is horizontally centered</a> Centers the given line(s) horizontally in the text box.
• a double quote character in a string file must be escaped with a additional double quote, ex. "Please use the ""Show preview"" button"
• for line breaks, you may alternatively use a ~ character in the string files or \n in literal strings in script

You can embed clickable links in a string by using

<html>http://www.slitherine.com</html>
<html>=0023Custom Link</html>
<html>http://www.slitherine.com|This is display text</html>

for a url link (which will close the game and open the link in a browser if clicked), or a custom link (which will be caught in a UI script with event==1024 and the data parameter containing the 4 digit decimal value following the = sign). Custom strings must always start with =NNNN. Display strings can be shown rather than the links by using the | seperator, link first followed by the display string. Note you can add a LINKCOLOUR entry to a text object to change the colour that a link shows as when moused over.

You can have text display in two columns (left column right justified) by using

<column:[center]:[gap]:[edge]>[first column text]===[second column text]===

e.g.

<column:50:10:5>First column===This is text in the second column===

The center, gap, and edge values are all percentages of the text rect width. Note that behaviour when this tag does not occur at the start of a line is undefined.

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, flags)

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. Returning 9999 will prevent the default rendering of the control. flags - bit 0: pressed or selected (button only), bit 1: mouse over, bit 2: disabled, bit 3: invisible.

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, data)

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. data is the control-specific data value, currently only listboxes return a value (the index of the currently moused over item, -1 if none). Other control types always set this to zero. 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.

Tutorial Popups

You can set up automated, one-time tutorial messages when screens are shown, or when a control is actioned. These should be set up in DATA/TUT.TXT, with entries of the form:

[<object or screen name>]
POPUP <poupname>        // optional, name of the screen used for the popup, defaults to TUTORIAL
STRING <string tag>     // required string ID for the string to be shown (see below)
TEX <texture name>      // optional texture to be applied to the popup when used (see below)
TAG <value>             // optional tag value. Only show this popup when a TAG value is set in the mission chunk in the current campaign and the values match.

e.g.

[MainMenu]  // this is a screen
STRING IDS_WELCOME_MESSAGE

[ScenEdUnitMode]  // this is a button
POPUP MyCustomPopup
STRING IDS_EXPLAIN_UNIT_EDITING
TEX MyCustomTexture

The popup should have controls in it with names of the form <base>String, <base>Image, and <base>Quit - for example you will see that the default CORE/TUTORIAL.TXT file has controls TutorialString and TutorialQuit - the String and Image controls are optional, but Quit is always required and the game will throw an error if it is missing (as there would be no way to close the tutorial message). The string and texture entries from the entry are applied to the String and Image controls respectively.

You may set up a chunk for a given control or screen more than once, which will lead to them showing the first defined entry the first time it is seen/used, and the second the next time the player uses the control or enters the screen. Each time an entry is shown this state is saved (in a local TUT.INF file) to prevent the tutorial popup being shown more than once. Because of this state saving, you should always add new tutorial entries to the end of the file to avoid going out of sync with the saved data.

UI Defaults

Certain UI global values are set via UI settings files. The default values are in SYSTEM/UIDEFAULTS.TXT. They are listed below. Note that this file also includes any COLOURDICTIONARY chunk.

<nowiki>TOOLTIPCOLOUR              // default tooltip colour

TOOLTIPOFFSETX // X offset of the tooltip from the cursor TOOLTIPOFFSETY // Y offset of the tooltip from the cursor TOOLTIPBORDER // width of the border around the tooltip text TOOLTIP9SLICESIZE // 9 slice corner size in texture pixels TOOLTIP9SLICEDRAWSIZE // draw size for 9 slice corner

UI and Font Scaling

Options values GlobalUIScale and GlobalFontScale. They are in 1000s, so 1500 (e.g.) means make things 50% larger. They are independent.

UI scaling is controlled from the UI files, and defaults to off. In the top chunk, add an ALLOWSCALING tag to enable it. Obviously screens which are fullscreen generally won't scale properly.

You can also set the scaling for a specific screen with ALLOWSCALINGCUSTOM <N> where N is the scaling value. e.g.:

ALLOWSCALINGCUSTOM 1300

The game attempts to keep things on the screen, but this can be broken if there are objects that you have stored offscreen (for debug etc) - and so these should be tagged with a IGNOREWHENSCALING line. This will ignore this object and all its children.

If you have elements which are detached from the main UI structure, you can tag their base object with SCALINGPANEL. This will ignore the object and its children when dealing with screen edges, AND also do a screen edge test on the base object and children, separately.