Learning the GUI

#1 Stickied.

Quote:Do I have it correct how these files work together?

Pretty much. The code in toolbox.cs is used to dynamically create controls, rather than load them from file. The code also handles callbacks. It's very specific to the Sandbox, but you can still learn a lot about the GUI system by studying the code.

Something very important worth noting is that stock Torque 2D absolutely requires a default GUI profile, which you can find at the very top of profiles.cs. Without it, you will run into problems.

Quote:The gui uses an image folder within the gui directory and gui images within the asset directory. Why the distinction?

This is due to Torque 2D MIT inheriting legacy GUI functionality. Most GUI controls use a legacy, non asset way of displaying bitmaps. For example, custom skinning of things like GuiWindowCtrl, GuiButtonCtrl, and so on require raw image files that do not get used by the Asset System. It's not very intuitive and goes against the new T2D MIT asset stuff. However, it's currently necessary.

That explains the gui/images folder. The new GUI controls introduced to T2D MIT were the GuiImageButtonCtrl and GuiSpriteCtrl. They allow you to display buttons and images using the asset system, primarily ImageAsset and AnimationAsset.

So if you want a generic button with dynamic text that uses simple bitmaps, you would use the GuiButtonCtrl which points to raw image file in gui/images. If you want an animated sprite or fancy image button, use GuiImageButtonCtrl or GuiSpriteCtrl, which will use assets instead of raw image files.

#2 The Sandbox has 3 distinct GUI "screens". They are defined using TAML XML and are named MainOverlay.gui.taml, ConsoleDialog.gui.taml, and ToolboxDialog.gui.taml. Let's start with the simplest GUI - the main overlay. This is the row of buttons at the bottom of the screen that is always displayed regardless of which toy is loaded - allowing you to change manipulation modes, reset/reload the toy, display the console, or the toolbox menu.

<GuiControl
    Name="MainOverlay"
    Profile="GuiDefaultProfile"
    HorizSizing="relative"
    VertSizing="relative"
    Position="0 0"
    Extent="1024 30"
    MinExtent="220 30"
    Visible="1">

This definition comes from the TGB docs:
GuiControl
Class Hierarchy
GuiControl ->SimGroup ->SimSet ->SimObject

The root class for all GUI controls.

Note: GuiControl is derived from SimGroup and can contain any number of child GUI controls. Each GuiControl maintains a bounding rectangle in the coordinate system of its parent control. GuiControl has virtual methods for processing input events (onTouchDown, onTouchUp, etc), methods called by the Canvas for rendering (onPreRender, onRender), methods to control the lock focus of the mouse (mouseLock, mouseUnlock), coordinate conversion methods (localToGlobalCoord, globalToLocalCoord), and automatic sizing behavior when its parent control is resized (for example, when the screen resolution changes). When a control is made visible, it (if not already loaded) loads the data associated with its GuiControlProfile.

One of the buttons:

<GuiButtonCtrl
        Name="ManipulationModeButton"
        Profile="BlueButtonProfile"
	    Text="Mode"
	    ButtonType="PushButton"
        command="cycleManipulation(true);"
        canSaveDynamicFields="0"
        isContainer="0"
        HorizSizing="left"
        VertSizing="bottom"
        Position="360 0"
        Extent="100 30"
        MinExtent="8 2"
        canSave="1"
        Visible="1"
        Active="1"
        hovertime="1000"
        groupNum="-1"
        useMouseEvents="1" />

This is the basic button element. If you look at the BlueButtonProfile in the guiProfiles.cs file, you see that it does not use the asset system (Mich covered this in this post above). The BlueButtonProfile also inherits any style properties from GuiButtonProfile that the BlueButtonProfile did not specifically override.

if (!isObject(BlueButtonProfile)) new GuiControlProfile (BlueButtonProfile : GuiButtonProfile)
{
    fontSize = $platformFontSize;
    fontColor = "255 255 255 255";
    fontColorHL = "255 255 255 255";
    bitmap = "^Sandbox/gui/images/blueButton.png";
};

Key for the button to do anything is what is specified in the command field. For the button above, it will call the function cycleManipulation which is found in the manipulation.cs file. This function is scripted to cycle through the pan, pull, and off modes.

This is all a very basic and general description, but I'll leave it like this for now and if anyone has questions they can post below. But using this as a base to get a button to display on the screen in your projects is a pretty basic but important exercise to learn.

#3 Michael-

That helps a lot.

"The code in toolbox.cs is used to dynamically create controls"

I am still trying to get used to that aspect of everything being a runtime creation.

I still don't understand the image format in the legacy gui/images directory. Some of the images are on a grid, which isn't puzzling so much (assuming that its a template), but the button images have a grid on them also. Is it drawing small portions of the button or something?

Mike-

In your first block of code, you explain all controls derive from GuiControl. Is "MainOverlay" sort of a general, generic control? The values defined look like they correspond to the darkened bar at the top of the screen where FPS is displayed. I can infer what the values mean:

"Extent" is the default size of the control. "MinExtent" is the smallest it can be resized to.

Side question- for Boolean fields can I just use "true" instead of "1"?

My only other question for that block is what the exact, technical definitions of "Horisizing" and "Vertisizing" and some typical values that could be entered?

I have a few questions about the button code block, but those can wait for the moment.

#4 Hi Robert, this post has been helpful. Being new to the engine myself I hadn't given the gui a real detailed look yet but I can help with the "Horisizing" and "Vertisizing".

These can be set to "relative" to keep gui controls relative to their Position on fullscreen. Try leaving all gui controls set to default and then change the resolution setting to fullscreen. You'll notice the gui controls 'collapse' based on their Horisizing and VertSizing setting.

HorizSizing="relative"
VertSizing="relative"

The above will keep the controls 'locked in' when fullscreen is enabled. Cheers!

#5 This thread looks so helpful... I'm going to go try to tackle this starting with this thread in my spare time. If I can make enough progress I'll make a beginner tutorial, but I can't promise it will be any time soon.

#6 I've been struggling with the GUI builder in T2D as well. When I open the builder I have a huge checkerboard grid that I can drag and drop from a pull down list of various GUI controls. However, if I want to make a cool looking interface for the title screen and menus, HUD in game, and so forth, am I right in understanding that is all done in the above mentioned files and with code?

Thanks for this thread and I agree with the OP that there really is very little in the docs that ship with T2D regarding GUI implementation.

#7 If you're using the old pre-MIT T2D then your GUI can be built right in the editor. You're going to have to script a bit anyway to handle button-clicks, screen changes, adding new profiles for fonts and buttons, etc.

If you're using T2D MIT then it is going to be really time consuming to change the output from the old GUI editor into usable TAML GUI files.

No matter which way you go there is script to deal with.

While there is indeed very little by way of GUI tutorials, there are plenty of examples available. Just look at any GUI file you find and follow the code. It's not the way most people learn best, but "that hardest earned is hardest lost."

#8 I agree with Richard. It seemed extrmely daunting to me at first when I looked at the gui code but after really following the order things were being called I managed to get it.

As a result of the learning experience and threads like this, I am currently working on my first intro to gui tutorial. There is a lot to cover, so I will be breaking it all into sections. The first of which I'm actively working on now and will introduce the very basics of understaing what files are where and how they interact with one another. Stay tuned!

#9 I have been experimenting with the controls the last couple of days, making a little progress. I will report back in a few days to try and document what I have learned. I am starting simple and will display simple examples.

#10 Take a look at my drag-drop inventory example - it's not really "complete" and there are a few flaws, but it's tight and small so you can stay more focused on what is going on.

Actually, I lie a little - the dynamic containers are a little complex....

#11 Robert: This is great news! The guide I am currently working on is a general introduction to T2D and implementing a gui. It is fairly in depth about modules, the flow of the application, and what is required to get a gui off the ground. This is all from a beginner's perspective and as such the guide shows the bare minimum it takes to implement a console gui to a new application. This guide does not go into detail about the settings involved with manipulating gui image locations on the screen. As such it will be an invaluable resource when paired with a "follow up" that actually introduces the settings required to alter the gui effectively. The guide is about 90% complete at the time of this posting. I need to add a couple basic visual elements and tie it in with a solid Conclusion section.

Richard: I am very interested in this implementation and at some point will need to learn this stuff about a drag-drop inventory. I will take a good look at this once my beginner's guide is complete. Thanks for sharing!

#12 Thanks Richard. One of the problems I have had as I am trying to pick this thing up is that the guys who know what is going on tend to assume the user has knowledge that he/she might not have.

With this in mind, let me explain how I was able to get a basic button working. Mike explained how to earlier in the thread, but it didn't really fit together until I had to code it.

You need 3 distinct bits of script to create a button:

I am assuming that anyone trying to do this has at least gone through the Getting Started guide, which helps you get together a bare bones program.

1- You will need at least one gui.taml file in which you define a parent container and a child button (see above in Mike's post).

2- You need to create a guiprofile for your button (In addition to the default, of course).

3- You need to add the parent container to the scene.

In the gui.taml file I created a parent container and a child button to put in the container. The parent is called "mainOverlay", which is the name you want to refer to when performing actions with this control. I set the guiprofile to the default one, which I filled out with settings from the sandbox default profile. I then defined the child button.

<GuiControl
Name="mainOverlay"
Profile="GuiDefaultProfile"
HorizSizing="relative"
VertSizing="relative"
Position = "0 0"
Extent="300 1000"
MinExtent="100 300"
Visible="1">

<GuiButtonCtrl
Name="testButton"
Profile="BlueButtonProfile"
Text="Test"
ButtonType="PushButton"
command=""
canSaveDynamicFields="0"
isContainer="0"
HorizSizing="relative"
VertSizing="relative"
Position="0 0"
Extent="100 30"
MinExtent="50 15"
canSave="1"
Visible="1"
Active="1"
hovertime="1000"
groupNum="-1"
useMouseEvents="1" />

</GuiControl>

The parent container dimensions are 300x1000 (pixels?). Basically a panel going from top to bottom on the left side of screen on my 1920x1080 resolution setting.

Here are my guiprofiles:

//Font types
$platformFontType = ($platform $= "windows") ? "lucida console" : "monaco";
$platformFontSize = ($platform $= "ios") ? 18 : 12;


//GuiDefaultProfile
if(!isObject(GuiDefaultProfile)) new GuiControlProfile (GuiDefaultProfile)
{
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 = 0;
borderColor = "100 100 100 255";
borderColorHL = "128 128 128";
borderColorNA = "64 64 64";

//Font
fontType = $platformFontType;
fontSize = $platformFontSize;
fontColor = "0 0 0";
fontColorHL = "32 100 100";
fontColorNA = "0 0 0";
fontColorSEL= "10 10 10";

//Bitmap information
bitmap = "^Base/gui/images/window.png";
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 = $ButtonSound.fileName;
//soundButtonOver = "";

};

//GuiButtonProfile
if (!isObject(GuiButtonProfile)) new GuiControlProfile (GuiButtonProfile)
{
opaque = true;
border = -1;
fontColor = "white";
fontColorHL = "229 229 229 255";
fixedExtent = true;
justify = "center";
canKeyFocus = false;
fontType = $platformFontType;
bitmap = "^Base/gui/images/smallButtonContainer";

};

//BlueButtonProfile
if (!isObject(BlueButtonProfile)) new GuiControlProfile (BlueButtonProfile : GuiButtonProfile)
{
fontSize = $platformFontSize;
fontColor = "255 255 255 255";
fontColorHL = "255 255 255 255";
bitmap = "^Base/gui/images/blueButton.png";

};

#13 Now keep in mind that you will need to copy the gui/images folder from the sandbox to your gui directory in your module. These are the legacy graphics that were referred to earlier. You will need to change any directory string to match your own project.

There you have all you need to define the controls. All you need to do is add it to your sceneWindow:

mainSceneWindow.add(mainOverlay);
mainOverlay.position = "0 0";

To get your gui up and running is much more than a copy and paste operation. The only real trip up you might run into is to forget to copy the default legacy graphics from the sandbox gui/images directory. Other than that it, your just incorporating these bits of script into the proper place in your project.

#14 I have finally finished my Intro to GUI Part I tutorial. While this tutorial doesn't help with the actual fields used to manipulate the gui, it is a great intro to modules, gui, and workflow. Check it out here:

github.com/GarageGames/Torque2D/wiki/Intro-to-the-GUI:-Part-1

As we all learn more (through use of this forum) I will add more parts to the tutorial. I already have some of the material for Part II in a document and will be updating it as time allows this week. Cheers!

#15 Wanted to add an update here about positioning the GUI. I will be including this information in my Intro to GUI Part II tutorial soon. Until then, here is a sneak peek for those out there who need to position their buttons. I'm going to assume that you have a scene.cs file in your project that is creating the SandboxWindow for your GuiControl.

You're going to need 2 files to get a button. guiGuiProfiles.cs and MainOverlay.gui.taml. The GuiProfiles.cs file you can just copy from the main T2D directory. The MainOverlay.gui.taml file is going to deserve a little more attention. Let's build this parent container first by itself, delete the rest of the text so you have this:

<GuiControl
    Name="MainOverlay"
    Profile="GuiDefaultProfile"
    HorizSizing="relative"
    VertSizing="relative"
    Position="0 0"
    Extent="1024 768"
    MinExtent="320 320"
</GuiControl>

HorizSizing and VertSizing have to do with how the container is going to 'pad': left, right, top, bottom, center. I like relative, since it will pad my gui to be the same as I set it here if the resolution changes.
Position is the top left corner of your scene here: "0 0".
Extent is how far to the right and down your container will go. You want to set this to match the lowest resolution you are planning on supporting. I went with "1024 768" resolution. This lets my empty parent container can accomodate the entire screen so I can place buttons anyplace I like within its empty space.
MinExtent is the minimum distance to the right and left the the container will scale down (from the position 0 0).

Cool, we have the empty container ready, now let's add the button within the .gui.taml to make it like this:

<GuiControl
    Name="MainOverlay"
    Profile="GuiDefaultProfile"
    HorizSizing="relative"
    VertSizing="relative"
    Position="0 0"
    Extent="1024 768"
    MinExtent="320 320"

	<!-- Test Button-->
        <GuiButtonCtrl
	    Name="Test Button"
        Profile="BlueButtonProfile"
	    Text="Test Button"
	    ButtonType="PushButton"
	    command=""
        canSaveDynamicFields="0"
        isContainer="0"
        HorizSizing="relative"
        VertSizing="relative"
        Position="412 0"
        Extent="200 30"
        MinExtent="100 15"
        canSave="1"
        Visible="1"
        Active="1"
        hovertime="1000"
        groupNum="-1"
        useMouseEvents="1" />
</GuiControl>

Here the fields act the same way as the parent container, only now they are actually moving the button within the area we set in the parent.

Position here is the center of the screen. "Why not 512?," you may ask, "That is half of 1024." The position sets the button's top left point, and because the button here is set to be 200px wide(Extent) that means that it extends 100px before it reaches 512px.

Extent is just like the parent. 300 across and 30 down. If we wanted to place another button just under this one it would need a y value greater than 30. I used "300 40" on the 2nd button I made.

This should get the ball rolling to move stuff around at least.

#16 Hi Jesse,

First off - awesome job with the tutorial. It is nicely organized and reads really well. There are a few issues with the content though - some of the concepts you describe aren't quite correct.

Let's start with the basics. You sort of lump the entire GUI system into a "GuiProfiles" concept but that is only one portion of it. Anyone with a bit of web design knowledge knows that HTML is used for the building blocks (content) of a website and CSS describes the look and formatting of those building blocks. Torque's GUI system is conceptually similar to this. GuiControls are the building blocks for your game's GUI. Everything that goes on the Canvas is a GuiControl or a child type derived from GuiControl. The SceneWindow, which we all need to display any 2D game content, is at its heart nothing more than a very special derived class of GuiControl.

class SceneWindow : public GuiControl, public virtual Tickable
{
typedef GuiControl Parent;

So if a GuiControl is our version of an HTML element, then a GuiProfile is our version of a CSS attribute - the GuiProfile describing the appearance of a GuiControl. All GuiControls need to be assigned a valid GuiProfile in order for them to work - otherwise the engine will gracefully boot you to the desktop. This is why in the workflow we take care to make sure all our GuiProfiles are defined first before we push GuiControls onto the Canvas.

There were a few other topics that need minor corrections in how they are described, if you want I can add them here in a follow-up post and you can correct the tutorial yourself - or, with your permission, I can directly edit your document on the wiki. It's up to you.

#17 Mike,

First off, of course you have my permission to edit the document. The purpose of the document is to help others like myself learn easier and faster. I got Torque for free, I'm getting help for free, and there's no reason I can't document my progress to help improve the newcomer's experience. I am sure, being a newcomer myself, there may be omissions or oversights when attempting to produce a document of this scope. By all means please help me, it only helps us all!

About the SceneWindow: I do know about the SceneWindow and how it renders most things to the screen. However, if you look very closely at the tutorial, just to render the console only none of the code calls to SceneWindow. 'Canvas' from our AppCore's canvas.cs is called to push the dialog in the console.cs.

Canvas.pushDialog(ConsoleDialog);

This appears to be just an extension of the AppCore basically. At any point in rendering only the console and no other gui graphics, I didn't find anything actually using the SceneWindow. I was under the impression this was just part of the pre-T2DMIT Legacy system. It wasn't until I began working on the 2nd part of the tutorial that I found the need to use scene.cs(creates SandboxWindow) to add buttons. Any clarity here would be appreciated.

In my 2nd tutorial, it goes farther than this simple guide and introduces scene.cs which includes SandboxWindow (is this the equivalent of SceneWindow you describe?). It also talks about adding a module for handling assets (Asset System) and how that would change our Workflow Diagrams. In summary, Part I is very literally an introduction to gui and doesn't even use all of the necessary components that we would use for a 'regular' gui.

Also to note is that a complete newcomer may not have any prior knowledge of parent/child containers and so on. It could be a good idea to have the tutorial that introduces them to gui (because the subject is so broad in scope) be oversimplified (like Part I) and then introduce more in future tutorials. This was my way of thinking when not including the assets system or the SandboxWindow in Part I and adding that stuff in Part II.

In any event, I am excited to see what changes you make to the document! Thanks for helping with this, it really is needed!

#18 Mike: I just got in and reviewed your above posting again and wanted to add a bit more clarity about the html and css comparison you brought up. I do mention this in the Part I tutorial in Section III:

Quote:This is because GuiProfiles.cs is the default profile from which all other profiles are enherited. GuiProfiles.cs serves as a template for other, newer profiles (usually called Dialogs) to follow and as such it must be in place to add any other profiles.

While I do basically put the GuiProfile and the GuiControl within the same 'block' on the Workflow Diagram, I do differentiate between the two if only briefly. I didn't feel much more clarification would be necessary in Part I for only the console. However, I believe that I do understand now what you mean by how some things are worded. Describing more about the template-based structure (like html/css) rather than describing the process as a call / response perhaps? Anyways, I'll wait to see any changes you make to the document before progressing with Part II to be sure everything is 100% accurate. Thanks again for your help, we may actually get a solid reference/tutorial out of all of this!

#19 I was working with my project today, and while implementing the Main Menu and a seperate Options Menu it dawned on me the cause of confusion. While rebuilding the console I was borrowing from Sandbox in the T2D directory. Since Sandbox creates a SceneWindow called SandboxWindow, I completely overlooked the fact that 'Canvas' can be used as the 'Window' component to push the dialogs directly. I had gotten so used to the structure of the Sandbox directory, that I failed to realize if I was building from scratch I could push/pop dialogs with Canvas independently before adding any SceneWindow. Canvas basically is the SceneWindow at this point, and I believe this is the part where the tutorial falls short since it doesn't talk about the 'Window'.

Anyways, I have the toggleable console and also toggleable options menu working only using Canvas:

main.cs

function Sandbox::create(%this)
{	

	exec("./scripts/console.cs");
	exec("./scripts/options.cs");
	exec("./gui/guiProfiles.cs");
	
	// Load and configure the console.
    Console.add( TamlRead("./gui/ConsoleDialog.gui.taml") );
	GlobalActionMap.bind( keyboard, "ctrl tilde", toggleConsole );
	
	// Load and configure the console.
    Console.add( TamlRead("./gui/OptionsDialog.gui.taml") );
	GlobalActionMap.bind( keyboard, "escape", toggleOptions );
	
    Canvas.pushDialog(OptionsDialog);
	
	echo("@@@ Console::create function called");	
}

function Sandbox::destroy( %this )
{
	echo("@@@ Console::destroy function called");
}

options.cs - No command functions yet, just for testing.

function initializeOptions()
{   
    Canvas.pushDialog(OptionsDialog);
}

//-----------------------------------------------------------------------------

function toggleOptions(%make)
{
    // Finish if being released.
    if ( !%make )
        return;
        
    // Finish if the console is awake.
    if ( ConsoleDialog.isAwake() )
        return;       
        
    // Are the options awake?
    if ( OptionsDialog.isAwake() )
    {
        // Yes, so deactivate it.
        if ( $enableDirectInput )
            activateKeyboard();
        Canvas.popDialog(OptionsDialog);
        return;
    }
    
    // Activate it.
    if ( $enableDirectInput )
        deactivateKeyboard();

    Canvas.pushDialog(OptionsDialog);
}

Am I correct in thinking it's okay to use Canvas as the window to push dialogs prior to adding other scene content (SandboxScene, SandboxWindow, scene.cs)? Or is there some reason I need to create a scene.cs and SceneWindow prior to pushing the dialogs?

#20 Let me edit my post a little, I wasn't clear.

As far as abstraction:

Canvas < Scene < SceneWindow

To me that means that you should always prefer the higher levels of abstraction. You put the scene on the canvas and you put the sceneWindow on the scene.

I would imagine you don't want to directly access the Canvas unless you need to. SceneWindow is just a specialized GUI control, as stated above. I wouldn't try and bypass that, because you are bypassing important functionality built into the higher level objects.

To add dialogs to scene window just use: sceneWindow.add(dialogname);

To remove it: sceneWindow.remove(dialogname);