Gauge API

GAUGE API

IMPORTANT! This API has been deprecated with the release of Microsoft Flight Simulator 2024, because it came from FSX and is not compatible anymore with the new engine architecture of the simulation. This API still works for backward compatibility reasons but you should strive to replace any calls to it using the Event API and Vars API, which provide the same features as the legacy Gauge API but in a way more compatible with the current simualtion architecture.

While the Microsoft Flight Simulator 2020 SDK doesn't currently support the old "Gauge Macros" that were available in previous versions of the simulator, it still offers certain Gauge functions. These are all listed below and you can click on the links to get more information about each of them.

It is worth noting that a lot of these functions relate to the use of Token Variables, which are explained on the following page:

Token Variables

Function	Description
`aircraft_varget`	Retrieves the value of an aircraft simulation variable. Deprecated. Use `fsVarsAircraftVarGet` instead.
`get_aircraft_var_enum`	Retrieves the enum value for a simulation variable, given the string name of that variable. Deprecated. Use `fsVarsGetAircraftVarId` instead.
`get_units_enum`	Retrieves the enum value for units, given the string name of the units. Deprecated. Use `fsVarsGetUnitId` instead.
`format_calculator_string`	Evaluates a formatted calculator string. Deprecated.
`execute_calculator_code`	Evaluates a coded calculator string. Deprecated.
`gauge_calculator_code_precompile`	Compresses a calculator string into a more efficient internal format. Deprecated.
`initialize_var`	Initializes a token variable. Deprecated.
`initialize_var_by_name`	Initializes a `MODULE_VAR` structure, given the name of a token variable. Deprecated.
`lookup_var`	Updates the contents of a token variable. Deprecated.
`check_named_variable`	Retrieves the ID number of a named local variable, if it exists. Deprecated. Use `fsVarsGetRegisteredNamedVarId` instead.
`register_named_variable`	Registers a local variable name. Deprecated. Use `fsVarsRegisterNamedVar` instead.
`register_var_by_name`	Registers a variable from another gauge, for use by this gauge. Deprecated. Use `fsVarsGetRegisteredNamedVarId` instead.
`get_name_of_named_variable`	Retrieves the name of a local variable, given an ID number. Deprecated.
`get_named_variable_typed_value`	Retrieves the value of a named local variable, in the specified units. Deprecated. Use `fsVarsNamedVarGet` instead.
`get_named_variable_value`	Retrieves the value of a local variable, given an ID. Deprecated. Use `fsVarsNamedVarGet` instead.
`get_gauge_flags`	Used to retrieve the flags set on a gauge. Deprecated.
`set_named_variable_typed_value`	Specifies a local variable should be set to the given value with the given units. Deprecated. Use `fsVarsNamedVarSet` instead.
`set_named_variable_value`	Sets a local variable to a given value. Deprecated. Use `fsVarsNamedVarSet` instead.
`set_gauge_flags`	Specifies the flags for a gauge. Deprecated.
`unregister_var_by_name`	Unregisters a named variable from another gauge, and frees up the memory used. Deprecated.
`unregister_all_named_vars`	Unregisters all token variables, and frees up the memory used. Deprecated.
`register_key_event_handler_EX1`	Registers a key event callback function. Deprecated. Use `fsEventsRegisterKeyEventHandler` instead.
`unregister_key_event_handler_EX1`	Unregisters the key event handler. Deprecated. Use `fsEventsUnregisterKeyEventHandler` instead.
`trigger_key_event_EX1`	Initiates the action of a key event. Deprecated. Use `fsEventsTriggerKeyEvent` instead.
`register_key_event_handler`	Registers a key event callback function. Deprecated. Use `fsEventsRegisterKeyEventHandler` instead.
`send_key_event`	Transmits a `WM_COMMAND` application event. Deprecated. Use `fsEventsTriggerKeyEvent` instead.
`trigger_key_event`	Initiates the action of a key event. Deprecated. Use `fsEventsTriggerKeyEvent` instead.
`unregister_key_event_handler`	Unregisters the key event handler. Deprecated. Use `fsEventsUnregisterKeyEventHandler` instead.

Triggering Key Events

An important part of the Gauge API is the ability to trigger any of the available Key Events. This is done using the trigger_key_event_EX1 function, however it requires a certain amount of setup for it to work correctly. The general schema for using key events is as follows:

First, a key event handler must be registered using the function register_key_event_handler_EX1 (you can have various handlers if you require them).
```
void EventHandler(ID32 event, UINT32 evdata0, UINT32 evdata1, UINT32 evdata2, UINT32 evdata3, UINT32 evdata4, PVOID userdata)
    {
        // ...
    }
void foo(...)
    {
    // ...
    register_key_event_handler_EX1((GAUGE_KEY_EVENT_HANDLER_EX1)&EventHandler, NULL);
    // ...
    }
```
It is important to note that the GAUGE_KEY_EVENT_HANDLER_EX1 handler will receive events triggered by the legacy functions as well as their modern replacements, while the deprecated GAUGE_KEY_EVENT_HANDLER handler will only receive events triggered by legacy functions. Therefor you should ensure that you are always using the modern handler, especially if using key events that require more than one input parameter.
Key events can then be triggered using trigger_key_event_EX1:
```
void bar(...)
    {
    // ...
    trigger_key_event_EX1(KEY_ALTERNATOR_SET, 18);
    // ...
    }
```
When calling the key event, note that there is no need to supply all the available parameters. If the event requires two parameters you supply two, if it requires four you supply four, etc... up to a maximum of five parameters.

Finally, you would then unregister the key using unregister_key_event_handler_EX1:

void baz(...)
    {
    // ...
    unregister_key_event_handler_EX1((GAUGE_KEY_EVENT_HANDLER_EX1)&EventHandler, NULL);
    // ...
    }