Contents

Introduction

Image:HelloWorld.jpg


This tutorial will show you how to use the Torque 3D GUI editor, where to find controls and what to do with them. We will use this lesson as a base for the rest of the series so if you are new to the GUI Editor this tutorial will be essential reading.


Suggested Reading:


Covered in this tutorial:

  • Create a GUI with a window, button and text label
  • Scale and position a control
  • Setup basic control properties
  • Dynamic label text
  • How to save your GUI

Setting Up

If you are new to Torque 3D, start with a new Blank project. The following projects will fit into any existing development environment.


NOTE: These tutorials will make reference to files from a blank project, so you will require knowledge of the Torque 3D file system or as recommended start from a new project.


Let’s start a new Blank project, click on the New Project button:


(click to enlarge)



Then from the following window name your new project as GUI Tutorials and select Empty from the drop down:


Image:NameProject.jpg


Click Create to make your project. A window will then show the progress of the new project creation process. When prompted click OK and then Finished to close down this window. Your new project named "GUI tutorials" will now show up in the Torque 3D toolbox.


Our First GUI

Run your new project, load a mission and open the GUI Editor:


(click to enlarge)



Head over to the file menu and select File->New GUI. Name our new "GUIHelloWorld" and leave the GUI Class set to GuiControl (There can not be any spaces when naming your GUI's). Press create button to move on.


Image:CreateNewGUI.jpg


You will notice, at the right hand side of the editor there is a list tree. Click on the entry for GuiControl highlight it:


Image:SelectGUI.jpg


NOTE: You must highlight the GuiControl to make it the active container for adding further controls.


Next make a save of our new GUI by going to File->Save As. Your file explorer will open to the current project game folder. You need to move to folder game/art/gui and give your new GUI a name HelloWorld.gui. Press the save button to continue.


HINT: Remember to make regular saves to prevent losing any of your work.


First Control


STEP 1: You will see the tab on the top right for the Library with all the available GUI control types, click on the tab:


Image:ControlPalette.jpg

You will notice that the Library can shows categories for all the available controls. Select the Containers category and from the list please choose GuiWindowCtrl it will be at the end of the common list. If you can not see the control, use the scroll bar to reach the other entries.



After you have clicked on the guiWindowCtrl, an instance of this control will be added to the editor.


STEP 2: You can move this new object by left clicking the mouse button and dragging the new window control to a new position on the screen. You can also resize this control by using the square handles. Try it now and make your window a little wider.


Image:NewWindow.jpg


STEP 3: Change the name in the window title bar. Select your window control either from the control list or directly in the editor work area, now you have access to its properties. Scroll down the list of properties until you find Window section and change the text value to read Hello World. Press enter to fix the new text in place.


Image:ChangeText.jpg


STEP 4: Now that we have a window, let's add a button. First we must ensure the new window control is highlighted as we want this to contain our button.


Image:SelectWindow.jpg


From the Library open the Buttons drop down and select GuiButtonCtrl a new button will now be placed in the window. Move this new button to a location near the bottom of your new window. Again you can resize this button control but for now we will leave it as it is.


Image:CreateButtonControl.jpg


STEP 5: Give the button a name. With the button control selected you will have access to all of its properties. In the standard layout these will be at the bottom of the controls list. Scroll down if needed, to the section named Button and change the display text entry to read Click Me:


Image:ChangeButtonText.jpg


This will update the Button Display text, notice your new button now shows Click Me. Save the GUI now by using the menu bar File > Save. Press F10 so that you can see your new GUI with clickable button. Press F10 again to return back to the GUI Editor.


HINT: You can press F10 at any time to see your GUI in action


Text Control

Next we will add a text label to our window, so that we can show some text when we press the button.


Image:ReselectWindowCtrl.jpg

With the GuiWindowCtrl selected, select the Library > Text category and select a new GuiTextCtrl from the control library.


Image:CreateTextControl.jpg


Move this new text control so that it sits above the button, you can either resize it so that it is the same width as the button by changing the position and extent under the Layout properties. To make it easier to see the text control, make sure it is selected and head over to its properties, change its text value to read as "Waiting".

Next we need to give the control a name so that we can easily refer back to it in script. Whilst the text controls properties are open, head to the top of the list and in name give it the id of lblHWDisplay and press enter.


Image:1_Images/lblHWDisplayName.jpg


You should have something looking like this;


Image:PrototypeWindow.jpg


HINT: Remember to save often, for ease use Ctrl + S,


Dynamic Text

STEP 1: Let's make our GUI do something when we press the button. This is made very easy in Torque 3D as all you have to do is call a little bit of script from within the button property pane. The script we will use changes the text property of the text control. Remember setting the text controls name? This is where it will be needed.


Sample Code:

lblHWDisplay.setValue("Hello World");


NOTE: Do not forget the semi-colon ( ;  ) or you will get an error.


Select the button control. Within its properties in the Control section there is an entry called command. It is in this property that we will enter our script from above.


Image:SetCommand.jpg


Save your GUI. Press F10 and try out your button; when you press the button the text should change to read "Hello World".


STEP 2: Now that you have pressed the button the text remains "Hello World". We need a way to clear and reset the display. This can be done by adding a similar bit of script to the text control Command parameter. Select the text control and in its Command add the following:


lblHWDisplay.setValue("Waiting");


Save your GUI. Now when you preview your GUI you can click on the text to reset it. You may have noticed the text looks a little small; this can be easily rectified by changing the text control Profile. The profiles hold data such as font color, size, and many other parameters. We we will explore this in greater detail in another tutorial.


For now while the text control is selected go to GuiControl and change the profile to GuiBigTextProfile. You may need to resize your GUI components to make every thing look nice and balanced.


Image:ChooseBigTextProfile.jpg


Save ( CTRL-S ) and preview ( F10 ) your GUI.


Image:FinalGUI.jpg


Conclusion

In this tutorial, you learned the following concepts:

  • Create window, Button and text label
  • Scale and position a control
  • Setup basic control properties
  • Dynamic label text
  • How to save your GUI


The next tutorial in this series we will look at other control types and how to use them.