== 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 <b>NOT</b> 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:

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

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:

<nowiki>
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.</nowiki>

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 ==
<nowiki>
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.
SQUAREASPECT // see below</nowiki>
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] ===
<b>This UI object is currently not supported</b>
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.
[[MapDisplayUIControl|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:

<nowiki>
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</nowiki>

==== DISPLAY ====

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

Valid tags:
<nowiki>
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.</nowiki>

==== 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:
<nowiki>
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)</nowiki>
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:
<nowiki>
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)</nowiki>

==== LISTBOX ====

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

Valid tags:
<nowiki>
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.</nowiki>
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:
<nowiki>
FONT <fontname>
COLOUR <colour>
MAXCHARS <count>
CURSORCOLOUR <colour>
Defines the display of the listbox item text.</nowiki>

==== 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

==== REGIONMAP ====

A specialist control for representing a map of distinct regions.

Valid Tags
<nowiki>
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</nowiki>

==== 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
<nowiki>
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.</nowiki>

==== TABSET ====

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

Valid tags
<nowiki>
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.</nowiki>

==== 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:

<nowiki>//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])</nowiki>

==== BARCHART ====

A vertical bar graph.

Tags:
<nowiki>
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</nowiki>

Special commands:
<nowiki>
//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)</nowiki>

==== PIECHART ====

A pie chart.

Tags:
<nowiki>
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)</nowiki>

Special commands:
<nowiki>
//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)</nowiki>

== 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:
<nowiki>
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. </nowiki>

for example
<nowiki>
COMMAND ENABLE MAINMENU
COMMAND DISABLE POPUP
COMMAND PRESS POPUPOKBUTTON
COMMAND SHOWBOX IDS_HELPFUL_MESSAGE
COMMAND CLOSEGAMEANDOPENLINK someurlonslitherine.html
COMMAND CUSTOM 55
COMMAND KEY F </nowiki>

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.

<nowiki>
[#<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 </nowiki>

== 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.
* <nowiki><b>bold</b></nowiki>
* <nowiki><i>italics</i></nowiki>
* <nowiki>line break: <br></nowiki>
* <nowiki><h1>heading</h1></nowiki>
* <nowiki><colour=0xffffff>colour (red)</colour></nowiki>
* <nowiki>inline image: <img=filename.tga></nowiki> If you place a # ahead of the filename it will scale the output to match the image's aspect ratio rather than being square
* <nowiki>tinted inline image: <img=filename.tga colour=0xff0000></nowiki>
* <nowiki>inline image with backdrop: <img=filename.tga|backdrop.tga></nowiki> Note the backdrop is always rendered to the same rect as the main image
* <nowiki><c>small caps string</c></nowiki>
* <nowiki><fN>another font</f></nowiki> The numeric value N is the (base zero) index of the font in the fonts file, e.g. <f12>
* <nowiki><a>This is horizontally centered</a></nowiki> 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"
* <nowiki>for line breaks, you may alternatively use a ~ character in the string files or \n in literal strings in script</nowiki>

You can embed clickable links in a string by using
<nowiki><html>http://www.slitherine.com</html>
<html>=0023Custom Link</html>
<html>http://www.slitherine.com|This is display text</html></nowiki>
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
<nowiki><column:[center]:[gap]:[edge]>[first column text]===[second column text]===</nowiki>
e.g.
<nowiki><column:50:10:5>First column===This is text in the second column===</nowiki>
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:
<nowiki>FUNCTION UI_OBJ_INIT()</nowiki>
Called once when the screen is loaded.
<nowiki>FUNCTION UI_OBJ_ACTIVATE(id)</nowiki>
Called when a screen is activated (shown) by the game.
<nowiki>FUNCTION UI_OBJ_DEACTIVATE(id)</nowiki>
Called when a screen is deactivated (hidden) by the game.
<nowiki>FUNCTION UI_OBJ_RENDER(x, y, width, height, pass, name, flags)</nowiki>
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.
<nowiki>FUNCTION UI_OBJ_HANDLE(data, event, id, name)</nowiki>
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).
<nowiki>FUNCTION UI_OBJ_UPDATE(mousex, mousey, buttons, over, dragging, flags, data)</nowiki>
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
<nowiki>FUNCTION UI_OBJ_EVENT(id, event, data)</nowiki>
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:

<nowiki>[<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</nowiki>

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.

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.

Latest Additions

2023-10-30T23:35:10Z

Phil: /* Copy + Paste in Edit Boxes */

= Copy + Paste in Edit Boxes =
You can now copy and paste in Edit boxes. There is a new tag SELECTIONCOLOUR which allows you to alter the colour of the selection box displayed when selecting for copy.

You cannot copy from a password box. You cannot paste over text (e.g. paste into a selection thus replacing it).

You can also copy from textmode listboxes (as used by the MP chat box). This is only possible if you add an ALLOWCOPY tag to the UI control. There is also a TEXTSELECTIONCOLOUR tag which can be set on these controls.

= 4:3 Ratio UI overrides =
In the rare case where a UI file needs special formatting for 4:3 ratio screens, you can define a different UI file to be loaded where appropriate. Simply create a folder called 43 in the same folder as the UI files. Any file in the 43 folder, which has the same name as a file in the parent folder, will be loaded instead, when running at a resolution with a 4:3 aspect ratio or lower.

= Pick Callback =
Tile. Use the following HELPERS.BSF callback to control picking/selection in battle.
PICK_CALLBACK(blocking)
Where blocking is set to 1 when the mouse is over any UI block set with BlockUIArea during a render call. Return 0 to pick normally, 1 to prevent picking/selection.

= Custom Mouse Handling =
Tile. Callbacks exist for custom mouse handling. These are
MOUSE_CLICK_HANDLER(action, tilex, tiley) // in HELPERS.BSF
DEBUG_MOUSE_CLICK_HANDLER(action, tilex, tiley) // in DEBUG_HELPERS.BSF when enabled
They are triggered on mouse up. action is 0 for LMB, 1 for RMB. Return non-zero in MOUSE_CLICK_HANDLER to prevent normal mouse handling.

= User Folder Redirection =
If the user places a REDIRECT.TXT file in their local folder (e.g. Documents/My Games/<game>) which contains the line
FOLDER <fullpath>
Then the game will treat the provided folder as the user folder for this game.

= Hotkey Tooltips =
You can now enable automatic hotkey tooltips. See the UI button documentation.

= Hotkey Modifiers =
Can now have UI control hotkeys with SHIFT and/or CTRL modifiers. See the UI documentation.

= New Tile Callbacks =
Tile. New callbacks

// Allows for additional text to be added to skirmish descriptions in the MP creation screen.
// Place any string to be added in the first UI string
FUNCTION SKIRMISH_COMMENT_CALLBACK()

// Called immediately after loading the userdata when a game is loaded
// skirmish param is zero or one. Userdata is in the first work array.
FUNCTION LOAD_USERDATA_CALLBACK(skirmish)

= StartCampaign & ReplaceUnit Script Commands =
Tile. StartCampaign can now take no params at which point it loads the ||SKIRMISH campaign as per skirmish battles. ReplaceUnit replaces one unit with another. In order to handle any custom setup (esp anything which is used in animation callbacks) there is a REPLACE_CALLBACK(me) callback where any required data can be set up after the new replacement unit has been initialized but before we try and sync up animations etc. So you will need to save out any specific attribs from the unit that you care about and then reset then in the callback (if needed) or after the ReplaceUnit call returns.

= Screenshot/Movie Capture =
Updates: there is now an onscreen flash when capturing a screenshot. You can also place entries for SCREENSHOTSFX and MOVIESFX into the UIDefaults.txt file in System. These should be numeric index values into the sfx list for sounds to be played when screenshotting, and when beginning a movie capture respectively.

= Global saves =
You can now pass an empty string into Load/SaveVariableData and it will load and save from a GLOBAL_DATA.TXT file in (e.g.) My Documents/My Games/FieldOfGlory2. This can be used to set up a global structure for persistent data across the game, e.g. hi scores or battles won.

= Load Sequence Function =
Tile. If the script CORE/LOADINIT.BSF exists then the function LoadInit from within it will be called at the very start of the main loading sequence, immediately after the first loadbar frame is shown.

= Progress Bars Accept KEEPSQUARE =
You can now use a KEEPSQUARE tag for progress bars if desired.

= Global Orders =
Tile. You can now include global orders which do not require a unit to be selected. These are defined in the CORE.BSF script, and should follow the template for standard unit orders (i.e. CHECK_, UIBUTTON_, etc functions must exist). These orders use a CORE_ prefix, rather than TILE_, UNIT_, or ALL_.

= Gamma Adjustment =
Two new commands allow for adjusting the gamma values when in fullscreen. To allow for saving of the gamma value (or others) there are 3 additional Custom* options values available. Custom1, Custom2, Custom3. All default to zero. Suggested values for gamma would be 0.5 to 2.0 or so, depending on the variation you wish to allow.
<nowiki>//set the gamma value, if possible. gamma is in 1000ths.
SetGamma(gamma)

//returns 1 if the current setup allows for gamma adjustment (e.g. driver support, or because gamma requires fullscreen).
AllowsGamma()</nowiki>

= Get/SetUnitString Script Commands =
Tile. New commands to allow a custom unicode string to be attached to a unit.
//place the contents of the first UI string as a custom string for the unit.
SetUnitString(me)

//place the contents of the unit custom string into the first UI string. Returns 0 if there is no custom string, 1 otherwise
GetUnitString(me)

= User Content Debugging =
Tile. When in DEBUGMODE is set to 2, the system will additionally load list_debug.txt into the user content list from the server. This is to allow for simpler testing of user content from the server without polluting the release list.

= GetSkirmishPoints & GetCurrentMod =
Tile. New script commands to fetch the currently set skirmish points, and to query the current mod.
<nowiki>//sets the first 4 values in the first work array with the current skirmish points values (fixed0, fixed1, select0, select1)
GetSkirmishPoints()

//if a mod is selected, place the name of the current mod into the first UI string and return its index, otherwise return -1. Always returns -1 in multiplayer.
GetCurrentMod()</nowiki>

= Modding Updates =
Tile. Mods can now override S4F and their animation files for units. They can also override scripts for AI, unit, HELPERS, and CORE BSF files. NOTE: to package global mods, you need a ModsPackage named button on the mod UI panel.

= Lobby Colouring Tweak =
Tile. You can now use the VALUE5 entry for the accept games list to define the RGB value for disabled games (where you do not have the necessary campaign etc). Alpha is set to 0xFF by the game. Zero uses the default colouring.

= String Attribs =
Tile. You can have up to 8 read-only strings attached to a squad template. These must be defined in the squads file using tags ##0 to ##7. The string data for each element must have 27 characters or less, and spaces are not permitted. You can then retrieve these using the new command
<nowiki>//place the given attrib string into the first work string. typeIndex is the index of the unit type. index is currently [0,7].
GetAttribString(typeIndex, index)</nowiki>
Note that the string returned will have been converted into upper case.

= UpdateUserStringFromUI and GetUIEditboxToInt Script Commands =
<nowiki>//take the UI string from an editbox object and update it if it has changed (or is new). Return 1 if a change has been made, zero otherwise.
UpdateUserStringFromUI(objectName, tag)

//takes the contents of the UI editbox and converts them to a string. If there are any non-numeric characters in the string, then the return value is invalidValue. Skips leading and trailing whitespace.
GetUIEditboxToInt(objectName, invalidValue)</nowiki>

= Review Battlefield After Battle =
Tile. You can now set up the UI to allow the user to review the battlefield after a battle ends. To do this you should:
* Add a button the the EndBattle control called EndBattleReview
* Create a new UI screen to allow the user to exit after they have finished reviewing. This screen should be called EndReview, and should include a button named EndReviewOK. EndReview should not be modal, but should have the same HANDLER as EndBattle (DeployHandler).
This should allow the player to review the battlefield, with all units shown.

= ShowUIListboxItem =
New script command which moves the viewable area (if needed) to show the given item.
//move the UI listbox to show the given item index. Scrolls unless immediate is non-zero, in which case it instantly changes the view
ShowUIListboxItem(objectName, index, [immediate])

= GetString Control Change =
If the UI object GetStringTitle exists, then the title text for the system GetString control will be placed there, rather than in the title of the GetString object window as per default.

= DEPLOY_DRAG_CALLBACK =
Tile. Unit script function that is called each time a unit is moved by dragging when in deployment.
FUNCTION DEPLOY_DRAG_CALLBACK(me, tilex, tiley)

= Multiline for UI Edit Controls =
Adding a CHATMODE tag to edit controls will now allow them to contain more than one line.

= Further INCLUDE Functionality for UI Files =
You can now use a prefix to rename included UI file components, allowing reuse of UI fragments. See here:[[UI]]

= User Music Control =
Tile. You can alter the music that is playing using the new script command
<nowiki>//switch to the denoted music track. Must be [0,5] currently as per the MUSIC.TXT file order.
SwitchMusic(track)</nowiki>
Can be combined with the new tweak DisableDefaultMusic, which stops all hardcoded changes of music (NOTE: other than the initial playing of the main menu music, and some other changes back to the main menu music when internal code takes the UI back to the main menu).

It is also worth reminding of the existence of the SetMusicFile command
<nowiki>//set a music file to be loaded and used. Looks in local then core files. A ? as filename means leave the existing music entry.
SetMusicFile(filename)</nowiki>

= New Script Commands: GetMapStyle & DeleteUserCampaign =
Tile.
<nowiki>//place the current map style string into the first work string.
GetMapStyle()

//delete a user campaign. The filename is expected to include the CAMPAIGNS or MULTIPLAYER path element depending upon where the campaign is. E.g. MULTIPLAYER/MYCAMPAIGN. NOTE: it is good practice to prompt the user to confirm deletion.
DeleteUserCampaign(filename)</nowiki>

= Including Templates in UI Files =
You can now include other files in UI files. Note this should be used with care as objects with the same names are still prohibited. All includes must be the first thing in the UI file. Lines must be of the form
#include "file.txt"
or
include "file.txt"
The template files must be in DATA/UI/TEMPLATES

= AreNewDownloads Script Command =
//returns 1 if there are new user content downloads available, 0 otherwise
AreNewDownloads()

= Button Text Colour Updates =
You can now define different colours for buttons to use when they are being actioned. These colours can be set globally in the UIDEFAULTS.TXT file using
BUTTONOVERCOLOUR <hex>
BUTTONDOWNCOLOUR <hex>
BUTTONDISABLEDCOLOUR <hex>
You can also over-ride these values on a per-button basis in the UI text file using
OVERCOLOUR <hex>
DOWNCOLOUR <hex>
DISABLEDCOLOUR <hex>

= PRESTARTEDITOR Callback =
Tile. There is now a callback when the editor starts. This can be located in either or both the CORE.BSF and scenario scripts. The function is of the same form as PRESTARTBATTLE:
<nowiki>FUNCTION PreStartEditor(mode)</nowiki>

= Older Entries =
[[Archive_1]]

Latest Additions

2023-10-30T23:33:48Z

Phil: /* Copy + Paste in Edit boxes */

= Copy + Paste in Edit Boxes =
You can now copy and paste in Edit boxes. There is a new tag SELECTIONCOLOUR which allows you to alter the colour of the selection box displayed when selecting for copy.
You cannot copy from a password box. You cannot paste over text (e.g. paste into a selection thus replacing it).
You can also copy from textmode listboxes (as used by the MP chat box). This is only possible if you add an ALLOWCOPY tag to the UI control. There is also a TEXTSELECTIONCOLOUR tag which can be set on these controls.

= 4:3 Ratio UI overrides =
In the rare case where a UI file needs special formatting for 4:3 ratio screens, you can define a different UI file to be loaded where appropriate. Simply create a folder called 43 in the same folder as the UI files. Any file in the 43 folder, which has the same name as a file in the parent folder, will be loaded instead, when running at a resolution with a 4:3 aspect ratio or lower.

= Pick Callback =
Tile. Use the following HELPERS.BSF callback to control picking/selection in battle.
PICK_CALLBACK(blocking)
Where blocking is set to 1 when the mouse is over any UI block set with BlockUIArea during a render call. Return 0 to pick normally, 1 to prevent picking/selection.

= Custom Mouse Handling =
Tile. Callbacks exist for custom mouse handling. These are
MOUSE_CLICK_HANDLER(action, tilex, tiley) // in HELPERS.BSF
DEBUG_MOUSE_CLICK_HANDLER(action, tilex, tiley) // in DEBUG_HELPERS.BSF when enabled
They are triggered on mouse up. action is 0 for LMB, 1 for RMB. Return non-zero in MOUSE_CLICK_HANDLER to prevent normal mouse handling.

= User Folder Redirection =
If the user places a REDIRECT.TXT file in their local folder (e.g. Documents/My Games/<game>) which contains the line
FOLDER <fullpath>
Then the game will treat the provided folder as the user folder for this game.

= Hotkey Tooltips =
You can now enable automatic hotkey tooltips. See the UI button documentation.

= Hotkey Modifiers =
Can now have UI control hotkeys with SHIFT and/or CTRL modifiers. See the UI documentation.

= New Tile Callbacks =
Tile. New callbacks

// Allows for additional text to be added to skirmish descriptions in the MP creation screen.
// Place any string to be added in the first UI string
FUNCTION SKIRMISH_COMMENT_CALLBACK()

// Called immediately after loading the userdata when a game is loaded
// skirmish param is zero or one. Userdata is in the first work array.
FUNCTION LOAD_USERDATA_CALLBACK(skirmish)

= StartCampaign & ReplaceUnit Script Commands =
Tile. StartCampaign can now take no params at which point it loads the ||SKIRMISH campaign as per skirmish battles. ReplaceUnit replaces one unit with another. In order to handle any custom setup (esp anything which is used in animation callbacks) there is a REPLACE_CALLBACK(me) callback where any required data can be set up after the new replacement unit has been initialized but before we try and sync up animations etc. So you will need to save out any specific attribs from the unit that you care about and then reset then in the callback (if needed) or after the ReplaceUnit call returns.

= Screenshot/Movie Capture =
Updates: there is now an onscreen flash when capturing a screenshot. You can also place entries for SCREENSHOTSFX and MOVIESFX into the UIDefaults.txt file in System. These should be numeric index values into the sfx list for sounds to be played when screenshotting, and when beginning a movie capture respectively.

= Global saves =
You can now pass an empty string into Load/SaveVariableData and it will load and save from a GLOBAL_DATA.TXT file in (e.g.) My Documents/My Games/FieldOfGlory2. This can be used to set up a global structure for persistent data across the game, e.g. hi scores or battles won.

= Load Sequence Function =
Tile. If the script CORE/LOADINIT.BSF exists then the function LoadInit from within it will be called at the very start of the main loading sequence, immediately after the first loadbar frame is shown.

= Progress Bars Accept KEEPSQUARE =
You can now use a KEEPSQUARE tag for progress bars if desired.

= Global Orders =
Tile. You can now include global orders which do not require a unit to be selected. These are defined in the CORE.BSF script, and should follow the template for standard unit orders (i.e. CHECK_, UIBUTTON_, etc functions must exist). These orders use a CORE_ prefix, rather than TILE_, UNIT_, or ALL_.

= Gamma Adjustment =
Two new commands allow for adjusting the gamma values when in fullscreen. To allow for saving of the gamma value (or others) there are 3 additional Custom* options values available. Custom1, Custom2, Custom3. All default to zero. Suggested values for gamma would be 0.5 to 2.0 or so, depending on the variation you wish to allow.
<nowiki>//set the gamma value, if possible. gamma is in 1000ths.
SetGamma(gamma)

//returns 1 if the current setup allows for gamma adjustment (e.g. driver support, or because gamma requires fullscreen).
AllowsGamma()</nowiki>

= Get/SetUnitString Script Commands =
Tile. New commands to allow a custom unicode string to be attached to a unit.
//place the contents of the first UI string as a custom string for the unit.
SetUnitString(me)

//place the contents of the unit custom string into the first UI string. Returns 0 if there is no custom string, 1 otherwise
GetUnitString(me)

= User Content Debugging =
Tile. When in DEBUGMODE is set to 2, the system will additionally load list_debug.txt into the user content list from the server. This is to allow for simpler testing of user content from the server without polluting the release list.

= GetSkirmishPoints & GetCurrentMod =
Tile. New script commands to fetch the currently set skirmish points, and to query the current mod.
<nowiki>//sets the first 4 values in the first work array with the current skirmish points values (fixed0, fixed1, select0, select1)
GetSkirmishPoints()

//if a mod is selected, place the name of the current mod into the first UI string and return its index, otherwise return -1. Always returns -1 in multiplayer.
GetCurrentMod()</nowiki>

= Modding Updates =
Tile. Mods can now override S4F and their animation files for units. They can also override scripts for AI, unit, HELPERS, and CORE BSF files. NOTE: to package global mods, you need a ModsPackage named button on the mod UI panel.

= Lobby Colouring Tweak =
Tile. You can now use the VALUE5 entry for the accept games list to define the RGB value for disabled games (where you do not have the necessary campaign etc). Alpha is set to 0xFF by the game. Zero uses the default colouring.

= String Attribs =
Tile. You can have up to 8 read-only strings attached to a squad template. These must be defined in the squads file using tags ##0 to ##7. The string data for each element must have 27 characters or less, and spaces are not permitted. You can then retrieve these using the new command
<nowiki>//place the given attrib string into the first work string. typeIndex is the index of the unit type. index is currently [0,7].
GetAttribString(typeIndex, index)</nowiki>
Note that the string returned will have been converted into upper case.

= UpdateUserStringFromUI and GetUIEditboxToInt Script Commands =
<nowiki>//take the UI string from an editbox object and update it if it has changed (or is new). Return 1 if a change has been made, zero otherwise.
UpdateUserStringFromUI(objectName, tag)

//takes the contents of the UI editbox and converts them to a string. If there are any non-numeric characters in the string, then the return value is invalidValue. Skips leading and trailing whitespace.
GetUIEditboxToInt(objectName, invalidValue)</nowiki>

= Review Battlefield After Battle =
Tile. You can now set up the UI to allow the user to review the battlefield after a battle ends. To do this you should:
* Add a button the the EndBattle control called EndBattleReview
* Create a new UI screen to allow the user to exit after they have finished reviewing. This screen should be called EndReview, and should include a button named EndReviewOK. EndReview should not be modal, but should have the same HANDLER as EndBattle (DeployHandler).
This should allow the player to review the battlefield, with all units shown.

= ShowUIListboxItem =
New script command which moves the viewable area (if needed) to show the given item.
//move the UI listbox to show the given item index. Scrolls unless immediate is non-zero, in which case it instantly changes the view
ShowUIListboxItem(objectName, index, [immediate])

= GetString Control Change =
If the UI object GetStringTitle exists, then the title text for the system GetString control will be placed there, rather than in the title of the GetString object window as per default.

= DEPLOY_DRAG_CALLBACK =
Tile. Unit script function that is called each time a unit is moved by dragging when in deployment.
FUNCTION DEPLOY_DRAG_CALLBACK(me, tilex, tiley)

= Multiline for UI Edit Controls =
Adding a CHATMODE tag to edit controls will now allow them to contain more than one line.

= Further INCLUDE Functionality for UI Files =
You can now use a prefix to rename included UI file components, allowing reuse of UI fragments. See here:[[UI]]

= User Music Control =
Tile. You can alter the music that is playing using the new script command
<nowiki>//switch to the denoted music track. Must be [0,5] currently as per the MUSIC.TXT file order.
SwitchMusic(track)</nowiki>
Can be combined with the new tweak DisableDefaultMusic, which stops all hardcoded changes of music (NOTE: other than the initial playing of the main menu music, and some other changes back to the main menu music when internal code takes the UI back to the main menu).

It is also worth reminding of the existence of the SetMusicFile command
<nowiki>//set a music file to be loaded and used. Looks in local then core files. A ? as filename means leave the existing music entry.
SetMusicFile(filename)</nowiki>

= New Script Commands: GetMapStyle & DeleteUserCampaign =
Tile.
<nowiki>//place the current map style string into the first work string.
GetMapStyle()

//delete a user campaign. The filename is expected to include the CAMPAIGNS or MULTIPLAYER path element depending upon where the campaign is. E.g. MULTIPLAYER/MYCAMPAIGN. NOTE: it is good practice to prompt the user to confirm deletion.
DeleteUserCampaign(filename)</nowiki>

= Including Templates in UI Files =
You can now include other files in UI files. Note this should be used with care as objects with the same names are still prohibited. All includes must be the first thing in the UI file. Lines must be of the form
#include "file.txt"
or
include "file.txt"
The template files must be in DATA/UI/TEMPLATES

= AreNewDownloads Script Command =
//returns 1 if there are new user content downloads available, 0 otherwise
AreNewDownloads()

= Button Text Colour Updates =
You can now define different colours for buttons to use when they are being actioned. These colours can be set globally in the UIDEFAULTS.TXT file using
BUTTONOVERCOLOUR <hex>
BUTTONDOWNCOLOUR <hex>
BUTTONDISABLEDCOLOUR <hex>
You can also over-ride these values on a per-button basis in the UI text file using
OVERCOLOUR <hex>
DOWNCOLOUR <hex>
DISABLEDCOLOUR <hex>

= PRESTARTEDITOR Callback =
Tile. There is now a callback when the editor starts. This can be located in either or both the CORE.BSF and scenario scripts. The function is of the same form as PRESTARTBATTLE:
<nowiki>FUNCTION PreStartEditor(mode)</nowiki>

= Older Entries =
[[Archive_1]]