GUI Scripting: Named Events

This page is part of a series. See GUI Scripting Language for overview.

The onNamedEvent Command

As mentioned in GUI Scripting: Event Handlers, a windowDef can contain:

onNamedEvent myEvent {...} // No double-quotes here around myEvent

This is a global command, meaning it should be put exclusively inside a top-level windowDef, not a child guiDef (says HMart in Ref 10).

Calling Custom Named Events from a .Script

Mappers will find this method of particular use. Call onNamedEvent myEvent from an associated .script function thusly:

void myFunction(entity me) {
...
me.callGui(1, "myEvent");  // or use "self.callGui" if function is part of script object
...
}

where the first parameter is the handle number, 1.

If you need to pass parameters, do that before callGui. See GUI Scripting: GUI:: Parameters.

Subscribing to Existing Standard Named Events

Events are as of TDM 2.10

If you are extending or over-riding standard GUIs (e.g., for the HUD, objectives, main menu system, or pop-up messages), you may be able to tie into existing named-event notifications, generated by the C++ code. Within engine code, a named event can be raised and sent just to a particular GUI:

m_gui->HandleNamedEvent(eventName);

Or, perhaps of more interest to mappers, raised and broadcast to all GUIs, e.g.:

m_overlays.broadcastNamedEvent("inventorySelectionChange");

In either case, you use the same onNamedEvent method to catch the event in your GUI.

Standard Broadcast Events

It’s relatively hard to depart from the original purpose of these events. An exception, where the key bindings associated with inventory events are re-purposed, is given in GUI Scripting: Number Wheel Example and also used for zooming the spyglass.

The broadcast events - all raised in Player.cpp - are as follows:

Body Shouldering

• OnStartShoulderingBody
• OnStopShoulderingBody

Weapons

• nextWeapon
• prevWeapon

Inventory

• inventoryPrevItem
• inventoryNextItem
• inventoryPrevGroup
• inventoryNextGroup
• inventoryDropItem
• inventoryUseItem
• inventorySelectionChange

The inventoryUseItem event is also involved in setting up the closure of a readable.

Also, if you try to use an inventory item, it will give positive (green glow) or negative (red glow) visual feedback whether that is possible, and raise one of these events:

• onInvPositiveFeedback
• onInvNegativeFeedback

Spyglass and Peek Overlays

Both the spyglass and peek system (through keyholes or cracks) have multiple overlays, for different screen aspect ratios.

• initBackground_4x3 // format 0
• initBackground_16x9 // format 1 or 4
• initBackground_16x10 // format 2
• initBackground_5x4 // format 3
• initBackground_21x9 // format 5

Other Standard Events, Sent to Particular Core System GUIs

Listed by GUI. Includes broadcast events mentioned above.

"MainMenu" GUIs

• mainmenu_briefing_video.gui: CinematicEnd, LoadVideoDefinitions, OnBriefingVideoPartChanged, OnBriefingVideoFinished, LoadVideoDefinitions
• mainmenu_debriefing_video.gui: CinematicEnd, LoadVideoDefinitions, OnDebriefingVideoPartChanged, OnDebriefingVideoFinished, LoadDebriefingVideoDefinitions
• mainmenu_download.gui: QueueDownloadableMissionListRefresh, onStartDownloadingNextScreenshot, onStartFadeToNextScreenshot, onFailedToDownloadScreenshot, onDownloadableMissionDetailsLoaded, onDownloadableMissionDetailsDownloadFailed, onAvailableMissionsRefreshed
• mainmenu_loadsave.gui: saveGameOverwrite
• mainmenu_message.gui: OnGameError
• mainmenu_music.gui: OnMenuMusicSettingChanged
• mainmenu_newgame.gui: OnModInstallationFinished, OnModInstallationFailed, OnModUninstallFinished, OnRequiredVersionCheckFail, OnNewMissionsFound, onMissionDetailsLoaded
• mainmenu_objectives.gui: GetObjectivesInfo, ObjMenuShowDifficultyOptions, ObjMenuHideDifficultyOptions, UpdateObjective1 ... UpdateObjective9
• mainmenu_settings_gameplay.gui: UpdateAutoParryOption
• mainmenu_shop.gui: SkipShop, UpdateItemColours
• mainmenu_success.gui: SuccessProceedToNextMission, SuccessGoBackToMainMenu
• mainmenu_utils.gui: ShowPostMissionScreen, HideSuccessScreen

Other Core GUIs

• msg.gui: Prompt
• numberwheel_handler.gui: prevWeapon, nextWeapon, inventoryPrevItem, inventoryNextItem, inventoryPrevGroup, inventoryNextGroup. See also GUI Scripting: Number Wheel Example
• tdm_crack.gui: initBackground_4x3, initBackground_5x4, initBackground_16x9, initBackground_16x10
• tdm_hud.gui: updateArmorHealthAir, OnStartShoulderingBody, OnStopShoulderingBody, DisplayMessage, SetupMessageSystem
• tdm_inv.gui: onInventoryCategoryChanged, onInvNegativeFeedback, onInvPositiveFeedback, DisplayInventoryPickUpMessage, SetupInventoryPickUpMessageSystem, OnStartShoulderingBody, OnStopShoulderingBody
• tdm_invgrid.gui; tdm_invgrid_brown.gui; tdm_invgrid_parchment.gui : InitInventoryGridGUI, prevWeapon, nextWeapon, inventoryPrevGroup, inventoryNextGroup, inventoryPrevItem, inventoryNextItem, clearGrid
• tdm_keyhole.gui: initBackground_4x3, initBackground_5x4, initBackground_16x9, initBackground_16x10, initBackground_21x9
• tdm_lockpick.gui: OnLockPickProcess, OnAttackButtonPress, onInventoryCategoryChanged, onInvNegativeFeedback, onInvPositiveFeedback
• tdm_objectives_core.gui:, GetObjectivesInfo, InitObjectivesGUI, prevWeapon, nextWeapon, inventoryPrevGroup, inventoryPrevItem, inventoryNextGroup:, inventoryNextItem, UpdateObjective1 ... UpdateObjective9
• map\loading.gui: loadBackground_4x3, loadBackground_5x4, loadBackground_16x9, loadBackground_16x9tv, loadBackground_16x10, loadBackground_21x9
• playertools\flashbomb.gui: doFullblind, doHalfblind
• playertools\spyglass.gui: initBackground_4x3, initBackground_5x4, initBackground_16x9, initBackground_16x10, prevWeapon, nextWeapon, inventoryPrevItem, inventoryNextItem, inventoryPrevGroup, inventoryNextGroup, inventorySelectionChange

• prologue.gui; tdm_message.gui; tdm_message_no_art.gui; tdm_message_no_art_secret.gui: doFadeOut