GUI Guide

Introduction

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. Also, this documentation applies to the latest version of the engine, currently in the development branch.

Overview

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!

Putting Your GUIs on the Screen

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.

1. 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");

2. 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.

3. 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.

Common Properties

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.

Position

This is the position of the top left corner of the control with (0,0) being the top left corner of its parent control's content area (i.e. the parent's area after applying margin, border, and padding). 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.

Extent and MinExtent

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 possible extent.

HorizSizing and VertSizing

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.

1. Center: The control will stay centered in its containing parent. The extent of the object will not change - only the position.
2. 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.
3. 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.
4. 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.

Profile

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. See below for more.

Visible

As the name suggests, true will cause the control to be rendered. False will cause the control and it's children to not render.

TooltipProfile, HoverTime, TooltipWidth, and Tooltip

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, fontSize, fillColor, fontColor, and border settings.

Less Common Properties

There are some properties that are inherited from the GuiControl but aren't always used. These properties are more specific in their function.

Text and TextID

The text of a control can appear in different places depending on the control. For example, the button control will place the text on the button. The textID finds the text in the localization system and sets the text. You should only need one of these. Not all controls render their text.

Command and AltCommand

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.

Accelerator

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.

GuiControlProfile

As stated above, 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 becomes "selected" when the mouse is over it.

• useInput - True means that it will consume events and pass them on to any children that also useInput. False means that it will ignore events, preventing them from reaching its children and allowing the parent to consume them instead.

• 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 hovered over. There are variations for font colors and borders that match this as well.

• fillColorSL - The SL stands for Selected. Use of this color is control specific.

• fillColorNA - The NA stands for Not Active. This color is used for disabled controls.

• borderDefault - A GuiBorderProfile that is used for all four borders of a control. This can be overridden with more specific settings. See the next section for more details on a GuiBorderProfile.

• borderLeft, borderRight, borderTop, and borderBottom - Profiles that can be used to override the borderDefault setting for a specific edge.

• 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, fontColorSL, and fontColorNA - The variant font colors for HighLight, Selected, and Not Active.

• 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.

• align - Handles how the font is aligned. Possible values are left, right, or center.

• vAlign - The vertical alignment of the font. Possible values are top, middle, or bottom.

• textOffset - The offset of the text from the position that it would normally be rendered. This is typically applied after the text's position has been calculated. You should be careful not to move the text outside of the control or it will be clipped.

• returnTab - True for certain controls will cause the return key to simulate a tab press.

• 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.

• 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.

Rendering options

There are three ways to render a control: assets, bitmaps, and default rendering. A profile defines which of these options will be used by its controls. If multiple ways are defined then the asset will be used first, followed by the bitmap, and finally default rendering. Every control has the option of using these three. Default rendering simply uses the fill color and border settings to render the control. You should note that even if you use ImageAssets or Bitmaps, border settings like margins will still apply. Additionally, padding and actual borders (even though they aren't visible) will still affect child and text placement.

• imageAsset - ImageAssets are the preferred way to apply an image to a control because it uses the new Asset Manager to dynamically load and unload the image. Its the same system used to give images to Sprites and it's simpler to only learn one system. ImageAssets with multiple frames will use one frame for each of the four states (normal, highlight, selected, and not active). If an image asset doesn't have enough frames to cover a state, bitmaps or default rendering will be used instead for that state. If the image frame has nine frames or more, the engine will automatically switch to "skinning" mode which requires nine frames per state: four frames for corners, four frames that stretch for edges, and a center frame that it stretched to fill the middle. See the example in the bitmap section below. Just like assigning an asset to a Sprite, you state the module name and the asset name separated by a colon.
• bitmap - The bitmap system uses images in the same way as the ImageAsset but it's older. 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. Like the asset, frames are applied as one per state if there are less than nine and nine per state otherwise. Here's and example with a full thirty-six frames.

As you can see, each section is divided by a red line. The dividing color is determined by the top left pixel. The corner images will not be stretched. The other images will be stretched to fit the size of the button. If you want the control to use default rendering then don't set this entirely. Setting it to an empty string will result in an error.

GuiBorderProfile

These profiles can be assigned to a GuiControlProfile either as a default border profile that covers all sides, or as a profile that covers a specific side. This allows you to control the look of each side separately from the others. This also has variations for the different control states, allowing you to customize the way each control looks. The spacing used for borders mimics that of the CSS Box Model with margin on the outside, then borders, then padding and finally content.

• margin, marginHL, marginSL, and marginNA - An integer state the size of the margin with state variations. The area of the visible control will be decreased by the size of the margin. Although nothing is rendered to the margin, it is still part of the control. So a button rendered with a margin of 10 will have an area 10 pixels deep around it that can still be clicked as part of the button. Because of this, you should use small margins for effect and use position and extent if you want to shrink and relocate the control.
• border, borderHL, borderSL, and borderNA - An integer stating the size of the border with state variations. Use zero for no border.
• borderColor, borderColorHL, borderColorSL, and borderColorNA - The color of the border with state variations.
• padding, paddingHL, paddingSL, and paddingNA - An integer stating the size of the padding with state variations. The padding is the distance between the border and the content of the control such as text and child controls.
• underfill - True if the control's fillColor should appear under the border. This really only matters if you decide to use partially transparent colors for your boarder.

Content or the Inner Rect

Occasionally in this guide, the content or inner rect of a control will be referred to. This means the area of the control after applying the margin, border, and padding for all sides. Both text and child controls are positioned with in the inner rect. So placing a child control at (0,0) will place the top left corner in the top left corner of the content. In most cases, you will want the inner rect to remain unchanged by the state variations. So for example, if you have a margin of 1 in the normal state and a margin of 0 when the control is hovered, then you should offset the change with a 1 pixel increase in border or padding when the control is hovered. This will keep text from moving around when the control changes states and keep child controls resizing in a consistent way.

List of Controls

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.

GuiControl

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 or to display single lines of text. The GuiControl renders using the standard fillColor and border settings. If you add text to the GuiControl then it will be rendered in the content section of the control. Here is an example of a plain GuiControl rendered over the Truck Toy.

GuiCanvas

The GuiCanvas is a very special control that sits at the root of the GuiControl tree. There is only one canvas: a named variable aptly called "Canvas". This is initiated through createCanvas(). The canvas can then set a GuiControl as its content and show additional GuiControls as dialogs. Details of all the functions available to the canvas can be found in the Doxygen documentation. A simple review of the code shows that the canvas does not use a GuiControlProfile at all. Like other controls, it uses position and extent.

SceneWindow

This is the only GuiControl that doesn't start with "Gui" so you know it's special! As it turns out, the concept of the SceneWindow is extremely important to developing with T2D which is why is already covered in the Getting Started Guide. To summarize, the SceneWindow is a GuiControl that renders a Scene to the screen. The various functions of the SceneWindow are covered by the Doxygen documentation.

The SceneWindow uses its profile's font and fontColor to render metrics. The background of the metrics banner uses the fillColor.

The position and extent of the SceneWindow is also important. When the extent of the SceneWindow changes, it will not adjust the camera area covering the scene. If the ratio of width to height for the scene does not match that of the camera then the image will appear stretched. To combat this, you should respond to the onExtentChange() callback and adjust the area of the camera to match the new extent.

MySceneWindow::onExtentChange(%this, %bounds)

The new bounds for the SceneWindow are passed into this callback. This is a space-separated string that contains positionX, positionY, width, and height.

GuiButtonCtrl

This is designed to be a button, but functionally it is the same as a basic GuiControl that interacts with the mouse or with touch. This is because the button can also act as a container for children.

Settings

• command - The button evaluates the contents of the command string if the button is clicked or otherwise activated. If no command is given, the button instead will call the onAction() callback.
• easeFillColorHL - This is the easing function that is used when the fill color changes to highlight. It defaults to Linear.
• easeFillColorSL - This is the easing function that is used when the fill color changes to selected. It also defaults to Linear.
• easeTimeFillColorHL - This is the time in milliseconds that it takes to change the fill color to highlight. It defaults to 500 (half a second).
• easeTimeFillColorSL - This is the time in milliseconds that it takes to change the fill color to selected. It defaults to 0 (instant).

Note: you can learn more about easing functions in the Easing Guide.

Callbacks

• onTouchEnter() - Called when the mouse passes over the button.
• onTouchLeave() - Called when the mouse leaves the button.
• onTouchUp() - Called when the mouse button is released over the control.
• onClick() - Called when the button is clicked, either with the mouse or with the accelerator key.
• onRightClick() - Called when the right mouse button is released over the control.
• onAction() - Called if no command is set after calling onClick().

Profile Fields Used

• Rendering - This uses all standard rendering methods (ImageAsset, bitmap, and default rendering) in all four possible states.
• Tab - True allows the button to be selected using the tab key.
• canKeyFocus - Will receive keyboard inputs first if this is true and the button is interacted with.
• soundButtonDown and soundButtonOver - These sounds will be played if useMouseEvents is set to true.
• align and vAlign - This will determine how the text is aligned within the button.

Methods Easing only applies to default rendering.

• setFillColorHLEase(%ease, %time) - Sets the ease function that is used to change the color to the highlight color. You can optionally set the time in milliseconds as well.
• setFillColorSLEase(%ease, %time) - Sets the ease function that is used to change the color to the selected color. You can optionally set the time in milliseconds as well.
• getFillColorHLEaseFunction(), getFillColorSLEaseFunction() - Returns the easing function used for the highlight and selected fill color transitions.
• getFillColorHLEaseTime(), getFillColorSLEaseTime() - Returns the ease time used for the highlight and selected fill color transitions in milliseconds.

GuiCheckBoxCtrl

The checkbox inherits from GuiButtonCtrl. The information for that control still applies to the checkbox but it won't be repeated here. Checkboxes expand on basic buttons by allowing them to toggle on and off. Please note that easing functions available on the button's fill color will not be applied to checkboxes or radio buttons.

Settings

• stateOn - Set this to true to start the checkbox as checked.
• boxOffset - The offset from the top left corner of the content that the actual checkbox should be rendered. Note that the entire control is still clickable.
• boxExtent - The size in width and height of the actual rendered checkbox. Note that the extent of the box cannot go outside the bounds of the content.
• textOffset - The offset from the top left corner of the content that the text area will begin. This has the same name as a field in the GuiControlProfile but is functionally different.
• textExtent - The width and height of the area that the text will be rendered in. Note that the textExtent will not expand outside of the control's content.

Callbacks - Has the same callbacks as GuiButtonCtrl.

Profile Fields Used - Uses the same fields as GuiButtonCtrl.

• imageAsset and bitmap - An imageAsset or bitmap can be used to render the checkbox but it works a little differently than other controls. The texture will only apply to the boxOffset and boxExtent. The checkbox requires eight frames. The frames are off, off hover, off selected, off disabled, on, on hover, on selected, and on disabled. This is essentially the four standard states twice. It's also possible to use an image with nine frames per state which is seventy-two frames. Here is an example bitmap magnified x4.

Methods

• setStateOn - True to check the box. False to uncheck.
• getStateOn - Returns the current state of the checkbox.
• setBoxOffset - Takes the x and y offset of the checkbox.
• getBoxOffset - Returns the x and y offset of the checkbox.
• setBoxExtent - Takes the width and height of the checkbox. Remember the checkbox will not be drawn outside of the control's content area.
• getBoxExtent - Returns the with and height of the checkbox.
• setTextOffset - Takes the x and y offset of the text draw area.
• getTextOffset - Returns the x and y offset of the text draw area.
• setTextExtent - Takes the width and height of the text draw area. Remember the text will not be drawn outside of the control's content area.
• getTextExtent - Returns the with and height of the text draw area.

GuiRadioCtrl

The radio button inherits from GuiCheckBoxCtrl so the information about that control applies to the radio button as well. Radio buttons stay on when clicked, but only one radio button in a group can be on at a time. Default rendering for radio buttons render them as circles instead of squares.

Settings

• groupNum - Radio buttons of the same group should have the same groupNum. When one button is clicked, the other buttons in the same group turn off (they "radio" to the other buttons that they should turn off).

Callbacks - Has the same callbacks as GuiButtonCtrl.

Profile Fields Used - Uses the same fields as GuiButtonCtrl.

• border - Since radio buttons are rendered as circles, they only have one border. As such, only the borderDefault value is used. The more specific settings, like borderLeft, are ignored.
• imageAsset and bitmap - An imageAsset or bitmap can be used to render the radio buttons. The texture will only apply to the boxOffset and boxExtent. Like the checkbox, the radio button requires eight frames. The frames are off, off hover, off selected, off disabled, on, on hover, on selected, and on disabled. This is essentially the four standard states twice. It's also possible to use an image with nine frames per state which is seventy-two frames. Here is an example bitmap magnified x4.

Methods The radio button inherits from the checkbox and button so it has the same methods.

GuiTabBookCtrl

Everybody knows how tabs work! This control adds tabs to the GUI system. The GuiTabBookCtrl is the main control that is responsible for keeping a list of "pages" and rendering tabs for them. Clicking on the tab switches to the page. Easy right? Tabs can be position on the top, bottom, left or right and have a wealth of rendering options.

Only a GuiTabPageCtrl can be added to the book as a child. To work as intended, the page should have the same extent as the book and be positioned at (0,0). The page and its contents will then be resized to fit the page area when the page is added to the book. For this reason, it is important that the contents of the page are added before the page is added to the book.

Settings

• tabPosition - The location of the tabs. Possible values are top, bottom, left or right.
• tabProfile - This is a GuiContentProfile. In addition to the normal profile, which applies to the area behind the tabs, this profile is used to render the tabs themselves.
• minTabWidth - This is the smallest a tab can shrink.

Profile Fields Used - In case you missed it, this control has two profiles: profile and tabProfile! The normal profile's border and fill color is applied to the area behind the tabs. This allows you customize the background. Only the normal state is used so don't both setting the other states (i.e. set border but don't bother with borderHL). The tabs are rendered in the inner rect of the profile. So adding padding to the top border of the profile will add some space between the tabs and the top of the tab section. The tabProfile is applied to the tabs. This includes the fill color, font settings, and border settings with all states. Like other controls, imageAssets or bitmaps can also be used.

Methods

• selectPage(%pageIndex) - Selects the active tab by a zero-based index.
• selectPageName(%pageName) - Selects the active tab by the name that appears on the tab. This is the text or textID field inherited from GuiControl.

GuiTabPageCtrl

The only possible child control of the tab book above. The GuiTabPageCtrl is basically a special container. It's profile is used to render the page section of the tab book when the page is active. The page should be set to use the entire area of the book and will be resized as needed. The text set on this control will be used in its matching tab. Here's an image to recap how the book and page work together.

Settings

• text or textID - These are inherited from GuiControl, but it's worth noting that the page control uses these values to display the text on the actual tab.

GuiScrollCtrl

This control is a simple container with scrollbars if the contents happen to overflow the container. The control's profile will be applied like other controls with margin on the outside, then the border, and last the padding. The actual scrollbars will appear between the border and the padding and the padding will appear within the scrolled area between the child controls and the border. Child controls should always be placed at positive coordinates. The scrollable area will not extend to the left or top past zero.

Some quick terminology: The scrollbar has arrow buttons on either end of it. The moving part between the arrow buttons is called the thumb. The thumb moves along the track.

Settings

• scrollBarThickness - Determines the width or height of a scroll bar. Since the bar is controlled by profiles (more on that later) this represents the thickness of the entire scroll bar including any margin, border, and padding. The scrollbar may not render correctly if these three are greater than the thickness. The arrow buttons are always a perfect square based on the thickness and the thumb will be two times the thickness if constant thumb height is used. If a texture is used, then this value is overwritten by the width of the vertical track frame. Defaults to 16 pixels.
• showArrowButtons - If false the arrow buttons will be hidden entirely. Hiding arrow buttons is a common trend in modern applications, but some users prefer to have them available. Defaults to true.
• constantThumbHeight - True if the thumb should be a constant size regardless of scroll area. Thumb will be twice the thickness in this case. If false then the scrollbar will reflect the size of the scroll area.
• hScrollBar and vScrollBar - Determines if these bars are visible. Possible values are alwaysOn, alwaysOff, and dynamic. Dynamic scrollbars will only appear if the contents of the container overflow the content area. If always on and the children fit in the contents, then the bar will appear but will be disabled using the profiles' disabled states. Defaults to alwaysOn.
• thumbProfile - This is the GuiContentProfile that will be applied to the thumb and arrow buttons.
• trackProfile - This is the GuiContentProfile that will be applied to the track. This profile can be ignored if you prefer an invisible track.
• arrowProfile - This is the GuiContentProfile that will be applied to the arrow buttons. This profile is ignored if the arrow buttons are hidden using showArrowButtons. It is required otherwise.

Profile Fields Used The scrollbar has four different profiles! The main profile applies to the body of the control and includes the margin, border, and padding in the normal state. Fonts and other states are ignored. The trackProfile uses the margin, border and padding of the normal and disabled states. The arrowProfile and thumbProfile both use the margin, border, and padding of all four states. Additionally, the arrowProfile uses the font colors of the four states to color the arrows which are drawn within the content of the arrow buttons.

• imageAsset and bitmap - Since each part of the scroll control has its own profile, each of those profiles can choose to use any of the three forms of rendering available. You can feel free to mix and match as you need to create the perfect scrolling experience.

Methods

• scrollToTop, scrollToBottom, scrollToLeft, scrollToRight, and scrollToPosition - Allows you to change the position that the content area is scrolled to.
• getScrollPositionX and getScrollPositionY - Returns the indicated scroll position.
• computeSizes - This is a function used internally by the control to position everything correctly. It is exposed here incase you need to refresh the contents of the control. It is unlikely you'll need this.

GuiGridCtrl

This control renders just like a normal GuiControl, but its children are automatically positioned and sized into a grid. There are a handful of options that allow you to customize how the grid looks and what order the objects appear in. The control can also automatically expand to fit the number of children. For this reason, it often appears inside a GuiScrollCtrl.

Settings

• CellSizeX and CellSizeY - The extent of each child control. Children will be resized to match this given extent. How these values are interpreted depends on CellModeX/Y.
• CellSpacingX and CellSpacingY - The distance between each cell horizontally and vertically. How these values are interpreted depends on CellModeX/Y. Keep in mind that child controls might have margins which may add additional space between them. The space will also not be applied to the edge of the GuiGridCtrl since you can use the control's padding for this.
• CellModeX and CellModeY - The way that cells are sized and spaced. Possible values are absolute, variable, and percent. Absolute values interpret the cells' size and spacing as pixel amounts that will not change. Variable cell sizes will grow or shrink to fill available space but the spacing will be treated like absolute sizes. This is useful when there is a max column or row count given so that the cells can expand to fill the remaining space. Percent allows you to set the cell size and spacing as percentage values. This assumes the whole row or column represents 100%.
• MaxColCount and MaxRowCount - Limits the number of columns and rows. A value of zero will allow the engine to automatically fit as many columns and rows as possible. Only one of these values will be used depending on the Order Mode.
• IsExtentDynamic - If true, the control will resize itself in one direction, based on the child controls. Defaults to true.
• Order Mode - This is the interesting setting. Order Mode allows you to change the way that the children are displayed. The default is Left to Right, Top to Bottom or LRTB for short. There are actually a full 8 different ways to list the child controls! They are: LRTB, RLTB, TBLR, TBRL, LRBT, RLBT, BTLR, BTRL. If the control can resize itself it will do so in the direction of the last letter.

Profile Fields Used The GuiGridCtrl renders itself as a normal GuiControl. So it can use margins, borders, padding, and text using all the normal settings.

Methods All the usual suspects are here, but it's important to note what's not here. You can't change the Order Mode or IsExtentDynamic once the GuiGridCtrl is created. Everything else is fair game.

• setCellSize - Takes the size of cells as width and height.
• getCellSize - Returns the size of cells as width and height.
• setCellSpacing - Sets the spacing between cells.
• getCellSpacing - Gets the spacing between cells.
• setCellModeX - Sets the horizontal cell mode. Possible values are Absolute, Variable, or Percent.
• setCellModeY - Sets the vertical cell mode. Possible values are Absolute, Variable, or Percent.
• getCellModeX - Returns the horizontal cell mode.
• getCellModeY - Returns the vertical cell mode.
• setMaxColCount - Sets the max number of columns. Ignored for order modes that end in L or R.
• setMaxRowCount - Sets the max number of rows. Ignored for order modes that end in T or B.
• getMaxColCount - Returns the max number of columns.
• getMaxRowCount - Returns the max number of rows.
• getIsExtentDynamic - Returns true if the control will grow and shrink to fit its contents. Growth will happen in the direction of the last letter of the order mode.
• getOrderMode - Returns the current order mode.

GuiChainCtrl

Like the grid, this control focuses on positioning its children, but only in a single row. More importantly, this control will not change the extent of the children - only the position in one direction. This allows the children to be different sizes. It places its children in a single line vertically or horizontally.

Settings

• ChildSpacing - The distance between each child control. Keep in mind that additional space may come from the child's margin.
• IsVertical - It true, the chain will be vertical. Otherwise, it will be horizontal.

Profile Fields Used The GuiChainCtrl renders itself as a normal GuiControl. So it can use margins, borders, padding, and text using all the normal settings.

Methods You should note that you cannot change the direction once the control is created.

• setChildSpacing(%space) - Sets the spacing used between children.
• getChildSpacing() - Returns the spacing used between children.
• getIsVertical() - Returns true if the chain is vertical, false otherwise.

GuiExpandCtrl

This is just like a standard GuiControl when in a "collapsed" state, but when it expands it grows to accommodate its children. Most controls clip off their children when they are outside their content area with some exceptions such as the GuiScrollCtrl. This control can actually switch between the two modes. The extent of the collapsed state is based on the initial extent given to the control. The extent of the expanded state is based on the size of the control's children. Note that only the extent of the control changes so children with a negative position will not be accommodated (i.e. the control only grows down and to the right).

Settings

• easeExpand - This is the easing function that is used when the control expands or collapses. It defaults to Linear.
• easeTimeExpand - This is the time in milliseconds that it takes to expand or collapse the control. It defaults to 500 (half a second).

Profile Fields Used This renders itself as a normal GuiControl. So it can use margins, borders, padding, and text using all the normal settings.

Methods

• getExpanded() - Returns true if the control is expanded and false if it is collapsed.
• setExpanded(%expanded) - Enter true to expand the control or false to collapse it.
• setExpandEase(%ease, %time) - Sets the ease function that is used to expand or collapse the control. You can optionally set the time in milliseconds as well.
• getExpandEaseFunction() - Returns the easing function used for the expand and collapse transitions.
• getExpandEaseTime() - Returns the ease time used for the expand and collapse transitions in milliseconds.

GuiPanelCtrl

This is a special expand control that creates a child button the size of the collapsible region. The expand control is then built to expand and collapse when the button is clicked. Child controls should be placed below the button. The Profile assigned to a panel will be directly handed to the child button control so the control itself will ignore margins, borders and padding. Otherwise, the GuiPanelCtrl has the same methods and settings as the GuiExpandCtrl.

GuiSpriteCtrl

This magic little control can directly load an ImageAsset or AnimationAsset without having to create a whole new profile for each one. As such it excels as an icon or still image in the GUI. Naturally, the ability to play an animation is also useful. It almost completely ignores the usual profile fields, except for the normal fill color, which it uses to change the color of the displayed image or animation. It will render child controls, but again, ignores margin, borders, and padding. The image will be stretched to fill the extent of the control.

Settings

• Image - An ImageAssetID that will be used by the control.
• Frame - The zero-based frame that will be used with the ImageAsset.
• NameFrame - The name of the frame to use with the ImageAsset.
• Animation - The AnimationAssetID that will be used by the control.

Callbacks

• onAnimationEnd - This is called when a non-looping animation plays. The animation will pause on the last frame and this callback will fire. The AnimationAssetID that just finished playing will be passed to the callback incase you want to play it again.

Profile Fields Used

• fillColor - This will be blended with the image or animation. A solid white fillColor will leave the image unchanged.

Methods

• isStaticFrameProvider() - Returns true if using a static image and false if using an animation.
• isUsingNamedImageFrame() - Returns true when using a named frame, false when using a numerical index.
• setImage(imageAssetID, frame) - Sets the control image and optionally the frame.
• getImage() - Gets current ImageAssetID.
• setImageFrame(frame) - Sets the frame to use for the control.
• getImageFrame() - Returns the numerical image frame.
• setNamedImageFrame(frame) - Sets the image frame based on the frame name.
• getNamedImageFrame() - Returns the current frame's name.
• setAnimation(animationAssetID) - Sets the animation to the given assetID.
• getAnimation() - Returns the assetID of the current animation.
• pauseAnimation(isPaused) - Pass true to pass the animation and false to unpause it.
• stopAnimation() - Stops the currently playing animation.
• setAnimationFrame(frame) - Sets the current animation frame. This is not the same as the image frame. Frame count starts at zero.
• getAnimationFrame() - Returns the current animation frame. This is not the same as the image frame. Frame count starts at zero.
• getAnimationImageFrame() - Returns the image frame of the currently playing animation.
• getAnimationNamedImageFrame() - Returns the named image frame of the currently playing animation.
• getAnimationTime() - Returns the current animation time.
• getIsAnimationFinished() - Returns true if the current animation has finished.
• setAnimationTimeScale(timeScale) - Sets the time scale which changes the speed of the animation. A time scale of 1 is normal speed.
• getAnimationTimeScale() - Returns the current animation time scale.

GuiWindowCtrl

This control is a window. It has a title bar that allows the window to be moved and a series of buttons. Most features are optional and can be turned on and off. Child controls are rendered in the content of the window and there is no need to compensate the child's offset for the window's title bar.

Settings

• CanMove, CanClose, CanMinimize, and CanMaximize - When true, these allow a control to move (by dragging the title bar), close, minimize and maximize. When false, the respective buttons for these functions will be hidden.
• ResizeWidth and ResizeHeight - When true, these allow the window to be resized in the applicable direction. In order for these to work though, the window content must have pixels on the right and bottom that don't contain children - otherwise the children will interact with the mouse instead of a the window. This is easiest to achieve with a margin/border/padding on the right/bottom of the content area.
• ResizeRightWidth and ResizeBottomHeight - This is the gutter area that will be checked for resizing (if no children are found) along the right and bottom edges of the window. It defaults to 10.
• TitleHeight - This is the height of the title bar area. It default to 20.
• ContentProfile - This is the GuiContentProfile that will be applied to the content area of the window.
• CloseButtonProfile - This is the GuiContentProfile that will be applied to the close button of the window.
• MinButtonProfile - This is the GuiContentProfile that will be applied to the minimize button of the window.
• MaxButtonProfile - This is the GuiContentProfile that will be applied to the maximize button of the window.
• LeftRightCursor - This is the GuiCursor that will be used when resizing horizontally.
• UpDownCursor - This is the GuiCursor that will be used when resizing vertically.
• NWSECursor - This is the GuiCursor that will be used when resizing diagonally.

Callbacks

• onMove - This is called when the window completes a move (when the user releases the mouse).
• onMinimize - This is called when the minimize button is clicked on a normal or maximized window.
• onMaximize - This is called when the maximize button is clicked on a normal or miniminzed window.
• onRestore - This is called when a minimized or maximized window is returned to the normal state.
• onResize - This is called when resizing a window has been completed (when the user releases the mouse).

Profile Fields Used The GuiWindowCtrl renders it's title bar using it standard Profile. It supports all the normal items with a few notable differences. The NA options of border and text will be applied when the window is minimized. The HL options will apply when the title bar is hovered and the SL options will apply when a child control of the window is the current target of key events. The content of the window has it's own profile (the ContentProfile) that controls the window content. The HL and NA states of the content profile will be ignored.

Methods Although this may be expanded on in the future, there are currently only setter function for the profiles and cursors of the window.

GuiListBoxCtrl

This control allows you to create a list with each item in its own box. The main profile applies to each individual list item instead of to the whole list. Each item can also have a color assigned to it which will add a small color dot to the left of the text. The meaning of this color is up to you. The extent of this control is dynamic. It will extend vertically to fit its items. It's horizontal extent depends on FitParentWidth.

Settings

• AllowMultipleSelections - If true, the user can hold shift or ctrl to select multiple items. Methods that return the selected item will return the first item if multiple items are selected. Defaults to true.
• FitParentWidth - This value changes how the ListBox sets its horizontal extent. If this is true, then the ListBox will match the content area width of its parent. You will likely want the place the control at horizontal position zero if you use this. If false, the horizontal extent will expand or shrink to fit the widest item in the list.

Callbacks All these callbacks pass the item index and item text as parameters.

• onSelect - Called when an item is selected.
• onUnselect - Called when an item is unselected. Not called when all selected items are cleared.
• onClick - Called when an item is clicked after calling onSelect or onUnselect.
• onDoubleClick - Called instead of onClick when an item is double clicked after calling onSelect or onUnselect.
• onTouchDragged - Called when an item registers a drag event.

Profile Fields Used The standard profile is used to render each item. The highlight state (HL) is used when an item is hovered. The select state (SL) is used when an item is selected. Finally, the disabled state (NA) is used when the control is not active.

Methods

• setMultiSelection(isMultiSelect) - Sets if multi-selction should be on or off.
• getMultiSelection() - Returns true if multi-selection is turn on.
• clearItems() - Removes all items from the ListBox.
• clearSelection() - Unselects all items. Does not call the onUnselected callback.
• setSelected(index, [isSelected]) - Selects an item using the index. Optionally allows a bool to select or unselect the item.
• getitemCount() - Returns the number of items.
• getSelCount() - Returns the number of selected items.
• getSelectedItem() - Returns the index of the first selected item or -1 if no items are selected.
• getSelectedItems() - Returns a space-delimited list all selected item indexes or -1 if no items are selected.
• findItemText(itemText, caseSensitive) - Returns a list of item indexes that matches a search string. Optionally allows a case-sensitive search or defaults to a case-insensitive search.
• setCurSel(index) - Selects the item at the given index.
• setCurSelRange(start, [stop]) - Selects a range of items starting with the start index and going to the end or a stop index.
• addItem(text, [color]) - Adds a new item to the end of the list with the give text. Optionally allows a color dot to be assigned.
• setItemColor(index, color) - Sets the color of the color dot used by an item. Colors, like other Gui colors, should be 3 or 4 space-delimited values of 0 to 255 (r/g/b/a).
• clearItemColor(index) - Removes the color dot from an item.
• clearAllColor() - Removes all color dots from all items.
• insertItem(index, text) - Adds an item at a given index.
• deleteItem(index) - Removes an item at a given index.
• getItemText(index) - Returns the item text at a given index.
• setItemText(index) - Sets the text at a given index.

GuiDragAndDropCtrl

This handy utility control can be moved by the cursor for drag-and-drop behavior. It renders just like a standard GuiControl in the normal state. Much of its power comes from callbacks that allow script to implement custom behavior.

Please note: In versions of Torque2D before 4.0, this control was named GuiDragAndDropControl. The name was shorten to be consistent with other controls.

Settings

• DeleteOnMouseUp - If true, this control will self-destruct when the cursor button is released. This is useful when creating these controls programmatically.

Callbacks Not all of these callbacks fire on the GuiDragAndDropCtrl itself. In some cases, the callback is fired on the target that the control is dropped on.

• onControlDragEnter() - Called on a potential target control when the drag-and-drop control enters its space.
• onControlDragExit() - Called on a potential target control when the drag-and-drop controls leaves its space.
• onControlDragged() - Called on a potential target control when the drag-and-drop control passes through its space.
• onControlDropped() - Called on a potential target control when a touch up event fire which releases the drag-and-drop control.

Profile Fields Used Renders like a standard GuiControl. Uses only the normal state (no HL, SL, or NA). In many cases, you will probably use this as a wrapper and use an invisible profile but you could also render it like any other control if you so desire.

Methods

• startDragging([x], [y]) - Starts dragging the control - essentially simulating a touch down event on the control. Optionally you can include an x and y offset to offset the cursor's position. These will default to (0, 0).

GuiProgressCtrl

This controls displays a progress bar. It can smoothly animate from one state to another and it makes creative us of the profile states to display the different parts of the bar.

Settings

• AnimationTime - Each time you set the progress of the progress bar, it will smoothly animate to that position. The AnimationTime is the amount of time in milliseconds that it takes to perform this smooth animation. It defaults to 250 or a quarter of a second. You can set this to zero if you want the progress bar to instantly respond.

Profile Fields Used The control renders the background of the progress bar using the normal state. This includes boarder, padding, and margins. The actual progress bar is rendered using the highlight state (HL) if the progress is incomplete. A complete progress bar is rendered using the selected state (SL). These two states are also used to render any text set to the progress bar. It's a bit unusual, but the FontColorHL and FontColorSL values are used but the normal FontColor is never used. The disabled state is also not used. Like other controls, you can use default rendering, bitmaps or assets to render the contents of the control.

Methods

• setProgress(progress, time) - Sets the current progress of the bar as a decimal value between 0 and 1. Optionally allows you to set the animation time.
• getProgress() - Gets the current progress of the bar as a value between 0 and 1. This reflects the actual set progress regardless of the animation.
• getDisplayProgress() - Gets the currently displayed progress. This may be different from the actual progress if the bar is in the middle of an animation.
• resetProgress() - Returns the progress to zero.
• setAnimationTime(time) - Sets the animation time in milliseconds.
• getAnimationTime() - Gets the animation time in milliseconds.