GUI Scripting: GUI:: Parameters - Revision history

Geep: /* Bound In a Property List */ fix & expand gui::BriefingVideoMaterial info

2023-11-13T16:03:30Z

Bound In a Property List: fix & expand gui::BriefingVideoMaterial info

← Older revision		Revision as of 16:03, 13 November 2023
Line 76:		Line 76:
	CAUTION: No example was found of a gui_parm or more broadly any gui:: parameter being bound to a non-register property... so possibly that's not legal. [Someone please test!]		CAUTION: No example was found of a gui_parm or more broadly any gui:: parameter being bound to a non-register property... so possibly that's not legal. [Someone please test!]

	Another string example, from the ~~mainmenu_briefing~~.gui:		Another string example, from the mainmenu_briefing_video.gui:
	background "gui::BriefingVideoMaterial"		background "gui::BriefingVideoMaterial"

			The value here is a path to a custom video material shader. It is set at runtime by the engine, based on information the FM author provided in mainmenu_custom_defs.gui as, e.g.:
			#define MM_BRIEFING_VIDEO_MATERIAL_1 "video/tdm_briefing_video"
			(In older FMs, the video was chopped into parts, in which case the engine updates the value just-in-time. See comments in mainmenu_custom_defs.gui for details.)

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

Geep: /* Bound In a Property List */ duration of re-eval. Also set sink example

2022-11-14T20:04:01Z

Bound In a Property List: duration of re-eval. Also set sink example

← Older revision		Revision as of 20:04, 14 November 2022
Line 82:		Line 82:
	visible "gui::is_visible"		visible "gui::is_visible"

	... is automatically re-evaluated every frame.		... is automatically re-evaluated every frame. Similarly, one could have an expression with changing value:
			visible 1-"gui::is_visible"

			But in any case, be aware that automatic re-evaluation of a particular property (like "visible" in these examples) can become deactivated/disabled...
			* prior to TDM 2.11, if you include ANY reference to that property in an event handler body. Deactivation happens at startup [or perhaps right after property's first initialization].
			* In TDM 2.11, if you manually assign to that property using the "set" command. [Probably doesn't apply to "transition"]. Deactivation happens when "set" is executed.
			Careful programming can avoid unwanted deactivation.

	===In Event Block’s Set Command===		===In Event Block’s Set Command===
	Usages are either sources or sinks for "set" commands (involving strings or floats, not vectors).		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":		Consider some scripting from readable entities. As source examples, 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 "title::text" "$gui::title";
	set "body::text" "$gui::body";		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".		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.
			Here's a sink example, where information is being passed from the .gui to the .script file:
			set "gui::InteractionState" "3";

			See also the example at this article’s end for more.

	===In Event Block’s "If" Statement===		===In Event Block’s "If" Statement===

Geep: Add category tag

2022-11-04T16:24:58Z

Add category tag

← Older revision		Revision as of 16:24, 4 November 2022
Line 129:		Line 129:
	* [[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: 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.		* [[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.

			{{GUI}}

Geep: /* Cautions when a .Script File is Involved */

2022-10-25T18:22:32Z

Cautions when a .Script File is Involved

← Older revision		Revision as of 18:22, 25 October 2022
Line 54:		Line 54:
	}		}
	===Cautions when a .Script File is Involved===		===Cautions when a .Script File is Involved===
	Be aware: if a GUI is created (or replaced) in a script (which is the norm for overlays), then NO spawnargs will be consulted for gui:: parameter creation and initialization. Also, if an "gui_parm..." spawnarg value is 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.		Be aware: if a GUI is created (or replaced) in a script (which is the norm for overlays), then during that process NO spawnargs will be consulted for gui:: parameter creation and initialization. Also, if an "gui_parm..." spawnarg value is 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: Any Spawnarg -> .Script -> .Gui==		==Important Use: Any Spawnarg -> .Script -> .Gui==

Geep: /* Bound In a Property List */ Can gui:: parameter be bound?

2022-10-25T18:16:41Z

Bound In a Property List: Can gui:: parameter be bound?

← Older revision		Revision as of 18:16, 25 October 2022
Line 73:		Line 73:
	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":		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"		text "gui::gui_parm1"

			CAUTION: No example was found of a gui_parm or more broadly any gui:: parameter being bound to a non-register property... so possibly that's not legal. [Someone please test!]

	Another string example, from the mainmenu_briefing.gui:		Another string example, from the mainmenu_briefing.gui:

Geep: /* What and Why of GUI:: Parameters */ add sign text info

2022-10-25T16:17:20Z

What and Why of GUI:: Parameters: add sign text info

@@ Line 6: / Line 6: @@
 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]].
+Besides these custom GUI:: Parameters, there are also predefined ones associated with certain 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"==
@@ Line 16: / Line 16: @@
 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.
+The magic prefix naming is particularly useful for entities that don't need a .script file, as shown next.
 ==Important Use: Any Spawnarg -> .Script -> .Gui==

Geep: /* Important Use: Spawnarg -> .Script -> .Gui */

2022-10-24T18:24:34Z

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

← Older revision		Revision as of 18:24, 24 October 2022
Line 18:		Line 18:
	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.		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==		==Important Use: Any 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:		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).		* 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:		* An attached script (say, specified in a "scriptobject" spawnarg) fetches the spawnarg value, with:

Geep: /* Bound In a Property List */

2022-10-23T21:17:11Z

Bound In a Property List

← Older revision		Revision as of 21:17, 23 October 2022
Line 39:		Line 39:
	background "gui::BriefingVideoMaterial"		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...		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"		visible "gui::is_visible"

Geep: /* Bound In a Property List */

2022-09-25T21:26:15Z

Bound In a Property List

← Older revision		Revision as of 21:26, 25 September 2022
Line 33:		Line 33:

	===Bound In a Property List===		===Bound In a Property List===
	A gui:: parameter can be "bound" to a standard float property (not a user variable or vector). For example, in the property list of a "windowDef SignText":		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"		text "gui::gui_parm1"

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

2022-09-22T18:56:14Z

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

← Older revision		Revision as of 18:56, 22 September 2022
Line 64:		Line 64:

	==In a SCRIPT File – Syntax, and Available Functions for GUI:: Parameters==		==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, bool, ~~int,~~ string) matches the usage in the GUI file. You must specify a handle with these functions, as discussed in [[GUI Scripting: Handles]].		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===		===GetGui… Functions===