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:

#define READABLE_FADE_TIME 200

This constant is then frequently used in other .gui for page-flipping visuals in readables. For instance, in tdm_gui01.pk4\guis\readables\sheets\sheet_paper_print_stone.gui (line 124):

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

Observe that in this case, the developer chose not to include double quotes around time_duration, accel, and decel values.

Sparingly Used

RunScript Command

Runs the specified parameterless function in the FM's game script. This works only if the command is in an "onAction" event block, i.e., in response to a LMB "Attack" press. Syntax choices...

• With the name of a particular function in a map script:

runScript "map_name::functionName"; // where "map_name::" is optional

• With the name of a placeholder spawnarg (like "gui::gui_parm6") on the attached entity, that holds the function name:

runScript "gui::gui_parmn";

Example

Adapted from stgatilov in New features in GUI engine (bugtracker 6164). See there for more.

Suppose you want some special action to occur when you click Attack when reading a readable. To that end, you've created a custom readables .gui override script, and within it's onAction block, added the line:

 runScript "testfunc";

In one of your FM's .script files, you will have defined that parameterless global function:

void testfunc() {
  sys.println("It works!"); // or whatever special action you want
}

Subsequently, when you click Attack when reading a readable, "testfunc" is triggered and you'll see "It works!" in the console.

Notes

1) The parameterless function must be a freestanding global, not a method that is part of a script object.

2) When runScript is encountered, the command and its function name are merely added to a buffer. It's execution (in a separate script thread) is not started until the invoking frame's GUI handling is done. The script function may have a duration as long as you'd like.

3) There can be multiple runScript calls in a .gui, and each will get its own script thread when run.

4) Through TDM 2.11, runScript is effectively ignored except when found in an "onAction" event block. This is because only the code associated with onAction retrieves the command from the buffer for execution, prior to buffer clearing.

5) Extending "runScript" to be effective from "onTime" and other "on..." event handlers is a possibility for TDM 2.12; See "New features in GUI engine" [bugtracker 6164].

6) The syntax specification is due to HMart (Ref 10).

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

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