GUI Scripting: User Variables - Revision history

Geep: Add vec4 synonym for definevec4

2023-10-07T17:01:19Z

Add vec4 synonym for definevec4

← Older revision		Revision as of 17:01, 7 October 2023
Line 2:		Line 2:

	==Introduction==		==Introduction==
	Optional user variables may be defined as part of (and conventionally at the end of) a guiDef's property list. There are 3 forms:		Optional user variables may be defined as part of (and conventionally at the end of) a guiDef's property list. There are traditionally 3 forms, with a 4th added for TDM 2.12:
	* float ''name''		* float ''name''
	* definefloat ''name'' // same as "float ''name''". No examples of this alias found in TDM.		* definefloat ''name'' // same as "float ''name''". No examples of this alias found in TDM.
			* vec4 ''name'' // same as "definevec4 ''name''"; added for TDM 2.12.
	* definevec4 ''name'' // Not used in core. Nor was an example in a sample of FMs found.		* definevec4 ''name'' // Not used in core. Nor was an example in a sample of FMs found.

Line 10:		Line 11:
	A user variable is directly known only to the guiDef in which it is defined and NOT its child guiDefs. However, it can be referenced elsewhere in the file by using the appropriate "guiDef_name::" prefix.		A user variable is directly known only to the guiDef in which it is defined and NOT its child guiDefs. However, it can be referenced elsewhere in the file by using the appropriate "guiDef_name::" prefix.

	==Float User Variable==		==Float or DefineFloat User Variable==
	Float and definefloat variables are the same thing. Reportedly, keyword "definefloat" was designed first by id Studio, then shortened to "float". Let’s refer to just "float" in what follows. Such a variable can serve as a decimal, integer, or boolean value. Boolean is the most frequent usage.		Float and definefloat variables are the same thing. Reportedly, keyword "definefloat" was designed first by id Studio, then shortened to "float". Let’s refer to just "float" in what follows. Such a variable can serve as a decimal, integer, or boolean value. Boolean is the most frequent usage.

Line 110:		Line 111:
	}		}

	==DefineVec4 User Variable==		==Vec4 or DefineVec4 User Variable==
			Vec4 and defineVec4 user variables are the same thing. Before TDM 2.12, only the defineVec4 keyword (used in the examples below) was available; see [https://bugs.thedarkmod.com/view.php?id=6164 New features in GUI engine]. (Some other id-family projects added the vec4 synonym a while ago.)

	If you thought the float user variable was squirrelly, the definevec4 is even worse. Which may be why it's not used in the core. If you want to use it, here's a suggestion.		If you thought the float user variable was squirrelly, the definevec4 is even worse. Which may be why it's not used in the core. If you want to use it, here's a suggestion.

Line 125:		Line 128:
	DON’T try to use it to give a value to a property, e.g., in a property list:		DON’T try to use it to give a value to a property, e.g., in a property list:
	matcolor show_it // Doesn’t work no matter what form you use		matcolor show_it // Doesn’t work no matter what form you use

	As a synonym for "definevec4", keyword "vec4" is available in some other id-family games, and has been proposed for TDM 2.12. See [https://bugs.thedarkmod.com/view.php?id=6164 New features in GUI engine].

	{{GUI}}		{{GUI}}

Geep: /* Declared in Property List */ Non-zero initialization of float

2022-11-15T20:46:32Z

Declared in Property List: Non-zero initialization of float

← Older revision		Revision as of 20:46, 15 November 2022
Line 14:		Line 14:

	===Declared in Property List===		===Declared in Property List===
	~~When declared in a property list, a float user variable~~ is ~~ALWAYS initialized to zero. Syntax~~:		Declaration syntax is:
	float myvar 0 // recommended form~~. 0 is only real value~~, ~~but needed for proper parsing. Matches~~ syntax style of properties.		float myvar 0 // recommended form, matching syntax style of properties.
	float myvar; // alternate form with semi-colon, ~~also~~ initialized to 0.		float myvar; // alternate form with semi-colon, initialized to 0.
	float myvar // BAD. Parser may or may not recover from this, depending on what follows.		float myvar // BAD. Parser may or may not recover from this, depending on what follows.
	float myvar 1 // ~~BAD~~. ~~Misleading~~, because variable is still initialized to 0.
			As for the value to assign, traditional best-practice guidance is:
			* A float user variable is ALWAYS initialized to zero. Attempting to use any other number (before TDM 2.11) is often ignored and replaced by 0.
			* It must be ended in either ";" or " 0".
			* This is because, although initialization with a non-zero value was intended with Doom 3, buggy implementation made that unreliable.

			However, code refactoring in TDM 2.11 may now make non-zero initialization reliable. Too early to tell, but hopeful.

			float myvar 1 // ALLOWED IN 2.11, WITHOUT WARNING. MISLEADING BEFORE 2.11, because variable is still initialized to 0.

	===Used to Affect Properties===		===Used to Affect Properties===

Geep: float vs definefloat, vec4 vs definevec4

2022-11-15T20:31:25Z

float vs definefloat, vec4 vs definevec4

← Older revision		Revision as of 20:31, 15 November 2022
Line 11:		Line 11:

	==Float User Variable==		==Float User Variable==
	Float and definefloat variables are the same thing~~; let’s~~ refer to just "float" in what follows. Such a variable can serve as a decimal, integer, or boolean value. Boolean is the most frequent usage.		Float and definefloat variables are the same thing. Reportedly, keyword "definefloat" was designed first by id Studio, then shortened to "float". Let’s refer to just "float" in what follows. Such a variable can serve as a decimal, integer, or boolean value. Boolean is the most frequent usage.

	===Declared in Property List===		===Declared in Property List===
Line 117:		Line 117:
	DON’T try to use it to give a value to a property, e.g., in a property list:		DON’T try to use it to give a value to a property, e.g., in a property list:
	matcolor show_it // Doesn’t work no matter what form you use		matcolor show_it // Doesn’t work no matter what form you use

			As a synonym for "definevec4", keyword "vec4" is available in some other id-family games, and has been proposed for TDM 2.12. See [https://bugs.thedarkmod.com/view.php?id=6164 New features in GUI engine].

	{{GUI}}		{{GUI}}

Geep: Add category tag

2022-11-04T16:19:05Z

Add category tag

← Older revision		Revision as of 16:19, 4 November 2022
Line 117:		Line 117:
	DON’T try to use it to give a value to a property, e.g., in a property list:		DON’T try to use it to give a value to a property, e.g., in a property list:
	matcolor show_it // Doesn’t work no matter what form you use		matcolor show_it // Doesn’t work no matter what form you use

			{{GUI}}

Geep at 18:04, 3 July 2022

2022-07-03T18:04:43Z

← Older revision		Revision as of 18:04, 3 July 2022
Line 1:		Line 1:
	''This page is part of a series. See [[GUI ~~Script~~ Language]] for overview.''		''This page is part of a series. See [[GUI Scripting Language]] for overview.''

	==Introduction==		==Introduction==

Geep: create this article

2022-07-03T18:01:22Z

create this article

New page

''This page is part of a series. See [[GUI Script Language]] for overview.''

==Introduction==
Optional user variables may be defined as part of (and conventionally at the end of) a guiDef's property list. There are 3 forms:
* float ''name''
* definefloat ''name'' // same as "float ''name''". No examples of this alias found in TDM.
* definevec4 ''name'' // Not used in core. Nor was an example in a sample of FMs found.

==Scope==
A user variable is directly known only to the guiDef in which it is defined and NOT its child guiDefs. However, it can be referenced elsewhere in the file by using the appropriate "guiDef_name::" prefix.

==Float User Variable==
Float and definefloat variables are the same thing; let’s refer to just "float" in what follows. Such a variable can serve as a decimal, integer, or boolean value. Boolean is the most frequent usage.

===Declared in Property List===
When declared in a property list, a float user variable is ALWAYS initialized to zero. Syntax:
float myvar 0 // recommended form. 0 is only real value, but needed for proper parsing. Matches syntax style of properties.
float myvar; // alternate form with semi-colon, also initialized to 0.
float myvar // BAD. Parser may or may not recover from this, depending on what follows.
float myvar 1 // BAD. Misleading, because variable is still initialized to 0.

===Used to Affect Properties===
Occasionally of interest. See Example #2 below.

===Used in Event Blocks===
* Typically used within event handler if(...) statements, e.g., to transfer local state info between event handler blocks.
* Changed with "set", or less commonly, "transition".

In the main menu system, user variables are important for crouch management, e.g., of lightgem height. "float exit" is common as well, as shown in the next example.

===Menu Button Example #1===
After mission success, the "button" to bring up game statistics is styled with mouse-over glows. Once the button is pressed (triggering the onAction block), it is no longer desirable for the glow transition of the onMouseExit block to operate. User variable "exit" controls that.

windowDef statistics_select
{
MM_POS_SUCCESS_STATISTICS_BUTTON
visible 1
float exit;

onMouseEnter
{
set "exit" 0;
transition "Statistics::forecolor" SWHITE_COLOR SGLOW_WHITE_COLOR "200";
transition "StatisticsH::forecolor" SINVISIBLE SGLOW_YELLOW_COLOR "200";
set "cmd" "play sound/meta/menu/mnu_hover";
}

onMouseExit {
if ( "exit" == 0 )
{
transition "Statistics::forecolor" SGLOW_WHITE_COLOR SWHITE_COLOR "200";
transition "StatisticsH::forecolor" SGLOW_YELLOW_COLOR SINVISIBLE "200";
}
}

onAction
{
transition "Statistics::forecolor" SGLOW_WHITE_COLOR SWHITE_COLOR "200";
transition "StatisticsH::forecolor" SGLOW_YELLOW_COLOR SINVISIBLE "200";
set "exit" 1;
...
}
}

===Menu Button Example #2===
Here’s another "button", styled with a different type of mouse-over recoloring. Float user variables bgCol and fgCol (i.e., background color and foreground text color) are bound as individual but identical R, G, B values. At the outset (and ignoring the winAlpha value), the button is gray with black type. On mouse-over, the type brightens to white, reversibly. When the button is hit, the background jumps to light gray, then reverts to dark gray.

windowDef GammaResetButton {
rect 20, 168, 80, 16
backcolor "bgCol","bgCol","bgCol","GammaStandardPicture::winAlpha"
forecolor "fgCol","fgCol","fgCol","GammaStandardPicture::winAlpha"
bordersize 1
bordercolor 0.5, 0.5, 0.5, "GammaStandardPicture::winAlpha"
textalign 1

text "#str_02277" // Reset
GAMMA_FONT
textscale 0.2

noevents 1

float bgCol 0
float fgCol 0

onTime 0 {
set "bgCol" "0.3"
set "fgCol" "0"
}
onMouseEnter
{
transition "fgCol" "0" "1" "50";
}
onMouseExit
{
transition "fgCol" "1" "0" "50";
}
onAction {
transition "bgCol" "0.5" "0.3" "200";
set "cmd" "resetBrightness";
set "cmd" "resetGamma";
}
}

==DefineVec4 User Variable==
If you thought the float user variable was squirrelly, the definevec4 is even worse. Which may be why it's not used in the core. If you want to use it, here's a suggestion.

Define it in the property list with exactly this syntax:
definevec4 show_it 1,1,1,1
definevec4 hide_it 1,1,1,0

Use it only in event blocks, like so:
transition "my_image::matcolor" "$show_it" "$hide_it" "2000";

If the event block is associated with a different guiDef than where the definevec4 is defined, you can add the proper prefix, e.g.:
transition "my_image::matcolor" "$desktop::show_it" "$desktop::hide_it" "2000";

DON’T try to use it to give a value to a property, e.g., in a property list:
matcolor show_it // Doesn’t work no matter what form you use