Torque GUI Builder Initial Release
by John Vanderbeck · in Torque Game Engine · 08/18/2004 (7:10 pm) · 22 replies
NOTE: Due to character limits this post will be done in a couple parts.
Its finally here. The initial release of the Torque GUI Builder!
What is it?
The Torque GUI Builder is a system for creating dynamic GUI systems via TorqueScript. Instead of creating GUI screens at design time, you can create them at runtime via script. This allows for completely dynamic GUIs.
How does it work?
In a nutshell you add controls to a global pool, then create sets of controls by specifying which controls from the pool are displayed together. Huh? Let's take that again a little slower.
There are a few basic concepts that you need to understand in order to work with the GUI Builder.
TGUIPool
The global pool is a global collection of controls. Think of this as a toolbox. You put all your tools into your toolbox so that they will be there when you need to use them later. When you add a control to the pool you define the basic properties of that control, things like extent, sizing options, and control specific options like what bitmap to use, etc. These properties define how the controls will look but not where they will be displayed.
TGUISet
A bunch of controls displayed together and in relation to each other is a GUI Set. You take the controls that you placed into the pool and add them into sets. One control in the pool can be placed into as many sets as desired. When you add a control to a set is when you specify positioning information. By keeping this at the set level and not the pool level, it is possible to have one control in the pool added to multiple sets an have completely different positioning in each set.
Control Definitions
When you add a new control to the pool, you specify some basic properties such as what type of control it is (such as GuiTextCtrl, or GuiBitmapButonCtrl), what you want to call it, and a control definition that defines the control's makeup. For the most part the control definition consists of all the fields that you see when editing a control in the GUI editor. The only field it does not include is the position field as that is computed automatically when the control is actually displayed through the use of positioning options. You can obtain a list of all definition fields used and supported by a specific control type at anytime by opening the console and typing:
Control Types
At the present time the system only supports 12 different control types. However more will be added, a little bit at a time. The plugin system makes adding new controls quick and easy, and all you will need to do to use them is drop the provided plugin files into the right directory. Controls in the GUI Builder use the same type name as they do in Torque itself. For example: GuiBitmapButtonCtrl. At any time you may obtain a list of all supported controls by opening the console and typing:
Its finally here. The initial release of the Torque GUI Builder!
What is it?
The Torque GUI Builder is a system for creating dynamic GUI systems via TorqueScript. Instead of creating GUI screens at design time, you can create them at runtime via script. This allows for completely dynamic GUIs.
How does it work?
In a nutshell you add controls to a global pool, then create sets of controls by specifying which controls from the pool are displayed together. Huh? Let's take that again a little slower.
There are a few basic concepts that you need to understand in order to work with the GUI Builder.
TGUIPool
The global pool is a global collection of controls. Think of this as a toolbox. You put all your tools into your toolbox so that they will be there when you need to use them later. When you add a control to the pool you define the basic properties of that control, things like extent, sizing options, and control specific options like what bitmap to use, etc. These properties define how the controls will look but not where they will be displayed.
TGUISet
A bunch of controls displayed together and in relation to each other is a GUI Set. You take the controls that you placed into the pool and add them into sets. One control in the pool can be placed into as many sets as desired. When you add a control to a set is when you specify positioning information. By keeping this at the set level and not the pool level, it is possible to have one control in the pool added to multiple sets an have completely different positioning in each set.
Control Definitions
When you add a new control to the pool, you specify some basic properties such as what type of control it is (such as GuiTextCtrl, or GuiBitmapButonCtrl), what you want to call it, and a control definition that defines the control's makeup. For the most part the control definition consists of all the fields that you see when editing a control in the GUI editor. The only field it does not include is the position field as that is computed automatically when the control is actually displayed through the use of positioning options. You can obtain a list of all definition fields used and supported by a specific control type at anytime by opening the console and typing:
$guiBuilder.displayDefinitionFields("ControlType");Replace "ControlType" with the specific type of control you want to know the fields for. For example if you wanted to know which fields were supported for GuiTextCtrl:$guiBuilder.displayDefinitionFields("GuiTextCtrl");Control Types
At the present time the system only supports 12 different control types. However more will be added, a little bit at a time. The plugin system makes adding new controls quick and easy, and all you will need to do to use them is drop the provided plugin files into the right directory. Controls in the GUI Builder use the same type name as they do in Torque itself. For example: GuiBitmapButtonCtrl. At any time you may obtain a list of all supported controls by opening the console and typing:
$guiBuilder.listValidControls();
#2
These docs really need to be more in depth, but for now i'm going to provide a very very simple basic tutorial that illustrates how the system works. First of all you need to make sure that the TGUIBuidler.cs file is exec'd at some point before you can use the system.
To begin, initialize the GUI Builder:
There are a couple global variables that are used to interact with the builder. $guiBuilder is one, and is a link to the main GUI Builder. $guiPool is another and is a link to the global pool.
Now that the system is intialized, we create a control definition for a button that we will be displaying. Note that this seems like a lot of code to display one button, but remember that in most cases this definition could be reused for any number of buttons with just changes to the text and command fields.
Next we define the specifics for THIS button which are the text and the command:
Then we add the button to the pool:
Next we create a new GUI set in which we will display our button:
Then add the button to the set as an anchor:
Finally we "enable" the set. By enabling it or turning it on, it gets displayed and all other sets get disabled. When we enable the set we specify what Torque GUI the set should be displayed on.
08/18/2004 (7:13 pm)
A Brief TutorialThese docs really need to be more in depth, but for now i'm going to provide a very very simple basic tutorial that illustrates how the system works. First of all you need to make sure that the TGUIBuidler.cs file is exec'd at some point before you can use the system.
To begin, initialize the GUI Builder:
$guiBuilder.init();
There are a couple global variables that are used to interact with the builder. $guiBuilder is one, and is a link to the main GUI Builder. $guiPool is another and is a link to the global pool.
Now that the system is intialized, we create a control definition for a button that we will be displaying. Note that this seems like a lot of code to display one button, but remember that in most cases this definition could be reused for any number of buttons with just changes to the text and command fields.
%def = new ScriptObject(); %def.extent = "150 17"; %def.profile = "GuiShowButtonProfile"; %def.minExtent = "8 2"; %def.extent = "150 17"; %def.horizSizing = "right"; %def.vertSizing = "bottom"; %def.groupNum = -1; // -- Button Properties -- %def.bitmap = "show2/client/ui/button_blank"; %def.buttonType = "PushButton";
Next we define the specifics for THIS button which are the text and the command:
%def.text = "Quit"; %def.command = "quit();";
Then we add the button to the pool:
%button = $guiPool.addControl("buttonQuit", "GuiBitmapButtonTextCtrl", %def);Next we create a new GUI set in which we will display our button:
%set = $guiBuilder.createSet();
Then add the button to the set as an anchor:
%set.addControl(%button, "Anchor", "5", "25%");
Finally we "enable" the set. By enabling it or turning it on, it gets displayed and all other sets get disabled. When we enable the set we specify what Torque GUI the set should be displayed on.
$guiBuilder.enableSet(%set, playgui);
#4
08/18/2004 (7:29 pm)
Can we see some pics?
#6
A long time ago I wanted something like this, but dropped it again due to the work involved. This is so great!!!! Thanks a bunch for making this!!
08/19/2004 (1:32 am)
MUCHO COOL JOHN!!!!!A long time ago I wanted something like this, but dropped it again due to the work involved. This is so great!!!! Thanks a bunch for making this!!
#8
In any case I wanted to take some time now and touch on the plugin system. From the beginning I wanted to design a core system that could then be expanded easily to allow for handling of new controls. There will always be cases where people have custom Torque controls, or where new controls are added to the base Torque and it would be a pain to have to modify the GUI Builder each and every time. So out of this need was born the plugin system. The plugin system is used for both Controls and Layouts. Layouts define ways for controls to be positioned. Controls define the controls themselves. Layout plugins must be located in TGuiBuilder\layouts and Control plugins must be located in TGuiBuilder\controls
Let's take a look at how to write each type of plugin. This is a very simple matter, and I firmly beleive that anyone can do it even if they have little to no programming experience. At least some experience with TorqueScript is certainly recommended though.
(Note: This is part of a multipart post. Please be patient as I type out each part due to limitations of the forum)
08/20/2004 (7:15 am)
Welp this apparently didin't turn out to be as big a hit as I expected lol but oh well. As long as at least one person finds it useful I guess thats ok. Eventually though it will be useful to myself as well and thats what really counts.In any case I wanted to take some time now and touch on the plugin system. From the beginning I wanted to design a core system that could then be expanded easily to allow for handling of new controls. There will always be cases where people have custom Torque controls, or where new controls are added to the base Torque and it would be a pain to have to modify the GUI Builder each and every time. So out of this need was born the plugin system. The plugin system is used for both Controls and Layouts. Layouts define ways for controls to be positioned. Controls define the controls themselves. Layout plugins must be located in TGuiBuilder\layouts and Control plugins must be located in TGuiBuilder\controls
Let's take a look at how to write each type of plugin. This is a very simple matter, and I firmly beleive that anyone can do it even if they have little to no programming experience. At least some experience with TorqueScript is certainly recommended though.
(Note: This is part of a multipart post. Please be patient as I type out each part due to limitations of the forum)
#9
Looks complicated, but it isn't that bad. The BEST way to build a plugin is to first use another one as a base. In this case we are going to use the code above, which is from the plugin for GuiTextCtrl as a base to make a plugin for the control GuiButtonCtrl.
Let's analyze sections of thise code.
This section defines the plugin. If you are familiar with Torque packages great, if you aren't don't worry about it. Just understand that this is how each plugin is defined as a seperate entity and how the plugin system internally knows what to load. When making a plugin for a control, simple change the text "GuiTextCtrl" to whatever the Torque name of your new control is. For example GuiButtonCtrl. This needs to be the exact same as what the control is called in Torque.
This is the function which physically creates the control. You don't need to change anything on this line.
This is what physically generates the Torque control. Take note of the last line, "groupNum". This is VITAL. All the lines from "profile" to "groupNum" are what I call default fields. These are things that EVERY control will have. You can leave this intact. You don't need to change it. What you do need to change though is in the very first line where you see "GuiTextCtrl". Simply replace that with the Torque name of the control just like you did previously.
08/20/2004 (7:42 am)
Control Plugin// Control plugin for the control: GuiTextCtrl
package TGUIControl_GuiTextCtrl
{
// override the function which actually creates the control
function createGUIControl(%control)
{
// Dynamiclly create the code which will create this control
%code = "%newControl = new GuiTextCtrl(" @ %control.name @ ") {" @
"profile = \"" @ %control.profile @ "\";" @
"horizSizing = \"" @ %control.definition.horizSizing @ "\";" @
"vertSizing = \"" @ %control.definition.vertSizing @ "\";" @
"position = \"" @ %control.x SPC %control.y @ "\";" @
"extent = \"" @ %control.definition.extent @ "\";" @
"minExtent = \"" @ %control.definition.minExtent @ "\";" @
"visible = 1;" @
"groupNum = " @ %control.definition.groupNum @ ";" @
"text = \"" @ %control.definition.text @ "\";" @
"maxLength = " @ %control.definition.maxLength @ ";" @
"};";
// If the user has debug mode set, we display the code we generated
if ($guiBuilder.debug)
echo(%code);
// evaluate (run) the code we created
eval(%code);
// return the control we created
return %newControl;
}
function getDefinitionFields()
{
return "text maxLength";
}
};Looks complicated, but it isn't that bad. The BEST way to build a plugin is to first use another one as a base. In this case we are going to use the code above, which is from the plugin for GuiTextCtrl as a base to make a plugin for the control GuiButtonCtrl.
Let's analyze sections of thise code.
package TGUIControl_GuiTextCtrl
This section defines the plugin. If you are familiar with Torque packages great, if you aren't don't worry about it. Just understand that this is how each plugin is defined as a seperate entity and how the plugin system internally knows what to load. When making a plugin for a control, simple change the text "GuiTextCtrl" to whatever the Torque name of your new control is. For example GuiButtonCtrl. This needs to be the exact same as what the control is called in Torque.
function createGUIControl(%control)
This is the function which physically creates the control. You don't need to change anything on this line.
// Dynamiclly create the code which will create this control
%code = "%newControl = new GuiTextCtrl(" @ %control.name @ ") {" @
"profile = \"" @ %control.profile @ "\";" @
"horizSizing = \"" @ %control.definition.horizSizing @ "\";" @
"vertSizing = \"" @ %control.definition.vertSizing @ "\";" @
"position = \"" @ %control.x SPC %control.y @ "\";" @
"extent = \"" @ %control.definition.extent @ "\";" @
"minExtent = \"" @ %control.definition.minExtent @ "\";" @
"visible = 1;" @
"groupNum = " @ %control.definition.groupNum @ ";" @This is what physically generates the Torque control. Take note of the last line, "groupNum". This is VITAL. All the lines from "profile" to "groupNum" are what I call default fields. These are things that EVERY control will have. You can leave this intact. You don't need to change it. What you do need to change though is in the very first line where you see "GuiTextCtrl". Simply replace that with the Torque name of the control just like you did previously.
#10
Here is where we add what I call the custom fields. These are fields specific to the control you are making the plugin for. This is the hardest step of the entire process, but it is pretty simple to do if you follow along carefully. The easiest way to know what fields you will need for the control is to either look at what fields there are when you place the control in the GUI Editor inside Torque or to load the .gui file and look at the control inside there. Any custom fields, which means any fields besides the default ones we saw above must be added in here. The big challenge here is knowing how to add the fields. There are two types of fields you will add here. 1) Simple Number fields. Any field that when in the GUI Editor you enter a standard number like 45, or something is a Simple Number field. 2) Text Field or Number String Field. If the field expects either text, a color name, a string of numbers, or really anything except a simple number then it is a Text Field. So how do you format these in the plugin?
Look at the two custom fields above. You have "text" and "maxLength". You can use these two as a template for any fields you need. The field "text" can be used as a template for any Text Field and the field "maxLength" can be used as a template for any Simple Number field.
Using these as a template all you have to do is replace either "text" or "maxLength" with whatever the name of your field is. As with the control name this MUST be the exact same name as what it is in Torque. Make sure you change the field name in BOTH places in the template.
Ok here is the very last piece of the plugin that we need to touch. This function is how the plugin communicates what custom fields the control uses. This is EXTREMELY IMPORTANT. If this is not correct then the plugin system will not know anything about your custom fields. This is extremely simple as well. As you can see it is simply a list of the field names seperated by spaces.
Once you've made all those changes, save the file with the fielname being the SAME as the Torque control name with the .cs extension and make sure it is in the controls plugin directory.
If you have the builder currently running you can reload the plugins without having to restart it by opening the console and typing:
Or you can just restart the application.
08/20/2004 (7:42 am)
"text = \"" @ %control.definition.text @ "\";" @ "maxLength = " @ %control.definition.maxLength @ ";" @
Here is where we add what I call the custom fields. These are fields specific to the control you are making the plugin for. This is the hardest step of the entire process, but it is pretty simple to do if you follow along carefully. The easiest way to know what fields you will need for the control is to either look at what fields there are when you place the control in the GUI Editor inside Torque or to load the .gui file and look at the control inside there. Any custom fields, which means any fields besides the default ones we saw above must be added in here. The big challenge here is knowing how to add the fields. There are two types of fields you will add here. 1) Simple Number fields. Any field that when in the GUI Editor you enter a standard number like 45, or something is a Simple Number field. 2) Text Field or Number String Field. If the field expects either text, a color name, a string of numbers, or really anything except a simple number then it is a Text Field. So how do you format these in the plugin?
Look at the two custom fields above. You have "text" and "maxLength". You can use these two as a template for any fields you need. The field "text" can be used as a template for any Text Field and the field "maxLength" can be used as a template for any Simple Number field.
Using these as a template all you have to do is replace either "text" or "maxLength" with whatever the name of your field is. As with the control name this MUST be the exact same name as what it is in Torque. Make sure you change the field name in BOTH places in the template.
function getDefinitionFields()
{
return "text maxLength";
}Ok here is the very last piece of the plugin that we need to touch. This function is how the plugin communicates what custom fields the control uses. This is EXTREMELY IMPORTANT. If this is not correct then the plugin system will not know anything about your custom fields. This is extremely simple as well. As you can see it is simply a list of the field names seperated by spaces.
Once you've made all those changes, save the file with the fielname being the SAME as the Torque control name with the .cs extension and make sure it is in the controls plugin directory.
If you have the builder currently running you can reload the plugins without having to restart it by opening the console and typing:
$guiBuilder.loadPlugins();
Or you can just restart the application.
#11
08/20/2004 (7:44 am)
Information on Layout controls will come a bit later as they are more complex, but at the same time I think what most anyone will be doing will be making new control plugins not layouts at least for the short term.
#12
08/20/2004 (11:09 am)
I don't know about others but I'm having a hard time figuring out how or why you would use this. Could you explain more on what this will do for you that stock torque wouldn't? Why you created it in the first place. What problem where you trying to solve with this etc.
#13
08/20/2004 (11:16 am)
It doesn't do anything that you couldn't do in stock Torque but it makes it about ten million times easier. Basically the GUI Builder allows you to dynamicaly create GUIs at runtime. One way that I am using it, is to generate a series of buttons with each button's text being the name of an animation thread for a model. Something that would be impossible to do with a menu made at design time. Yes its something you COULD do with stock Torque but this makes that a million times easier.
#14
08/21/2004 (1:37 am)
Or (as I plan to use it) have the GUI modify itself to the context of the game (without having to code all the GUI's prior to the game). E.g. if you picked up item X, a button to use it is added dynamically
#15
For some reason loadplugins was commented out, so no controls will be recognised initially.
Also, I found that some of the control plugins contain fields that will give input errors when trying to create them. For example, the GuiBitmapCtrl contains the groupNum field which will cause the creation to fail since I guess the bitmap control must not have that.
11/05/2004 (11:56 pm)
Hey John this is a really cool resource, I did find a couple glitches though. function TGUIBuilder::init(%this)
{
%this.numSets = 0;
%this.nextID = -1;
%this.maxSets = 50;
// %this.loadPlugins();
$guiPool.init();
}For some reason loadplugins was commented out, so no controls will be recognised initially.
Also, I found that some of the control plugins contain fields that will give input errors when trying to create them. For example, the GuiBitmapCtrl contains the groupNum field which will cause the creation to fail since I guess the bitmap control must not have that.
#16
TIA
11/06/2004 (3:52 am)
Anyone got a link to this resource? The authors' site appears down for whatever reason.TIA
#17
www.ontargetgames.com/torque/TGuiBuilder_001.zip
02/08/2005 (11:46 am)
I apologize for this file becoming unavailable. Something i'd rather not get into in this post (I'll do a .plan soon), but in the meantime here is a good link to the file:www.ontargetgames.com/torque/TGuiBuilder_001.zip
#20
10/03/2005 (11:38 am)
It is for me aswell. 
Torque Owner John Vanderbeck
VanderGames
When adding a control to a GUI Set, you define where it will be displayed. To do that you make use of control layout options. There are several layout options already supported and more will be added via the plugin system over time.
There are three parameters specified to control where a control is displayed. The first parameter indicates which layout option to use, and the second two parameters are layout specific options which vary depending on which layout type is being used. There are essentially two different types of layouts. Absolute layouts and Relative layouts. Absolute layouts specify an absolute position for the control that does not depend on the position of any other controls. For example specifying a control should be positioned at the coordinates of 100,100 would be an absolute layout. The position is not in relation to any other controls. Relative layouts specify the position of the control is relation to another control such as indicating the control should be placed below another one. Below is a list of all currently supported layout options with a brief description of each as well as an indication of what the parameters mean in each.
Absolute
This is, duh, an absolute layout. The control is placed at the coords specified.
param1 = The X position of the control. This can be specified either in pixels (ie 50) or in percent of screen resolution (ie "25%").
param2 = The Y position of the control. This can be specified either in pixels (ie 50) or in percent of screen resolution (ie "25%").
Anchor
Anchor is a special case layout option. It is exactly the same as Absolute except for one small difference. The control is "flagged" as being the anchor control, and other controls can be placed in relation to this one simply by specifying that they are in relatin to the "Anchor". Only one control in a set should ever be the anchor. If multiple controls are specified as the anchor then only the first one will be treated as such and un-defined behaviour may develop.
Above
Above is a relative layout. It specifies that the control be placed above the control it is related to.
param1 = The control that this one should be placed above. This can specify a control handle, specify "Anchor" or specify a null string "". In the case of a null string, the system defaults to placing this control above the last control added to the set.
param1 = The distance or spacing between the two controls. If one is not given then a default value will be used.
Below
Similiar to the Above layout option except this control is placed below the one specified. The parameters are the same.
Left
Similiar to the Above layout option except this control is placed to the left of the one specified. The parameters are the same.
Right
Similiar to the Above layout option except this control is placed to the right of the one specified. The parameters are the same.