GUI File Format

Document version 1.0 by Dark Rain

This is a description of the GUI file format used by TA to store
menus layout information. Its used in build menus, dialogs etc.

All the stuff in this file was found by trial and error and some 
deduction, hours of fun ^_^.


----------------------------------------------------------------
Generic Infos about gui files : 
----------------------------------------------------------------
Each gui files represent an interface on the screen, it can be
full screen or just a small part of it. We'll call a gui file as
as whole an Interface.

Each interface is divided into sub components called Gadgets, 
these components can be anything from a button to a scroll bar.

Here's an example of a simple gui file : 

[GADGET0]
	{
	[COMMON]
		{
		id=0;
		assoc=205;
		name=Mainmenu.GUI;
		xpos=0;
		ypos=0;
		width=640;
		height=480;
		attribs=52685;
		colorf=52685;
		colorb=52685;
		texturenumber=0;
		fontnumber=-51;
		active=1;
		commonattribs=-51;
		help=;
		}
	totalgadgets=6;
	[VERSION]
		{
		major=-51;
		minor=-51;
		revision=-51;
		}
	panel=;
	crdefault=;
	escdefault=;
	defaultfocus=SINGLE;
	}
[GADGET1]
	{
	[COMMON]
		{
		id=1;
		assoc=126;
		name=SINGLE;
		xpos=139;
		ypos=393;
		width=96;
		height=20;
		attribs=2;
		colorf=0;
		colorb=0;
		texturenumber=0;
		fontnumber=0;
		active=1;
		commonattribs=54;
		help=;
		}
	status=0;
	text=SINGLE;
	quickkey=83;
	grayedout=0;
	stages=0;
	}


Each gadget is between the 
[GADGET0]
	{
	[COMMON]
		{
		Gadget infos go here
		}
	}

You have to note that only the [] are necessary. We have to
suppose that GAGDET1, GAGDET2 etc are for the benefice of Cavedog
Menu Editor, so the following is valid : 

[]
	{
	[COMMON]
		{
		Gadget infos go here
		}
	}



Each Gadget is divided in 2 parts, the common attributes and the
gadget specific attributes. 

COMMON : The common attributes are attributes
that are well.. common to each gadgets ^_^. This mean that each
gadget has all these attributes BUT it doesn't mean that all are
effective. Some just dont apply to a type of gadget, like a button
doesnt react to any change in size and witdth etc. 

SPECIFIC : These are attributes that are needed for some type
of gadgets, for example, some gadgets need a Text description or
they need to be grayed out or not etc.


Another important thing, is the first gadget. This gadget
represent the interface itself. It defines the interface position
on the screen, it'S size, position, background graphic etc. All
the following gadgets are for element of the interface in question.

----------------------------------------------------------------


----------------------------------------------------------------
COMMON Tag descriptions : 
----------------------------------------------------------------
id : 
----------------------------------------------------------------
The ID, is the most important attribute of a gadget, it defines
what the gadget is. Is it a button, text field, scrollbar etc?
This ID decides it. 

Here are the various values the ID tag can take and their effects :

0 -> The ID 0 is always used in cavedog gui files to represent the
     first gadget that defines the interface. However, this is like
     Gadget#, it'S optional and probably only for their interface tool.
     In truth, you can give to the ID of the first Gadget in the file
     any value. Personaly, I would leave it to 0, it could have
     unpredictable results.

1 -> It makes the gadget a button

2 -> Creates a listbox.

3 -> Creates a textfield, it's doesnt have any borders, so you have 
     to create them yourself in the background image of the form for
     example.

4 -> Creates a Vertical/horizontal Scroll bar.

5 -> It seems to makes the gadget the equivalent of a label for those 
     familiar with VB. It allows you to place only text where you want 
     to. 

6 -> This creates a blank surface that will receive a picture at run time.
     It's used to display a small picture of the map when you're selecting
     a map, or to show a screenshot of your saved game.     

7-> It is used to set the default font for labels

12 -> Used to display a picture box, really handy.

Most of these gadget types need other optional fields or have
extra possibilites, we'll discuss it later in this text.
----------------------------------------------------------------


----------------------------------------------------------------
Name :
----------------------------------------------------------------
The name is used for two things, the first one is the graphic
used for the gadget and as a target for "events" that are hard coded.

GRAPHIC :

The name you choose for it, is used to look directly in a gaf 
file that has the same name as your menu file. For example,
MAINMENU.GUI has a corresponding file named MAINMENU.GAF. As you may
or may not know, Gaf file are made of several image sequences that
are packed inside of it and each sequence has a name. It will try to
match that name with one inside the gaf file. Failling to do that,
it will resort to using the default graphics for it's ID and for it's
size. This is why the buttons in MAINMENU.gui, which represent the 
main menu that appear when you open TA, use a button graphic 
even thought there's no corresponding sequence in the gaf file.

You have to understand that a menu, any menu, be it a unit menu or 
the battle room menu, has access only to the graphic sequence stored
in the gaf file with it's name and the sequences in commongui.gaf.
This is because all the sequences in commongui.gaf are treated like
global variable.

For changing those graphic individualy you can either change the 
default graphic in commongui.gaf but this will change the 
button for ALL the buttons using the default graphics. This is a
bit clunky. The right way to do this, would be to create a sequence
inside MAINMENU.gaf called INTRO (for the Intro gadget). Create it
with two frame for pressed and unpressed and voila.

This open a lot of doors, this would allow TC to assign a different
graphic to each button, sure as hell makes for more variety than
the same damn default button everywhere ^_^.

Note : I thought of adding all the units Build Pictures to
       commongui.gaf. It would save a LOT of space for
       gui based menus and MDF would be able to be done
       with little or no additional space compared to
       normal factories. Sadly, adding anything to commongui.gaf
       crash TA on startup. I urge ppl to try to find a solution
       if you're interested but personaly I'm flat out of ideas.

EVENT :

For a button to actualy do something, it has to be linked to an
event that's often hard coded. In MAINMENU.gui, you can see several
button gadgets, one named INTRO, Credits, MULTI, SINGLE and EXIT.
These 5 words are hard coded variable names for this menu. You cannot
had one from another menu, as far as I can tell. So you cant really
had functionalities to a TA menu, just substract some by not using them.

There's a lot of hard coded events, pretty much a completly different
new set for each menus. The only way to know them, is to look at
Cavedog original gui files and deduce them from the buttons in it.

Something interesting to note, is that while you cannot add events,
you can take out some. A use for this, is in a TC, to remove the 
Cavedog Logo that looks kind of ugly.

A button with a name that isnt linked to an event will be pressable
but it wont have any impact on the game.


UNIVERSAL EVENT NAME : 
As far as I can tell, HELPTEXT, works in every gui. It's used as
a label name, to make it display infos about a gadget your cursor
is on. It seems that the info is hard coded sadly, so you cant
add new ones. I'm really not sure about this so if anyone else
finds out gimme a call ^_^.
----------------------------------------------------------------


----------------------------------------------------------------
width/height
----------------------------------------------------------------
This one is pretty obvious, it just specify the with and height
of a gadget. However, it's useless for most types of gadgets, since 
buttons, labels and picture boxes aren't affected by it.
----------------------------------------------------------------


----------------------------------------------------------------
xpos/ypos : Read, not so obvious detail inside.
----------------------------------------------------------------
These two tags represent the x, y coordinates of the gadget.
Pretty easy, but there's a detail to know. For the first gadget,
the x, y coordinates will be respected ONLY if it still allow the 
interface to fit completly in the screen. This is why in 
MAINMENU.gui, you need to reduce the interface width and height
to something smaller than 640x480 before you move it around.
----------------------------------------------------------------


----------------------------------------------------------------
active :
----------------------------------------------------------------
If 1, then the gadget will be visible, if 0 then it's invisible.
----------------------------------------------------------------


----------------------------------------------------------------
fontnumber :
----------------------------------------------------------------
I found ONE use for this but I'm sure I'm missing something.
When you set a custom font, it sets all the labels to this font.
Well if you set fontnumber to something differant than 0, then
it will use the default TA font again.
----------------------------------------------------------------


----------------------------------------------------------------
attribs :
----------------------------------------------------------------
There's only one use for it, that I've stumbled upon. For 
scrollbars, the value for vertical one has to be 2 and 1 for 
horizontal scrollbars.
----------------------------------------------------------------


----------------------------------------------------------------
assoc :
----------------------------------------------------------------
I did a lot of searching to find this one and I'm sure I'm only
scratching the surface. 

What it does is very simple, it assocy gadgets together (duh). For 90%
of the gadgets I've seen so far, the value of assoc doesnt change
anything. It gets activated only when it's used with gadgets that are
what we'll call "assoc aware". So far, I found only 2 such gadget that
can communicate with each others, it's the scrollbar and the listbox.

When associated together, the listbox will tell the scrollbar how many
item it has, what length the knob should have etc. The scrollbar on
ther other hand, will tell the listbox when to scroll up or down the
list as the user moves it around.

useless side effect :
When 2 scrollbar have the same assoc number, using the arrows 
to make the knob move will result in making the knob on the 
other scrollbar move. 


I'm sure there's more to it, but I cant seem to figure it out.
----------------------------------------------------------------


As far as I can tell, the following tags do nothing : 

	colorf/colorb, 
	texturenumber, 
	commonattribs.



----------------------------------------------------------------
UNCOMMON Tag descriptions :
----------------------------------------------------------------
I'll describe these tags with the gadget they're used with, it'll
simplify things greatly, since many have to be used in conjunction
with each others.

Many of these tags have default value of 0 or
an empty text but in game, the value isnt 0 or the text is 
different. This is because for gadgets having Event name for
the current interface, TA do some special checks or in this case
it modify some variables value. 

One last thing, some gadget are invisble in game but you KNOW
they're there and they should be visible. Things like buttons or
labels. This is because TA checks for gadgets with some 
specific Event name and make them invisible under some circumstances.

----------------------------------------------------------------
Headers (ID 0) :
----------------------------------------------------------------
The header is the first gadget in an interface that I spoke of
earlier. The special tags are :


totalgadgets -> This is used to indicate the total number of
                gadgets in the interface but it's a bogus tag.
                It doesnt have any effect on the interface, that
                I can see.

panel -> This is used to set the background picture of the interface.
         If the interface already use a pcx based background, then
         leave it blank : panel=;

	 Setting the gaf works a bit like the name tag, it refers to the name
         of a sequence in a gaf file with the same name as the gui menu
         or a sequence in the commongui.gaf.


crdefault -> I have no idea yet.

escdefault -> This indicate the name of the button that will be
              pressed when Escape is pressed.

defaultfocus -> This contain the name of the button that will be
                have the focus on by default when the interface
                open. (The focus is represented by the glowing rectangle)

Version -> This bit has to be added, after the common section.
           Put whatever value you want to, for the major, minor
           and revision. It doesnt matter.             

	[VERSION]
		{
		major=-51;
		minor=-51;
		revision=-51;
		}

EXAMPLES : 

[GADGET0]
	{
	[COMMON]
		{
		id=0;
		assoc=205;
		name=Mainmenu.GUI;
		xpos=0;
		ypos=0;
		width=640;
		height=480;
		attribs=52685;
		colorf=52685;
		colorb=52685;
		texturenumber=0;
		fontnumber=-51;
		active=1;
		commonattribs=-51;
		help=;
		}
	totalgadgets=6;
	[VERSION]
		{
		major=100;
		minor=-51;
		revision=-51;
		}
	panel=;
	crdefault=MULTI;
	escdefault=IGPATCH;
	defaultfocus=SINGLE;
	}

----------------------------------------------------------------


----------------------------------------------------------------
Buttons (ID 1) :
----------------------------------------------------------------
The special tags for a button are : 

status -> For simple buttons, this dictate which frame of the
          sequence in the gaf file the button will start on. 
          If you go past the max number of frames in the sequence,
          the button will be invisible.
          
          For multiple stages buttons, the status has to be 0 or
          you'll get the wrong frame.

stages -> This is used to indicate the number of stages a button
          posses. For example, a On/Off button would have 2 stages.

text -> This is just the text of the button, type whatever you 
        want to. For simple buttons, you just type your text, 
        however, for multiple stages button, you have to 
        use pipes to separate the text of each stages of the button.
        It works as follow (3 stages) : text=Continues|Ends|Deathmatch;

quickkey -> This is a shortcut key that you can set for the gadget.
            The key is an ascii number. Consult your nearest 
            ASCII character table for more infos ^_^.

grayedout -> Tells if the button is grayed out not. It makes the 
             button disabled but visible, unlike setting active
             to 0.

EXAMPLES :
Normal button ->

[GADGET4]
	{
	[COMMON]
		{
		id=1;
		assoc=126;
		name=INTRO;
		xpos=409;
		ypos=393;
		width=96;
		height=20;
		attribs=2;
		colorf=0;
		colorb=0;
		texturenumber=0;
		fontnumber=0;
		active=1;
		commonattribs=54;
		help=;
		}
	status=0;
	text=INTRO;
	quickkey=73;
	grayedout=0;
	stages=0;
	}

Multi Stage Button (2 stages) ->

[GADGET6]
	{
	[COMMON]
		{
		id=1;
		assoc=0;
		name=ARMPREV;
		xpos=100;
		ypos=283;
		width=300;
		height=40;
		attribs=32;
		colorf=240;
		colorb=0;
		texturenumber=0;
		fontnumber=0;
		active=1;
		commonattribs=0;
		help=;
		}
	status=0;
	text=On|Off;
	quickkey=O;
	stages=2;


Note that the text is aligned in the middle for simple buttons
and it's aligned to the right for multiple stages buttons.
----------------------------------------------------------------


----------------------------------------------------------------
Listbox (ID 2) :
----------------------------------------------------------------
Well sadly, there's no special tags for it, so I'll just
give an example :


[GADGET1]
	{
	[COMMON]
		{
		id=2;
		assoc=1;
		name=GAMES;
		xpos=10;
		ypos=10;
		width=242;
		height=176;
		attribs=1;
		colorf=15;
		colorb=0;
		texturenumber=0;
		fontnumber=0;
		active=1;
		commonattribs=54;
		help=;
		}
	}
----------------------------------------------------------------


----------------------------------------------------------------
Textbox (ID 3) :
----------------------------------------------------------------
Pretty simple gadget, just indicate it's size and position.


maxchars -> The maximum number of character in the textbox.


EXAMPLE :

[GADGET9]
	{
	[COMMON]
		{
		id=3;
		assoc=0;
		name=ADDRESS;
		xpos=53;
		ypos=61;
		width=250;
		height=26;
		attribs=0;
		colorf=100;
		colorb=0;
		texturenumber=0;
		fontnumber=0;
		active=1;
		commonattribs=-125;
		help=;
		}
	maxchars=30;
	}
----------------------------------------------------------------


----------------------------------------------------------------
Scrollbar (ID 4) :
----------------------------------------------------------------
Wether it's a vertical or horizontal scrollbar is decided by
the width and height. One with say a width of 16 and a height of 184
will be a vertical scrollbar, where one with a width of 184 and a 
height of 16 will be an horizontal scrollbar.

With the height and witdth, you'll get the graphic for the orientation
you want but to make it fully operational, you need the right
attribs value : 1 for horizontal and 2 for vertical.

range -> This is the number of item the scroll bar contains. This isnt
         important, because it seems TA will always change it for
         scrollbar that have Event name and have an associate,
         beside, the result inst visible.

thick -> ? Doesnt seem to affect anything.

knobpos -> I assume it's a position within the range of the number 
           in the "range" tag. Sadly, you cant pre set it, it doesnt
           do anything.

knobsize -> This, is obviously the size of the know on the scrollbar.
            This too is usualy changed by TA when the srollbar has an
            associate.

EXAMPLES :
Vertical ->

[GADGET1]
	{
	[COMMON]
		{
		id=4;
		assoc=243;
		name=KNOB;
		xpos=17;
		ypos=30;
		width=13;
		height=150;
		attribs=2;
		colorf=4;
		colorb=0;
		texturenumber=0;
		fontnumber=0;
		active=1;
		commonattribs=0;
		}
	range=151;
	thick=50;
	knobpos=0;
	knobsize=10;
	}


Horizontal ->

[GADGET4]
	{
	[COMMON]
		{
		id=4;
		assoc=243;
		name=SLIDER;
		xpos=317;
		ypos=63;
		width=150;
		height=13;
		attribs=1;
		colorf=4;
		colorb=0;
		texturenumber=107;
		fontnumber=0;
		active=1;
		commonattribs=10;
		}
	range=151;
	thick=100;
	knobpos=0;
	knobsize=10;
	}
----------------------------------------------------------------


----------------------------------------------------------------
Labels (ID 5) :
----------------------------------------------------------------
Labels are used to display text, you can place them anywhere
inside the interface and make them say whatever you want to.

text -> This is the text that the label will display on the screen.
        Like scrollbar, if the label name is an even name, then
        the text you picked might get changed by TA at run time.

link -> This is used to link a label to a button. What will happen
        is that when you click on the label instead of the button,
        it'll act just as if you clicked on the button. To make it
        work, just give the name of the target button as the link value.

EXAMPLE :

[GADGET3]
	{
	[COMMON]
		{
		id=5;
		assoc=243;
		name=TEXT;
		xpos=476;
		ypos=132;
		width=117;
		height=13;
		attribs=17;
		colorf=0;
		colorb=0;
		texturenumber=0;
		fontnumber=0;
		active=1;
		commonattribs=0;
		help=;
		}
	text=Location;
	link=StartLocation;
	}


----------------------------------------------------------------


----------------------------------------------------------------
Blank Surfaces (ID 6) :
----------------------------------------------------------------
As I mentioned earlier, blank surfaces, are dynamic picture box.
They're used in TA mainly to display the Mini map, as a preview 
when you're selecting a map, to show the screenshot of the minimap
of your saved games etc. Just make sure it has the right event name
so that TA can fill it with a nice picture.. Ooooooooooh a map.
(I'm tired I think ^_^;)

hotornot -> This is used to enable the selection rectangle visible
            on button and such to be visible on the Blank Surface.
            If hotornot = 1 then it's visible, if it's equal to 0 
            then the focus rectangle is invisible.            

EXAMPLE : 

[GADGET2]
	{
	[COMMON]
		{
		id=6;
		assoc=0;
		name=MAPPIC;
		xpos=328;
		ypos=78;
		width=252;
		height=252;
		attribs=0;
		colorf=15;
		colorb=0;
		texturenumber=0;
		fontnumber=0;
		active=1;
		commonattribs=0;
		help=;
		}
	hotornot=0;
	}

----------------------------------------------------------------


----------------------------------------------------------------
Fonts (ID 7) :
----------------------------------------------------------------
This sets the default font for labels for the whole interface.
Sadly, I havent been able to change the font color or size yet,
so you're stuck with black colored fonts.


filename -> This is the name of the font you want to use, check the
            fonts directory to know the names of the font. It's very
            important that you only use the name of the font in 
            filename and not include the extansion. So, for example,
            the files SMLFONT.FNT becomes filename=SMLFONT; .

EXAMPLE :

[GADGET1]
	{
	[COMMON]
		{
		id=7;
		assoc=243;
		name=FONT2;
		xpos=600;
		ypos=321;
		width=26;
		height=66;
		attribs=13;
		colorf=15;
		colorb=0;
		texturenumber=100;
		fontnumber=9;
		active=1;
		commonattribs=-125;
		help=;
		}
	filename=SMLFONT;
	}
----------------------------------------------------------------


----------------------------------------------------------------
Picture Box (ID 12) :
----------------------------------------------------------------
This allow you to display a picture of a gaf sequence. As usual, 
the name correspond to the sequence in the gaf file that you
want the picture to display.

[GADGET13]
	{
	[COMMON]
		{
		id=12;
		assoc=0;
		name=IGPATCH;
		xpos=0;
		ypos=0;
		width=300;
		height=40;
		attribs=2;
		colorf=15;
		colorb=0;
		texturenumber=0;
		fontnumber=0;
		active=1;
		commonattribs=86;
		help=;
		}
	}
----------------------------------------------------------------


Well that's it for now. I'll probably update when I find what the 
3 mystery tags do ^_^. For more infos or questions email 
me at rochdenis@hotmails.com





















