Controls

The name says it all—controls are graphical items provided to the program user to control what the program will do. In Torque, interactive controls are used by clicking on them or click-dragging the mouse across them. Some controls, like edit boxes, also require you to type in some text from the keyboard. Some of the controls have built-in labels that identify their purpose, and some will require you to create an accompanying noninteractive control to provide a label. Noninteractive controls, as the name implies, are used to only display information and not to capture user input.

Torque provides a number of default controls right out of the box; the most commonly used ones are listed next.You will have encountered a few of these controls in earlier chapters, and we will discuss several more of them in this chapter. You can use them as is; you can modify them by adjusting the control's profile; or you can use them as the basis for defining new controls.

 GuiArrayCtrl                         GuiControlListPopUp          GuiPlayerView GuiAviBitmapCtrlGuiBackgroundCtrl    GuiCrossHairHud              GuiPopUpBackgroundCtrl GuiBitmapBorderCtrl                  GuiEditCtrl                  GuiPopUpMenuCtrl GuiBitmapButtonCtrl                  GuiFadeinBitmapCtrl          GuiPopUpTextListCtrl GuiBitmapButtonTextCtrl              GuiFilterCtrl                GuiProgressCtrl GuiBitmapCtrl                        GuiFrameSetCtrl              GuiRadioCtrl GuiBorderButtonCtrl                  GuiHealthBarHud              GuiScrollCtrl GuiBubbleTextCtrl                    GuiInputCtrl                 GuiShapeNameHud GuiButtonBaseCtrl                    GuiInspector                 GuiSliderCtrl GuiButtonCtrl                        GuiMenuBackgroundCtrl        GuiSpeedometerHud GuiCanvas                            GuiMenuBar                   GuiTerrPreviewCtrl GuiCheckBoxCtrl                      GuiMenuTextListCtrl          GuiTextCtrl GuiChunkedBitmapCtrl                 GuiMessageVectorCtrl         GuiTextEditCtrl GuiClockHud                          GuiMLTextCtrl                GuiTextEditSliderCtrl GuiConsole                           GuiMLTextEditCtrl            GuiTextListCtrl GuiConsoleEditCtrl                   GuiMouseEventCtrl            GuiTreeViewCtrl GuiConsoleTextCtrl                   GuiNoMouseCtrl               GuiWindowCtrl 

Figure 10.3 shows a screen used to select missions to play. There is a list of available missions on the client, some buttons to run the mission or go back to the main menu, and a check box to indicate whether you want to host this mission for other players. Note, too, that there is a background, which is the same as the background used for our Emaga game program's start-up menu.

Figure 10.3: Start mission interface screen.

What we'll do is examine each of the screen's GUI elements in detail.

GuiChunkedBitmapCtrl

The GuiChunkedBitmapCtrl class is usually used for the large backgrounds of interfaces, like menu screens. Figure 10.4 shows such a background. The name derives from the concept of breaking up an image into a collection of smaller ones (chunked bitmaps) in order to improve display performance.

Figure 10.4: GuiChunkedBitmapCtrl background sample.

Here is an example of a GuiChunkedBitmapCtrl definition:

 new GuiChunkedBitmapCtrl(MenuScreen) {    profile = "GuiContentProfile";    horizSizing = "width";    vertSizing = "height";    position = "0 0";    extent = "640 480";    minExtent = "8 8";    visible = "1";    bitmap = "./interfaces/emaga_background";    // insert other controls here }; 

The first thing to note about this definition is the line "// insert other controls here". Typically, a GuiChunkedBitmapCtrl control would contain other controls, functioning as a sort of super-container. All other controls in a given screen using this control would be children, or subelements, of this control. This line is a comment, so in and of itself, it has no effect on the control's definition. I include it here to indicate where you would start nesting other controls.

Note the extent property, which specifies a width of 640 and a height of 480. These are "virtual pixels" in a way. Any subelements you insert in this control will have a maximum area of 640 480 to work with for positioning and sizing. These virtual pixels are scaled in size according to the actual canvas size, which you can change by setting the value of the global variable $pref::Video::windowedRes and then calling CreateCanvas, or if you already have a canvas, calling Canvas.Repaint;—we used CreateCanvas in Chapter 7.

The minExtent property specifies the smallest size that you will allow this control to be shrunk down to when using the Torque built-in GUI Editor. We will use that editor later in this chapter.

GuiControl

The GuiControl class, as shown in Figure 10.5, is a sort of generic control container. It's often used as a tablike container, or as what other systems often call a frame. With it, you can gather together a collection of other controls and then manipulate them as a group.

Figure 10.5: GuiControl sample.

Here is an example of a GuiControl definition:

 new GuiControl(InfoTab) {    profile = "GuiDefaultProfile";    horizSizing = "width";    vertSizing = "height";    position = "0 0";    extent = "640 480";    minExtent = "8 8";    visible = "1"; }; 

Probably the property you will be most interested in is the visible property. You will probably want to programmatically make the control visible or invisible based on the contents (the other controls) you place within the control. You can do that this way:

 InfoTab.visible = true; InfoTab.visible = false; 

Note that true is the same as 1 or "1" and false is the same as 0 or "0".

GuiTextCtrl

The GuiTextCtrl, as shown in Figure 10.6, is a straightforward, commonly used control. You can use it to display any text you want. You can put it on an interface with no text and then fill in the text as the game progresses.

Figure 10.6: GuiTextCtrl sample.

Here is an example of a GuiTextCtrl definition:

 new GuiTextCtrl(PlayerNameLabel) {    profile = "GuiTextProfile";    horizSizing = "right";    vertSizing = "bottom";    position = "183 5";    extent = "63 18";    minExtent = "8 8";    visible = "1";    text = "Player Name:";    maxLength = "255"; }; 

You would specify the text font and other characteristics with your choice of profile. You can change the contents quite easily in this example by doing the following:

 PlayerNameLabel.text = "Some Other Text"; 

The maxLength property allows you to limit the number of characters that will be stored with the control. Specifying fewer characters saves memory.

GuiButtonCtrl

The GuiButtonCtrl, as shown in Figure 10.7, is another clickable control class. Unlike GuiCheckBoxCtrl or GuiRadioCtrl, this class does not retain any state. Its use is normally as a command interface control, where the user clicks on it with the expectation that some action will be immediately invoked.

Figure 10.7: GuiButtonCtrl sample.

Here is an example of a GuiButtonCtrl definition:

 new GuiButtonCtrl() {    profile = "GuiButtonProfile";    horizSizing = "right";    vertSizing = "top";    position = "16 253";    extent = "127 23";    minExtent = "8 8";    visible = "1";    command = "Canvas.getContent().Close();";    text = "Close";    groupNum = "-1";    buttonType = "PushButton"; }; 

The most significant property is the command property. It contains a script statement to be executed when the button is pressed. This example will close the interface screen being shown in the canvas.

Another feature is the buttonType property. This can be one of the following:

• ButtonTypePush

• ButtonTypeCheck

• ButtonTypeRadio

The property groupNum is used when the buttonType is specified to be ButtonTypeRadio. Radio buttons in an interface screen that have the same groupNum value are used in an exclusive manner. Only the most recently pressed radio button will be set to the checked value (true); all others in the group will be unchecked. Otherwise, the radio button type works the same as the GuiCheckBoxCtrl class, described in the next section.

This control is also used as a base for deriving the three button classes shown previously. You would probably be better off to use the specialized classes GuiCheckBoxCtrl and GuiRadioCtrl for types ButtonTypeCheck and ButtonTypeRadio, rather than this control, because they have additional properties.

So the upshot is, if you use this control, it will probably be as a ButtonTypePush.

GuiCheckBoxCtrl

The GuiCheckBoxCtrl, as shown in Figure 10.8, is a specialized derivation of the GuiButtonCtrl that saves its current state value. It's analogous to a light switch or, more properly, a locking push button. If the box is empty when you click the control, the box will then display a check box. If it is checked, it will clear the check mark out of the box when you click the control.

Figure 10.8: GuiCheckBoxCtrl sample.

Here is an example of a GuiCheckBoxCtrl definition:

 new GuiCheckBoxCtrl(IsMultiplayer) {    profile = "GuiCheckBoxProfile";    horizSizing = "right";    vertSizing = "bottom";    position = "155 272";    extent = "147 23";    minExtent = "8 8";    visible = "1";    variable = "Pref::HostMultiPlayer";    text = "Host Mission";    maxLength = "255"; }; 

If you specify the variable property, then the value of the specified variable will be set to whatever the current state of the control is after you've clicked it.

When the control is first displayed, it will set its state according to the value in the specified variable. You need to make sure that the variable you use contains appropriate data.

You can also specify the text label that will be displayed next to the check box using the text property.

Note that the GuiRadioCtrl control functions much like this control, except that it automatically enforces the principle that only one button in the same group will be checked.

GuiScrollCtrl

The GuiScrollCtrl class, as shown in Figure 10.9, is used for those famous scrolling lists that everyone likes. Okay, so not everyone may like them, but everyone has used them.

Figure 10.9: GuiScrollCtrl sample.

Here is an example of a GuiScrollCtrl definition:

 new GuiScrollCtrl() {    profile = "GuiScrollProfile";    horizSizing = "right";    vertSizing = "bottom";    position = "14 55";    extent = "580 190";    minExtent = "8 8";    visible = "1";    willFirstRespond = "1";    hScrollBar = "dynamic";    vScrollBar = "alwaysOn";    constantThumbHeight = "0";    childMargin = "0 0";    defaultLineHeight = "15";    // insert listing control here }; 

Normally we would populate a scroll control with a list, usually defined by the contents of a GuiTextListCtrl control. The control containing the list would be added as a subelement of this control.

The willFirstRespond property is used to indicate whether we want this control to respond to arrow keys when they are pressed (to control scrolling) or to let other controls have access to arrow key inputs first.

Both the hScrollBar and vScrollBar properties—referring to the horizontal and vertical bars, respectively—can be set to one of these modes:

• alwaysOn. The scroll bar is always visible.

• alwaysOff. The scroll bar is never visible.

• dynamic. The scroll bar is visible only when the list exceeds the display space.

The property constantThumbHeight indicates whether the thumb, the small rectangular widget in the scroll bar that moves as you scroll, will have a size that is proportional to the number of entries in the list (the longer the list, the smaller the thumb) or will have a constant size. Setting this property to 1 ensures a constant size; 0 will ensure proportional sizing.

The property defaultLineHeight defines in virtual pixels how high each line of the control's contents would be. This value is used to determine how much to scroll when a vertical arrow is clicked, for example.

Finally, childMargin is used to constrain the viewable space inside the parent control that would be occupied by whatever control contained the list to be scrolled. In effect, it creates a margin inside the scroll control that restricts placement of the scroll list. The first value is the horizontal margin (for both left and right), and the second is the vertical margin (both top and bottom together).

GuiTextListCtrl

The GuiTextListCtrl, as shown in Figure 10.10, is used to display 2D arrays of text values.

Figure 10.10: GuiTextListCtrl sample.

Here is an example of a GuiTextListCtrl definition:

 new GuiTextListCtrl(MasterServerList) {    profile = "GuiTextArrayProfile";    horizSizing = "right";    vertSizing = "bottom";    position = "2 2";    extent = "558 48";    minExtent = "8 8";    visible = "1";    enumerate = "0";    resizeCell = "1";    columns = "0 30 200 240 280 400";    fitParentWidth = "1";    clipColumnText = "0";    noDuplicates = "false"; }; 

The enumerate property indicates which line of text is presented as highlighted.

You can allow the cells to be resized with the GUI Editor by setting the resizeCell property to true.

Each record, or line, in the array has space-delimited fields. You can format the display of these fields by using the columns property to indicate at which column number each field will be displayed.

The fitParentWidth property indicates whether the control will be enlarged in size to fill the available display space of any control that might contain this control.

We can decide whether overlong text in each column is to be clipped, or will be left to overrun adjoining columns, by setting the clipColumnText property.

We can automatically prevent the display of duplicate record entries by setting the noDuplicates property to true.

GuiTextEditCtrl

The GuiTextEditCtrl, as shown in Figure 10.11, provides a tool for users to manually enter text strings.

Figure 10.11: GuiTextEditCtrl sample.

Here is an example of a GuiTextEditCtrl definition:

 new GuiTextEditCtrl() {    profile = "GuiTextEditProfile";    horizSizing = "right";    vertSizing = "bottom";    position = "250 5";    extent = "134 18";    minExtent = "8 8";    visible = "1";    variable = "Pref::Player::Name";    maxLength = "255";    historySize = "5";    password = "0";    sinkAllKeyEvents = "0";    helpTag = "0"; }; 

With this control, the variable property is the key one. When the user types a string of text into the control's edit box, that string is entered into the variable indicated. When the control is first displayed, the contents of the indicated variable are stuffed into the edit box for display.

Text edit controls have a nifty history feature that can be quite handy. All of the previous entries—up to a maximum specified by historySize—are saved and can be recalled using the Up Arrow key to go back in history or the Down Arrow key to go forward.

If you are using this control to accept a password, then set the password property to true. The control will substitute asterisks ("*") in place of whatever is typed by the user so that bystanders can't see what is being typed.

The sinkAllKeyEvents property, when set to true, causes the control to throw away any keystrokes that it receives but doesn't understand how to handle. When sinkAllKeyEvents is set to false, these keystrokes will be passed to the parent.