GUI Scripting: Event Handlers
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-Clauses.
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.
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. Deployed in restart.gui, which is shown when the player dies or the mission fails, to fade the “fail skull”.
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
