GUI Guide
The GUI system in T2D allows you build dialogs with controls to handle things like menus and in-game option screens. The system has been handed down from T3D and remains very similar to its roots. However, there are a few differences to using the GUI system in T2D. Most notably, it's easy to build your own user interfaces out of sprites. Doing so has some advantages, but a basic knowledge of the GUI system is still necessary to setting up a SceneWindow. Because this topic is so expansive, we will start with an overview of how the GUI system works and them move on to the details of each control and how it can be used.
Please note: This guide is a work in progress. The GUI system is large and documenting it will take us some time. Please be patient.
All GUI controls inherit from a single object aptly called GuiControl. GuiControl inherits from SimGroup which means that it can hold other controls inside of it. Each control has a set of its own properties, such as position and extent, and a set of shared properties which are contained in a different object called a GuiControlProfile. Every control needs to have a profile. The profile contains values such as the fill color. So the obvious question is, why do it this way? There are several advantages. First, you could change the entire look of a control simply by giving it a different profile. You could also change a value of a profile and immediately affect every control that uses it. So if all your buttons share a single button profile, you can change the button profile in one place and every button will change. This idea has been used with great success in other programming fields like web development where HTML and CSS fill the same roles as controls and profiles.
Unfortunately, there is also a downside to doing it this way. Namely, the GuiControlProfile has a lot of fields and each control can pick and choose which values it will actually use. How will you know which fields of the profile will be used with each control? By reading this documentation of course!
Before we go an further, we need to cover some basics. Let's walk through the steps needed to get your GUIs up on the screen.
-
Call createCanvas() to create an instance of GuiCanvas and wire it up to a window. The canvas will be a named object called "Canvas" and you can only have one. The canvas is actually a GuiControl as well and you can learn more about it in the List of Controls below. For now, let's just say the canvas is top level GUI element. If you want anything to appear before the user, you need to hand it to the canvas.
createCanvas("Window Name");
-
Call Canvas.setContent() to set a GuiControl as the current "screen" that appears before the user.
Canvas.setContent(%myScreen);
In this example, %myScreen would hold a GuiControl and that control would probably have several children, including a SceneWindow. More on that later.
-
When you want another GUI to go over the main screen, you push a "dialog" onto the Canvas.
Canvas.pushDialog(%myDialog);
Here %myDialog also contains a GuiControl. This dialog could actually cover the whole screen, but then you might as well use setContent() instead. So it makes sense if you use this for the control to cover part of the screen. This has been compared to a save or open dialog that you see in most applications. Most importantly, when you push a dialog onto the canvas, the dialog will capture all input events until it is removed with popDialog(). You can stack multiple dialogs in the Canvas.
These are properties that exist on every control because they inherit them from GuiControl. It's super important to understand these so we'll cover them here before we get to the master list.
This is the position of the top left corner of the control with (0,0) being the top left corner of its parent control. Larger y positions are further down the screen. This matches the way most screen/window positioning works in most operating systems, but it is backwards from the way a Scene works.
This is the width and height of the control. The extent will change automatically when its parent's extent changes based on the values of HorizSizing and VertSizing which are covered next. There's also a callback when the extent changes called onExtentChange(). It is important for SceneWindows to catch this to adjust their camera ratio. More on that in the SceneWindow section below. As you would expect, MinExtent is the smallest that the control can become.
Here's where things get confusing. These settings determine how a control is repositioned and resized when its parent is resized. This is based on its related size/position when it is added to its parent. The possible options are center, relative, left/top, right/bottom, and width/height.
- Center: The control will stay centered in its containing parent. The extent of the object will not change - only the position.
- Relative: The control will maintain the same position and extent to its parent. So if the parent doubles in size so will the control. Also the distance between the edges will double. Basically this matches zooming in and out on the GUI.
- Left/Top and Right/Bottom: Any change to the parent's size will be applied to the distance between the control and the specified edge which effectively anchors the control to the opposite edge.
- Width/Height: These settings allow the only extent of the control to change. So the control will remain the same number of pixels from the edges of its parent. This is kind of like anchoring the control to both edges.
This is the GuiControlProfile that the control will use. The profile holds a lot of information on how a control should look and can be quickly swapped to change the entire look of a control.
Do you really need me to explain this? Ok, true means it gets rendered. False means it's hidden.
Every control can have a tool tip. These four fields control how that tip works. The HoverTime determines how long the cursor should "hover" over a control before the tip appears (1000 = 1 second) and the width is used to determine how wide the tip is in pixels. The field Tooltip is the actual text of the tip. The TooltipProfile is another GuiControlProfile that is used to determine the look of the tip. If this is not set it will fall back to the profile for the control. It uses the profile's font, fillColor, borderColor, and fontColor.
There are some properties that are inherited from the GuiControl but aren't always used. These properties are more specific in their function.
Both of these properties take a string of code that will be evaluated at certain points. For example, the GuiButtonCtrl calls the command when it is clicked. Most controls don't use both command and altCommand. Generally, the command is code that is called during the use of the control, whereas altCommand is called when the control is done being used. But there are no hard rules here! Just two commands that each control can use as they see fit. See the detailed section below for each control to see which command you should set.
The Accelerator Key gives you an easy way to set a key that will activate the control. What that means exactly depends on the control. A button control for example will simulate a click. If another control absorbs a key press nothing will happen. This basically give you an easy way to build hot keys into your GUIs.
This class is not actually a GuiControl. Instead it holds a handful of common values that each control uses to render itself. Here is a list of all of those properties. Most controls won't use all of these properties and you'll want to go the section for the control in question to see exactly which properties should be set for a control.
-
tab - True if the tab key can be used to access the control.
-
canKeyFocus - True if the control can be given keyboard focus.
-
mouseOverSelected - True if a control because "selected" when the mouse is over it.
-
modal - This really only applies top level controls that are pushed onto the Canvas with pushDialog(). True means that it will allow events that it doesn't consume to pass to the dialog or screen below it in the stack. False means that it will consume all events. Sounds scary...
-
opaque - This is true if the object is not completely translucent. The fillColor will only be used if opaque is true.
-
fillColor - Normally this is used for the background of the control.
-
fillColorHL - The HL stands for HighLight. This color is typically used when a control is selected.
-
fillColorNA - The NA means "not available". This color is used for disabled controls.
-
border - An integer value. Zero means no border. Other values can mean different things to different controls such as different types of borders. See details about each control below.
-
borderSize - The number of pixels thick that border should be. Before version 4.0, this was called borderThickness and was generally ignored by the engine.
-
borderColor, borderColorHL, and borderColorNA - The color of the border with selected and disabled variants.
-
bevelColorHL - Used by some controls that show a bevel. This is the HighLight color.
-
bevelColorLL - Similar to the HL version, this is the LowLight color.
-
fontType - The name of the font that should be used by the control.
-
fontSize - You guessed it! The size of the font that should be used by the control.
-
fontColor - The color of the font.
-
fontColorHL, fontColorNA, and fontColorSEL - The variant font colors for HighLight, Not Available, and Selected.
-
fontColorLink and fontColorLinkHL - As the name suggests, some controls use this to render links and HighLighted links.
-
fontCharset - Possible values are: ANSI, SYMBOL, SHIFTJIS, HANGEUL, GB2312, CHINESEBIG5, OEM, JOHAB, HEBREW, ARABIC, GREEK, TURKISH, VIETNAMESE, THAI, EASTEUROPE, RUSSIAN, MAC, and BALTIC.
-
justify - Handles how the font is aligned. Possible values are left, right, or center.
-
textOffset - The offset of the text from the position that it would normally be rendered.
-
autoSizeWidth and autoSizeHeight - True if the control should expand to fit its contents.
-
returnTab - True for certain controls will cause the return key to simulate a tab press instead.
-
numbersOnly - The control should only allow numbers. Mostly useful with text edit controls.
-
cursorColor - The color of the blinking text cursor in text edit controls.
-
bitmap - The name of the bitmap file to use for the control. Typically you would start this string with a carrot (^) followed by the name of the module and then the file path to the image. Many controls break this image into multiple pieces based on a separator color. The separator color can be any color and is determined by the color of the top left pixel in the image. The number of and configuration of the bitmap pieces needed are highly dependent on the control. See the section below for the control you're interested in.
-
soundButtonDown - A sound asset that should be played when a button is pressed down. Obviously, not all controls will use this.
-
soundButtonOver - A sound asset that should be played when the cursor enters a control.
-
profileForChildren - The profile to use with children controls (such as the scroll bar on a popup menu) when defined.
Up to this point, we've covered in a general way how the Gui system works. This section will take an in depth look at each control. These are grouped with similar controls together. The most important controls come first.
This section is still under construction. Although incomplete, we hope you will find some of this useful.
All controls inherit from the GuiControl. In most cases, the only reason to use the GuiControl directly is as a container to hold other controls. The GuiControl renders with a background based on the fillColor and can optionally include a border. Things get a bit complicated with the border. There are 7 options to create the border which use the "border" value in the profile. They are documented here with pictures. This profile is used in the pictures:
GuiControlProfile(DemoProfile)
{
opaque = true;
fillColor = "40 44 52 255";
border = 1; //This value determines the type of border. A value of 0 mean no border.
borderColorHL = "244 184 0 255";
borderColor = "0 0 0 60";
borderColorNA = "187 0 0 255";
borderSize = 4;
bevelColorHL = "255 255 255 60";
bevelColorLL = "0 0 0 90";
};
This is a standard border that works as you would expect. The fillColor appears under the border. The borderSize determines the thickness of the border and borderColor is used for its color.
This border uses bevelColorHL and bevelColorLL to create a "pillow" effect. It makes it appear as if the control is sinking into the background and sticking up a little. The lines take two pixels on each side and cannot be changed with borderSize. They are drawn over the fillColor. Prior to version 4.0, this used borderColorNA instead of bevelColorLL.
