GUI Scripting: GUI:: Parameters

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

What and Why of GUI:: Parameters

"GUI:: Parameters" are different from standard GUI properties and GUI user variables. But just like user variables, you invent their names. They can easily take on float values (including representing boolean and integer values) or string values. Vector values such as color can handled not as a whole, but by passing any given component as a float.

If you have an entity with both a .gui and .script, a GUI:: Parameter provides a channel to pass a value in either direction. This will be potentially "instantaneous", in that values could be re-evaluated on every frame. In the GUI file, the GUI:: Parameter is always prefixed with "gui::". That prefix is NOT used in the .script file.

Besides these custom GUI:: Parameters, there are also predefined ones associated with system CVars. These are global, in the sense that they can be accessed in your .gui without mention in your .script. They are not covered here; see GUI Scripting: Getting System CVars.

The Magic Prefix "Gui_Parm"

If you have an entity with:

• a "gui" spawnarg of valid value, and
• one or more spawnargs with name prefix "gui_parm".

then when the entity and its GUI are spawned, gui:: parameters with the gui_parm names will be created and initialized from the spawnargs values, and can be used immediately in the GUI. The usual naming convention is "gui_parm" alone or followed by a digit, but any suffix string will do.

If a gui_parm has an i18n string value (i.e., a #str value), the corresponding gui:: parameter is automatically initialized with the correct language string.

The magic prefix naming is particularly useful for entities that don't need a .script file. Be aware: if the overlay is created (or replaced) in a script, then spawnargs will NOT be consulted for gui:: parameter creation and initialization. Also, if an updatable spawnarg value is so updated by a script, that change is not automatically propagated to the gui:: parameter. However, in both those cases, script code can be written as needed to get the spawnarg value and send it to the gui:: parameter, as indicated next.

Important Use: Spawnarg -> .Script -> .Gui

Except for the magic prefix initialization, a .gui attached to an entity cannot read or access the entity’s spawnargs directly. Instead, a .script function acts as the intermediary. The usual dance is:

• The mapper sets a key/value spawnarg on the entity (with key and default value often predefined in an entityDef).
• An attached script (say, specified in a "scriptobject" spawnarg) fetches the spawnarg value, with:
  • GetKey(spawnarg_name); // gets value in string form
  • GetIntKey(spawnarg_name);
  • GetFloatKey(spawnarg_name);
• The script can then pass that on the GUI in a desired form, as discussed next.

As mentioned above, gui:: parameters do not involve or affect entity spawnargs (other than magic prefix initialization). Internally, a GUI's gui:: parameters are stored in a separate "dictionary" data structure. You create gui:: parameters in the dictionary by referencing them in your .gui and .script. If a GUI can access multiple script functions (e.g., both a frob_action_script and script object functions) , then each function can potentially access the gui:: parameters. Just the correct handle number and use of the appropriate names/types is needed.

In a GUI File – Syntax and Use

In the GUI file, use a "gui::" prefix, followed by a name, all in double quotes. A gui:: parameter can appear multiple times within a file and at any level of "guiDef" nesting.

Bound In a Property List

A gui:: parameter can be "bound" to a standard float or string property (not a user variable or vector). For example, in the property list of a "windowDef SignText":

text	"gui::gui_parm1"

Another string example, from the mainmenu_briefing.gui:

background	"gui::BriefingVideoMaterial"

For a more dynamic use, see GUI Scripting: On Entity’s Surface, where it is important that the boolean value of the bound property...

visible "gui::is_visible"

... is automatically re-evaluated every frame.

In Event Block’s Set Command

Usages are either sources or sinks for "set" commands (involving strings or floats, not vectors).

Consider this readable example. In one of the onTime handlers, strings are copied from two gui:: parameters to the text property of the two other windowDefs named "title" and "body":

set "title::text" "$gui::title";
set "body::text" "$gui::body";

As usual with "set", a "$" on the source indicates that the value is to be copied, not a literal string such as "gui::title". See the example at this article’s end for more.

In Event Block’s "If" Statement

A gui:: parameter can be tested in a "if" conditional clauses. For example, when a readable fades out its background, it uses an onTime event handler containing:

if ("gui::numPages" > 1) {
  transition "backgroundmulti::matcolor" "1 1 1 1" "1 1 1 0" READABLE_FADE_TIME;
}
if ("gui::numPages" == 1) {
  transition "backgroundsingle::matcolor" "1 1 1 1" "1 1 1 0" READABLE_FADE_TIME;
}

In a SCRIPT File – Syntax, and Available Functions for GUI:: Parameters

In the body of a SCRIPT function, use a double-quoted parameter name that matches that in the GUI file, but without the "gui::" prefix. Pass that name in a SetGui… or GetGui… function call whose type - float, int (also used for bool), or string - matches the usage in the GUI file. You must specify a handle with these functions, as discussed in GUI Scripting: Handles.

GetGui… Functions

Each of these functions returns the value of the GUI:: Parameter given by "key":

• getGuiFloat(float handle, string key); // returns a float
• getGuiInt(float handle, string key); // returns a float with int value
• getGuiString(float handle, string key); // returns a string

Don’t confuse that last one with this function:

• getGui(float handle); // returns a string with the file currently loaded by the GUI.

SetGui… Functions

Similarly:

• setGuiFloat(float handle, string key, float val);
• setGuiInt(float handle, string key, float val);
• setGuiString(float handle, string key, string val);

There is a 127 character size limit on script strings that can impede that last function. An alternative function gets around that, by copying a string value directly from an entity spawnarg to a gui:: parameter:

• setGuiStringFromKey(float handle, string key, entity src, string srcKey);

So, for example, in the body of a script object function, it would typically take the form:

$player1.setGuiStringFromKey(myhandle, "myGuiParamName", self, "mySpawnArgName");

For More

• GUI Scripting: Number Wheel Example shows how a GUI can detect a user action, then originate a change to a gui:: parameter in order to pass it on to a script object for processing.
• GUI Scripting: Flashbomb Example also is relevant. In particular, it shows how to use a gui:: parameter to control color transitions, even though the GUI language parser will not accept a gui:: parameter embedded into a color vector.