GUI Scripting: Commands

This page is part of a series. See GUI Scripting Language for overview.

These "GUI Script Commands" occur in the body of event handlers, often within the arms of if-clauses. They are required to end in ";".

In syntax descriptions, [ ] = optional.

Widely Used

ResetTime Command

Resets the timer for the current or specified guiDef to the stated time in milliseconds. This also starts the timer if it is stopped (e.g., because of "noTime 1"). Syntax:

resetTime ["guiDef_name"] time;

Double-quotes around time are optional. While in some idTech4 documentation, time itself is optional and assumed zero, TDM can crash if time is omitted.

Examples

resetTime 0; // Typical use
resetTime "InventoryPickUpMessage" 0;
resetTime "InventoryPickUpMessage" "1900";

Set Command

Set a property, user variable, or GUI::parameter to a given value, in order to change the appearance or behavior of guiDefs during runtime. Not all properties can be changed by script command. Those that can be are called "registers" and so listed in GUI Scripting: Properties in Common and the property lists of Other "GuiDef" Types. Syntax:

set "[guiDef_name::]variable" "new_value";

where variable is either

• a property or user variable of the current guiDef
• a property or user variable of another guiDef of the GUI as specified by the "guiDef_name::" prefix, or
• a GUI:: parameter, specified by the "gui::keyName" syntax. See GUI Scripting: GUI:: Parameters.

Examples with a Literal Value

set "buttonTwo::visible" "0";
set "livePan::rect" "0 0 640 200";
set "text" "You have clicked me";
set "gui::somestring" "How long";

Copying a Value from Another Variable

If you are trying to set one variable (variable_sink) equal to another (variable_source) you must reference the source using the ‘$’ prefix. This lets the parser know that you are referencing another variable, not just a literal string. Syntax:

set "variable_sink" "$variable_source";

Expression Mode and Vector Components

Starting in TDM 2.11, you can specify an arithmetic expression on the "right-hand side" (i.e., as a source parameter). You do this by using enclosing parentheses to enter the set command's "expression mode". Within expression mode, you can also specify vector components. As an example of both:

set backcolor (backcolor[0], backcolor[1], backcolor[2], 1 - backcolor[3]);

CAUTION: expression mode calculations that involve changeable variables ONLY use the values that are present when the handler starts. (This surprising "early evaluation" behavior traditionally has been seen in expression calculations in if-conditions. For more, see GUI Scripting: Evaluating Expressions & Variables.)

Using Set "Cmd" to Execute a Game/Engine Command

In addition to changing the values of properties and user variables, "set" allows special global property "cmd" to request the C++ code to execute commands. See GUI Scripting: Parsing of Set 'Cmd'.

Transition Command

Linearly interpolates a variable from one value to another over time_duration, in milliseconds. Often used for color changes. Not all properties can be changed by script command. Those that can be are called "registers" and so listed in GUI Scripting: Properties in Common and and the property lists of Other "GuiDef" Types. Syntax:

transition "[guiDef_name::]variable" "from_value" "to_value" time_duration [accel decel];

where

• from_value and to_value are most often color vectors represented by double-quoted, space-separated RGBA strings. But other vectors and floats are also permitted. In any case, they must match the variable type.
• accel and decel are values < 1 that specify a fraction of the time spent accelerating or decelerating (defaults to both 0). If accel + decel > 1, they are normalized.

Double-quotes around each float value accel and decel are optional. So are double-quotes around time_duration, but arguably recommended by TDM convention. For vectors, surrounding double-quotes and whitespace-separation (not commas) are required.

Examples

transition "MainMenuInGameParchment::matcolor" "1 1 1 0" "1 1 1 1" "400" ;

By convention, all-capitals variables are #defines. Here’s two typical color vector, with double-quotes and separating spaces, #defined in tdm_gui01.pk4\guis\mainmenu_defs.gui. They are widely used as part of a technique to make clickable menu text "glow" when moused-over, as in this specific transition example from mainmenu_main_ingame.gui:

#define SNORMAL_COLOR		"0 0 0 0.90"
#define SGLOW_WHITE_COLOR 	"0.98 0.93 0.82 1"

transition "MMIGCreditsText::forecolor" SNORMAL_COLOR SGLOW_WHITE_COLOR "50" ;

Another example, with a time_duration value #defined in tdm_gui01.pk4\guis\readables\readable.guicode, and frequently used in other .gui for page-flipping visuals in readables. Observe that in this case, the developer chose not to include double quotes around time_duration, accel, and decel values:

#define READABLE_FADE_TIME 200

transition "leftPageCurl::matcolor" "1 1 1 0" "1 1 1 1" READABLE_FADE_TIME 0.5 0;

Sparingly Used

SetFocus Command

Sets the input/selection focus to a particular editDef or listDef. Syntax:

setFocus "guiDef_name";

Example

setFocus "available_list"; // from mainmenu_download.gui

ShowCursor Command

Shows (with value "1") or hides ("0") the cursor. Syntax:

showCursor "bool";

Example

From mainmenu_briefing_video.gui:

showCursor "0" ; // Hide cursor for video
showCursor "1" ; // Show cursor after video

Notes

1) This command is relatively uncommon, because many guiDefs just leave the cursor visible, or hide it throughout with property:

nocursor 1

2) Many existing FMs override the mainmenu_briefing.gui, as custom edits of the some earlier standard .gui, which contained these lines:

showCursor "1" ; // Hide cursor
...
showCursor "1" ; // UNhide cursor

This would seem to indicate showCursor "1" acts oddly as a toggle. Or perhaps the first comment, widely propagated, is just wrong (or at least wrong now).

ResetCinematics Command

Resets the cinematics playing in the windowDef to frame 0 (i.e., start). Syntax:

resetCinematics;

Example usages of this may be seen throughout mainmenu_credits.gui, mainmenu_briefing_video.gui, mainmenu_debriefing_video.gui.

Commands Unavailable in TDM

The following are applicable to other related games using this GUI language, but not TDM. While in some cases, there is remnant code to parse and ignore these without complaint, it is best to avoid:

evalRegs, localSound, endGame, runScript

However, resurrecting "runScript" is a possibility for TDM 2.12; See New features in GUI engine.

For more about these 4 commands, see GUI Scripting: TDM vs Doom 3, Quake 4.