This is a list of the GUI control elements that come with the Torque Game Engine. There are a lot of GUI elements, and not all are very clear as to their purpose. Included are descriptions of what they are typically used for, any relevant references (usually to appropriate TGE Documentation pages), and, when possible, links to examples (such as forum threads or resources) that demonstrate their usage. Obviously this is a work in progress, so please feel free to contribute.

In the future, perhaps we can also include some user-contributed GUI elements as well (such as from resources). Enjoy.

CreatorTree

Description: A subclass of GuiArrayCtrl. A specialized form of an array for creating tree structures?
Reference: [Documentation]
Usage Example: None

DbgFileView

Description: None
Reference: None
Usage Example: None

DebugView

Description: Helper class to render a HUD debug display. A subclass of GuiTextCtrl.
Reference: [Documentation]
Usage Example: None

EditManager

Description: A subclass of GuiControl.
Reference: [Documentation]
Usage Example: None

EditTSCtrl

Description: A Gui for rendering 3D scenes. It is the TS Gui control often used for an editor. Subclass of GuiTSCtrl; Parent of Terrain Editor and World Editor
Reference: [Documentation]
Usage Example: Commander Map Resource - not the best example but helps show its use.

GameTSCtrl

Description: A Gui for rendering 3D scenes. It is the TS Gui control often used for the main screen during gameplay. A subclass of GuiTSCtrl.
Reference: Documentation
Usage Example:

GuiArrayCtrl

Description:
Reference:
Usage Example:
See Also: Resource GuiArray2Ctrl

GuiAviBitmapCtrl

Description:
Reference:
Usage Example:

GuiBackgroundCtrl

Description:
Reference:
Usage Example:

GuiBitmapBorderCtrl

Description:
Reference:
Usage Example:

GuiBitmapButtonCtrl

Description: The GuiBitmapButtonCtrl is used whenever you want to use a button that was created in a graphics program like Photoshop. You need to create four copies of the image located in the same directory and named button_h, button_d, button_i, and button_n. These images represent the normal (_n), hilight (_h), depressed (_d), and inactive (_i) states. You tell the control which bitmap files to use with the bitmap field, setting it to the directory path of the bitmap files. Note that in the "bitmap" field you should not use any file suffixes; thus, if your button image files are named myButton_h.png, myButton_d.png, myButton_i.png, and myButton_n.png, then the "bitmap" field of the GuiBitmapButtonCtrl should just be set to "\directoryPath\myButton". You can save your buttons as either *.png or *.jpg files depending on your need for transparency.
Reference:
Usage Example:

GuiBitmapButtonTextCtrl

Description:
Reference:
Usage Example:

GuiBitmapCtrl

Description: Puts an image on the canvas just for display
Reference:
Usage Example: ???

GuiBorderButtonCtrl

Description:
Reference:
Usage Example:

GuiBubbleTextCtrl

Description:
Reference:
Usage Example:

GuiButtonBaseCtrl

Description:
Reference:
Usage Example:

GuiButtonCtrl

Description: A button with a grey background and the text you decide to enter into it. This can have many different purposes such as loading a/your game.
Reference:
Usage Example:

GuiCanvas

Description: The Canvas object, a singleton instance of the GuiCanvas class, is the root of the currently active GUI hierarchy. It is responsible for processing and dispatching mouse and keyboard events, managing update regions and cursor handling, and calling the GuiControl render methods when it is time to draw the next frame. The GuiCanvas keeps track of a stack of content controls - separate hierarchies of GuiControls that render from bottom to top. The main content control is a screen in the shell, and can be covered by any number of floating windows or dialogs. The root of each content control hierarchy is sized to cover the entire canvas, so generally dialogs are composed of a content control containing a dialog control.
Reference:
Usage Example:

GuiCheckBoxCtrl

Description: Creates a checkbox on the canvas. It can take onClick() callbacks.
Reference:
Usage Example:

GuiChunkedBitmapCtrl

Description:
Reference:
Usage Example:

GuiClockHud

Description:
Reference:
Usage Example:

GuiColorPickerCtrl

Description: This control draws a box containing a color specified by mPickColor, in a way according to one of the PickMode enum's, stored as mDisplayMode.

The color the box represents is stored as mBaseColor (for pPallet, pBlendColorRange), whilst the color chosen by the box is stored as mPickColor.

Whenever the control is clicked, it will do one of many things:
1) If its in pPallet mode, execute the regular "command"
2) If its in pBlendColorRange mode, update the selector position. The position will be re-read upon the next render. In addition, a cross will be drawn where the color has been selected from. As with (1), "command" will be executed.
3) If its in pHorizColorRange or pVertColorRange mode, it will function in a similar manner to (2), but the selector will resemble a horizontal or vertical bar.
4) If its in pHorizAlphaRange or pVertAlphaRange mode, it will also function the same way as (3)
5) If its in pDropperBackground mode, nothing will happen.


Colors are drawn in different ways according to mDisplayMode:
1) With pPallet, a box with a blank color, mBaseColor is drawn.
2) With pHorizColorRange, a horizontal box with colors blending in the range mColorRange.
3) With pVertColorRange, a vertical box with colors blending in the range mColorRange.
4) With pBlendColorRange, a box, the bottom colors being black, but the top left being white, and the top right being mBaseColor.
5) With pHorizAlphaRange, a horizontal box with black blending with an alpha from 0 to 255.
6) With pVertAlphaRange, a vertical box with black blending with an apha from 0 to 255.
7) With pDropperBackground, nothing is drawn
Reference:
Usage Example:

GuiConsole

Description: Provides the on-screen, in-game console. Calls getLog() to get the on-screen console entries, then renders them as needed.

Reference: Documentation
Usage Example:

GuiConsoleEditCtrl

Description:
Reference:
Usage Example:

{{{1}}}

GuiControl

Description: The GuiControl class is the root class for all the GUI controls in the system. GuiControl is derived from SimGroup and can contain any number of child GUI controls. Each GuiControl maintains a bounding rectangle in the coordinate system of its parent control. GuiControl has virtual methods for processing input events (onMouseDown, onMouseUp, onMouseEnter, onMouseLeave, onMouseMove, onMouseDragged, onRightMouseDown, onKeyDown, onKeyUp,onKeyRepeat), methods called by the Canvas for rendering (onPreRender, onRender), methods to control the lock focus of the mouse (mouseLock, mouseUnlock), coordinate conversion methods (localToGlobalCoord, globalToLocalCoord), and automatic sizing behavior when its parent control is resized (for example, when the screen resolution changes). When a control is made visible, it (if not already loaded) loads the data associated with its GuiControlProfile.
Reference:
Usage Example:

GuiControlArrayControl

Description:
Reference:
Usage Example:

GuiControlListPopUp

Description:
Reference:
Usage Example:

GuiCrossHairHud

Description:
Reference:
Usage Example:

GuiDirectoryFileListCtrl

Description:
Reference:
Usage Example:

GuiDirectoryTreeCtrl

Description:
Reference:
Usage Example:

GuiEditCtrl

Description:
Reference:
Usage Example:

GuiEditorRuler

Description:
Reference:
Usage Example:

GuiEffectCanvas

Description: Includes built in code to fade a scene for simple things like splash screens. Parameters allows you to change the timing of fade in and fade out.
Reference:
Usage Example:

GuiFadeinBitmapCtrl

Description:
Reference:
Usage Example:

GuiFilterCtrl

Description:
Reference:
Usage Example:

{{{1}}}

GuiHealthBarHud

Description:
Reference:
Usage Example:

GuiInputCtrl

Description:
Reference:
Usage Example:

GuiInspector

Description:
Reference:
Usage Example:

GuiInspectorDatablockField

Description:
Reference:
Usage Example:

GuiInspectorDynamicField

Description:
Reference:
Usage Example:

GuiInspectorField

Description:
Reference:
Usage Example:

GuiInspectorGroup

Description:
Reference:
Usage Example:

GuiInspectorTypeCheckBox

Description:
Reference:
Usage Example:

GuiInspectorTypeColor

Description:
Reference:
Usage Example:

GuiInspectorTypeColorF

Description:
Reference:
Usage Example:

GuiInspectorTypeColorI

Description:
Reference:
Usage Example:

GuiInspectorTypeEnum

Description:
Reference:
Usage Example:

GuiInspectorTypeFileName

Description:
Reference:
Usage Example:

GuiInspectorTypeGuiProfile

Description:
Reference:
Usage Example:

GuiMenuBar

Description:
Reference:
Usage Example:

GuiMessageVectorCtrl

Description: This renders messages from a MessageVector. The MessageVector holds all the messages, but the Gui controls (GuiMessageVectorCtrl) to display them can be created and destroyed as needed. Basically, you create a GuiMessageVectorCtrl and a MessageVector, and then attach the MessageVector to the GuiMessageVectorCtrl. Then you add text to the MessageVector as needed, and it is displayed in the GuiMessageVectorCtrl.
Reference: see GuiMessageVectorCtrl.h/.cc and MessageVector.h/.cc in the TGE engine.
Usage Example: In starter.fps, the ChatHud is a GuiMessageVectorCtrl. It has the HudMessageVector attached to it. The GuiMessageVectorCtrl is created in chatHud.gui, the MessageVector is created in chatHud.cs, and they are attached in playGui.cs.

GuiMLTextCtrl

Description: This is a text control that uses the Gui Markup Language ('ML') tags to dynamically change the text, for example with colors or styles or links, without having to use separate text controls with separate text profiles. The following markup tags are recognized by the engine:

<font:fontName:fontSize> - sets the font and fontsize as indicated. Example: <font:Arial Bold:20>
<tag:4> - allows a scroll ctrl to scroll to the position of this tag in the mlTextCtrl
<color:rrggbb> - sets text color in hex format. Example: <color:ff0000> will display red text
<bitmap:filePath> - displays a bitmap image indicated by the file path. Example: <bitmap:demo/client/ui/seperator>
<spush> - saves the current text formatting so that temporary changes to formatting can be made. Used with spop.
<spop> - restores the previously saved text formatting. Used with spush. See the file "3. Gui Editor.hlf" included with the TGE demo for an example of usage.
<sbreak> - section break?
<strikethrough> - renders text as strikethrough. ([resource required])
<b> - renders text as bold. ([resource required])
<just:left> - left justify
<just:right> - right justify
<just:center> - center justify
<a:ExternalURL>LinkTitle</a> - inserts a hyperlink into the text which will open the user's browser.
The external URL does not need the "http://" format. Example: <a:www.garagegames.com>Garage Games Website</a> When the user clicks on the hyperlink text, GuiMLTextCtrl::onUrl(%this, %text) function is called. Your implementation can do whatever you want, including but not limited to opening the user's browser and navigating to the url.
<lmargin: ##> - sets the left margin
<lmargin%: ##> - sets the left margin (not sure what the % does)
<rmargin: ##> - sets the right margin
<rmargin%: ##> - sets the right margin (not sure what the % does)
<clip:> - not sure what this does
<div:> - not sure what this does
<tab:##(,##,etc)> - sets the tab stops (multiple tabs are separated by commas)

Reference: These were extracted from guiMLTextCtrl.cc. A couple of threads have mentioned these as well.
Usage Example: See the files that end with .hlf that come with the TGE fps demo for examples.

GuiMLTextEditCtrl

Description:
Reference:
Usage Example:

GuiMouseEventCtrl

Description:
Reference:
Usage Example:

GuiNoMouseCtrl

Description:
Reference:
Usage Example:

GuiPaneControl

Description:
Reference:
Usage Example:

GuiPlayerView

Description:
Reference:
Usage Example:

GuiPopUpMenuCtrl

Description:
Reference:
Usage Example:

GuiProgressCtrl

Description:
Reference:
Usage Example:

GuiRadioCtrl

Description:
• The radio button control is a lot like the check box, except it sends messages to its siblings so that only one radio button per group is checked.
• Specify a group by entering a number in the groupNum field.
• When the user clicks on a radio button, all of the other radio buttons with the same groupNum will automatically "uncheck" themselves.

Reference: None
Usage Example: If you have TGB, this is a great example.

GuiScrollCtrl

Description:
Reference:
Usage Example:

GuiShapeNameHud

Description:
• This control displays the name and damage value of all named ShapeBase objects on the client. The name and damage of objects within the control's display area are overlayed above the object.
• This GUI control must be a child of a TSControl, and a server connection and control object must be present.
• This is a stand-alone control and relies only on the standard base GuiControl.

Reference: engine/game/fps/guiShapeNameHud.cc
Usage Example: starter.racing/client/scripts/playGui.cs

GuiSliderCtrl

Description:
Reference:
Usage Example:

GuiSpeedometerHud

Description: A Speedometer control. This gui displays the speed of the current Vehicle based control object. This control only works if a server connection exists and it's control object is a vehicle. If either of these requirements is false, the control is not rendered.
Reference:
Usage Example: starter.racing/client/scripts/playGui.cs

GuiStackControl

Description:
Reference:
Usage Example:

GuiTabBookCtrl

Description:
Reference:
Usage Example:

GuiTabPageCtrl

Description:
Reference:
Usage Example:

GuiTerrPreviewCtrl

Description:
Reference:
Usage Example:

GuiTextCtrl

Description:
Reference:
Usage Example:

GuiTextEditCtrl

Description: A component that places a text box on the gui screen. Fonts and sizes are changed using profiles. It acts like a text box where the user can type something.
Reference:
Usage Example:

GuiTextEditSliderCtrl

Description:
Reference:
Usage Example:

GuiTextListCtrl

Description:
Reference:
Usage Example:

GuiTheoraCtrl

Description:Adds a theora video screen as a splash screen.
Reference:
Usage Example:


<b>startupGui.gui</b><br>
new GuiTheoraCtrl(StartupGui) {
   canSaveDynamicFields = "0"; 
   Profile = "GuiDefaultProfile";
   HorizSizing = "right";
   VertSizing = "bottom";
   position = "0 0";<br>
   Extent = "640 480";
   MinExtent = "8 2";
   canSave = "1";
   Visible = "1";
   hovertime = "1000";
   theoraFile = "./video/myVideo.ogg";
   done = "0";
   stopOnSleep = "1";
   backgroundColor = "0 0 0 255";

GuiTickCtrl

Description:
Reference:
Usage Example:

GuiTreeViewCtrl

Description: A gui control that acts like the Windows treeview. It organizes information into headers called parents and items called children. Click on plus to expand the branch of the tree. All parents and children sit under a root and additions/removals are reference by level instead of object.
Reference:
Usage Example:

GuiTSCtrl

Description: The main Gui control for rendering 3D scenes. The most 'senior' TS (Three-Space) control. Parent of GameTSCtrl, GuiPlayerView, and EditTSCtrl (which is the parent of Terrain Editor and World Editor).
Reference: [Documentation]
Usage Example: TicTacToe Resource

GuiVectorFieldCtrl

Description:
Reference:
Usage Example:

GuiWindowCtrl

Description:
Reference:
Usage Example:

MissionAreaEditor

Description: A subclass of GuiBitmapCtrl.
Reference: [Documentation]
Usage Example:

ShowTSCtrl

Description:
Reference:
Usage Example:

TerrainEditor

Description:
Reference:
Usage Example:

WorldEditor

Description:
Reference:
Usage Example: