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. 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. Valid key values are A-Z and 0-9 as well as TAB, SPACE, RETURN, BACKSPACE, ESC, LEFT, RIGHT, UP, DOWN 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
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 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 32.
ITEMSPACING <value> - spacing between listbox items (vertical or horizontal depending on type of listbox), default value is 0
ITEMSIZE <value> - the size of the listbox items (vertical or horizontal depending on type of listbox), default is the height of one line of text for vertical listboxes and the max width to fit all items for horizontal listboxes
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, items 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
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.
EDITBOX
A single line text entry box.
Valid tags:
FONT <fontname> COLOUR <colour> MAXCHARS <count> Defines the display of the listbox item text.
REGIONMAP
A specialist control for representing a map of distinct regions.
Valid Tags
FILE <texture> The texture for the region map must be crafted in a specific way. It should be a 4 channel TGA file. The channels in the file are used in the following way: R - a monochrome image layer. A region is coloured with its owning sides colour modulated with this channel. G - selected layer. The currently selected region has this layer coloured with the defined selection colour and blended with the normal map pixels. B - currently unused A - region layer. The alpha value of each pixel denotes which region the pixel belongs to. Value 255 is a special value for invalid pixels which belong to no region. You can also provide a .DAT file (with the same name as the texture file) to define the owner and selection colours. These are of the format: SELECT <hexcolour> COL0 <hexcolour> COL1 <hexcolour> ... e.g. SELECT FFFF00 COL0 FFFFFF COL1 FF00FF Enhanced Graphics You can also provide enhanced graphical files if you desire. There are two ways of doing this, which all interoperate correctly. You can provide a single drawn image by using the tag in the global chunk HANDDRAWN <texture> This image is used in place of the monochrome channel from the main texture file. The alpha channel determines how the side colours are blended with the image colour, with zero meaning that the image colours are fully modulated with the side colour, and other values blending the modulated colour with the original image. You can also provide pre-created images for each side. That is, when a side owns an area then if an image for that side exists, the system will display that section of the drawn image with no colouration or other changes. These are defined by the tag in the global chunk DRAWN<N> <texture> e.g. DRAWN0 side0.tga sets the texture to be shown when an area is owned by side zero. Per-Area Data You can also set up data for each area in their own chunk. Valid tags are: X <x> Y <y> DATA <a> [<b> <c> <d>] Where X and Y are the region map image pixel coordinates of the center point of the area (retrieved in script as 1024x768 coordinates using the RegionMapGetX/Y functions). DATA can be used for preset data on each area to be used in the script. There can be up to 4 data elements in the list. NOTE: While there are both Get and Set functions (RegionMapGetData/RegionMapSetData) it is important to note that this region data is NOT saved as part of a save game and so the Set function should only be used for data which can be rebuilt when the screen is activated etc. e.g. [44] // chunk header should contain the index of the area X 100 Y 300 DATA 100 4 5 // unset data is initialised to zero
VARIABLEEDIT
This is a control specially built to enable quick and simple editing of data stored in a script structure. The UI file itself only contains the basic positioning details of the control, with scripting being used to set up the structure type to be edited and any custom layout functionality.
The default behaviour is to list all the structure elements arranged to fill the control area, or centered horizontally if all elements will fit. The logic attempts to ensure the same layout irrespective of resolution.
Valid Tags
FONT <fontname> The commands used to set up and control a VariableEdit control are //set up a variable edit control with the structure you want to edit. The customFilename points to a file which allows setup of custom entry positioning/fonts and other details. VariableEditSetStruct(objectName, structName, [customFilename]) //fill the edit control with the values from the given variable. Requires the variable name string, not the variable itself. VariableEditSetVariable(objectName, variableName) //use the edit control to set the values of a given variable. Requires the variable name string, not the variable itself. VariableEditGetVariable(objectName, variableName) The custom layout file has a syntax as below <elementName> I <elementName> R <x> <y> <width> <height> [<editbox width>] <elementName> C <hexColour> <elementName> F <fontname> <elementName> B<sizePercent>:<buttonTextureName> The elementName can be either an explicit name, a wildcard string name, or apply to all members of an array, as follows type I // ignore the type element of the structure type* I // ignore the type element and any other elements which start with type type? I // ignore all array entries for the type element Examples of usage are type R 10 10 100 40 // all in 1024x768 coordinate space type C FFFF00FF // magenta fully opaque type F smallFont type B50:plain_button.tga // rather than an edit box, have a button taking up 50% of the width of the area By default the edit boxes are set up to only accept numeric input.
TABSET
Creates a set of buttons which automatically enable or disable other objects in the screen based on which is currently active.
Valid tags
FONT <fontname> COLOUR <hex colour> MAXWIDTH <maximum button width> FILE <button texture filename> The control creates a button for each of its direct child objects. The button order is the reverse of the order the objects are defined in the UI file. The text on the buttons defaults to the name of the UI object, but you can add a text file entry of the form TAB_<objectname> and this will be used.
3DVIEW
Creates a 3D viewport into which you can load 3D models for viewing. The COLOUR tag for this control sets the background clear colour (use zero for a transparent background, FF000000 for black).
Script commands to control this are:
//if filename starts with # then defaults to standard unit loading paths. UIObject3DLoad(objectName, filename, [texturePath]) //automatically set the zoom and camera origin to the size of the currently loaded object UIObject3DAuto(objectName) //set the origin position and vertical angle of the camera. 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) 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>
- inline image: <img=filename.tga>
- tinted inline image: <img=filename.tga colour=0xff0000>
- <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.
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