The purpose of a profile is to alter the look and feel of a GUI Control. So, in order to test our profiles we will have to first create a simple GUI.

Start a new project and open up the GUI Builder. Create a new GUI called "ProfileSandbox". Select it in the tree view and set it's profile to 'GuiModelessDialogProfile'. In this new GUI create a 'GuiControl' for our main window and set it's profile to 'GuiWindowProfile'. Then highlight it by right-clicking on it and create a 'GuiTextCtrl' and a 'GuiMLTextCtrl'. Add some text to them and adjust their size and positions. Notice that you can only scale the 'GuiMLTextCtrl's width because the height is scaled automatically.

That's all we need. Make sure you save this GUI as 'guiProfileSandbox.gui' in your 'gui' folder and exit TGB. Now let's edit our scripts to exec the gui and push it to the screen when we start our game.

We need initializeProject in 'main.cs' to exec our gui script. Edit your 'main.cs' to look like the following:

function initializeProject()
{
   // Load up the in game gui.
   exec("~/gui/mainScreen.gui");
   
   // Exec game scripts.
   exec("./gameScripts/game.cs");
   
   // exec our sandbox gui
   exec("~/gui/guiProfileSandbox.gui");
   
   // Remove the following four lines if you would like to start the game without running the
   // level builder.
   if ($runWithEditors)
   {
      toggleLevelEditor();
      return;
   }
   
   // This is where the game starts. Right now, we are just starting the first level. You will
   // want to expand this to load up a splash screen followed by a main menu depending on the
   // specific needs of your game. Most likely, a menu button will start the actual game, which
   // is where startGame should be called from.
   startGame($levelEditor::LastLevel[$currentProject]);
}

Ok, now edit the startGame function in 'game.cs' in your 'gameScripts' folder to look like the following:

function startGame(%level)
{
   // Set The GUI.
   Canvas.setContent(mainScreenGui);
   Canvas.setCursor(DefaultCursor);
   
   // push the profile sandbox
   Canvas.pushDialog(ProfileSandbox);
   
   moveMap.push();
   
   if( isFile( %level ) || isFile( %level @ ".dso"))
      sceneWindow2D.loadLevel(%level);
}

Great, now start up TGB and press play. You should see your GUI on the screen. Not very pretty, is it? Also notice that when you drag the mouse over the 'GuiMLTextCtrl' you can highlight the text, which you might not want.

This is where profiles come in. There are all sorts of things we can do here to make this GUI easier on the eyes. Let's make a new cs file called 'profiles.cs' and save it in our 'gui' folder. This file is where we are going to store all our 'GuiControlProfile's.

Before we get started, it is important that you understand that any settings you don't specifically set in your profile will be set to the default values. This makes it easier on us as developers since we don't have to clutter up our profile scripts with settings we don't want to change.

Also note that although all 'GuiControlPrifile's have exactly the same fields, different fields affect different aspects of different controls. This may be confusing at first, but it just takes a little time playing with the profile settings and applying them to different controls to figure out what's what. For example: the exact same profile might have a drastically different appearance on a 'GuiControl' and a 'GuiButtonCtrl' because the two controls use the pofile information differently.

Let's start by defining a profile for our dialog window:

if(!isObject(ClearWindowProfile)) new GuiControlProfile (ClearWindowProfile)
{
   // use fillColor for guiControl background
   opaque = true; 

   // draw a border
   border = 1;       

   // set the border color -> "R G B"
   borderColor   = "80 140 140";

   // set the background color -> "R G B A"
   fillColor = "40 165 20 110";
};

Note that we set borderColor with three numbers and fillColor with four. All profile colors can be set with either three or four numbers. The first three numbers are red, green, and blue respectively. The fourth is an optional alpha (or transparency). Valid values for R, G, B and A are from 0 to 255. If no alpha value is specified, 255 is assumed.

Now let's define a profile for our 'GuiTextCtrl'

if(!isObject(HeaderTextProfile)) new GuiControlProfile (HeaderTextProfile)
{
   // set the type face
   fontType = "Times";

   // set the font size
   fontSize = 20;

   // set the font color
   fontColor = "240 160 45";
};

Note that 'fontType' is assigned as a string. TGB automatically caches fonts when you use them so you can release a game with a font that your users might not have.

Now let's set up our profile for the 'GuiMLTextCtrl' and make the highlighting invisible:

if(!isObject(BodyTextProfile)) new GuiControlProfile (BodyTextProfile)
{
   // GuiMLTextCtrl's draw borders, so lets turn 'border' off on this profile
   border = 0;

   // set the font type and color
   fontType = "Courier New";
   fontColor = "100 140 200";
 
   // set the highlighted text color to be the same as the normal text color
   fontColorHL = "100 140 200";

   // set the highlighted fillColor to be completely transparent
   // (on GuiMLTextCtrl's fillColor is the text background)
   // note that when alpha is 0, the RGB values don't matter
   fillColorHL = "0 0 0 0";
};

Now that we have three basic profiles, let's save this file and edit our 'main.cs' so it loads our profiles script. Note that for a GUI to use a profile, the profile has to be executed before the GUI, like so:

function initializeProject()
{
   // Load up the in game gui.
   exec("~/gui/mainScreen.gui");
   
   // Exec game scripts.
   exec("./gameScripts/game.cs");
   
   // exec our profiles, then our sandbox gui
   exec("~/gui/profiles.cs");
   exec("~/gui/guiProfileSandbox.gui");
   
   // Remove the following four lines if you would like to start the game without running the
   // level builder.
   if ($runWithEditors)
   {
      toggleLevelEditor();
      return;
   }
   
   // This is where the game starts. Right now, we are just starting the first level. You will
   // want to expand this to load up a splash screen followed by a main menu depending on the
   // specific needs of your game. Most likely, a menu button will start the actual game, which
   // is where startGame should be called from.
   startGame($levelEditor::LastLevel[$currentProject]);
}

This won't affect us the first time we start up, but once the GUI is saved with our custom profiles we will have to exec the profile first for the GUI to load up properly in the future.

Great. Now we're ready to test our profiles. Start up TGB and open the GUI Builder. Find and select 'ProfileSandbox' from the center dropdown list up top. Now let's apply our profiles. Because we executed our profile script we should be able to find our profiles in the profile list. It may be hard to find them because that list is not sorted, but they're in there.

Apply 'ClearWindowProfile' to the 'GuiControl' dialog window; 'HeaderTextProfile' to the 'GuiTextCtrl'; and 'BodyTextProfile' to the 'GuiMLTextCtrl'.

Make sure to save your gui file. Now run your level and you should see your profiles at work.

Now that you've successfully applied profiles to GUI Controls, try messing around with the settings. See what happens when you apply 'HeaderTextProfile' to the 'GuiMLTextCtrl'. Notice that in that case all of a sudden the 'GuiMLTextControl' shows a black semi-transparent border (the default border). We didn't need to turn border off in that profile because that profile was made for a 'GuiTextCtrl' and 'GuiTextCtrl's don't normally show borders.

TIP: Put your profiles in a file named guiProfiles.cs in the gameScripts directory to have them automatically loaded by Torque Game Builder on start-up, so you can edit your GUI with the built-in GUI editor, and see the effects of your profiles while editing.

Below is a list of all the basic fields on a GuiControlProfile and their default values. Try them out and see what they affect.

Thanks for reading and congratulations on completing this tutorial!

   tab = false;
   canKeyFocus = false;
   hasBitmapArray = false;
   mouseOverSelected = false;

   // fill color
   opaque = false;
   fillColor = "211 211 211";
   fillColorHL = "244 244 244";
   fillColorNA = "244 244 244";

   // border color
   border = 1;
   borderColor   = "40 40 40 100";
   borderColorHL = "128 128 128";
   borderColorNA = "64 64 64";

   // font
   fontType = "Arial";
   fontSize = 14;

   fontColor = "0 0 0";
   fontColorHL = "32 100 100";
   fontColorNA = "0 0 0";
   fontColorSEL= "200 200 200";

   // bitmap information
   bitmap = "./images/window";
   bitmapBase = "";
   textOffset = "0 0";

   // used by guiTextControl
   modal = true;
   justify = "left";
   autoSizeWidth = false;
   autoSizeHeight = false;
   returnTab = false;
   numbersOnly = false;
   cursorColor = "0 0 0 255";

   // sounds
   soundButtonDown = "";
   soundButtonOver = "";