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 but has seen a lot of changes over the past few years. Even if you plan to build your user interfaces directly out of sprites, 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 documentation applies to version 4.0 (including early access versions of 4.0) and onward. Much of this information will not apply to previous versions of the engine.
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'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.
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.
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.
- Fill: This is new experimental option that attempts to have the control fill the entire content area of its parent. This will likely become a heavily used option in the future but may be a little unstable for now.
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.
As the name suggests, true will cause the control to be rendered. False will cause the control and it's children to not render.
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.
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 plain GuiControl can render text as well, both single line and wrapped. 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.
These two flags impact the way text is rendered and are most useful when you want to display text in a plain GuiControl. When TextWrap is set to true, the text in a control (not every control) will wrap to the another line when it exceeds the horizontal space for text. TextExtend causes a GuiControl to increase its extent dynamically to fit its text. The GuiControl will shrink too, so use MinExtent to prevent this if you want. This is most useful inside of a GuiChainCtrl which repositions children based on their extent.
This powerful field can prevent a control and all of its children from receiving any input. When input occurs, say for example a mouse click, the engine first checks to see if any control is in focus (referred to as the first responder). If no control is in focus, the engine then looks down through the tree of GuiControls until it reaches a control with no children - or at least no children with the clicked point inside of them. The engine then passes the event to this inner-most control. The control can then consume the event or let the event "bubble up" to its parent. If UseInput is set to false, it removes the control and it's children from this process. Normally you will not need to change this.
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.
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. Every control must have a profile. If no profile is provided the engine will search for a named profile of the form [GuiControlName - "Ctrl"]Profile. For example, for the GuiTextEditCtrl it will look for GuiTextEditProfile as a default profile if one is not provided. If it can't find a profile it will fall back to a named profile of GuiDefaultProfile. It is wise to have default profiles defined.
-
tab - True if the tab key can be used to access the control.
-
canKeyFocus - True if the control can be given keyboard focus. Note that some controls, like the Text Edit control, will be completely useless without this set to 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 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.
-
fillColorTextSL - Used as the background color of selected text.
-
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.
-
fontColorTextSL - The color of the text when it is selected. This color should contrast with fillColorTextSL.
-
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.
-
cursorColor - The color of the blinking text cursor in text edit controls. This is also used to highlight certain controls that have gained focus through tabbing. For example, checkboxes and dropdown boxes are outlined in this color when tabbed to.
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 is 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 an 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.
There are a handful of times when you can override the profile directly in the control. These are generally connected to the text. First, you can set the align and vAlign properties directly on the control to override text positioning. Next, you can adjust the font size with the FontSizeAdjust value. This setting is multipled by the fontSize on the profile to get the actual font size. So if the profile has a font size of 12, you could set the FontSizeAdjust to 0.75 and the control would display with a font size of 9 (because 12 * 0.75 = 9). Last, you can directly override the font color of the profile. Simply add the FontColor to the control and then turn on the OverrideFontColor flag. You can revert to using the profile's color by turning the flag back off.
- Align and vAlign
- FontSizeAdjust (multipled by FontSize)
- FontColor with OverrideFontColor set to true
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 border.
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 within 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. Child controls assume the size of the content will not change between states.
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.
All controls inherit from the GuiControl and it is extremely useful both as a container and for displaying 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.
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.
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 it is already covered in the Getting Started Guide. To summarize, the SceneWindow is a GuiControl that renders a Scene to the screen.
Settings
- lockMouse - When true, mouse events will always go to the scene window.
- useWindowInputEvents - If true, the scene window will fire off events like onTouchDown.
- useObjectInputEvents - If true, individual objects in the scene such as sprites will be able to receive events like onTouchDown.
- useBackgroundColor - If true, a solid color will be drawn behind the scene window as a background.
- backgroundColor - A red/green/blue/alpha color to be used as a background. Unlike most colors in the gui system, this uses floating point color values between 0 and 1 much like sprites. Most colors in the gui system use integer colors between 0 and 255.
- constantThumbHeight - If scroll bars are turned on, this will cause the thumbs to be a single size and not grow and shrink based on viewable area. Defaults to false.
- scrollBarThickness - If scroll bars are turned on, this will determine the thickness of the bars in pixels. Defaults to 16 pixels.
- showArrowButtons - If scroll bars are turned on, this will determine if arrow buttons appear at the ends of the track. Defaults to true.
Callbakcs
- onExtentChanged(%newArea) - Called when the size of the window in pixels has changed. Normally you should respond to this by adjusting your camera. See note below.
- TouchEvents - All touch events are emitted by the scene window.
A Note On Camera Ratios 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.
Profile Fields Used The scene window uses its profile's font and fontColor to render metrics. The background of the metrics banner uses the fillColor.
Methods Brace yourself. There's a lot!
- getWindowExtents() - Returns the window position and extent as four values.
- getScene() - Returns the scene associated with this window.
- setScene(%scene) - Sets the scene associated with this window.
- resetScene() - Detaches the current scene from the scene window.
- setCameraPosition(%position) - Sets the center of the window to focus on a given world position.
- getCameraPosition() - Returns the world x and y position that is at the center of the camera.
- setCameraSize(%width, %height) - Sets the width and height of the camera in world units. This is the size before zooming is applied.
- getcameraSize() - Returns the width and height of the camera. Zooming is not applied.
- setCameraArea(%area) - Sets the area of the camera using four values: the bottom left x and y and the width and height in world units. This is before applying zooming.
- getCameraArea() - Returns four values: the bottom left x and y and the width and height in world units before zooming is applied.
- setCameraZoom(%zoom) - The zoom should be a value greater than zero. Values between 0 and 1 will zoom out (objects on the scene will appear further away). Values greater than 1 will zoom in (objects will appear closer).
- getCameraZoom() - Returns the current zoom.
- setCameraAngle(%angle) - A value in degrees to rotate the camera. Please note that a rotated camera will not happily coexist with scrollbars since scrollbars ignore rotation.
- getCameraAngle() - Returns the degree of rotation of the camera.
- getCameraWorldScale() - Returns the world scale of the camera as two values: the width scale and height scale.
- getCameraRenderPosition() - This will return the actual rendered position of the camera which will not always be exactly the same as the normal position.
- getCameraRenderScale() - Similar to the world scale, this will return a more accurate value.
- setTargetCameraPosition(%x, %y) - Sets the position that the camera will move when animating.
- getTargetCamreaPosition() - Returns the current target camera position.
- setTargetCameraSize(%width, %height) - Sets the size (before zoom) that the camera will animate to.
- getTargetCameraSize() - Returns the target camera size.
- setTargetCameraArea(%area) - Sets the target camera area that the camera will animate to.
- getTargetCameraArea() - Gets the current target camera area.
- setTargetCameraZoom(%zoom) - Sets the target camera zoom that the camera will animate to.
- getTargetCameraZoom() - Returns the target camera zoom.
- setTargetCameraAngle(%angle) - Sets the target angle in degrees that the camera will animate to.
- getTargetCameraAngle() - Returns the target camera angle in degrees.
- setCameraInterpolationTime(%time) - This sets the default time used to move the camera to its target settings. Time should be provided in floating point seconds. So a value of 1.5 is a second and a half.
- setCameraInterpolationMode(%mode) - This sets the mode used to animate the camera to its target settings. Possible values are Linear and Sigmoid. Linear provides constant change over time while sigmoid provides a smoother start and stop.
- startCameraMove([%time]) - The camera will start moving toward its target settings. You can optionally provide a time in seconds if you don't want to use the default.
- stopCameraMove() - The camera will stop moving toward its target settings.
- completeCameraMove() - The camera will jump to its target settings.
- undoCameraMove([%time]) - The camera will return to the settings that it had before it most recently moved.
- getIsCameraMoving() - Returns true if the camera is currently moving.
- getIsCameraMounted() - Returns true if the camera is mounted.
- startCameraShake(%magnitude, %time) - Shakes the camera by a magnitude in world units for a time in seconds.
- stopCameraShake() - Ends a camera shake prematurely.
- **mount(%obj, [%offset], [%force], [%sendToMount], [%mountAngle]) - Mounts the camera to a scene object.
- dismount() - Dismounts the camera.
- setViewLimitOn(%left, %bottom, %right, %top) - Sets the min and max values that the camera can view. View limits are also required if you plan to turn on scrollbars.
- setViewLimitOff() - Turns off the view limit.
- clampCameraViewLimit() - Ensures the view is within the view limits. Nothing will happen if the camera is mounted or moving.
- setShowScrollBar(%setting) - If true and if view limits have been set, scroll bars will appear to scroll the available space. This does not work with mounting or camera rotation, but you can use camera animation and zooming.
- setMouseWheelScrolls(%setting) - If true, and scrollbars are on, the mouse wheel will cause the vertical scroll bar to move up and down. If false, the window will receive the mouse wheel event instead. Holding the shift key will reverse this behavior. Try to be consistent in your game.
- setRenderGroups(%groups) - Sets the groups you want to render.
- setRenderLayers(%layers) - Sets the layers you want to render.
- setREnderMasks(%layerMask, %groupMask) - Sets the layers and groups you want to render. You can learn more about this other tutorials on this site.
- getRenderLayerMask() - Returns the layer mask for rendering.
- getRenderGroupMask() - Returns the group mask for rendering.
- setBackgroundColor(%red, %green, %blue, %alpha) - Sets the background color as floating point values between 0 and 1.
- getBackgroundColor() - Returns the background color.
- setUseBackgroundColor(%setting) - If true, the background color will be drawn behind the scene.
- getUseBackgroundColor() - Returns if the background color is on.
- setUseWindowInputEvents(%setting) - If true, the window will received input events.
- getUseWindowInputEvents() - Returns if the window input events are on.
- setUseObjectInputEvents(%setting) - If true, the objects in the scene will received input events.
- getUseObjectInputEvents() - Returns if object input events are on.
- setObjectInputEventGroupFilter(%groupMask) - Sets a filter for which objects will receive input events by group.
- setObjectInputEventLayerFilter(%layerMask) - Sets a filter for which objects will receive input events by layer.
- setObjectInputEventFilter(%groupMask, %layerMask) - Sets a filter for which objects will receive input events by group and layer.
- setObjectInputEventInvisibleFilter(%setting) - Sets whether invisible objects should be filtered or not.
- addInputListener(%object) - Adds an object as an input listener.
- removeInputListener(%object) - Removes an object as an input listener.
- setLockMouse(%setting) - If true, the mouse events (or touch events) will only be sent to this scene window.
- getLockMouse() - Returns if mouse lock is on or not.
- setMousePosition(%x, %y) - Sets the mouse at the position given.
- getMousePosition() - Returns the position of the mouse.
- getWorldPoint(%windowPoint) - Converts a point in window coordinates into world coordinates.
- getWindowPoint(%worldPoint) - Converts a point in world coordinates into window coordinates.
- getCanvasPoint(%worldPoint) - Converts a world point into a canvas point.
- getIsWindowPoint(%worldPoint) - Returns true if the world point is inside the viewable camera.
- setAudioListener(%setting) - If true, this window will be used in processing audio distance. Only one scene window should have this set to true at a time or crashes may occur.
- setThumbProfile(%profile) - If you turn on scrolling, this sets the GuiControlProfile that will be used for the thumb.
- setTrackProfile(%profile) - If you turn on scrolling, this sets the GuiControlProfile that will be used for the track.
- setArrowProfile(%profile) - If you turn on scrolling, this sets the GuiControlProfile that will be used for the arrow buttons.
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. Buttons also support easing for the fill color during default rendering. Easing will likely expand to other controls in the future.
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.
- 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.
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.
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.
The text edit control in some ways is one of the most important controls available and packs a lot of punch in a small package. It has multiple input modes that can be used to ensure the data is correct. It has a wide array of commands and callbacks that can be used including validation.
Note: several features in the GuiTextEditCtrl have changed since versions before 4.0. Be sure to check this documentation for changes.
Settings
- escapeCommand - If set, this will be executed when the escape button is pressed.
- sinkAllKeyEvents - If true, key events not used by this box will not go to other controls (such as parent controls). This box will consume all events. Scary.
- password - If true, this will be a password field and will hide its true value from sight.
- returnCausesTab - If true, pressing return causes a tab event to go after.
- maxLength - The number of characters that can be typed in the text box. Must be a value between 1 and 1024.
- inputMode - The type of value that should be entered. Possible input modes are AllText, Number, Decimal, Alpha, and AlphaNumeric.
- textWrap - When text wrap is turned on, the text box because a multi-line text box. You should note that this has replaced the GuiMLTextEditCtrl from previous versions.
Callbacks
- onValidate - Called on Enter press or loss of focus. Should return true if the contents of the box are valid to continue execution.
- onTouchDown(%modifer, %point, %clickCount) - Called when the mouse or a touch down event fires.
- onTouchDragged(%modifer, %point, %clickCount) - Called when the mouse or a touch dragged event fires.
- onTouchUp(%modifer, %point, %clickCount) - Called when the mouse or a touch up event fires.
- onTab(%tabBack) - Called when a tab event is fired. The variable %tabBack will be true if the shift key is held.
- onReturn - Called when the return key is pressed.
- onLoseFirstResponder(%isValid) - Called when the box loses focus. Passes along the result from the validation callback.
- onDenied - Called when a key press is denied because of the input type. Consider playing a sound or giving the user some other feedback that the input was rejected.
Commands There are three code commands that are evaluated at different times. It is worth knowing when each fires.
- Command - This code is called on every key stroke.
- AltCommand - This is called when the control loses focus.
- ReturnCommand - This is called when enter/return is pressed after the validate callback.
- EscapeCommand - This is called when the escape key is pressed.
Profile Fields Used The text edit box renders using the usual settings in the normal state. The HL state is used when the box is hovered. The SL state is used when the text edit box has the focus and NA is used when it is inactive. The fillColorTextSL and fontColorTextSL are used together when text is selected. It also uses the cursor color setting for the cursor. And of course, the font, font colors, and alignment settings are used for the text.
Methods - In addition to the methods below, the methods getValue() and setValue() can be used to retrieve and set the text.
- getText() - Returns the text in the text edit box.
- getCursorPos() - Returns the current position of the text cursor in the control, where 0 is at the beginning of the line, 1 is after the first letter, and so on.
- setCursorPos(%pos) - Sets the cursor position.
- selectAllText() - Highlights all the text in the box.
- validate() - Calls the validation callback and returns true if the contents are deemed valid.
- setReturnCausesTab(%setting) - Sets the flag for the return key to also cause a tab to the next control.
- getReturnCausesTab() - Gets if the return causes a tab flag is set.
- setSinkAllKeyEvents(%setting) - Sets the flag for sinking or consuming all key events even if they were not used directly by the text box.
- getSinkAllKeyEvents() - Gets if the sink all key events flag is set.
- setIsPassword(%setting) - Sets if the text box is in password mode.
- getIsPassword() - Returns true if the text box is in password mode.
- setMaxLength(%max) - Sets the maximum number of characters that can be used in the text box. Must be a value between 1 and 1024.
- getMaxLength() - Returns the current max length of the text box.
- setInputMode(%mode) - Sets the current input mode. Doing so will cause characters that are not allowed in the mode to be removed from the box. Possible modes include AllText, Number, Decimal, Alpha, and AlphaNumeric.
- getInputMode() - Returns the current input mode used by the text edit box.
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. Tabs can be positioned 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 if possible.
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 bother 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.
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.
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.
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 be treated like minimum pixel values that can expand. This is useful when there is a max column or row count given so that the cells can expand to fill the remaining space. In the direction that the grid expands (determined by the last letter of the Order Mode), variable mode allows a child control to maintain it's own extent in that direction. Percent mode 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.
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.
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.
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.
This magic little control can directly load an ImageAsset, AnimationAsset, or Bitmap 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 also renders like a normal control behind the image using the normal state. You can use this to add margin, border, padding and a background color to the image. The image can be set to fill the entire content area or you can give it a size independent of the control. An image smaller than the content area will be positioned by the alignment and vertical alignment of the profile. You can further offset this position to get the image exactly where you want it. The image also has its own blend color. Finally you can control all of these over time with moveTo, growTo, and fadeTo methods. These allow you to animate the image and even take an optional easing function.
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.
- Bitmap - The path to the bitmap that will be used by the control. The control will use an asset over a bitmap if both are given.
- SingleFrameBitmap - If true, the bitmap will be used entirely for a single frame. If false, the bitmap will be divided into frames using the color of the top left corner of the image.
- TileImage - If true, the image will be tiled over the entire content area of the control. If false, only one copy of the image will be displayed.
- FullSize - If true, the image will fill the content area of the control.
- ClampImage - If true, the image will be forced to stay inside the content area of the control. If false, the image can overflow the content area, although it will still be cut off outside of the content area. This defaults to true.
- ConstrainProportions - If true, the aspect ratio of the image will be fixed. False will allow the image to be stretched.
- ImageSize - The size of the image to display. Note that FullSize will override this size.
- PositionOffset - The image will positioned by the alignment settings in the profile. This will allow you to offset it from its position. However, the image will not leave the bounds of the content area of the control unless clampImage is set to false.
- ImageColor - This color will be blended with the image. Solid white will cause the image to appear as normal. Color values should be between 0 and 255.
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 The control renders all profile fields in the normal state. The fill color will appear behind the image. Text is not rendered and font colors are not used. Additionally, alignment settings are used to position the image.
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.
- setPositionOffset(x/y) - Sets the position offset of the image.
- getPositionOffset() - Gets the position offset of the image.
- setImageSize(x/y) - Sets the size of the image. This will be ignored if FullSize is set to true.
- getImageSize() - Gets the size of the image.
- setImageColor(color) - Sets the blend color of the image. Requires four space-separated values of 0 to 255.
- getImageColor() - Returns the current blend color of the image.
- setSingleFrameBitmap(isSingle) - Sets if the bitmap has just one frame or should be parsed using the color of the top left corner pixel.
- getSingleFrameBitmap() - Returns if the bitmap is a single frame or not.
- setTileImage(isTiled) - Sets if the image should be tiled.
- getTileImage() - Gets if the image should be tiled.
- setFullSize(isFullSized) - Sets if the image should fill all available space.
- getFullSize() - Gets if the image should fill all available space.
- setClampImage(isClamped) - Sets if the image can overflow content area.
- getClampImage() - Gets if the image can overflow the content area.
- setConstrainProportions(isConstrained) - Sets the image should maintain a fixed aspect ratio.
- getConstrainProportions() - Gets the image should maintain a fixed aspect ratio.
- moveTo(x/y, time, [easingFunction]) - Changes the position offset over time with an optional easing function.
- growTo(x/y, time, [easingFunction]) - Changes the image size over time with an optional easing function.
- fadeTo(r/g/b/a, time, [easingFunction]) - Changes the image color over time with an optional easing function.
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
- onClose - This is called when the window close button is pressed. Closing behavior is not automatic so you must handle this event if the window has a close button.
- 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 minimized 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 its 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.
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, the item text, and the item ID 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.
- onDeleteKey - Called when the list box has key focus and the user presses the delete key.
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.
- setItemID(index, ID) - Sets the ID of the item at the given index.
- getItemID(index) - Gets the ID of the item at the given index.
- findItemID(ID) - Returns the item index of the first item that has the given ID.
- setItemActive(index) - Activates the item at the given index.
- setItemInactive(index) - Deactivates the item at the given index.
- getItemActive(index) - Returns if an item is active at the given index.
- 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.
- addItemWithID(text, ID) - Adds a new item to the end of the list with the given text and ID.
- 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, text) - Sets the text at a given index.
- sortByAText([ascending]) - Sorts the list by the item text. An optional direction can be provided. True is ascending. False is descending.
- sortByID([ascending]) - Sorts the list by the item ID. An optional direction can be provided. True is ascending. False is descending.
This control is a cross between a button, a list box and a scroll control and it can do many of the same things as all three of those controls. The result is a classic drop down control that shows a list of options when clicked.
Please note: In versions of Torque2D before 4.0, this control was called a GuiPopUpMenuCtrl. To gain consistency with the GuiListBoxCtrl, many of the console function have changed slightly as well.
Settings
- All GuiButtonCtrl settings
- MaxHeight - The max height of the drop down in pixels.
- ScrollProfile, ThumbProfile, ArrowProfile, and TrackProfile - The four profiles used by the scroll bar.
- ConstantThumbHeight - If true, thumbs will not adjust to show how much space is visible.
- showArrowButtons - If true, the scroll bar will include arrow buttons.
- ScrollBarThickness - Thickness of the scrollbar in pixels.
- ListBoxProfile - The profile used by each item in the list box that appears in the drop down.
Callbacks
- All GuiButtonCtrl callbacks
- All GuiListBoxCtrl callbacks
- onOpen - Called when the drop down opens.
- onClose - Called after the drop down closes.
Methods
- All GuiButtonCtrl methods
- All GuiListBoxCtrl methods - With the exception of the multiselect methods. The drop down can only select one item at a time.
- GetText() - Simply returns the currently selected text.
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).
This controls displays a progress bar. It can smoothly animate from one state to another and it makes creative use 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 border, 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.
As you might expect, these two controls create a menu bar. The menu bar automatically positions itself in the top of whatever container it is placed in. Menu items are the only children that can be placed in the menu bar and they can be nested to create sub-menus. The menu bar itself takes more profiles than any ctrl mentioned so far but its children, the menu items, don't take a profile at all. This is to keep you from having to place the same profile on each child.
The menu bar comes with a host of features: hot keys, spacers, toggle options, radio options, sub-menus, hidden menus, disabled menus, and keyboard controls. Each of these is described below. In addition, it's possible to have more than one menu bar on the screen. For example, you may want several window controls, each with their own menu bar.
Settings for GuiMenuBarCtrl
- Profile - All controls use the profile. In this case, it is applied to the bar itself. Only the normal state is used.
- MenuProfile - Used to display the menu item that appears on the menu bar itself.
- MenuItemProfile - Used to display the menu items that appear inside a menu. It's worth noting that the SL state here mean "Spacing Line".
- MenuContentProfile - Used for the menu that opens when an item on the menu bar is clicked on.
- BackgroundProfile - Render's its normal state over the entire canvas behind the menu when the menu is open. Normally this transparent but you could do something else if you want.
- ThumbProfile, ArrowProfile, and TrackProfile - The three profiles used by the scrollbar. You may notice that the profile used for the content of the scroll bar is missing. This is actually the same as the MenuContentProfile, it just has a different name here. Keep in mind that scrollbars will not appear unless there's not enough space between the menu and the bottom of the screen. Menus, unlike drop downs, will not open in the up direction. They need space below them to open.
- ConstantThumbHeight - If true, thumbs will not adjust to show how much space is visible.
- showArrowButtons - If true, the scroll bar will include arrow buttons.
- ScrollBarThickness - Thickness of the scrollbar in pixels.
- Accelerator - A key or key combination that selects the menu when pressed. On the menu bar, this defaults to Alt, but you can change it to fit your needs.
Settings for GuiMenuItemCtrl
- Text - The text that appears for the menu item. Setting this to a single dash "-" will cause the item to be a spacer.
- Accelerator - A key or key combination that can be used to activate the command without opening the menu. This will be ignored for top-level menus, sub-menus and spacers. Accelerators should be the modifiers keys (such as alt, ctrl, and shift) separated by dashes "-" followed by a space and the actual hot key. So the classic Copy combination would be "Ctrl C". If you want to add a "shift" it would be written "Ctrl-Shift C". Also, when viewed on a Mac, Ctrl will automatically be converted to Cmd. So "Ctrl-Shift C" would become "Cmd-Shift C".
- Toggle - If true, then this is a toggle menu item instead of a normal menu item.
- Radio - If true, then this is a radio menu item instead of a normal menu item. When pressed, other radio items directly above or below this radio item will be turned off. Use spacer lines to separate different sets of radio buttons.
- IsOn - True if a toggle or radio button should be on initially.
- Command - The Command of an item is called when it is chosen on the menu or when a toggle or radio button is turned on.
- AltCommand - This is called when a toggle or radio button is turned off. You're free to ignore this if you don't need it.
Callbacks
- onOpen() - Called on the menu bar when the menu first opens.
- onClose() - Called on the menu bar when the menu closes.
- onAction() - Called on the item when a menu is activated. This is only called if the Command is not set.
Profile Fields Used
- Profile - This displays the menu bar itself using the normal state only. You should also turn on canKeyFocus if you want to be able to use the arrow keys to navigate the menus.
- MenuProfile - This is used to display the top level menus that appear on the menu bar. All four states are used.
- MenuItemProfile - This is used to display the items that appear inside a menu. The normal state and hover state work as expected. The SL state stands for "Spacer Line" and is used to create a spacer by render with a content area with no height. The disabled state it shown when a menu item is not active.
- MenuContentProfile - This is used to create a box that holds the menu items when a menu opens. Only the normal state is used.
- BackgroundProfile - Displays its normal state over the entire canvas behind the menu when it's open.
Methods Its worth noting that the menu items are just plain children of the menu bar. Since they inherit from SimSet (as do all GuiControls), adding a menu or changing their order can be accomplished in the same way as adding an item to a SimSet or changing the order of a SimSet. SimSets have methods like add(), remove() and BringToFront() that can all be used to manipulate your menus. A full list of SimSet methods can be found here.
The color picker is a low-level control that allows you to construct more complicated color controls. It has multiple modes offering a lot of functionality. The down side is that it is complicated. If you want something simplier you should see the color popup below. Also note that the color picker and popup both use decimal values to define a color since this allows for more percision than integer values.
Settings
- BaseColor - The displayed color when in pallet or blend mode. Use values between 0 and 1.0.
- PickColor - The selected color that has been picked from the control. Again uses values between 0 and 1.0.
- DisplayMode - Possible values include: Pallet, HorizColor, VertColor, HorizBrightnessColor, VertBrightnessColor, BlendColor, HorizAlpha, VertAlpha, and Dropper.
- ActionOnMove - If true, onAction is called anytime the pickColor changes.
- ShowSelector - If true, the selector will be visible. This excludes Pallet and Dropper mode.
- SelectorProfile - The profile used to render the selector. The values used by the selector differ greatly from other controls. The selector is a ring and uses the normal state at rest, the highlight state when hovered, and the selected state when moving. The color of the ring is based on fill color from these three states and the border is drawn around the outside edge of the ring. The default or top margin + 1 is used to determin the radius of the hole in the center of the ring. The default or top padding is used to determine the thickness of the ring.
Callbacks
- onAction - The onAction callback is used when the pick color changes (if ActionOnMove is true) or when the dropper selects a color.
- onTouch... - The various onTouch events also work for the picker.
Profile Fields Used First, it is worth noting that this control will render nothing when in Dropper mode (since the point is to capture the color of whatever is under it). It will also not apply margins, border or padding. When in any other mode, the color picker will render as any control and then render its color box over the content area. When chosing one of the alpha modes, the color picker will render a checker pattern under the transparent portions. The color picker will also render text using all the same profile settings as a regular gui control.
Methods
- getSelectorPos() - Returns the position of the selector in space-separated coordinates.
- getSelectorPosForColor(red, green, blue, alpha) - Returns the position of the given color. Values should be between 0 and 1.0.
- setSelectorPos(x/y) - Sets the selector to the given position.
- updateColor() - Forces the color picker to update.
The color popup uses several color pickers to build a working user interface to choose a color with. It takes very little configuration to get a color popup to work. The popup is a button that displays a color. When clicked, it open up standard color picker overlay where the user can select a color. It can optionally include transparency.
Settings
- BackgroundProfile - Displays its normal state over the entire canvas behind the popup when it's open.
- popupProfile - Used to render the box that pops up.
- pickerProfile - A profile given to the various color pickers that are used by the popup.
- selectorProfile - A profile used by the color selectors.
- BaseColor - The color that sets the hue of the popup. Should be a color that uses 0 to 1.0.
- PopupSize - The extent of the popup when it opens.
- barHeight - The height given to the color hue bar and optionally the alpha bar under the main color picker.
- showAlphaBar - If true, the color picker will include an alpha bar to adjust transparency.
Callbacks
- onOpen() - Called when the popup opens.
- onClose() - Called when the popup closes.
Profile Fields Used The popup renders as a normal gui control using all the expected values. It then renders the solid selected color over content area.
Methods
- openColorPopup() - Opens the popup.
- closeColorPopup() - Closes the popup.
- setBackgroundProfile(profile) - Set the background profile.
- setPopupProfile(profile) - Set the popup profile.
- setPickerProfile(profile) - Set the picker profile.
- setSelectorProfile(profile) - Set the selector profile.
- getColorF() - Returns the currently selected color with values as decimals between 0 and 1.0.
- getColorI() - Returns the currently selected color with values as integers between 0 and 255.
The tree view displays the contents of a Sim Set or file system. This control is mostly intended for internal use with T2D's editors, but you are welcome to use it in a game if it makes sense. The TreeView inherits from the ListBoxCtrl and will have all of the features of the list box as a result.
Please note: This control was rewitten for Torque2D 4.0 Early Access 3.0. As such, its fields, methods and behaviors are different and older code will likely need to be updated to work as intended.
Callbacks
- onClick(%obj) - Called when a line is clicked in the tree. Includes the object that the line represents.
- onDoubleClick(%obj) - Called when a line is double-clicked in the tree. Includes the object that the line represents.
- onGetObjectText(%obj) - Called when the tree is about to generate the text for an object. If text is returned it is used instead.
Profile Fields Used Like the ListBoxCtrl, each line of the tree is rendered using the profile. A triangle and focus line is drawn using the reverse of the fill state (between normal state and selected state).
Methods
- inspect(%obj) - The object to set as the root of the tree. This should be a SimGroup.
- uninspect() - Uninspects the current root of the tree.
- refresh() - Rebuilds the tree. Useful if you changed the contents of the tree.
- setItemOpen(%index) - Sets if an item is open based on the given zero-based index.
- getItemOpen(%index) - Returns true if the item based on the given index is open.
- getItemParent(%index) - Returns the index of the parent of the given item.
- refreshItemText(%index) - Causes the tree to update the text of the given item. Use the onGetObjectText callback to directly change the text.
The frame set is a powerful, complex control that breaks a space up into specific frames that can be adjusted in size using a bar between them. This is common behavior in many apps today and greatly improves the user experience. If a window is a direct child of a frame set then it can be dragged out into a floating window by the user. It can then be placed into a new frame if desired or placed into an exsiting frame to form a tab book. When a control is added as a child to the frame set, the frame set tries to add it to the first empty frame available starting with the left-top-most empty frame.
Settings
- DividerThickness - The thickness of the divider between frames.
- DropButtonProfile - The profile used for the buttons the display when dragging a window in front of a GuiFrameSet.
- LeftRightCursor - The GuiCursor that should be used when moving a divider left and right.
- UpDownCursor - The GuiCursor that should be used when moving a divider up and down.
- TabBookProfile - The profile given to tab books when one is created.
- TabProfile - The profile given to tabs when a tab book is created.
- TabPageProfile - The profile give to a tab page when a tab book is created.
Profile Fields Used The GuiFrameSetCtrl only uses its profile to render the dividers between frames. However, it does not apply margins.
Methods
- createVerticalSplit(%frameID) - Splits the given frame so that there is a top frame and a bottom frame. The new IDs for these frame are returned as a pair with the top frame first.
- createHorizontalSplit(%frameID) - Splits the given frame so that there is a left frame and a right frame. The new IDs for these frame are returned as a pair with the left frame first.
- anchorFrame(%frameID) - In a pair a frames, one must always be anchored. An achored frame tries to maintain its size when a parent resizes. This sets a frame to anchored based on the frameID.
- setFrameSize(%frameID, %size) - Sets the width or height of a given frame.