UI: Difference between revisions
|Line 444:||Line 444:|
Revision as of 17:28, 3 January 2017
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.
All objects are defined by a minimal data chunk of the form:
[<objectName>] TYPE <type> X <x> Y <y> WIDTH <w> HEIGHT <h>
the different types of UI objects and their capabilities, defined using additional tags in the chunk, are described below. All x,y and width, height values are assumed to be based on a 1024x768 screen.
The Parent Object
The first object defined in a file is assumed to be the screen parent object. Any other object in the file without an explicit PARENT definition is assumed to be a child of the screen parent object.
The screen parent object has a number of unique tags which can be set:
HANDLER <handlerName> // handler tags hook in to the code and so should be used with caution. //In most cases you will want to keep handler values as they are already set in existing/equivalent files. MODAL // if set, this says that the screen is modal and prevents interaction with any screens below it in the display stack. LEVEL <level> // each screen is created at a fixed level in the screen layers. It is the order in which screens are displayed.
There can be a hierarchy of parent / child objects below the screen parent object indicated by the PARENT tag on the child. Child objects are drawn in front of their parents and some properties (for example visibility) of a parent will automatically propagate to their children. When two sibling objects overlap visually, the object appearing first in the layout is drawn in front.
Additional Common Tags
DRAGGABLE <size> // denotes that an object is draggable. Size is the height of draggable top border. FOCUS // can this object have focus (be moused over, clicked on, etc). Some objects (e.g. buttons) are always focus-able. SFXFOCUS <id> // play the sound (based on the position in the sound list) when the object is moused over. ALWAYSTOOL // always display the tooltip text at the bottom of the object ALWAYSTOOLX <offset> // x display offset for ALWAYSTOOL display ALWAYSTOOLY <offset> // y display offset for ALWAYSTOOL display CLIPPING // DX <x> // horizontal position relative to parent (overrides X) DY <y> // vertical position relative to parent (overrides Y) PARENT <parentName> // see The Parent Object 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.
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
This is a generic UI object. It is neither visible nor interactable.
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
A display object is a non interactive display. It draws a simple window using a window template texture.
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 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
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
A static text object used to display information to the user.
STRING <stringID> FONT <fontname> COLOUR <colour> BORDER <colour> CENTER // Causes the text to be centered horizontally in the rectangle. WINDOWEDBACK RESCALE FILE <filename> TEXTLEFT <value> TEXTTOP <value> TEXTWIDTH <value> TEXTHEIGHT <value> Screen placement values for the actual text list within the main object window. SCROLLING <filename> // adds a scrollbar to the text of needed, filename is the name for the scrolling control texture (equivalent to CONTROLTEX on a LISTBOX) BARSIZE <size> // this size of the scrollbar is a SCROLLING control texture is specified
A listbox allowing the user to scroll through and select lines.
CONTROLTEX <filename> Required, contains all the various listbox controls. The texture is laid out as follows: Up scroll arrow - top left Down scroll arrow - bottom right Scrollbar - bottom left (this is stretched to the height of the listbox) Scroll nub - bottom right FRAMETEX <filename> - used for the listbox frame SELTEX <filename> - selection display, this is stretched across the width of the selection box BUTTONTEX <filename> - applied to element in the listbox, texture layout is the same as a BUTTON type TEXTLEFT <value> TEXTTOP <value> TEXTWIDTH <value> TEXTHEIGHT <value> Screen placement values for the actual text list, absolute if list is placed absolutely, relative to list if object is placed relatively FONT <fontname> - the font of the listbox item text COLOUR <colour> - the colour of the listbox item text. BARSIZE <value> - Sets the size of the scrollbar. Default value is 32. ITEMSPACING <value> - spacing between listbox items (vertical or horizontal depending on type of listbox), default value is 0 ITEMSIZE <value> - the size of the listbox items (vertical or horizontal depending on type of listbox), default is the height of one line of text for vertical listboxes and the max width to fit all items for horizontal listboxes 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 TEXTMODE - mode for showing multiline text entries
A single line text entry box.
FONT <fontname> COLOUR <colour> MAXCHARS <count> Defines the display of the listbox item text.
A specialist control for representing a map of distinct regions.
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.  // chunk header should contain the index of the area X 100 Y 300 DATA 100 4 5 // unset data is initialised to zero
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.
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.
Creates a set of buttons which automatically enable or disable other objects in the screen based on which is currently active.
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.
Creates a 3D viewport into which you can load 3D models for viewing. The COLOUR tag for this control sets the background clear colour (use zero for a transparent background, FF000000 for black).
Script commands to control this are:
//if filename starts with # then defaults to standard unit loading paths. UIObject3DLoad(objectName, filename, [texturePath]) //automatically set the zoom and camera origin to the size of the currently loaded object UIObject3DAuto(objectName) //set the origin position and vertical angle of the camera. SetUIObject3DCamera(objectName, x,y,z,angle,[zoom]) //set the options for the view. 0 for off, nonzero for on. SetUIObject3DOptions(objectName, allowZoom, allowHorizontalRotate, allowVerticalRotate)
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.
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 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.
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.
- line break: <br> or \n
- <colour=0xffffff>colour (red)</colour>
- inline image: <img=filename.tga>
- a double quote character in a string file must be escaped with a additional double quote, ex. "Please use the ""Show preview"" button"
You can embed clickable links in a string by using
<html>http://www.slitherine.com</html> <html>=0023Custom Link</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.
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:
Called once when the screen is loaded.
Called when a screen is activated (shown) by the game.
Called when a screen is deactivated (hidden) by the game.
FUNCTION UI_OBJ_RENDER(x,y,width,height,pass, name)
Called to allow scripts to do additional rendering on a control. All screen params are in 1024x768 space. The function is called twice each time the control is rendered, with the pass value set to 0 when called prior to default object rendering, and 1 when called after.
FUNCTION UI_OBJ_HANDLE(data, event, id, name)
Receives events from controls when they are actioned. The data parameter varies depending upon the control type, e.g. it is the region clicked in Region Map controls, or the clicked item in a list in a Listbox control. The event varies, but is generally 0 for a left mouse action, 1 for a right. The id is the id of the actioned control. Use the IsUIObject system function to map this to a specific object name. The name is the name of the owning object (e.g. the object to which the script is attached).
FUNCTION UI_OBJ_UPDATE(mousex, mousey, buttons, over, dragging, flags)
Called on the object update, and providing information on the current mouse position, button states, object the mouse is over, and any object being dragged. The mouse coordinates are in 1024x768. The buttons value is a bitmask, with bit 0 being the left button state, and bit 1 being the right. The over and dragging values are object IDs as per the UI_OBJ_HANDLE function. The flags value can be one of the following values:
0 - normal per tick update 1 - the dragging object has just been dropped
FUNCTION UI_OBJ_EVENT(id, event, data)
This is called when a script uses the UIEvent command to trigger and event on another control. This can be used for inter-control communication.
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.