GUI Engine - 0ad - Wildfire Games

(http://code.wildfiregames.com/resources/divisions/GUI/TDD/GUI_Engine_TDD_1.41.doc) http://code.wildfiregames.com/resources/divisions/GUI/TDD/GUI_Engine_TDD_1.41.xls

Technical Design Document for:

GUI Engine

This document belongs to the 0ad Technical Design Document

All work reserved by WildFire Games

Written by Gustav Larsson (aka Gee) gee@pyro.nu

GUI Engine TDD Version 1.41

Documentation Files: GUI_Engine_TDD_1.41.doc GUI_Engine_TDD_1.41.xls

GUI Homepage / Online Documentation: http://gee.pyro.nu/GUI/

Or e-mail me and I<>ll reply the files you need.

2 December 2003

Table of Contents

TABLE OF CONTENTS 3 INTRODUCTION 4 VERSION HISTORY 4 VERSION 1.0 (RELEASED 26 MARCH 2003) 4 VERSION 1.1 (RELEASED 9 APRIL 2003) 4 VERSION 1.11 (RELEASED 15 APRIL 2003) 4 VERSION 1.2 (RELEASED 1 MAY 2003) 4 VERSION 1.3 (RELEASED 12 SEPTEMBER 2003) 5 VERSION 1.4 (RELEASED 2 DECEMBER 2003) 5 CURRENT VERSION COMMENT 5

BASIC LAYOUT 6 1.1 XML 6 1.2 JAVA-SCRIPTS 6 1.3 GUI 6 1.3.1 Parent Objects 6 1.3.2 Dependencies and Media used 6 1.3.3 Custom 7 1.3.3.1 Styles 7 1.3.3.2 Sprites 7 1.4 OBJECT 7 1.4.1 Settings 7
XML FILES 8 2.1 8 2.1.1 An Object<63>s anatomy 8 2.1.1.1 Object String 8 2.1.1.2 Type-dependent Elements 8 2.1.1.3 Actions 9 2.1.1.4 Children 9 2.1.2 Settings 9 2.1.2.1 Base settings 9 2.1.2.2 Excel Types and Settings file 10 2.1.2.3 Value types 11 2.1.3 Types 12 2.1.4 Drawing order 13 2.2 13 2.2.1 Creating styles 13 2.3 14 2.3.1 Skip a step 15 2.4 15 2.4.1 15 2.4.1.1 Appearing text-box 16 2.4.1.2 Existing text-box 16 2.4.2 16 2.4.3 17 2.5 INLINE JAVA-SCRIPT 17 2.5.1 The <-solution 17 2.5.2 The CDATA-solution 18
C++ API 19 3.1 SETTINGS 19 3.2 THE CLASS GUI 20 3.3 MESSAGES 20 3.4 XML READING 20 3.4.1 Flexibility 20
JAVASCRIPT API 22
MISCELLANEOUS 23 5.1 NAMING RULES 23
ISSUES 24

Introduction The GUI in this documentation does not include the whole GUI of the game. Let<65>s say the map, it is part of the actual Graphical User Interface, but it will hardly be a part of the GUI Engine. The GUI Engine includes all buttons, text-boxes, progress-bars, and all such (and probably a lot more than the obvious too). The GUI Engine<6E>s goal is to enable creation of GUIs completely without having to recompile (let alone, bloat your game code). This will be done with the help of XML files for the layout of the GUI, and JavaScripts for the functionality.

Version History Version history since first release. Version 1.0 (released 26 March 2003) <0A> Skeleton for the document is made. 7 pages in length. Version 1.1 (released 9 April 2003) <0A> Front page added to fit a 0 A.D. TDD. <0A> Second page added with credits, contact and current version. <0A> Version history added. <0A> Chapter<65>s divided into root element types (, etc). <0A> Examples added. <0A> A lot of additions to the objects<74> chapter, such as standard actions. <0A> Whole new chapter 4. added. <0A> Whole new chapter 5. added. <0A> Issue 6.1 updated with 6.1.1 and 6.1.2, two different solutions. <0A> Issue 6.2 added. <0A> Issue 6.3 added. <0A> Decision about name ambiguity made, sibling objects can<61>t share name, that<61>s all. Version 1.11 (released 15 April 2003) <0A> Changed all Word<72>s quotations marks from fancy <20>these<73> to "these" in code examples because <20>these<73> are incorrect XML syntax if one would copy paste them. <0A> The whole concept of animations is removed; I<>ve been informed this feature will be supported beyond the GUI Engine as an integral part of texture database. <0A> Issues are moved from 6 to 5. <0A> A lot of adjustments made from Raj<61>s helpful comments. <0A> Issue 5.1.2 is updated. Version 1.2 (released 1 May 2003) <0A> I<>ve compiled an excel file that keeps track of types and all their settings. This has changed <20>2.2.2 Type-dependent options<6E>; it now explains how to read the excel file instead of listing all options. <0A> A new chapter 5 called <20><> has been added. It includes how to setup tooltips, scrollbars and icons. <0A> The ideas of horizontal scroll-bars and movable dialog-windows have been removed from planning. Lack of need. <0A> The issue about drawing order has been settled and chapter <20>2.4 Drawing order<65> has been added. <0A> Object names should now be completely unique, and the idea of making the name option perhaps not essential is rebuked. <0A> Description added on the different types of values (int, bool, string etc). <0A> Issue 6.2 about simple sprites has been removed and replaced by <20>4.1 Skip a step<65>. <0A> The issue chapter has been moved again, it is now number 9. <0A> <09>6. C++ API<50> and <20>7. JavaScript API<50> have has been added just to reserve space. <0A> <09>8. Miscellaneous<75> has been added, it is a chapter that doesn<73>t really chronologically fit into the rest of the design document, and it should be used as a reference. <0A> Current version comment added.

Version 1.3 (released 12 September 2003) <0A> The chapters CGUI and CGUIObject has been renamed to GUI and Object since language specific information solely should be found in the C++ API chapter. <0A> The chapters , , and has all been given a parent called <20>XML Files<65>, this makes it clearer because we now have three major chapters: XML, C++ and JavaScript. All chapters that are placed after this new one have reduced its chapter number<65>s value by 3, thus making it <20>6. Issues<65> again. <0A> Text in <20>Document Layout<75> has been moved to introduction to the <20>XML Files<65> chapter. <0A> Previously I<>ve used both the name <20>options<6E> and <20>settings<67> for all object settings, they have hopefully all been changed to <20>settings<67> since that<61>s the name I use for them, and it can otherwise be confusing. <0A> Settings added in Excel file: frozen, ghost, absolute. <0A> The setting disabled was changed to a base setting. <0A> Previously I had size1024 and sizerel024 like in AoM. I<>ve removed sizerel1024 and added the boolean setting absolute that let<65>s you know if it<69>s absolute or relative. <0A> The low-leveled C++ documentation has been moved to a separate file. <0A> From empty filled the C++ API chapter with 2 pages. <0A> Solution .1 and .2 to issue 6.1 are tested and works with the XML parser used. So they are now no longer in the issues section. <0A> Before name, type and size1024 were essential settings, now they are ALL optional. I decided to make the defaults: type = <20>empty<74>, size1024 = <20>0 0 0 0<> and name will just not be required. This means you can just specify and you get a typical transparent group. <0A> The JavaScript/XML syntax collision issue is not an issue anymore, can be found in the XML chapter. <0A> I<>ve added an index of files which accompanies this file. I<>ve seen many links which only provides this file, so it can be good to know you need all files to have the full documentation.

Version 1.4 (released 2 December 2003) <0A> File GUI_ClassRelations_*.png has been removed, replaced by the online documentation. <0A> Some class names has been changed, like CGUIObject is now IGUIObject since it<69>s interfaces. <0A> The new settings type client area has been added. <0A> Sizing has been updated from ratio-sizing to tileable. size1024 is now just size and of type client area instead of rect. <0A> When making sprites, pixel and percent has been combined to size using the new type client area. Also the t_pixel and t_percent has been replaced by texture_size accordingly. <0A> Done a lot of small updates of things that was outdated or deprecated.

Version 1.41 (released 18 December 2004) <0A> Added reference to new attributes created by Philip Taylor aka Ykkrosh: sprite effects (2.3.3) and cellular sprites (2.3.2). Also added cell-id to the base attributes in 2.1.2.1. <0A> Removed mention of LUA, since we<77>re currently using JavaScript.

Current version comment This version lacks the important object types listbox, combobox and slider because I need more feedback from the GUI graphics designers before I can set that up properly.

Basic Layout This is the basic approach and layout of the GUI Engine, comments and suggestions are always helpful.

1.1 XML The whole GUI will be read in from XML files. Why? Most importantly because XML is a mark-up language, which enables us to create the tree structures we require. In the main GUI class there will be a function that lets us input an XML file, so what we do when we setup a GUI is just having all the XML files being passed through this function and inputted into the engine. I<>m sure it<69>s easier to understand the concept of the XML files with an example:

1.2 JavaScripts JavaScript scripts will be used to carry out actions. If there is something in the game that should be controlled by<62>for instance<63>a button, it is essential for the script-engine to be able to carry out the button<6F>s assignment. So if there<72>s anything the script-engine can<61>t control, you can<61>t make a button of it; but hopefully the script-engine will be able to control everything we need buttons and objects for. A script interface for controlling the GUI will be an important part as well, because it enables us to change the GUI not only from the GUI itself, but from wherever we can use the script-engine.

1.3 GUI 1.3.1 Parent Objects A primary list of parent objects will be stored in a list, they will all be objects that have no natural parent, such as the intro-menu or a dialog window. All buttons in the intro-menu though, will be stored as children within the intro-menu object. Each XML file (with the root element ) will be one or more of these base trees.

1.3.2 Dependencies and Media used The GUI Engine will need access to the game<6D>s keyboard and mouse inputting structure for interaction. Also the GUI will want access to all the fonts, which<63>s residing place I don<6F>t know yet, but perhaps in some graphics structure outside the GUI. Sound I<>m not sure about if the GUI needs access to yet, because it can be enough to just make a sound-playing interface for the script-system. It would mean you could go:

Inline script part [PlaySound](PlaySound)("click") Inline script part

<EFBFBD> and that might be enough.

1.3.3 Custom This section refers to things you declare in other XML files than , but they are of course used within the ; for instance styles and sprites.

1.3.3.1 Styles Let<65>s say we want to create a button style for all the tray buttons, and one that<61>s slightly (or completely) different for the main menu buttons. Now, we don<6F>t want to code how they will look each and every time we need one. We<57>ll just store the information as a style/template and then reference to that style when creating our buttons. Read more about styles here.

1.3.3.2 Sprites Sprites are declared separated, describing size, texturing etc. Read more about sprites here.

1.4 Object As mentioned in the GUI part, everything you see, everything you press, is an object belonging to one of the base trees of objects. Objects can have a dynamic amount of children, also regardless of object type, i.e. buttons can also have children, although you might only notice it in theory.

1.4.1 Settings Object settings are defined within the object tag, all settings cannot be used by all objects; type decides what more settings you can put within the tag than the base options (name, type, size etc). For instance, if you want an empty area, then textcolor=<3D>0 0 255<35> will make very little sense, as oppose to if it were a text box. A list of which settings are available for which types can be found here.

XML Files Different XML files with different root elements will be loaded into the GUI. So basically you have a long list of XML files, and voil<69> that gives you your entire GUI. As said, there are different kinds of XML documents for the GUI, for instance one that declares objects, and one that declares styles. These two mentioned would have the root elements and . Each different root element will have its own chapter ahead.

2.1 In CGUI I<>ve mentioned that there is a list of main objects; they are the only parentless objects. To input one of these objects you just need to create an XML file with the main tag and input it into the GUI Engine. Within the root element you can enter as many objects as you like, they will all be root parents. Here<72>s an example of a perfectly valid XML file:

GUI Objects XML file example

2.1.1 An Object<63>s anatomy Within an object the order of all sub-elements is syntactically indifferent, but it is wise to keep the recommended standard: GUI Parent XML file example 2.1.1.1 Object String This is a plain string within the object that could mean a variety of things depending on object type; a text box for instance uses this string as caption. This is the same string as in Gee, only we<77>ll have this string next to sub-elements too. 2.1.1.2 Type-dependent Elements Type-dependent elements are rare and can look completely different from type to type. It<49>s used for information that is too dynamic for a regular option such as name or type. As in an earlier example we used type-dependent elements to declare a list box<6F>s items. There will be information about the type-dependent elements in the types<65> section. 2.1.1.3 Actions When certain events occur you want to be able to run a script to give for instance a button functionality, this is made with . The action tag takes one option and that is <20>on<6F>, like this: JavaScript goes here Here is the list of actions that all types can use because they depend on essential information: <0A> [MouseEnter](MouseEnter) Called when the cursor enters the object<63>s parameters. <0A> [MouseLeave](MouseLeave) Same as above only when the cursor leaves. <0A> [MouseOver](MouseOver) Called continuously when the cursor is hovering the object. <0A> [MouseLeftPress](MouseLeftPress) Called when left mouse button is pressed (and of course the mouse hovering the object too). <0A> [MouseLeftDown](MouseLeftDown) Called continusously when left mouse button is down. <0A> [MouseLeftRelease](MouseLeftRelease) Called when left mouse button is released. <0A> [MouseRight](MouseRight)* Same as above only with right mouse button. <0A> Load When the GUI is first loaded. Actually there is one more option for the action tag, it is optional and used when wanting to run a script from a separate file. It will be used as if you had opened the file, selected everything and copied it to within the tags, except within the file you don<6F>t have to worry about syntax collisions between [JavaScript](JavaScript) and XML. 2.1.1.4 Children All objects can have children, i.e. objects within the object. The children must not all be drawn within the parent, but do notice that if you add a scroll-bar, they will be cut-off at the edges. If you hide an object all its children are hid too, same with moving if the children<65>s setting absolute has been set to false, which means you specify the position and size relative to the parent<6E>s coordinate-system (and not to the screens). This means you can create a whole group of buttons and hide them or move them all with a single call. An example of a parent/child-relationship is if you have a lot of text and perhaps images which is too much for the screen to show at once, you need a scroll-bar of course. This is done by creating an empty parent with scroll-bars and then specifying relative size and position of all children. The scroll-bars will then be adapted so they can scroll and display all children. 2.1.2 Settings Settings go within the object tag like this: