Gauge API

GAUGE API

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

You can find a sample project to use as a reference when using the Gauge API here:

GaugeAircraft

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);
    // ...
    }

Note On Deprecated Functions

The schema examples given above use the modern functions for handling events, and they should work exactly the same as the deprecated functions they replace. The old functions will, for the moment, also keep working and do not require that you update them unless you are looking for the specific extra functionality that these updated functions supply, ie: multiple parameters for a single key events, which is something the legacy functions did not permit. This does not mean that you can keep using the legacy functions. They have been deprecated for a reason, and as such you should only be using the modern versions for all new projects.