Learning the GUI
by Robert Lohaus · in Torque 2D Beginner · 11/09/2013 (12:23 am) · 35 replies
Being a newcomer to T2D, I am happy to have found such a great and easy to use engine powered by a cool scripting language. My initial enthusiasm has been quenched just a bit when I looked at the GUI code and lack of documentation. Frankly, the Sandbox GUI code is intimidating. Being someone who is going to need a robust GUI, I have no choice but to learn this stuff. So, I am starting this thread as an attempt to document my learning experience and perhaps aid others in the future. The more the experts contribute, the more I will learn. The Sandbox has pretty robust functionality and the code and files are somewhat confusing. So I am going to get small bites of information and build controls from there.
With that out of the way, I am going to start with more of an organizational overview. The GUI controls (from what I see) use at least 4 different files.
-guiprofiles.cs
-toolboxDialog.gui.taml
-customToolboxGui.cs
-toolbox.cs
guiprofiles.cs:
This file contains profiles that can be attached to different controls. These profiles look to contain visual information such as font, colors, images, and sounds.
toolboxDialog.gui.taml:
This file contains size and position information about particular controls.
customToolboxGui.cs:
The functions in this file look like they control things at the dialog level.
toolbox.cs:
This file essentially tell Torque what to do when a control is activated (onSelect, onClick)
Do I have it correct how these files work together? In addition some information/definitions overlap, especially in the guiprofiles and gui.taml. Images are attached to controls in both files. The gui uses an image folder within the gui directory and gui images within the asset directory. Why the distinction?
I know this question is going to open a can of worms, but I need to create my own gui graphics. I see that the graphics used in the sandbox obey more than one format with regards to creation of the graphic itself. Some buttons have a grid overlaying the image. Some are straight forward. Is there a default sprite template with default GUI graphics on it? There doesn't seem to be any rhyme or reason to the graphic images, certainly no formal organization.
With that out of the way, I am going to start with more of an organizational overview. The GUI controls (from what I see) use at least 4 different files.
-guiprofiles.cs
-toolboxDialog.gui.taml
-customToolboxGui.cs
-toolbox.cs
guiprofiles.cs:
This file contains profiles that can be attached to different controls. These profiles look to contain visual information such as font, colors, images, and sounds.
toolboxDialog.gui.taml:
This file contains size and position information about particular controls.
customToolboxGui.cs:
The functions in this file look like they control things at the dialog level.
toolbox.cs:
This file essentially tell Torque what to do when a control is activated (onSelect, onClick)
Do I have it correct how these files work together? In addition some information/definitions overlap, especially in the guiprofiles and gui.taml. Images are attached to controls in both files. The gui uses an image folder within the gui directory and gui images within the asset directory. Why the distinction?
I know this question is going to open a can of worms, but I need to create my own gui graphics. I see that the graphics used in the sandbox obey more than one format with regards to creation of the graphic itself. Some buttons have a grid overlaying the image. Some are straight forward. Is there a default sprite template with default GUI graphics on it? There doesn't seem to be any rhyme or reason to the graphic images, certainly no formal organization.
About the author
#22
The Canvas is the foundation upon which all rendering occurs. So what can the Canvas render? Basically, content controls. A content control is the top level GuiControl for a screen. This GuiControl will be the parent control for all other GuiControls on that particular screen.
Dialogs:
A dialog is essentially another screen, only it gets overlaid on top of the current content control, and all input goes to the dialog. This is most akin to the "Open File" dialog box found in most operating systems. When you choose to open a file, and the "Open File" dialog pops up, you can no longer send input to the application, and must complete or cancel the open file request. Torque keeps track of layers of dialogs. The dialog with the highest layer is on top and will get all the input, unless the dialog is modeless, which is a profile option.
The two paragraphs above are from the Torque 3D documentation.
The SceneWindow is nothing more than a GuiControl. So yes, the Canvas is used to push "windows" in the generic sense and SceneWindow is a specific kind of window that displays the 2D contents of a Scene.
My original mention of SceneWindow a few posts above was more to highlight the various types of GuiControls available. I know for the first part of the GUI tutorial a SceneWindow isn't needed to display the Console and shouldn't be mentioned. So to your last question, you can use the Canvas to display any type of window or dialog prior to Scene content, yes. You only need to create a SceneWindow and Scene when you want to display game content like Sprites, CompositeSprites, etc.
11/16/2013 (11:54 am)
I don't have a ton of time right now to go into a lot of detail, but I will try to explain what I can. The Canvas is the foundation upon which all rendering occurs. So what can the Canvas render? Basically, content controls. A content control is the top level GuiControl for a screen. This GuiControl will be the parent control for all other GuiControls on that particular screen.
Dialogs:
A dialog is essentially another screen, only it gets overlaid on top of the current content control, and all input goes to the dialog. This is most akin to the "Open File" dialog box found in most operating systems. When you choose to open a file, and the "Open File" dialog pops up, you can no longer send input to the application, and must complete or cancel the open file request. Torque keeps track of layers of dialogs. The dialog with the highest layer is on top and will get all the input, unless the dialog is modeless, which is a profile option.
The two paragraphs above are from the Torque 3D documentation.
The SceneWindow is nothing more than a GuiControl. So yes, the Canvas is used to push "windows" in the generic sense and SceneWindow is a specific kind of window that displays the 2D contents of a Scene.
My original mention of SceneWindow a few posts above was more to highlight the various types of GuiControls available. I know for the first part of the GUI tutorial a SceneWindow isn't needed to display the Console and shouldn't be mentioned. So to your last question, you can use the Canvas to display any type of window or dialog prior to Scene content, yes. You only need to create a SceneWindow and Scene when you want to display game content like Sprites, CompositeSprites, etc.
#23
11/16/2013 (11:57 am)
Robert - just a quick correction: the abstraction is Canvas < SceneWindow < Scene < SceneObjects (Sprite, etc). 
#24
This is exactly what I was trying to achieve. I was literally trying to build only a gui menu (actually a couple different dialogs involved there) to come up before any content. As usual, your posting has been helpful!
11/16/2013 (12:18 pm)
Thanks Mike, you're the greatest man! That all makes perfect sense.Quote:So to your last question, you can use the Canvas to display any type of window or dialog prior to Scene content, yes. You only need to create a SceneWindow and Scene when you want to display game content like Sprites, CompositeSprites, etc.
This is exactly what I was trying to achieve. I was literally trying to build only a gui menu (actually a couple different dialogs involved there) to come up before any content. As usual, your posting has been helpful!
#25
I'm still going through the intro tutorial, it's probably going to take me a few days to complete it (not that I am rewriting everything, I just don't have a ton of time to sit in front of the computer).
A quick list of things from the AppCore section:
1. Since we can develop on both Windows and OSX, I put in some comments about the OSX setup just to prevent confusion from beginners using a Mac with T2D.
2. I changed the AppCore description to better describe what happens when you start up the engine. There is no module.taml file in the root folder - the engine runs the root main.cs file and tells the ModuleDatabase to scan for modules and then load AppCore specifically.
3. I define the Canvas briefly without going into a ton of detail - one thing that was not right was the $canvasCreated = true; sentence. This is nothing more than a global variable that we set to true or false to prevent us from trying to create more than one Canvas. The real creation function is found here:
It's a bit tricky since the createCanvas function is wrapped in a if statement, but basically createCanvas returns a true or false depending on whether it was successful in creating a Canvas.
I didn't include all that in the tutorial though - I thought maybe that would be too confusing for a beginner.
I'm not done with the Console section yet, but I did notice in the module.taml file you are telling the reader to leave the ModuleId to be "Sandbox" but in the main.cs file you have Console::create and Console::destroy. This won't work - the create and destroy functions need to have the same name as the ModuleId you define. More detail on this can be found in the module manager guide:
github.com/GarageGames/Torque2D/wiki/Module-Manager-Guide#module-scripts
11/17/2013 (6:08 am)
Glad I could help!I'm still going through the intro tutorial, it's probably going to take me a few days to complete it (not that I am rewriting everything, I just don't have a ton of time to sit in front of the computer).
A quick list of things from the AppCore section:
1. Since we can develop on both Windows and OSX, I put in some comments about the OSX setup just to prevent confusion from beginners using a Mac with T2D.
2. I changed the AppCore description to better describe what happens when you start up the engine. There is no module.taml file in the root folder - the engine runs the root main.cs file and tells the ModuleDatabase to scan for modules and then load AppCore specifically.
3. I define the Canvas briefly without going into a ton of detail - one thing that was not right was the $canvasCreated = true; sentence. This is nothing more than a global variable that we set to true or false to prevent us from trying to create more than one Canvas. The real creation function is found here:
if ( !createCanvas(%windowName) )
It's a bit tricky since the createCanvas function is wrapped in a if statement, but basically createCanvas returns a true or false depending on whether it was successful in creating a Canvas.
I didn't include all that in the tutorial though - I thought maybe that would be too confusing for a beginner.
I'm not done with the Console section yet, but I did notice in the module.taml file you are telling the reader to leave the ModuleId to be "Sandbox" but in the main.cs file you have Console::create and Console::destroy. This won't work - the create and destroy functions need to have the same name as the ModuleId you define. More detail on this can be found in the module manager guide:
github.com/GarageGames/Torque2D/wiki/Module-Manager-Guide#module-scripts
#26
So I encourage anyone who worries that they might not know enough or might make mistakes in writing a tutorial - don't be. It's a huge benefit to you and everyone else to put your thoughts down on (electronic) paper and describe in a guide how to make either something simple like a main menu screen or something more complex like a basic platformer game. There is no such thing as too much documentation.
11/17/2013 (10:47 am)
One thing I want to mention to everyone since sometimes it is difficult to show intent with just text - I'm not trying to be overly critical of Jesse's work. I am really happy that he took the time to write about the GUI. This is really the perfect example that shows you don't have to be an "expert" with the engine to contribute meaningfully to the documentation. And at the end of the day, not only will Jesse have a deep understanding of T2D's GUI system, but a great tutorial series will come out of it as well to help everyone.So I encourage anyone who worries that they might not know enough or might make mistakes in writing a tutorial - don't be. It's a huge benefit to you and everyone else to put your thoughts down on (electronic) paper and describe in a guide how to make either something simple like a main menu screen or something more complex like a basic platformer game. There is no such thing as too much documentation.
#27
Additionally, it's okay if you are critical when dealing with this sort of thing. This information needs to be precise, and 'almost' just won't get the job done in a situation like this. Thanks again Mike!
11/17/2013 (1:43 pm)
Thanks so much for helping with the tutorial Mike. Obviously as a beginner with the engine, the guide wasn't perfect but with your help I suspect it will be! Glad to see that you are correcting mistakes and adding more clarity to the document. I'm excited to see the tutorial once it's fully completed, but in the meantime as you edit the relevant content I have more time to work on my current project. Once I review all of Part I, I'll continue with Part II. Perhaps the 2nd time around I can have you proofread it before sharing it, to be sure there is no added confusion for any users (myself included haha). The documentation is definately needed for the GUI, if nothing else I am glad to have helped get the ball rolling there. Additionally, it's okay if you are critical when dealing with this sort of thing. This information needs to be precise, and 'almost' just won't get the job done in a situation like this. Thanks again Mike!
#28
After I figured out how to get a button displayed (in my bits of code above), I picked up the rest of the controls very quickly. Using label, edit, and list boxes are pretty darn easy. Its really a smooth system.
Having said that, I am missing a great deal of information regarding the various fields in the gui.taml file. Is there old documentation that anyone can link that details that stuff? A lot of that stuff I probably won't use, but it would be good to know.
11/18/2013 (8:01 pm)
Just wanted to update my progress:After I figured out how to get a button displayed (in my bits of code above), I picked up the rest of the controls very quickly. Using label, edit, and list boxes are pretty darn easy. Its really a smooth system.
Having said that, I am missing a great deal of information regarding the various fields in the gui.taml file. Is there old documentation that anyone can link that details that stuff? A lot of that stuff I probably won't use, but it would be good to know.
#29
www.garagegames.com/products/torque-3d/documentation
Bear in mind this is T3D documentation, but a lot of that is still applicable with T2D. Really good diagrams of hierarchy there; what I wouldn't give to have that detailed of a documentation that was T2D specific. You may need to dig in some, and scroll to the bottom of the pages to find actual code fields. Good luck and cheers my friend.
11/19/2013 (10:33 pm)
I may be a bit late here, but since no one beat me to it I figured I'd go ahead and drop this here:www.garagegames.com/products/torque-3d/documentation
Bear in mind this is T3D documentation, but a lot of that is still applicable with T2D. Really good diagrams of hierarchy there; what I wouldn't give to have that detailed of a documentation that was T2D specific. You may need to dig in some, and scroll to the bottom of the pages to find actual code fields. Good luck and cheers my friend.
#30
github.com/GarageGames/Torque2D/wiki/Intro-to-the-GUI:-Part-1
Congrats and looking forward to part 2!
11/21/2013 (5:23 am)
Ok, with a few modifications - your tutorial is now up in the official wiki, Jesse:github.com/GarageGames/Torque2D/wiki/Intro-to-the-GUI:-Part-1
Congrats and looking forward to part 2!
#31
11/21/2013 (5:33 am)
Well done! I like it.
#32
11/21/2013 (12:59 pm)
Newcomers rejoice! I will look over all this closer when I have more time, and resume work on Part 2 soon. I really like the clarity and simplification of the initial workflow. Thanks for getting it up on the wiki Mike!
#33
This part of the guide really gets into the 'meat' of the GUI, revealing most of the more difficult to understand aspects of the GUI system. Anyone who is not familiar with T2D MIT GUI will be absolutely well informed about its use after following these 2 tutorials!!
11/28/2013 (10:36 pm)
The document for Intro to the GUI: Part II is complete! I will be proofreading, revising if necessary, and then forwarding the document to Mike for approval on tomorrow! This part of the guide really gets into the 'meat' of the GUI, revealing most of the more difficult to understand aspects of the GUI system. Anyone who is not familiar with T2D MIT GUI will be absolutely well informed about its use after following these 2 tutorials!!
#34
11/29/2013 (12:12 pm)
Bump in case Mike notices this post before he checks his e-mail! Intro to the GUI: Part II is now in my repository pending review.
#35
github.com/GarageGames/Torque2D/wiki/Intro-to-the-GUI:-Part-2
11/30/2013 (10:19 am)
I read through it and made a few minor changes. It's up on the official wiki for the community now. Thanks again Jesse!github.com/GarageGames/Torque2D/wiki/Intro-to-the-GUI:-Part-2
Torque Owner Jesse Allen