XML: Events and Traps

EVENT: An Event is a user-initiated instruction to execute a certain Flight Sim (FS) function. Examples include control surface movement, radio tuning, landing gear retraction/extension, throttle movement, etc. Events are initiated via joystick or other controller, keyboard, mouse, or gauge software. Initiating an event from within one’s gauge software is often referred to as “throwing”, “firing” or “triggering” an event.

From within XML gauge script, an event is triggered using (>K:EVENT) or <Click Event="EVENT"/> instructions. Examples:

(>K:MIXTURE_RICH) 

instructs FS to set all mixture levers to maximum rich. This event does not require a number, or argument, to be passed to it. It’s just (>K:MIXTURE_RICH). The majority of events require no argument.

8100 (>K:MIXTURE_SET) 

instructs FS to set mixture levers to 8100, or about mid range. This is an example of an event that requires an argument. The SDK has the complete list in the Events ID section of the online Microsoft ESP SDK (FSX).

Almost all events have related read-only simulation variables (A:Variables) that change in response to the event’s execution. The simulation variable

(A:GENERAL ENG MIXTURE LEVER POSITION:index, percent) 

is associated with the MIXTURE_SET event. If 8100 is passed to MIXTURE_SET, then the A:Var will return 49.44.

8100/16383 = 49.44. As per SDK, 16383 is the maximum value allowed for MIXTURE_SET. Its range is 0 to 16383 **.

Events are single and discrete. Even the smooth increase of the throttle on a game controller is sampled as a series of singular THROTTLE_INCR_SMALL events.

Event expressions don’t contain Units.

EVENT TRAP: An Event Trap is gauge code that ‘listens’ for specified events to be triggered. Its purpose is to allow customized, user-defined script to also be executed with the specified event. By nature, it’s conditional: if Event A is triggered, then process the event trap script and then execute the event.

In XML, the trap is defined using an <On Event> block placed within a <Keys> block:

<Keys>
   <On Event="LANDING_LIGHTS_TOGGLE">
     1 (>L:Sound_Click,number)
   </On>
</Keys>

The event is LANDING_LIGHTS_TOGGLE. The event trap routine is 1 (>L:Sound_Click,number).

<On Event> blocks should be placed at the bottom of the gauge script in order to catch all events triggered during each gauge update cycle.

EVENT PROCESSING AND XML SCRIPT: All events that are triggered in the current gauge update cycle are queued and then executed sequentially along with their trap routines, if any exist, at the end of the cycle. All simulation variables (A:Vars) affected by the executed events return updated values on the subsequent cycle.

Event Traps across the Gauge Set: FS processes <On Event> trap routines found in all gauges of the aircraft’s panel (the ‘gauge set’) before coming back to the point where the original event was processed – at the end of the update cycle in the gauge that triggered the event.

So, if Gauge00 contains the following:

<Keys>
  <On Event="PITOT_HEAT_ON">
    (L:MyVarA,enum) 10 + (>L:MyVarA,enum)
  </On>  
</Keys>

and Gauge01 contains:

<Keys>
  <On Event="PITOT_HEAT_ON">
    (L:MyVarA,enum) 20 + (>L:MyVarA,enum)
  </On>  
</Keys>

Then, on the update cycle of the triggering gauge following the PITOT_HEAT_ON event trigger, (L:MyVarA, enum) will return 30.

A condition is that gauges must be in a visible window for their trap routines to be processed. If a gauge is part of a window whose visibility is set to visibility=0, then no <On Event> routines in that gauge will be run until visibility of the window is set to 1, or if the window is visible on the screen.

Another important condition is that event trap routines in XML gauges are disabled when the user is in External view. Code-fired events still work fine, but their <On Event> capture sections will not. This is a problem for those who like to manage systems (i.e. the autopilot) via keystrokes while flying in External view.