3D Game Programming All In One (2004)

338 Chapter 10 ■ Creating GUI Elements

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

Figure 10.3 Start mission interface screen. would contain other controls, functioning as a sort of supercontainer. 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

Figure 10.4 GuiChunkedBitmapCtrl background sample. 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.

Team LRN

Controls 339

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.

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

Team LRN

340 Chapter 10 ■ Creating GUI Elements

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.

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.

Figure 10.7 GuiButtonCtrl sample.

Team LRN

Controls 341

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.

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. Figure 10.8 GuiCheckBoxCtrl sample.

Team LRN

342Chapter 10 ■ Creating GUI Elements

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.

Team LRN

Controls 343

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.

Here is an example of a GuiTextListCtrl definition:

new GuiTextListCtrl(MasterServerList) { profile = "GuiTextArrayProfile";

Team LRN

344Chapter 10 ■ Creating GUI Elements

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.

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

Figure 10.11 GuiTextEditCtrl sample. stuffed into the edit box for display.

Team LRN

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.

The Torque GUI Editor

Torque has an editor built in for creating and tweaking interfaces. You can invoke the GUI Editor by pressing the F10 key (this is defined in the common code base scripts, but you can change it if you want). You are perfectly free to ship your game with this editor code, or you can remove it in any shipping version to ensure that people will not fiddle with the interfaces. Or you can modify it to suit your heart's desire!

The Cook's Tour of the Editor

When you launch the editor by pressing the F10 key, the editor will appear and load whatever interface is current, making it ready for editing.

Visually, there are four components to the GUI Editor: the Content Editor, the Control Tree, the Control Inspector, and the Tool Bar. Figure 10.12 shows the GUI Editor open and working with one of the earlier main menu screens from the Emaga sample game.

The Content Editor

The Content Editor is where you can place, move, and resize controls. In Figure 10.12 the Content Editor is the large rectangular area at the upper left in the GUI Editor view.

Selection

Normally, you select a control by clicking the mouse on it. Some controls can be difficult to select because of their

Figure 10.12 The Torque GUI Editor.

Team LRN

346Chapter 10 ■ Creating GUI Elements

positions. Another way to select controls is by using the Control Tree, which is covered in a later section.

If you hold down the Shift key while clicking the mouse (shift-clicking) on several controls, you can select more than one control at once. Each time you shift-click you add that control to the selection. The sizing knobs turn white and can no longer be used to size the control. You can still move the controls. Only controls that share the same parent can be selected at the same time.

Movement

Move a control by clicking and dragging its content area after selecting it. When you move controls, be aware of which controls they may be contained by—when you drag the control to one side or another, you may be dragging it outside the display area of its parent control, and you don't want that.

Resizing

You resize a control after selection by clicking on and dragging one of the eight black sizing knobs. As with movement, you need to stay aware of how the control you are resizing is related to other controls. The sizing might be restricted by a parent control's display area. Figure 10.12 shows the sizing knobs, attached to the Start Mission button.

Adding

The parent control of the currently selected control is outlined with a yellow and blue band. This control is known as the Current Add Parent. Any new control created from the toolbar or pasted from the Clipboard will be added to this control. The Current Add Parent control can be set manually by either clicking one of its children or right-clicking the control itself.

The Control Tree

The Control Tree shows the current content control hierarchy. It is in the upper-right corner of the GUI Editor view.

Parent controls, also called containers—controls that contain other controls—have a little box to the left of their entry in the tree. If the box is a plus sign, clicking it will expand that control into the list, bringing the child controls into view. If you click it when it looks like a minus sign, it will contract the control's list back to a single entry comprising solely the parent control.

Clicking any control in the tree will cause it to be selected in the Content Editor view and cause the control's properties to be displayed in the Control Inspector view. You can see this effect by looking back at Figure 10.12.

Team LRN

The Control Inspector

The Control Inspector is where the currently selected control's attributes are displayed. It is located in the lower-right corner of the GUI Editor, below the Control Tree. All of the properties of a control are displayed in the Inspector and can be changed here. After changing a value, you must click the Apply button to assert the changes.

When first displayed, all of the properties are collapsed visually within categories, such as Parent, Misc, and Dynamic Fields. To access the properties within those categories, simply click the buttons in the Inspector view that have those category names, and the list expands, giving you edit boxes and buttons with which you can manipulate the properties.

The Tool Bar

The Tool Bar contains functions for creating new controls and for aligning and spacing them. It has several command buttons that operate on the current selection set, and create and save GUIs. The Tool Bar also has pop-up menus for creating new controls and changing the currently edited GUI. The functions of the buttons are described in Table 10.1.

Table 10.1 Tool Bar Button Functions

Team LRN