Torque 2D Tutorial – GUI Buttons

by: Matthew "King BoB" Langley
edited by: Spider

• Introduction to the GUI Editor
• Creating GUI Buttons from images
• Loading your new GUI from the console

SETTING UP YOUR FILES

To start, create a folder called ‘buttons’ for our button files. Create it in the SDK\games\T2D\data\images folder. Next, in order to make an image button, we’re going to need an image. Actually, Torque uses 4 images for each button because a button has 4 states, but we’re just going to use one image copied 4 different times. We’re going to use the Garage Games logo as our image… you can copy the ‘gglogo.png’ file from the SDK\games\T2D\data\images\ folder and paste it into the buttons folder you just created. Now make 4 copies of the image, named ‘gglogo_n.png’, ‘gglogo_h.png’, ‘gglogo_d.png’, and ‘gglogo_i.png’. These are the images used for the button in its normal, highlighted, depressed, and inactive state, respectively.

MAKING THE BUTTON

Now, fire up T2D by running ‘T2D.exe’ in the SDK\games folder. Launch the Gui Editor by hitting F10 and create a new GUI by selecting File>New GUI.

Enter “TestGui” as the name for your new control. Note that in actual practice you should always name your GUI objects something descriptive, and it helps to end their names in “Gui” just to avoid confusion. Now click on GuiControl…

This is where you can choose what type of GUI you want to make. If you are making a small menu that pops up over your game, for example, you will use a GuiControl. If you want your GUI to have a background image, you’ll use a GuiBitmapCtrl, etc. We’re going to use a GuiControl for this tutorial, so leave that selected and click ok.

Now click the New Control button and select GuiBitmapButtonCtrl. This creates a GuiBitmapButtonCtrl within the GuiControl that we created in the last step. In other words, we are adding a button to ‘TestGui’… we can add many buttons or other items to a single GuiControl and thus create a whole menu.

Drag the new button out more towards the center a bit. Now in the bottom-right properties list click on Expand All... go down to the bitmap field in the general section and type in the path to the image: "T2D/data/images/buttons/gglogo". Do this without the _n, _h, or _d... it automatically adds those in at the right time. Now click apply and you should see the image. Resize it a bit using the black handles, then go to the command field in the properties list and enter ‘echo("test button press");’

Now click Apply and hit "F10" to leave the Gui Editor... ignore any weird artifacts (since it has no background it doesn't refresh as your pointer moves across it) and look for your image button and click it...

Now bring up the console (with the “~” tilde key) and see if the echo text “test button press” appears at the bottom like this:

If you got this then we’re in business. If not, go back and make sure you followed the steps properly. Forgetting to hit Apply is a common mistake… Once it’s working, hit “F10” again to re-enter the Gui Editor and select File>Save GUI. Click on the directory button and select T2D/data/gui.

Press the Save button and enter the name “testGui.gui”. Now, hit the “~” tilde key and type in “quit();” and press enter to leave T2D.

LOADING THE GUI IN SCRIPT

At this point we’ve created a Torque GUI. All that’s really left to do is tell our scripts to load it up at runtime, and then it will be available whenever we need it. A GUI can be loaded at any time while your game is running, but usually it’s a good idea to load up all the GUI’s you’ll be using when your program first runs. One of the main places this happens is in the client.cs script in the SDK\example\T2D\client directory in the 'client.cs' script file. Go ahead and open that script up in your favorite text editor. Scroll down to the line that says:

// Load-up GUIs.
exec("./mainScreenGui.gui");

The exec line loads mainScreenGui and we’re going to do the same thing for testGui so go ahead and duplicate that line and replace “mainScreenGui” with “testGui” so that it looks like this:

// Load-up GUIs.
exec("./mainScreenGui.gui");
exec("./testGui.gui");

Okay, we’re ready to test our GUI, so run T2D.exe again. At the start screen, open the console by pressing “~”. Type “canvas.pushDialog(testGui);” and press Enter. Close the console by pressing “~” again and you should see the button. Click it a few times. What we did was tell the canvas, the screen area where Torque draws, to ‘push’ our testGui dialog onto the top layer. We can push GUI after GUI on top of each other using this method.

The reverse of push is pop, so when we want to remove our Gui, we use the command “canvas.popDialog(testGui);”. These commands can, of course, be in script as well as the console. For now, open up the console (notice the “test button press” echos from when you tested your button) and remove your Gui using the popDialog command.

Alright! We’ve got our button working, and we know how to push it onto the screen and pop it off. One last thing you should know is that now that we have our testGui loading in script, it will be available in the Gui Editor. Go to the Editor by pressing F10. Click the middle button on top and select testGui from the dropdown. This is where you can select for editing any GUI that has been loaded, as shown above, with an exec command.

Okay, good job! That’s it for this tutorial. You should now have a basic idea of how the GUI editor works. Of course, there’s lots more to learn… Torque provides a wide array of different controls for use in your GUI’s, and we’ve only taken a look at buttons. For more information, see the other tutorials in this series and the Torque 2D documentation.