GUI Scripting: Properties in Common

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

Introduction

Here is a catalogue of Properties common to windowDefs and all other members of the "guiDef" family. (Other members have additional task-related Properties; see GUI Scripting: Properties Def-Specific). The catalogue is arranged by:

1) Frequency of use in TDM (widely; seldom; debug; unlikely to be useful)

2) General purpose

• rectangle size, location, and appearance
• text and font attributes
• cursor attributes
• timer and events

3) Alphabetically

A Property has a predefined name, type (Boolean, float, vec2, vec4, string) and default value. Properties appear in a <Property List> at the start of a guiDef's body, after the "{". Conventionally, one Property is listed per line. Any property not explicitly listed still exists, with its default value.

About "Registers", Marked Here As ®

As indicated in the listing below, properties are of two types:

• those that can only be given an initial unchanging value.
• those that can be changed, called "Registers", and indicated here by a ® symbol.

A Register can be changed by one of these two methods:

1. By a "set" or "transition" event handler command, which updates the initial value. If the command is in a different guiDef (while still part of the same GUI), use the "guiDef_name::" prefix before the variable.
2. By "binding" a gui:: parameter to it, as its value. This value will then be checked every frame. The value of the gui:: parameter is updated either from an associated .script file, or from a "set" or "transition" command in some guiDef of the GUI. For more, see GUI Scripting: GUI:: Parameters.

While changing a non-register value is not possible, you can probably get the desired effect by cloning the guiDef and selective hiding.

About Syntax & Usage Examples

Syntax examples shown here start with how they can appear in a property list. For properties that are registers, there may be additional examples with event handler commands "set", "transition", or "if (condition)". Property list and event handler commands have different syntax; don’t confuse them.

Used Widely in TDM

Rectangle Size, Location, and Appearance

backcolor color_vector ®

Defines the guiDef’s background color. Colors are normalized RGB and alpha values. . Default: all 0 values (black but transparent).

backcolor 1,1,0,1 // Yellow with no transparency.

background path ®

Defines the guiDef’s background image or video. Typically, this specifies the logical path to a material shader, as defined in a .mtr file. Alternatively, it could be a relative file path, e.g., to a .tga file; the file extension is left off. Default is "".

background "guis/assets/readables/books/book_rightpage_01"
set "background" "guis/video/credits/city_sequence01"; // Logical path shown, defined in materials/tdm_gui.mtr, is to a roq video.

bordercolor color_vector ®

Defines the color of the guiDef’s border. Colors are normalized RGB and alpha values. The bordersize property must be non-zero for a bordercolor to show. Default: all 1 values (opaque white).

 bordercolor 1,1,0,1 // Yellow with no transparency.
 bordercolor 0, 0, 0, 0.7 // Used in mainmenu_loadsave.gui. Semi-transparent black border.

bordersize pixels

Defines the stroke size used to draw the guiDef’s border, in [presumably logical] pixels. Default: 0.

bordersize 1 // Only sizes 0 and 1 are used in core.

forceaspectwidth width & forceaspectheight height

Force a specific draw surface width and height. Used in a top-level windowDef.

While these commands make only a single appearance in core TDM, in #include file "readables.guicore", that’s within a macro hierarchy affecting all the readables. Default: 640w x 480h.

matcolor color_vector ®

Defines the color of the image displayed in the guiDef’s "background" property. While in a R,G,B,A format, each float is not an absolute color value; it is a percentage (from 0 to 1) of how much of that channel will be rendered. Usually only the A channel is changed. Default: all 1 values (100% rendered).

matcolor 1,1,1,0 // In windowDef backgroundsingle, hide this background initially, then,
set "backgroundsingle::matcolor" "1 1 1 1"; // in a script command, show it right away or fade in.
transition "backgroundsingle::matcolor" "1 1 1 0" "1 1 1 1" READABLE_FADE_TIME;

noclip bool

Don’t clip draw operations that lie outside the guiDef rectangle? Default: 0 (false).

noclip 1 // Widely set to 1 in core, e.g., for readables.

rect vector_with_4_values ®

Defines the location, width and height of the guiDef rectangle as x-origin, y-origin, width, height. 0, 0, 640, 480 would be a guiDef of 640 by 480 logical pixels whose top left corner is at coordinate 0,0. The first two values always represent the guiDef’s upper left corner. The rect of a child guiDef is relative to its parent's rect but within its inner border as given by bordersize. That is, if the parent x/y origin coordinates are 0,0, and the parent's bordersize is 3, then if the child x/y origin coordinates are 0,0, that's actually at the parent's 3,3 location.

rect      0, 0, 640, 480 // By convention, a top-level windowDef is explicitly set to these values, to define the logical coordinate system for child guiDefs.
set "body::rect" "20, 10, 250, 380"; // In guis\readables\parchment_everett_hand_2.gui
transition "message::rect" "0, 0, 185, 1000" "10, 59, 185, 1000" "1" // a script event in tdm_message_no_art.gui that appropriately sizes a popup message box, in this case for 2 lines of text.

visible bool ®

Should this guiDef be visible? Default: 1 (true).

visible 0 // Default is 1 (true). In core, widely used as a toggle.
if ("StealthScoreDetail::visible" == 1) { // Fragment from within mainmenu_success.gui’s
 set "StealthScoreDetail::visible" "0"; …}  // onAction, showing test and change of value.

Text and Font Attributes

font font_path

Sets the font to be used for the text, from among available TDM fonts. Default: "".

font "fonts/stone" // Property is widely used in core.

forecolor color_vector ®

Defines the color of the guiDef’s text. Colors are normalized RGB and alpha values. Default: all 1 values (opaque white).

forecolor 1,1,1,1 // This example is opaque white, widely used.
forecolor 0, 0, 0, 0.66 // Black text, semi-transparent, as used for various sign texts.
transition "title::forecolor" "0 0 0 0" "0 0 0 0.85" READABLE_FADE_TIME; // As script command, here to fade in title of a readable sheet of paper.

text string_literal_or_variable ®

The text to be displayed in the guiDef. The character limit is 1024 [true?]. Default: "".

text "Heading" // In property list. Widely used.
set "leftCapital::text" "$gui::left_capital"; // script command used in core for readable books with illuminated drop caps.

textalign align_enum

Defines the text’s alignment within the guiDef. Values are 0 (align left), 1 (center horizontally), or 2 (align right). Default: 0 (align left).

textalign 1 // In property list. Value of 1 widely used for centering. Value of 2 rarely, e.g., in tdm_loot.gui .

textalignx offset_x & textaligny offset_y

Offset respectively the x & y value of the text relative to the guiDef. Defaults: 0.

textalignx -3 // mainmenu_defs.gui includes these 2 properties
textaligny -2 // in #defines to properly space button captions.

textscale factor ®

Uniformly scales the text’s font size in the guiDef. The range is generally from 0.0 to 1.0 but can exceed 1.0. Default: 1.

textscale 1.5 // Widely used in readables, ranging from 0.2 to 3.

Cursor Attributes

menugui bool

Use on a top-level windowDef. A value of 1 marks the gui as a menu gui. This affects the look of the cursor pointer. Helpful too when debugging world guis. Default: 0 (false).

menugui 1 // Value of 1 used in mainmenu.gui, which the #includes all other mainmenu… gui files.

nocursor bool

Use on a top-level windowDef. A value of 1 shows no cursor over the windowGui. This can be used for non-interactive GUIs such as videos and in-world monitors. Default: 0 (false).

nocursor 1 // Most HUD and other overlays will set "nocursor 1".

Timer and Events

modal bool

Should this guiDef eat events if active? Used for pop-up boxes. Default: 0 (false).

modal 1 // Typical use in core: mainmenu_message.gui

noevents bool ®

Should all of the guiDef’s onAction scripts be disabled? Default: 0 (false).

noevents 1
set "noevents" "1" // Representative use in core: in mainmenu_loadsave.gui

notime bool ®

Should all of the guiDef’s onTime scripts be stopped from running? Used for guiDefs holding animation scripts. Default: 0 (false).

notime 1 // Widely used in core.
set "notime" "1"; // Representative use in core: in tdm_inv.gui

Seldom or Never Used in TDM

These properties were not found to be used in the core unless otherwise noted with specific examples. Generic examples are given in some cases.

Rectangle Size, Location, and Appearance

invertrect bool

Correct for this guiDef being upside-down? Default: 0 (false).

invertrect 1 // Not used in core.

matscalex factor_x & matscaley factor_y

Scales the background material in the x & y directions respectively. When set to -1, flips the guiDef’s texture along the horizontal & vertical axis respectively. Default: 1.

matscalex -1 // Used in mainmenu_background when player failed, to flip the texture of "big chains". Matscaley not used in core.

naturalmatscale bool

Use the real size of the background material? Default: 0 (false).

naturalmatscale 1 // Not used in core.

rotate degrees ®

Defines the angle in degrees that the guiDef’s image will be rotated. This property can also be used in a "transition" statement to rotate the image over time. Default: 0 degrees.

// Not used in property list in core.
set "rotate" "0"; // Examples from the mainmenu_background.gui, if player fails, rotate a small
transition "rotate" "0" "9" "5000" "0.7" "0.7"; // chain in the background

shear vector_with_2_values

"Shear" the rectangle, which turns it into a parallelogram. Range of each value is 0 to 1. Vec2 Default: 0,0.

 shear 0.5,0 // Not used in core.

Text and Font Attributes

nowrap bool

Don’t wrap text that can’t fit in the rectangle? Default: 0 (false), so wrap

nowrap 1

shadow bool

Use a black drop-shadow when drawing the text? Default: 0 (false)

shadow 1

Timer and Events

wantenter bool

When the user presses enter, and there's no child guiDef that has the focus, should the guiDef’s onAction (and/or onActionRelease) event handler run? Default: 0 (false)

wantenter 1

Debug Only

showtime bool

Display the guiDef time? Default: 0 (false).

showtime 1

showcoords bool

Display the guiDef coordinates? Default: 0 (false).

showcoords 1

Unlikely to be Useful

For more about these properties, likely more pertinent to other idTech4 games, see GUI Scripting: TDM vs Doom 3, Quake 4.

comment string

Free form comment area. Unnecessary. Usually, just use /*…*/ or // for comments. Or if this gui is paired with an entity, add a "comment" spawnarg to the latter.

name new_name_string

Re-defines the guiDef’s name.. Each guiDef in a GUI file must have a unique name, which by default is initialized by the <guiDef Type> <name> {...}. But can be overwritten by using "name" property explicitly.

play sound_path

Prints a warning message telling you not to use it. Main menu system developers: Use 'set "cmd" "play ..." ' instead. Mappers: trigger sounds from a .script or deploy a separate entity.

Unused in Doom 3 & TDM

Says Ref 1:

scale®, translate®, varbackground®

runscript® Not available as property, only as script command in Doom 3 (though unused in that form in TDM.)

Listed in Ref 3 (Quake 4), but not in Ref 1:

dpadgui

For More

This property listing is largely from Ref 3 of GUI Scripting: References & Resources as supplemented by Ref 1, but re-ordered. Examples are largely from TDM 2.10 core menus.