GUI Scripting: Event Handlers: Difference between revisions
m Add category tag |
|||
| (3 intermediate revisions by the same user not shown) | |||
| Line 7: | Line 7: | ||
} | } | ||
For the body contents, see [[GUI Scripting: Commands]] and [[GUI Scripting: If | For the body contents, see [[GUI Scripting: Commands]] and [[GUI Scripting: If Statements]]. | ||
==Used Widely in TDM== | ==Used Widely in TDM== | ||
| Line 13: | Line 13: | ||
Fires when ''time'' in milliseconds is reached, for the specific guiDef’s timer. | Fires when ''time'' in milliseconds is reached, for the specific guiDef’s timer. | ||
===onNamedEvent ''event''=== | ===onNamedEvent ''event''=== | ||
Catches a custom event, generated by your entity’s script function (e.g., in a script object). Or catches an engine-generated event. Example: The 'overwrite save game' windowDef is implemented with a named event. For more, see [[GUI Scripting: Named Events]]. | Catches a custom event, generated by your entity’s script function (e.g., in a script object). Or catches an engine-generated event. Example: The 'overwrite save game' windowDef is implemented with a named event. For more, see [[GUI Scripting: Named Events]]. This should appear only in a top-level guiDef. | ||
===onAction=== | ===onAction=== | ||
| Line 26: | Line 26: | ||
Responds to an Escape keypress. In mainmenu_utils.gui, this does general escape key handling during briefing (text or video), debriefing, main menus, and in-game menus. | Responds to an Escape keypress. In mainmenu_utils.gui, this does general escape key handling during briefing (text or video), debriefing, main menus, and in-game menus. | ||
===onActivate=== | ===onActivate=== | ||
Runs once when gui first activated. | Runs once when gui first activated. This is a global command, meaning it should be put exclusively inside the main desktop window, says HMart in Ref 10 of [[GUI Scripting: References & Resources]]. | ||
In TDM, it appears only once, in windowDef MainMenuStartUp of mainmenu_utils.gui. This windowDef gets executed exactly once when the main menu is displayed for the first time. onActivate is used to reliably trigger initialization instead of onTime 0. This avoids a problem, indicates stgatilov: onTime 0 events can trigger before activation on engine restart, with all GUI cmds suppressed. | |||
===onEvent=== | ===onEvent=== | ||
Runs every frame. In mainmenu_settings_guisize.gui, associated with a sliderDef to change objectives text size, In tdm_hud.gui, used to catch player crouching and adjust light gem height. | Runs every frame. In mainmenu_settings_guisize.gui, associated with a sliderDef to change objectives text size, In tdm_hud.gui, used to catch player crouching and adjust light gem height. | ||
| Line 41: | Line 44: | ||
These “leftover” commands are parsed in “Windows.cpp”, but used in neither core GUIs or those of a sample of FMs. So functionality or applicability is suspect. | These “leftover” commands are parsed in “Windows.cpp”, but used in neither core GUIs or those of a sample of FMs. So functionality or applicability is suspect. | ||
* onDeactivate, onTrigger, onEnterRelease | * onDeactivate, onTrigger, onEnterRelease | ||
{{GUI}} | |||
Latest revision as of 16:20, 4 November 2022
This page is part of a series. See GUI Scripting Language for overview.
General Purpose & Syntax
Event Handlers are located within a windowDef (or any guiDef), at the end, after properties, user variables, and embedded child guiDefs. Each one fires when its condition is met, then processes its body (that is, contained commands and if-clauses) in the usual function-body order. Syntax (where [ ] = optional ):
eventHandler [eventHandlerParam] {
...
}
For the body contents, see GUI Scripting: Commands and GUI Scripting: If Statements.
Used Widely in TDM
onTime time
Fires when time in milliseconds is reached, for the specific guiDef’s timer.
onNamedEvent event
Catches a custom event, generated by your entity’s script function (e.g., in a script object). Or catches an engine-generated event. Example: The 'overwrite save game' windowDef is implemented with a named event. For more, see GUI Scripting: Named Events. This should appear only in a top-level guiDef.
onAction
Generally responses to a click of the mouse "Action" button (LMB by default). Also fires upon editDef text changes, or choiceDef pick changes.
onMouseEnter & onMouseExit
Fires respectively, upon mouse cursor entry to & exit from the guiDef’s rectangle. (May be sluggish.)
Used Sparingly
onActionRelease
Runs when the action is finished, e.g., 'left mouse button up'. Used in mainmen_loadsave.gui as part of process of loading a mission.
onEsc
Responds to an Escape keypress. In mainmenu_utils.gui, this does general escape key handling during briefing (text or video), debriefing, main menus, and in-game menus.
onActivate
Runs once when gui first activated. This is a global command, meaning it should be put exclusively inside the main desktop window, says HMart in Ref 10 of GUI Scripting: References & Resources.
In TDM, it appears only once, in windowDef MainMenuStartUp of mainmenu_utils.gui. This windowDef gets executed exactly once when the main menu is displayed for the first time. onActivate is used to reliably trigger initialization instead of onTime 0. This avoids a problem, indicates stgatilov: onTime 0 events can trigger before activation on engine restart, with all GUI cmds suppressed.
onEvent
Runs every frame. In mainmenu_settings_guisize.gui, associated with a sliderDef to change objectives text size, In tdm_hud.gui, used to catch player crouching and adjust light gem height.
onEnter
Fires if the user:
- presses Enter/Return key (e.g., in an editDef)
- double-clicks in a listDef
For example, in loadsave.gui, onEnter responds to:
- the Return key, after entering the name of the save file.
- double-clicking on the name of a previously-saved game file to load.
Evidently Unused
These “leftover” commands are parsed in “Windows.cpp”, but used in neither core GUIs or those of a sample of FMs. So functionality or applicability is suspect.
- onDeactivate, onTrigger, onEnterRelease
