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 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