Programming C++ Gauges

Overview

The recommended method of creating gauges is to use the XML based system, refer to the document, Creating XML gauges. However, if the flexibility of this system does not meet your requirements, gauges can be created programmatically using C++. This document describes a number of samples that show how to do this.

Note

Gauges.h has been updated for the release of the Flight Simulator X SDK. To use the samples and updated header file, C++, rather than C, must be used as the development language. There is also an additional sample that shows how to link an XML gauge with C++ code (see the section Creating a Gauge using XML and C++).

See Also

• SDK Overview
• Creating XML Gauges
• HelpIDs
• Panel Configuration Files
• Tooltips
• Token Variables

Table of Contents

• Sample Code for C++ Gauges
• Tutorial: Creating a C++ Gauge File
• Step 1: Defining Variables and Resources
• Step 2: Setting up the Gauge Header
• Step 3: Simulating System Failures
• Step 4: Using the Gauge Macros
• Step 5: Making the Background Image
• Step 6: Defining Mouse Rectangles
• Step 7: Compiling and Using Your Gauges
• C++ Gauge Reference
• Using Token Variables
• Accessing Token Variables
• Gauge Macros and Drawing Elements
• Shared Data Elements
• Drawing Element Header
• Drawing Element Structures
• Gauge Macros
• Drawing Element Macros
• String Element Macros
• Draw Flags
• Aircraft Special Instrumentation
• Custom Events
• C++ Gauge Function Reference
• Creating a Gauge using XML and C++
• Running the Cabin Comfort sample
• Key steps in creating the Cabin Comfort sample

Sample Code for C++ Gauges

This SDK includes source code for several sample gauges, along with their associated resources. Use these samples to learn how to build gauges and feel free to modify them in creating your own gauges and panels. The following table shows the samples provided and a brief description.

Tutorial: Creating a C++ Gauge File

The goal of the sample is to create a file called SDK.gau. This is a gauge file for use by the panel system. A gauge file is a Windows DLL with the extension .gau, which is loaded by the panel system. A gauge file can contain one or more individual gauges within the panel. The panel system interacts with each gauge using the exported interface defined by the gauge header file (Gauges.h). The interface used by a gauge consists of a list of drawing elements and the exported functions used to manage the gauge. All .gau files reside within the Gauges folder. When compiled, the sample code generates a single SDK.gau containing six different gauges, each illustrating a different type.

Step 1: Defining Variables and Resources

Your gauges will need access to various resources and variables to function properly. The sample code provided with this SDK accomplishes these key definitions in three files (found in the \C-Gauge Samples folder):
SDK.h
SDK.cpp
SDK.rc
Make sure to go through the following sections carefully because they describe what’s happening within each file. Read through the sources as you go through this information as well.

SDK.h: Defining Gauge Resources

When you open SDK.h you’ll first see a series of #define directives that set version information as well as some constants within the C++ preprocessor.


#define         VERSION_MAJOR           1
#define         VERSION_MINOR           0
#define         VERSION_BUILD           0
// magic to get the preprocessor to do what we want
#define     lita(arg) #arg
#define     xlita(arg) lita(arg)
#define     cat3(w,x,z) w##.##x##.##z##\000
#define     xcat3(w,x,z) cat3(w,x,z)
#define     VERSION_STRING xlita(xcat3 (VERSION_MAJOR,VERSION_MINOR,VERSION_BUILD))
#ifndef           VS_VERSION_INFO
#define           VS_VERSION_INFO         0x0001
#endif

Depending on which C++ compiler you are using, you may need to tweak the preprocessor information somewhat, but otherwise, you won’t need to modify the #define directives. The primary task you’ll need to accomplish inside SDK.h is to define the various resources (bitmaps) used by all the gauges you are building into the target .gau file. The following code fragment defines the constants used for resources (i.e., the resource_id) associated with the Attitude Indicator sample (SDK.attitude.cpp):


// Attitude Bitmaps
//
#define           BMP_ATTITUDE_SMALL_BACKGROUND       0x1000
#define           BMP_ATTITUDE_SMALL_CARD1            0x1100
#define           BMP_ATTITUDE_SMALL_MASK1            0x1101
#define           BMP_ATTITUDE_SMALL_CARD2            0x1200
#define           BMP_ATTITUDE_SMALL_MASK2            0x1201

The actual linking of these constants to specific .bmp files happens in SDK.rc as described later in this document. There are some rules associated with setting these constants:

• You can identify lower-resolution and higher-resolution bitmaps by incrementing the hex value by 500. For example, you could set your defines for two different resolutions as follows:

• Bitmaps that you intend to apply as masks over other bitmaps should increment by 1 as in this example.

The sample SDK.h provided defines constant values for all the bitmap resources used by the sample gauge files.

SDK.rc: Associating Resource IDs with .bmp Files

The sample resource file associates the resource_id for all the resources in all the gauges with the corresponding .bmp file. First, note that the SDK.rc file contains an include directive for SDK.h near the top:

#include “sdk.h”

You’ll need to adjust this for whatever you name your gauge header file. Just below this, you’ll find more versioning information, along with a block entitled “StringFileInfo” as shown below:

In the string values for “CompanyName”, “FileDescription”, “LegalCopyright”, and “ProductName” replace the placeholder text with information appropriate for you. This information will appear whenever anyone checks the properties for the .gau file you create. The next section is where each resource_id defined in SDK.h gets associated with the appropriate .bmp file:


// Attitude Bitmaps
//
BMP_ATTITUDE_SMALL_BACKGROUND BITMAP      DISCARDABLE       "res\\SDK.Attitude.bg.BMP"
BMP_ATTITUDE_SMALL_CARD1      BITMAP      DISCARDABLE       "res\\SDK.Attitude.card1.BMP"
BMP_ATTITUDE_SMALL_MASK1      BITMAP      DISCARDABLE       "res\\SDK.Attitude.mask1.BMP"
BMP_ATTITUDE_SMALL_CARD2      BITMAP      DISCARDABLE       "res\\SDK.Attitude.card2.BMP"
BMP_ATTITUDE_SMALL_MASK2      BITMAP      DISCARDABLE       "res\\SDK.Attitude.mask2.BMP"

You’ll need to create similar resource_id assignments for all resource files used by your gauges.

SDK.cpp: Naming and Positioning Gauges, Including Source Files, and Exporting Pointers for Gauges

The SDK.cpp file included with this SDK enables you to manage the various gauges from a single file while still separating the individual gauge source files for easier maintenance. You don’t necessarily have to create a corresponding SDK.cpp file for your gauges, but there are some specific things you need to do within your gauge code as explained below. First, notice that SDK.cpp has #include statements for both Gauges.h and SDK.h. Make sure you include Gauges.h and SDK.h in your gauge code as well. SDK.cpp then breaks out into sections for each individual gauge, finishing up with a series of gauge table entries. Each individual gauge section contains the following coding:


/////////////////////////////////////////////////////////////////////////////
// Attitude
/////////////////////////////////////////////////////////////////////////////
#define           GAUGE_NAME        "Attitude"
#define           GAUGEHDR_VAR_NAME gaugehdr_attitude
#define           GAUGE_W                 100

#include "SDK.Attitude.cpp"
/////////////////////////////////////////////////////////////////////////////
// Control Surfaces
/////////////////////////////////////////////////////////////////////////////
#define           GAUGE_NAME        "Control_Surfaces"
#define           GAUGEHDR_VAR_NAME gaugehdr_control_surfaces
#define           GAUGE_W                 100

#include "SDK.Control_Surfaces.cpp"
/////////////////////////////////////////////////////////////////////////////
// Fuel
/////////////////////////////////////////////////////////////////////////////
#define           GAUGE_NAME        "Fuel"
#define           GAUGEHDR_VAR_NAME gaugehdr_fuel
#define           GAUGE_W                 100

#include "SDK.Fuel.cpp"

This code is then repeated for the remaining gauges. Here’s what’s happening with each assignment: GAUGE_NAME is assigned the string that becomes the gauge’s name. This gauge name is used in the Panel.cfg file under the [windowXX] section where each gauge is defined. For the fragment above, panel.cfg would identify these gauges as:


gauge00=SDK!Attitude, 247, 58
gauge01=SDK!Control_Surfaces, 370, 160
gauge02=SDK!Fuel, 146, 57

GAUGEHDR_VAR_NAME is assigned the gauge name used by the Gauge Table (the module’s export table). The Gauge Table gets defined at the end of SDK.cpp. GAUGE_W is assigned a value for the number of X-axis design units used by the gauge. Note that the units used by the gauge correspond to the units used by the panel background. For example, if your panel is 1000 units and a gauge is 100 units, then that gauge will be 1/10 the size of the panel. (You can override this ratio in the Panel.cfg file.)

#include “SDK_xxx.cpp” simply includes the specific gauge code file for each gauge in the compilation.

This code repeats for each gauge within SDK.cpp. Accordingly, each of the gauge code files (SDK_xxx.cpp) ends with #undef for GAUGE_NAME, GAUGEHDR_VAR_NAME, and GAUGE_W so they’re ready to reset with new values for the next gauge.

Finally, at the end of SDK.cpp, the Gauge Table assignments are made. The Gauge Table in the sample file looks like this:

You’ll need a GAUGE_TABLE_ENTRY for each gauge identified by GAUGEHDR_VAR_NAME, so the gauge table can export a pointer. These names must match as shown in the sample code.

The Sample Gauges

Now that we’ve covered some of the basic constant and variable assignments for gauges, we’ll move on to code for the sample gauges. This SDK includes sample code for the following gauges.

All of these files contain static image examples. The following sections describe the basic calls made within a gauge source file, pointing out the individual distinctions for each gauge type.

Step 2: Setting up the Gauge Header

At the beginning of each sample gauge source file, you’ll see a code fragment like this:


//    Set up gauge header

char attitude_gauge_name[]    = GAUGE_NAME;
extern PELEMENT_HEADER        attitude_list;
extern MOUSERECT        attitude_mouse_rect[];

First, the code assigns values for the following variables used by the gauge header:

Then the code fills in values for GAUGE_HEADER_FS700, the gauge header macro. The gauge header is a structure that defines the interface used by the panel system to control the gauge DLL. You must export the gauge header to expose the gauge interface to the panel system.

GAUGE_HEADER_FS700

Use the GAUGE_HEADER_FS700 macro to create and export the gauge header (GAUGEHDR). The GAUGE_HEADER_FS700 macro creates GAUGEHDR, filling in the unique members of the GAUGEHDR structure (see the full definition of this structure in gauges.h).

The following example shows how to use the GAUGE_HEADER_FS700 macro in code:


GAUGE_HEADER_FS700(GAUGE_W, attitude_gauge_name, &attitude_list, attitude_mouse_rect, 0, 0, 0, 0);


Here’s the syntax for the GAUGE_HEADER_FS700 macro:

The GAUGE_HEADER_FS700 macro has these members:

The GAUGE_HEADER_FS700 macro creates the GAUGEHDR structure and an exported variable, gauge_header. The panel system uses the gauge_header variable to initialize each of the drawing elements. Most of the Panel API functions use gauge_header as one parameter to be passed. You will use this variable often.

Step 3: Simulating System Failures

Several types of aircraft system failures can be simulated. Almost all of the sample gauge source files contain code that illustrates how to set up a simulated system failure.

FAILURE_RECORD

You’ll use the FAILURE_RECORD structure to identify the systems that—should they fail—would need to be reflected by the gauge. The structure inside Gauges.h looks like this:


typedef     struct      FAILURE_RECORD
{
      FAILURE_KEY       key;
      FAILURE_ACTION    action;
      PVOID             reserved;
}
FAILURE_RECORD, *PFAILURE_RECORD, **PPFAILURE_RECORD;

The following code illustrates how you can build FAILURE_RECORD for a Fuel gauge:

This code creates a FAILURE_RECORD called fuel_fail. Each FAILURE_KEY enum value identifies the system undergoing failure; its associated FAILURE_ACTION identifies what happens in the event of that failure. The final FAILURE_KEY and FAILURE_ACTION pair is always FAIL_NONE, FAIL_ACTION_NONE. The failure record can contain any number of failure keys and actions.

FAILURE_KEY

System failures are listed in the FAILURE_KEY enum values defined in gauges.h, and described below:

FAILURE_ACTION

You can set up a gauge element to react to one or more of the system failures shown in the FAILURE_RECORD by using one of the defined FAILURE_ACTION enum values:

Step 4: Using the Gauge Macros

Moving a little further down in the sources for the various sample gauges, you’ll see different macros being used to pass parameters between the gauge and the panel system. These macros are defined in Gauges.h, and you can use them to create various types of gauges. Let’s continue through the code to where macros first start appearing—we’ll look specifically at the sliders example and then cover all the gauge macros in detail later on.

Sliders Example

The SDK.control_surfaces.cpp example shows how to build a gauge using sliders that move over a static image in the background. The code that follows uses the bitmaps listed in the table below as resources:

To create a slider use the MAKE_SLIDER macro:


#define     MAKE_SLIDER(      NAME,                         \
                              RES_ID,                       \
                              NEXT_LIST,                    \
                              FAILURE,                      \
                              DRAW_FLAGS,                   \
                              ASI_FLAGS,                    \
                              POSITION_X, POSITION_Y,       \
                              SOURCE_VAR_X, CALLBACK_X, SCALE_X,  \
                              SOURCE_VAR_Y, CALLBACK_Y, SCALE_Y )

Fill the structure out with slider-specific information, such as the following from SDK.Control_Surfaces.cpp:

MAKE_SLIDER
(
      cs_slider_trim,
      BMP_CS_SMALL_TRIM,
      NULL,
      0,
      IMAGE_USE_ERASE | IMAGE_USE_TRANSPARENCY,
      0,
      20,44,
      MODULE_VAR_NONE, NULL, 0,
      ELEVATOR_TRIM, NULL, -100
)

Refer to the MAKE_SLIDER macro for an explanation of each of these properties. The code in SDK.control_surfaces.cpp contains four separate MAKE_SLIDER macros, one for each of the different sliders used.

PELEMENT_HEADER

After the final MAKE_SLIDER macro has been defined, you’ll see the following code:


PELEMENT_HEADER         cs_sliders_list[] =
{
      &cs_slider_trim.header,
      &cs_slider_ailerons.header,
      &cs_slider_elevator.header,
      &cs_slider_rudder.header,
      NULL
};

This PELEMENT_HEADER code signals the end of the series of macros and sets the order in which these different parts of the gauge appear. The display order goes from top to bottom. This works very well here since the various sliders do not overlap one another. Note that every macro you define must have an associated PELEMENT_HEADER somewhere, and it must end with a NULL. The specific code fragment above sets the order for all sliders simultaneously. In cases where sliders or other resources overlap, you could instead break these out separately. For example:

Note that the NEXT LIST parameter for the second slider references &cs_sliders_list1, &cs_sliders_list2, and so forth, indicating the links between each MAKE_SLIDER instance.

Step 5: Making the Background Image

To set the background image for the gauge, use the MAKE_STATIC macro. You will always use this macro with every gauge you create. First, here’s the background resource used by Control_surfaces.cpp:

You’ll create the static background image with the MAKE_STATIC macro. As an example, here’s the macro structure from Gauges.h:


#define     MAKE_STATIC(      NAME,                   \
                              RES_ID,                 \
                              NEXT_LIST,              \
                              FAILURE,                \
                              DRAW_FLAGS,             \
                              ASI_FLAGS,              \
                              POSITION_X, POSITION_Y )\

And here’s the code fragment from Control_surfaces.cpp that uses MAKE_STATIC:

Refer to the MAKE_STATIC reference for descriptions of each field.

Finally, the PELEMENT_HEADER for the macro gets set to identify this image as the gauge background:


PELEMENT_HEADER         cs_list     = &cs_background.header;

If you look back near the top of the code, you’ll see:


EXTERN PELEMENT_HEADER cs_list;

Here, the initial assignment of cs_list identifies this specific macro with the background image for the gauge. We’re pretty much nearing the end of our sample code inside the Control_surfaces.cpp file. Let’s wrap up with a discussion of how to tell the mouse the gauge exists.

Step 6: Defining Mouse Rectangles

By using mouse rectangles, you can specify how a gauge will interact with the mouse pointer (i.e., mouse movement and mouse button clicks). For example, you can change the cursor or display a ToolTip as the mouse enters the area you've defined as a mouse rectangle; you can also trigger a simulation event or execute a callback function. Note that the mouse rectangle you define is specific to the gauge itself—it works off the gauge coordinates, not the panel background coordinates. This allows you to move the gauge around the panel, while keeping the mouse rectangle intact.

To define a mouse rectangle, you use a combination of the mouse definition macros, as shown in the following code example from the SDK.control_surfaces.cpp file:

MOUSE_BEGIN, MOUSE_PARENT, and MOUSE_END are all macros you can use when defining mouse rectangles. You should look inside the Gauges.h file to get a detailed understanding of how these macros are defined. MOUSE_BEGIN uses the following parameters.

MOUSE_END ends the definition of the rectangle. You can also create rectangles within rectangles by using the capabilities of MOUSE_PARENT_* and MOUSE_CHILD_*.

Rectangles within Rectangles

You can also define sub-rectangles within the gauge rectangle using the MOUSE_PARENT and MOUSE_PARENT_BEGIN macros. Both of these macros use the following parameters.

The only difference between MOUSE_PARENT and MOUSE_PARENT_BEGIN is that MOUSE_PARENT includes both MOUSE_PARENT_BEGIN and MOUSE_PARENT_END.

Generating Events

The MOUSE_CHILD_EVENT macro defines a sub-rectangle of the rectangle created by MOUSE_PARENT_BEGIN. Using this macro, you can generate panel system events (such as KEY_SMOKE_TOGGLE, which toggles the smoke system ON/OFF) from a mouse rectangle. This macro uses the following syntax:


MOUSE_CHILD_EVENT(x, y, w, h, cursor, mouse_flags, event_id)

MOUSE_CHILD_EVENT uses the following parameters.

The following is an example of mouse rectangle setup code that generates the KEY_FLAPS_DECR and KEY_FLAPS_INCR events:

Using Callback Functions

You can use the MOUSE_CHILD_FUNCT macro to specify a callback function when an event specified by the mouse_flags parameter is triggered. You will need to define the callback function with the mouse_child_funct function. The trigger_key_event and panel_window_toggle functions are often used in the mouse event callback functions. For information on all the functions available, refer to the C++ Gauges Function Reference section. The syntax for MOUSE_CHILD_FUNCT is as follows:


MOUSE_CHILD_FUNCT(x, y, w, h, cursor, mouse_flags, function)

MOUSE_CHILD_FUNCT uses the following parameters:

Here’s a code snippet showing how you would use the MOUSE_CHILD_FUNCT macro to designate a callback function:

Creating Dynamic Mouse ToolTips

The SDK.FlightMap.cpp file contains the following code example of how you can use dynamic ToolTips (that is, ToolTips where the text changes depending on the state of the gauge):

The first argument in MOUSE_TOOLTIP_TEXT_STRING above is the ToolTip text. Note that changeable parts of the ToolTip text are specified by constructs such as “%1!d!”. These constructs always start with a percent sign (“%”), followed by the argument number (in the arguments array, GPS_Args). The argument number starts at 1 and increases sequentially. This argument number is followed by a formatting argument. The formatting argument is placed between exclamation marks (“!”), for example, !d!. This formatting argument is similar to the arguments of the printf function (from the C Standard Library), where “d” (in the formatting argument) prints an integer and “f” (in printf) prints a floating point number. GPS_Args, in the code example above, is the name of the argument’s array. The code below, taken from the sample file, illustrates how this array is defined.


MOUSE_TOOLTIP_ARGS (GPS_Args)
      MOUSE_TOOLTIP_ARG (MODULE_VAR_NONE, 0, NULL, NULL, NULL, GPSARG_Get_GroundSpeed, NULL, NULL)
      MOUSE_TOOLTIP_ARG (MODULE_VAR_NONE, 0, NULL, NULL, NULL, GPSARG_Get_Track, NULL, NULL)
      MOUSE_TOOLTIP_ARG (MODULE_VAR_NONE, 0, NULL, NULL, NULL, NULL, NULL, GPSARG_Get_WP_ID)
      MOUSE_TOOLTIP_ARG (MODULE_VAR_NONE, 0, NULL, NULL, NULL, GPSARG_Get_WP_Distance, NULL, NULL)
MOUSE_TOOLTIP_ARGS_END

Arguments in the MOUSE_TOOLTIP_ARG macro follow this order:

• First, the MODULE_VAR enum, which defines a module variable from which to get the value.
• Second, a scaling number which can be applied to the value of the module variable.
• Next, pointers to three different lookup tables. If you don’t want to use them, just use NULL pointers. The three tables are for numbers, ids and strings.
• Finally, the pointers to three callback functions, to use with numbers, ids and strings, respectively.

All functions have the same argument but have a return result of different types. The arguments are:

• The numeric value of the module variable after scaling and lookup in the numeric lookup table.
• The id, which is the value from the id lookup table.
• A string pointer, from the string lookup table.
• The pointer to the MODULE_VAR structure initialized to the first argument of the MOUSE_TOOLTIP_ARG macro.
• The pointer to the gauge header.

These functions can return: a numeric value, used together with numeric formats “d” or “f”; the id value used as a HELPID enum; or a string value used with “s” format. For details, see the SDK.FlightMap.cpp example.

Step 7: Compiling and Using Your Gauges

Once you’ve finished defining the mouse rectangles for your gauges, you can compile the files and start the process of testing, debugging, and rebuilding—until you wind up with gauges you’re happy with. You can create gauges using the Visual C++ compiler, version 4.0 or later. The process used for compiling gauges with other compilers should be similar. To compile and view your new gauges, complete these steps:

• If you are using Visual Studio, load and run the SDKSample project. This will create a file sdk.dll. Rename this sdk.gau. If you are using the command line, change to the sample directory (\sample) and type nmake. This will build the Sdk.gau file.
• Copy Sdk.gau to your \Flight Simulator X\Gauges directory.
• Make sure you have the Panel.cfg file properly set up with the gauges positioned where you want them.
• Make sure you have your aircraft container system properly configured (pointing to the right .air file, panel folder, and so on).
• Start Flight Simulator X, load your aircraft, and check out your new panel.

C++ Gauge Reference

• Using Token Variables
• Accessing Token Variables
• Gauge Macros and Drawing Elements
• Shared Data Elements
• Drawing Element Header
• Drawing Element Structures
• Gauge Macro Reference

Using Token Variables

Gauges have access to information about the simulation state. You can access state information through a set of token variables. The state information provided to the token variables depends on the aircraft’s .air file. Each .air file provides access to different token variables. For example, the Cessna 182 provides access to GROUND_ALTITUDE, as does every other aircraft. The Cessna 182, however, doesn’t provide access to the TURB_ENGINE_1_VIBRATION variable because the Cessna 182’s .air file specifies that this aircraft has a reciprocating engine, not a turbine engine. Therefore, it’s important to make sure that the .air file you’re using for your aircraft and gauges supports the token variables those gauges require.

UNIVERSAL_VAR Types

Each token variable returns a specific type of data. The following structure shows how the UNIVERSAL_VAR variable is defined and the types that could be returned:


typedef union UNIVERSAL_VAR {
    FLOAT64 n; // any number.
    BOOL b; // any boolean
    ENUM e; // any enumerated value
    FLAGS f;// any flags field
    PVOID p;// any pointer
    VAR32 d;// any binary coded decimal
    VAR32 o;// any binary coded octal
} UNIVERSAL_VAR, *PUNIVERSAL_VAR, **PPUNIVERSAL_VAR;

The table in the Token Variables document lists the module variable name and specifies which UNIVERSAL_VAR union member to use with each variable.

Accessing Token Variables

You can access token variables in three ways:

1. From various Gauge macros as described earlier.
2. Through drawing elements. In the element structure, you can specify which variable controls the element. For example, you may have a needle (ELEMENT_NEEDLE) that is controlled by the variable VERTICAL_SPEED. As the needle is updated, it will refer to the variable VERTICAL_SPEED to determine the angle at which it will be displayed. For details, see the section Gauge Macros and Drawing Elements.
3. Through the Panel API, using the following procedure:

To access a tokenized variable through the Panel API

• Instantiate a MODULE_VAR variable initializing the GAUGE_TOKEN ID structure member. You can set the ID to one of the token variables provided in the Token Variables document. For example:
  
  typedef struct MODULE_VAR
{
    GAUGE_TOKEN id;
    PVOID var_ptr;
    VAR_TYPE var_type;
    UNIVERSAL_VAR var_value;
    UNIVERSAL_VAR var_old;
} MODULE_VAR, *PMODULE_VAR, **PPMODULE_VAR;

 

• To update the contents of the variable from state information, use lookup_var:
  
   lookup_var(PMODULE_VAR module_var )

After the lookup_var function is called, the value of a MODULE_VAR variable is stored in the var_value member of the structure.
Important: Token variables are read-only. Any attempt to set these variables through the var_ptr variable may result in unpredictable behavior. The following code example shows how the MODULE_VAR variable is used. Note that this is a callback function and, in this specific example, it is for a sprite element.

Gauge Macros and Drawing Elements

Each of the Gauge macros makes use of the drawing elements available. These drawing elements are part of the macro definition in Gauges.h. Here is each macro and its associated element.

Shared Data Elements

Each macro has twelve shared data elements, which aren't included in the declaration of each structure. Instead, a #define HEADER is present that, when expanded, produces the twelve data members. The following code examples show the drawing element ELEMENT_NEEDLE before and after expansion. Before expansion:


typedef struct ELEMENT_NEEDLE
{
    HEADER;
    'Needle-specific data members
};

After expansion:

Drawing Element Header

The first twelve data members are the same for all the drawing element structures. The data members are described in the following table.

Drawing Element Structures

Each drawing element structure has one or more MODULE_VAR members. You can initialize these members to one of the token variable values. Call the function element_install or element_list_install to initialize the MODULE_VAR element(s). The element_update or element_list_update function can be used to update the contents of the MODULE_VAR. The elements themselves use the MODULE_VAR information at render time to determine in what state they'll be rendered.

Graphical elements can use the MODULE_VAR structure member to determine the state in which the element will be rendered. Sometimes, however, MODULE_VAR may not be a useful value. You can get around this problem by using callbacks. For each of the MODULE_VAR structures listed in the element structure, you can set an associated PMODULE_VAR_CB pointer. The pointer points to a callback function that you can use to set the variable to a useful value. The callback function is called by the panel system after the variable has been updated from the simulation state information. The callback function is generally used to normalize or scale the MODULE_VAR value into a valid range. You can also use the callback function to convert enumerated values, interpret a flag's variable, and so on. For example, the following code uses a callback routine to clip the airspeed to a useful range that can be used by the airspeed gauge. All elements use the same style callback routine in which the argument to the function acts as a pointer to that element.


FLOAT64 convert_var_aspeed(PMODULE_VAR var)
{
    if (var->var_value.n > GAUGE_MAX_AIRSPEED)
    var->var_value.n = GAUGE_MAX_AIRSPEED;
    if (var->var_value.n < 60)
    var->var_value.n = 60;
    return var->var_value.n;
}

You can set any callback pointer to NULL so that no call will occur. Any assignments to the MODULE_VAR in a callback routine are discarded. The final value set in MODULE_VAR is the return value of the callback function.

Drawing Element Lists

In code, the drawing elements are organized (using the next_element data member) in a tree structure (the element list). This element list defines the drawing order of the gauge elements:

• The first element in the list in the gauge header is drawn first.
• Each subsequent element in the list is drawn in the order it appears in the list.
• Before drawing the next element in the list, the current element’s element-list pointer is examined. If the pointer is not NULL, the element’s element list is drawn using the same logic.

You don't need to set the previous_element pointer. This pointer is initialized by the panel system when the gauge is initialized.

Gauge Macros

This section describes each of the following gauge macros:

• MAKE_STATIC
• MAKE_NEEDLE
• MAKE_STRING
• MAKE_SLIDER
• MAKE_MOVING
• MAKE_ICON
• MAKE_SPRITE
• Drawing Element Macros
• String Element Macros
• Draw Flags
• Aircraft Specific Information Flags

MAKE_STATIC

The MAKE_STATIC macro draws the simplest type of graphical element. Use MAKE_STATIC to draw an image that never changes.
Here’s the macro structure from Gauges.h:


#define     MAKE_STATIC(      NAME,                   \
                              RES_ID,                 \
                              NEXT_LIST,              \
                              FAILURE,                \
                              DRAW_FLAGS,             \
                              ASI_FLAGS,              \
                              POSITION_X, POSITION_Y )\

And here’s the code fragment from Control_surfaces.cpp that uses MAKE_STATIC:

The following table explains the different fields in MAKE_STATIC.

MAKE_NEEDLE

Use MAKE_NEEDLE to draw an image that pivots around a specific point in another image. MAKE_NEEDLE supports transparency and nonlinear gauges. For MAKE_NEEDLE, POS (position) is the center of rotation in the background image; OFS (offset) is the center of rotation in the needle image.
Here’s the macro structure from Gauges.h:


#define     MAKE_NEEDLE(      NAME,                               \
                              RES_ID,                             \
                              NEXT_LIST,                          \
                              FAILURE,                            \
                              DRAW_FLAGS,                         \
                              ASI_FLAGS,                          \
                              BKND_POSITION_X, BKND_POSITION_Y,   \
                              NDL_POSITION_X, NDL_POSITION_Y,     \
                              SOURCE_VAR, CALLBACK,               \
                              NONLINEARITY_TABLE,                 \
                              MAX_DEG_PER_SEC )                   \

And here’s the code fragment from SDK.fuel.cpp that uses this macro:

The following table explains the different fields in MAKE_NEEDLE.

Using Non-Linearity Tables

In some cases, you might want a needle to move in a nonlinear manner. For example, an airspeed gauge sometimes shows a greater angle between 0 and 50 knots than the angle between 100 and 150 knots. You can specify this behavior by using a non-linearity table. A non-linearity table is an array of NONLINEARITY structures. Each element in the array represents a discrete point on a gauge where the value is known. For example, your gauge might show airspeed as values from 0 to 160 knots, with tick marks every 20 knots. You could create an entry for each tick, filling in the pt and value member variables of the NONLINEARITY structure.

A NONLINEARITY structure uses the following members.

In SDK.Fuel.cpp, the linearity table deals with the fuel quantity, which ranges from 0 to 75. Here’s the non-linearity table it uses:


NONLINEARITY  fuel_nonlinearity[] =
{
      {{30, 182}, 0, 0},
      {{119, 47}, 25, 0},
      {{246, 93}, 50, 0},
      {{241, 221}, 75, 0}
};

At runtime, the value of the needle is examined and the angle to be drawn is interpolated from the non-linearity table. Values are listed in the table as they appear on the gauge (clockwise around the face). If gauge values increase when rotating clockwise, values in the non-linearity table will start at the minimum and increase. If gauge values decrease when rotating clockwise, then values in the table will start with the maximum and decrease.

MAKE_STRING

Use MAKE_STRING to display text on a gauge. MAKE_STRING is particularly useful when you have a string that changes as the gauge is updated; the string can be automatically updated by setting up the MODULE_VAR elements and using callback functions. Using MAKE_STRING, you can specify the font name, weight, and the background and foreground colors of the text. You can also specify a highlight text color to use when the string is selected.
Here’s the macro structure from Gauges.h:


#define       MAKE_STRING(  NAME,                                          \
                                         NEXT_LIST,                        \
                                         FAILURE,                          \
                                         DRAW_FLAGS,                       \
                                         ASI_FLAGS,                        \
                                         POSITION_X, POSITION_Y,           \
                                         SIZE_X, SIZE_Y,                   \
                                         NUM_CHARS,                        \
                                         SOURCE_VAR_1,                     \
                                         SOURCE_VAR_2,                     \
                                         SOURCE_VAR_3,                     \
                                         FORECOLOR,                        \
                                         BACKCOLOR,                        \
                                         HILITECOLOR,                      \
                                         FONT_NAME,                        \
                                         FONT_WEIGHT,                      \
                                         FONT_CHARSET,                     \
                                         FONT_SIZE,                        \
                                         DRAW_TEXT_FLAGS,                  \
                                         HILITE_LIST,                      \
                                         CALLBACK)                         \

Here’s the code fragment from SDK.Temperature.cpp that uses the MAKE_STRING macro:

The following table explains the different fields in MAKE_STRING.

Defining the Font Type

To define the font type you must place #define statements (after the initial #include) in your gauge code. For example, SDK.Temperature.cpp looks like this:


#define GAUGE_CHARSET               DEFAULT_CHARSET
#define GAUGE_FONT_DEFAULT          "Courier New"
#define GAUGE_WEIGHT_DEFAULT        FW_NORMAL

The first line in the code above is the default character set for English (UK and US). Most instruments are labeled in English. The second line defines the font set name. You want to define a font that will, with almost certainty, exist on your user’s PC. Therefore, choose one of the following fonts: Courier New, Arial, Times New Roman, or Helvetica. The third line defines how the font will display. Here are the available options:

FW_THINFW_EXTRALIGHT
FW_LIGHT
FW_NORMAL
FW_MEDIUM
FW_SEMIBOLD
FW_BOLD
FW_EXTRABOLD
FW_HEAVY

Selecting a String by KEY_EVENT

You can use the SEQ_REC table to select a string automatically on certain KEY_EVENTs. The user can select certain gauge elements by using different keyboard combinations. The SEQ_REC structure sets up the relationship between the current selection state and the characters that can be selected for that state. The following code shows the SEQ_REC structure definition (from gauges.h):


typedef struct SEQ_REC
{
    int seq_id;
    int sel_str;
    int sel_end;
} SEQ_REC, *PSEQ_REC, **PPSEQ_REC;

SEQ_REQ uses the following members.

To mark the end of the array you must add one blank record that sets seq_id, sel_str, and sel_end to SELECT_NONE, 0, and 0, respectively. The following code example shows a sample SEQ_REC definition:

The following table includes the gauge selection states available in Flight Simulator.

MAKE_SLIDER

Use MAKE_SLIDER to move a drawing element around a gauge on the X and Y axes. You can use MAKE_SLIDER to move an image in only one direction as well. Just set the MODULE_VAR, for either X or Y, to MODULE_VAR_NONE. Here’s the macro structure from Gauges.h:


#define     MAKE_SLIDER(      NAME,                         \
                              RES_ID,                       \
                              NEXT_LIST,                    \
                              FAILURE,                      \
                              DRAW_FLAGS,                   \
                              ASI_FLAGS,                    \
                              POSITION_X, POSITION_Y,       \
                              SOURCE_VAR_X, CALLBACK_X, SCALE_X,  \
                              SOURCE_VAR_Y, CALLBACK_Y, SCALE_Y )

You’ll need to fill this structure out with slider-specific information, such as the following from SDK.Control_Surfaces.cpp:


MAKE_SLIDER
(
      cs_slider_trim,
      BMP_CS_SMALL_TRIM,
      NULL,
      0,
      IMAGE_USE_ERASE | IMAGE_USE_TRANSPARENCY,
      0,
      20,44,

      MODULE_VAR_NONE, NULL, 0,
      ELEVATOR_TRIM, NULL, -100
)

The following table explains the different fields in MAKE_SLIDER.

MAKE_MOVING

MAKE_MOVING, like MAKE_SLIDER, moves an image around on a gauge on the X and Y axes. The difference is that MAKE_MOVING specifies a mask, which does not move, and is used to hide parts of the image. The moving image moves in reference to where the mask is placed. Whiskey compasses are drawn using MAKE_MOVING. Here’s the macro structure from Gauges.h:


#define     MAKE_MOVING(            NAME,                  \
                                    RES_ID,                 \
                                    NEXT_LIST,              \
                                    FAILURE,                \
                                    DRAW_FLAGS,             \
                                    ASI_FLAGS,              \
                                    POSITION_X, POSITION_Y, \
                                    SOURCE_VAR_X, CALLBACK_X,     \
                                    MIN_X, MAX_X,                 \
                                    SOURCE_VAR_Y, CALLBACK_Y,     \
                                    MIN_Y, MAX_Y )

You’ll need to fill this structure out with specific information, such as the following from SDK.Wiskey.cpp:


MAKE_MOVING
(
      wiskey_moving_card,
      BMP_COMPASS_SMALL_CARD,
      NULL,
      wiskey_fail,
      IMAGE_USE_ERASE | IMAGE_USE_TRANSPARENCY,
      0,
      22,41,
      WHISKEY_COMPASS_DEGREES, wiskey_moving_card_x_cb,
      0, 360,
      MODULE_VAR_NONE, wiskey_moving_card_y_cb,
      0, 0
)

The following table explains the different fields in MAKE_MOVING.

When you specify a mask with MAKE_MOVING, you’re actually specifying the area within which another part of the gauge can move and appear. Once that other part moves outside of that area (as defined by MIN_X, MAX_X, MIN_Y, and MAX_Y) it won’t display. These fields identify the top left and bottom right corners of this area within the gauge background.

MAKE_ICON

Use MAKE_ICON to toggle between one of several images at a static location on a gauge. The RES_ID member of the structure specifies the first icon image. The panel system loads the first icon image using RES_ID. The panel system loads the next icon image by adding 1 to the RES_ID. It then adds 1 more to RES_ID and loads the next image, and so on. The panel system continues this process as many times as NUM_ICONS specifies. Icon images can be any size, although all images in the same MAKE_ICON have the same upper left location. If you specify IMAGE_USE_ERASE in the image flags for MAKE_ICON, the save buffer will only be as large as the first image. If source_var is set to -1, the icon image is automatically hidden.

Here’s the MAKE_ICON structure as defined in gauges.h:


#define     MAKE_ICON(              NAME,            \
                                    RES_ID,          \
                                    NEXT_LIST,       \
                                    FAILURE,         \
                                    DRAW_FLAGS,      \
                                    ASI_FLAGS,       \
                                    POSITION_X, POSITION_Y,\
                                    SOURCE_VAR, CALLBACK,  \
                                    SWITCH_TYPE,     \
                                    NUM_ICONS,       \
                                    SCALE,           \
                                    OFFSET )         \

You’ll need to fill this structure out with specific information, such as the following from SDK.Fuel_Selector.cpp:


MAKE_ICON
(
      fuel_selector_icon,
      BMP_FUEL_SELECTOR_OFF,
      NULL,
      NULL,
      IMAGE_USE_ERASE | IMAGE_USE_TRANSPARENCY,
      0,
      0,0,
      FUEL_TANK_SELECTOR,fuel_selector_icon_cb,
      ICON_SWITCH_TYPE_STEP_TO,
      4,
      0,
      0
)

The following table explains the different fields in MAKE_ICON.

MAKE_SPRITE

MAKE_SPRITE, like MAKE_MOVING_IMAGE, moves an element in X and Y directions and uses a mask to hide parts of the element. The difference is that MAKE_SPRITE can rotate an element around a pivot point. For MAKE_SPRITE, TEXTURE_CENTER_X and TEXTURE_CENTER_Y identify the center of the sprite—the center of the texture maps to this point. Textures used for ELEMENT_SPRITE must be 256 x 256. When the gauge is loaded, the RES_ID specifies the image to use for the texture. RES_ID + 1 specifies the mask image. The mask doesn't have to be a specific size. The mask is placed on the gauge using the position member. The texture slides and rotates underneath the mask. Element transformations occur in the following order:

• Rotate, based on SOURCE_VAR_0.
• Scale, based on TEXTURE_SCALE_X and TEXTURE_SCALE_Y.
• Transpose, based on SOURCE_VAR_X and SOURCE_VAR_Y.

Here’s the MAKE_SPRITE structure as defined in gauges.h:


#define     MAKE_SPRITE(            NAME,      \
                                    RES_ID,    \
                                    NEXT_LIST,  \
                                    FAILURE,    \
                                    DRAW_FLAGS, \
                                    ASI_FLAGS,  \
                                    BKND_POSITION_X, BKND_POSITION_Y,   \
                                    TEXTURE_CENTER_X, TEXTURE_CENTER_Y, \
                                    TEXTURE_SCALE_X, TEXTURE_SCALE_Y,   \
                                    SOURCE_VAR_X, CALLBACK_X, SCALE_X,  \
                                    SOURCE_VAR_Y, CALLBACK_Y, SCALE_Y,  \
                                    SOURCE_VAR_0, CALLBACK_0, SCALE_0 ) \

You’ll need to fill this structure out with specific information, such as the following from SDK.Attitude.cpp:


MAKE_SPRITE
(
      attitude_sprite_outer,
      BMP_ATTITUDE_SMALL_CARD2,
      NULL,
      (PFAILURE_RECORD)&attitude_fail,
      IMAGE_USE_TRANSPARENCY,
      0,
      16, 13,
      137,134,
      1.05, 1.05,
      MODULE_VAR_NONE, NULL, 0,
      MODULE_VAR_NONE, NULL, 0,
      ATTITUDE_INDICATOR_BANK_DEGREES, NULL, -1
)

The following table explains the different fields in MAKE_SPRITE.

Drawing Element Macros

The following macros have been defined to manipulate drawing elements:

String Element Macros

The following macros have been defined to manipulate string elements:

#define STR_UNSEL( ELEment)           (ELEMENT->sel_end = -1; ELEMENT->sel_str = -1;)
#define STR_SEL( ELEMENT, STR, END)   (ELEMENT->sel_end = END; ELEMENT->sel_str = STR;)
#define IS_STR_SEL( ELEment)          (ELEMENT->sel_end != -1 && ELEMENT->sel_str != -1)

DRAW_FLAGS

The DRAW_FLAGS field is a combination of one or more of the following flags (combine them using the | operator):

Aircraft Special Instrumentation

These flags specify how the element will react in a special instrument situation. Currently this is used only with autopilot. This member can have the following values:

Custom Events

Third parties can use custom events with ID numbers in the following range to communicate between 3D virtual cockpits and 2D C++ gauges. See the example code for the function register_key_event_handler.

Refer also the documentation on the function SimConnect_MapClientEventToSimEvent.

C++ Gauges Function Reference

The following functions can be used in combination with various gauge and mouse rectangle macros. Note that you will not see many of these functions in the samples provided, because they are encapsulated in the macros and there is no need to call them explicitly if the macros are used.

See Also

• Structures
  

aircraft_varget

The aircraft_varget function retrieves the value of an aircraft simulation variable.

Syntax

Parameters

simvar
  [in]  Specifies a simulation variable enum value. Use get_aircraft_var_enum to retrieve the enum value from a string.
units
  [in]  Specifies the units enum value the returned value should have. Use get_units_enum to retrieve the enum value from a string.
index
  [in]  Specifies an index number, which is required for some engine and communication data. Refer to the Simulation Variables document for details.

Return Values

The function returns the value in a FLOAT64. If the simulation variable is not found, zero will be returned.

Example

See Cabin_Comfort.cpp for an example of the use of this function, and refer to Creating a Gauge using XML and C++ for a description of this sample

Remarks

None.

See Also

• C++ Gauges Function Reference
• get_aircraft_var_enum
• get_units_enum

check_named_variable

The check_named_variable function retrieves the ID number of a named local variable, if it exists.

Syntax

Parameters

name
  [in]  Specifies the variable name.

Return Values

The function returns an ID number if the variables exists, or -1 if it does not.

Remarks

Local variable names are case-insensitive.

See Also

• C++ Gauges Function Reference
• register_named_variable

element_list_erase

The element_list_erase function is used before redrawing a gauge.

Syntax

Parameters

element
  [in]  A pointer to the element header.

Return Values

This function does not return a value.

Remarks

It is not necessary to call this function if the redrawing of the gauge is handled by element_list_plot.

See Also

• C++ Gauges Function Reference
• element_list_install

element_list_generate

The element_list_generate function is regenerates a the effects mask and images for a gauge.

Syntax

Parameters

element
  [in]  A pointer to the element header.
phase
  [in]  Unused, enter zero.

Return Values

This function does not return a value.

Remarks

See the remarks for element_list_plot.

See Also

• C++ Gauges Function Reference

element_list_initialize

The element_list_initialize function prepares a gauge before being redrawn.

Syntax

Parameters

element
  [in]  A pointer to the element header.

Return Values

This function does not return a value.

Remarks

See the remarks for element_list_plot.

See Also

• C++ Gauges Function Reference

element_list_install

The element_list_install function is used to install a gauge during initialization of a panel.

Syntax

Parameters

element
  [in]  A pointer to the element header.
resource_file_handle
  [in]  Specifies the resource file handle.

Return Values

This function does not return a value.

Remarks

Use this function before calling any of the other element_list functions. A gauge is defined by an element list, however the macros used to create gauges described in the tutorial mean that in many cases these functions do not need to be called directly.

See Also

• C++ Gauges Function Reference

element_list_kill

The element_list_kill function is used to remove a gauge completely, for example when changing user aircraft.

Syntax

Parameters

element
  [in]  A pointer to the element header.

Return Values

This function does not return a value.

Remarks

None.

See Also

• C++ Gauges Function Reference
• element_list_install

element_list_plot

The element_list_plot function redraws a gauge.

Syntax

Parameters

element
  [in]  A pointer to the element header.

Return Values

This function does not return a value.

Remarks

Before calling this function, each and every time, call the following functions in this order:

1. element_list_initialize
2. element_list_update
3. element_list_generate
4. element_list_plot

See Also

• C++ Gauges Function Reference
• element_list_install

element_list_query

The element_list_query function used to register the failure conditions for a gauge.

Syntax

Parameters

element
  [in]  A pointer to the element header.

Return Values

This function does not return a value.

Remarks

Call this function once, after element_list_install.

See Also

• C++ Gauges Function Reference

element_list_update

The element_list_update function calculates new values for each gauge element.

Syntax

Parameters

element
  [in]  A pointer to the element header.

Return Values

This function does not return a value.

Remarks

See the remarks for element_list_plot.

See Also

• C++ Gauges Function Reference

element_use_color

The element_use_color function selects the text color for string elements.

Syntax

Parameters

element
  [in]  A pointer to the element header.
override
  [in]  Specifies if a color selected by the user should be overridden..
color
  [in]   RGB value for the color.

Return Values

This function does not return a value.

Remarks

None.

See Also

• C++ Gauges Function Reference

execute_calculator_code

The execute_calculator_code function evaluates a coded calculator string.

Syntax

Parameters

code
  [in]  Specifies the calculator code.
fvalue
  [out]  Pointer to a float. Returns the result of the calculation, if it is a floating point value.
ivalue
  [out]  Pointer to an integer. Returns the result of the calculation, if it is an integer value.
svalue
  [out]  Pointer to a string. Returns the result of the calculation, if it is a string.

Return Values

If the function succeeds, it returns a non-zero value. If it fails, it returns zero.

Example

Remarks

None.

See Also

• C++ Gauges Function Reference
• format_calculator_string
• gauge_calculator_code_precompile

format_calculator_string

The format_calculator_string function evaluates a formatted calculator string.

Syntax

Parameters

result
  [out]  Returns the formatted string.
resultsize
  [out]  Returns the length of the formatted string.
format
  [in]  Specifies the calculator string to format.

Return Values

If the function succeeds, it returns a non-zero value. If it fails, it returns zero.

Remarks

None.

See Also

• C++ Gauges Function Reference
• execute_calculator_code
• gauge_calculator_code_precompile

gauge_calculator_code_precompile

The gauge_calculator_code_precompile function compresses a calculator string into a more efficient internal format.

Syntax

Parameters

pCompiled
  [out]  Pointer to a string, which will contain the compiled string if the function call is successful.
pCompiledSize
  [out]  Pointer to an integer, which will contain the length of the compiled string if the function call is successful.
source
  [in]  Specifies the source calculator string. Refer to the Creating XML Gauges document for details on format strings.

Return Values

If the function succeeds, it returns a non-zero value. If it fails, it returns zero.

Remark

A precompiled (compressed) calculator string can be used as input to the execute_calculator_code and format_calculator_string functions.

See Also

• C++ Gauges Function Reference
• execute_calculator_code
• format_calculator_string

get_aircraft_var_enum

The get_aircraft_var_enum function retrieves the enum value for a simulation variable, given the string name of that variable.

Syntax

Parameters

simvar
  [in]  Specifies the simulation variable name.

Return Values

The function returns the ENUM value of the simulation variable, or SIMVAR_NONE (-1) if the variable name is not found.

Example

See Cabin_Comfort.cpp for an example of the use of this function, and refer to Creating a Gauge using XML and C++ for a description of this sample

Remarks

Use this function before calling aircraft_varget.

See Also

• C++ Gauges Function Reference
• aircraft_varget
• get_units_enum

get_gauge_flags

The get_gauge_flags function is used to retrieve the flags set on a gauge.

Syntax

Parameters

name
  [in]  Specifies the name of the gauge.

Return Values

The function returns a FLAGS32 value containing the flags that are set. See set_gauge_flags for a table of gauge flags.

Remarks

None.

See Also

• set_gauge_flags
• C++ Gauges Function Reference

get_name_of_named_variable

The get_name_of_named_variable function retrieves the name of a local variable, given an ID number.

Syntax

Parameters

id
  [in]  Specifies the ID of the variable.

Return Values

The function returns the name in a PCSTRINGZ, or NULL if the name is not found.

Remarks

None.

See Also

• C++ Gauges Function Reference

get_named_variable_typed_value

The get_named_variable_typed_value function retrieves the value of a named local variable, in the specified units.

Syntax

Parameters

id
  [in]  Specifies the ID of the variable.
units
  [in]  Specifies the enum value of the units required. Use get_units_enum to retrieve the enum value from a string.

Return Values

The function returns the value in a FLOAT64. Zero is returned if the variable ID is not found.

Remarks

None.

See Also

• get_named_variable_value
• set_named_variable_typed_value
• set_named_variable_value
• C++ Gauges Function Reference

get_named_variable_value

The get_named_variable_value function retrieves the value of a local variable, given an ID.

Syntax

Parameters

id
  [in]  Specifies the ID of the variable.

Return Values

The function returns the value in a FLOAT64. Zero is returned if the variable ID is not found.

Remarks

None.

See Also

• get_named_variable_typed_value
• set_named_variable_typed_value
• set_named_variable_value
• C++ Gauges Function Reference

get_units_enum

The get_units_enum function retrieves the enum value for units, given the string name of the units.

Syntax

Parameters

unitname
  [in]  Specifies the string name of the units.

Return Values

The function returns the ENUM. value for the units, or UNITS_UNKNOWN (-1) if the string name is not found.

Example

See Cabin_Comfort.cpp for an example of the use of this function, and refer to Creating a Gauge using XML and C++ for a description of this sample

Remarks

Use this function before calling aircraft_varget.

See Also

• C++ Gauges Function Reference
• aircraft_varget
• get_aircraft_var_enum

initialize_var

The initialize_var function initializes a token variable.

Syntax

Parameters

module_var
  [in]  Specifies a pointer to a MODULE_VAR structure, containing the token variable to initialize.

Return Values

This function does not return a value.

Example

MODULE_VAR gs_var = {VOR1_GS_FLAG};
void install_routine(HINSTANCE resource_file_handle)
{
initialize_var(&gs_var);
'Include other initialization code.
}

Remarks

Before a token variable can be used, you must initialize it with a call to this function.

See Also

• initialize_var_by_name
• C++ Gauges Function Reference

initialize_var_by_name

The initialize_var_by_name function initializes a MODULE_VAR structure, given the name of a token variable.

Syntax

Parameters

module_var
  [in]  Specifies the address of the MODULE_VAR structure that will receive information about the variable.
name
  [in] Specifies the name of the variable (the same name used in register_var_by_name).

Return Values

This function does not return a value.

Example

MODULE_VAR var;
initialize_var_by_name (&var, GPS_INFO_PANEL_VARIABLE_NAME);

Also see SDK.FlightMap.cpp for an example of the use of this function.

Remarks

None.

See Also

• initialize_var
• C++ Gauges Function Reference

is_master

The is_master function returns true if the aircraft is the master aircraft of a shared cockpit.

Syntax

Parameters

This function takes no parameters.

Return Values

If the aircraft is the master aircraft, it returns a non-zero value. If it is not, it returns zero.

Remarks

This function is used in the multiplayer scenario of a shared cockpit. One aircraft is the master and one is not. There is a maximum of two users in this scenario.

See Also

• process_shared_event_out
• C++ Gauges Function Reference

The is_panel_window_visible_ident function returns true if the specified panel window is visible.

Syntax

Parameters

panel_id
  [in]  Specifies the identification number of the window to query. The identification number is specified in the Panel.cfg file in the [WindowXX] section by the variable ident.

Return Values

If the function succeeds, it returns a non-zero value. If it fails, it returns zero.

Remarks

None.

See Also

• C++ Gauges Function Reference

lookup_var

The lookup_var function updates the contents of a token variable.

Syntax

Parameters

module_var
  [in]  Pointer to a MODULE_VAR structure, containing the token variable to update.

Return Values

This function does not return a value.

Example

MODULE_VAR gs_var = {VOR1_GS_FLAG};
Void update_routine()
{
  lookup_var(&gs_var);
  if(gs_var.var_value.n == 0)
  {
    HIDE_IMAGE((&gs_slider));
    HIDE_IMAGE((&gs_background));
  }
  else
  {
    SHOW_IMAGE((&gs_slider));
    SHOW_IMAGE((&gs_background));
  }
'Include other update code
}

Remarks

Before using the contents of a module variable, you must call the lookup_var function.

See Also

• C++ Gauges Function Reference

mouse_list_install

The mouse_list_install function creates the mouse rectangles for a gauge.

Syntax

Parameters

rect
  [in, out]  Specifies a pointer to a list of MOUSERECT structures. The first rectangle in the list is the main box. The rectangles are scaled according to the settings in the gauge_header. The last rectangle structure in the list should have the type MOUSE_RECT_EOL.
gauge_header
  [in]  Specifies a pointer to a gauge_header structure (defined in gauges.h).
size
  [in]  Specifies a pointer to a PIXPOINT structure, which contains an x and y value, defining the size of the rectangle.

Return Values

This function does not return a value.

Remarks

Call mouse_list_register after setting up the mouse rectangles with this function. Note that the mouse rectangle creation macros can be used instead of these low level function calls.

See Also

• C++ Gauges Function Reference
• mouse_list_register
• mouse_list_unregister

mouse_list_register

The mouse_list_register function registers the mouse windows.

Syntax

Parameters

rect
  [in]  Specifies a pointer to a MOUSERECT structure.
gauge_header
  [in]  Specifies a pointer to a gauge_header structure (defined in gauges.h).

Return Values

This function does not return a value.

Remarks

None.

See Also

• C++ Gauges Function Reference
• mouse_list_install
• mouse_list_unregister

mouse_list_unregister

The mouse_list_unregister function unregisters the mouse windows.

Syntax

Parameters

rect
  [in]  Specifies a pointer to a MOUSERECT structure.
gauge_header
  [in]  Specifies a pointer to a gauge_header structure (defined in gauges.h).

Return Values

This function does not return a value.

Remarks

None.

See Also

• C++ Gauges Function Reference
• mouse_list_install
• mouse_list_register

panel_get_aircraft_c_callback

The panel_get_aircraft_c_callback function retrieves a pointer to the aircraft callback function.

Syntax

Parameters

name
  [in]  Specifies the name of the callback function.

Return Values

The function returns a pointer to the IAircraftCCallback function, or NULL if the name is not found.

Remarks

None.

See Also

• C++ Gauges Function Reference

panel_get_registered_c_callback

The panel_get_registered_c_callback function retrieves a pointer to the registered callback function.

Syntax

Parameters

name
 [in]  Specifies the name of the module, "CABIN" in the Cabin_Comfort.cpp example.

Return Values

The function returns a pointer to an IPanelCCallback function.

Remarks

None.

See Also

• C++ Gauges Function Reference
• panel_register_c_callback

panel_register_c_callback

The panel_register_c_callback function specifies the registered callback function.

Syntax

Parameters

name
  [in]  Specifies the name of the module, "CABIN" in the Cabin_Comfort.cpp example.
pcallback
  [in]  Specifies a pointer to the IPanelCCallback function.

Return Values

If the function succeeds, it returns a non-zero value. If it fails, it returns zero.

Example

See Cabin_Comfort.cpp for an example of the use of this function, and refer to Creating a Gauge using XML and C++ for a description of this sample

Remarks

None.

See Also

• C++ Gauges Function Reference
• panel_get_registered_c_callback

panel_resource_string_get

The panel_resource_string_get function retrieves the resource string, given an ID.

Syntax

Parameters

id
  [in]  Specifies the resource ID.

Return Values

The function returns the resource string in a PCSTRINGZ , or NULL if the ID is not found.

Remarks

None.

See Also

• C++ Gauges Function Reference

panel_window_close_ident

The panel_window_close_ident function closes the specified panel window.

Syntax

Parameters

panel_id
  [in]  Specifies the identification number of the window to close. The identification number is specified in the Panel.cfg file in the [WindowXX] section by the variable ident.

Return Values

If the function succeeds, it returns a non-zero value. If it fails, it returns zero.

Remarks

None.

See Also

• panel_window_open_ident
• C++ Gauges Function Reference

panel_window_open_ident

The panel_window_open_ident function displays the specified panel window.

Syntax

Parameters

panel_id
  [in]  Specifies the identification number of the window to open. The identification number is specified in the Panel.cfg file in the [WindowXX] section by the variable ident.

Return Values

If the function succeeds, it returns a non-zero value. If it fails, it returns zero.

Remarks

None.

See Also

• panel_window_close_ident
• C++ Gauges Function Reference

panel_window_toggle

The panel_window_toggle function toggles the visible state of a panel window.

Syntax

Parameters

panel_id
  [in]  Specifies the identification number of the window to toggle. The identification number is specified in the Panel.cfg file in the [WindowXX] section by the variable ident.

Return Values

If the function succeeds, it returns a non-zero value. If it fails, it returns zero.

Example

BOOL window_open_cb(PPIXPOINT relative_point, FLAGS32 mouse_flags)
{
  return panel_window_toggle(50);
}

Remarks

None.

See Also

• panel_window_toggle_hud_color
• panel_window_toggle_hud_units
• panel_window_toggle_menu_id
• C++ Gauges Function Reference

panel_window_toggle_hud_color

The panel_window_toggle_hud_color function changes the global HUD color to the next in the list.

Syntax

Parameters

This function takes no parameters.

Return Values

This function does not return a value.

Remarks

This function cycles through the range of HUD colors (green, dark green, blue, dark blue, red, dark red, black, white), setting the global HUD color to the next in the list..

See Also

• panel_window_toggle
• panel_window_toggle_hud_units
• panel_window_toggle_menu_id
• C++ Gauges Function Reference

panel_window_toggle_hud_units

The panel_window_toggle_hud_units function toggles the HUD units between metric and imperial.

Syntax

Parameters

This function takes no parameters.

Return Values

This function does not return a value.

Remarks

None.

See Also

• panel_window_toggle
• panel_window_toggle_hud_color
• panel_window_toggle_menu_id
• C++ Gauges Function Reference

panel_window_toggle_menu_id

The panel_window_toggle_menu_id function selects a menu item given an ID.

Syntax

Parameters

menu_id
  [in]  Specifies the menu ID

Return Values

If the function succeeds, it returns a non-zero value. If it fails, it returns zero.

Example

Remarks

This function does not "toggle", but rather "selects", but the name is left unchanged for backwards compatibility.

See Also

• panel_window_toggle
• panel_window_toggle_hud_color
• panel_window_toggle_hud_units
• C++ Gauges Function Reference

process_shared_event_out

The process_shared_event_out function sends data to the other aircraft, in a multiplayer shared cockpit scenario.

Syntax

Parameters

gauge_header
  [in]  Specifies the gauge header, which is used to identify the gauge that the event applies to.

pBuf
  [in]  A pointer to an array of data.

nSize
  [in]  The length of the data array, in bytes.

Return Values

If the function succeeds, it returns a non-zero value. If it fails, it returns zero.

Remarks

This function is used to send data from one aircraft to another in the shared cockpit scenario of multiplayer operations. Only two aircraft can share a cockpit, one is the master and the other is not. This function can be used to send data from either one to the other.

See Also

• is_master
• C++ Gauges Function Reference

radio_stack_autoclose

The radio_stack_autoclose function closes the radio stack, if it was opened with radio_stack_popup.

Syntax

Parameters

This function takes no parameters.

Return Values

This function does not return a value.

Remarks

None.

See Also

• C++ Gauges Function Reference
• radio_stack_popup

radio_stack_popup

The radio_stack_popup function displays the radio stack

Syntax

Parameters

This function takes no parameters.

Return Values

This function does not return a value.

Remarks

This function has no effect if the radio stack is already displayed.

See Also

• C++ Gauges Function Reference
• radio_stack_autoclose

register_key_event_handler

The register_key_event_handler function registers a key event callback function.

Syntax

Parameters

handler
  [in]  Specifies the handler function, which should match the following definition:
typedef void (*GAUGE_KEY_EVENT_HANDLER) (ID32 event, UINT32 evdata, PVOID userdata);
userdata
  [in]  Specifies an optional value for use by the gauge developer. This value will be returned to the key event handler function, whenever it is called.

Return Values

This function does not return a value.

Example

This example shows how to receive custom numeric events from part animations (refer to the Creating a New Animation section of the Using Modeling Tools document).

Defined in gauges.h:

Code in the gauge handler:

Remarks

None.

See Also

• C++ Gauges Function Reference
• unregister_key_event_handler

register_named_variable

The register_named_variable function registers a local variable name.

Syntax

Parameters

name
  [in]  Specifies the variable name.

Return Values

The function returns an ID. If the named variable already exists, its existing ID will be returned. If it does not exist, a new registered variable is created.

Remarks

Local variable names are case-insensitive. The value of the variable is set to zero, and the units to UNITS_UNKNOWN, on creation.

See Also

• C++ Gauges Function Reference
• check_named_variable

register_var_by_name

The register_var_by_name function registers a variable from another gauge, for use by this gauge.

Syntax

Parameters

var
  [in]  Specifies the address of the variable.
var_type
  [in]  Specifies the type of the variable, one of the following enum:

typedef enum VAR_TYPE {
    VAR_TYPE_NONE,
    TYPE_BOOL8,
    TYPE_UINT8,
    TYPE_SINT8,
    TYPE_FLAGS8,
    TYPE_ENUM8,
    TYPE_BOOL16,
    TYPE_ANGL16,
    TYPE_UINT16,
    TYPE_SINT16,
    TYPE_UIF16,
    TYPE_SIF16,
    TYPE_FLAGS16,
    TYPE_ENUM16,
    TYPE_BCD16,
    TYPE_BCO16,
    TYPE_VAR16,
    TYPE_BOOL32,
    TYPE_ANGL32,
    TYPE_UINT32,
    TYPE_SINT32,
    TYPE_UIF32,
    TYPE_SIF32,
    TYPE_FLAGS32,
    TYPE_ENUM32,
    TYPE_VAR32,
    TYPE_ANGL48,
    TYPE_SINT48,
    TYPE_UIF48,
    TYPE_SIF48,
    TYPE_UINT64,
    TYPE_SINT64,
    TYPE_SIF64,
    TYPE_FLOAT64,
    TYPE_BOOL,
    TYPE_FLAGS,
    TYPE_ENUM,
    TYPE_VOID,
    TYPE_PVOID,
    TYPE_PUINT32,
    TYPE_PSINT32,
    TYPE_PFLOAT64,
    VAR_TYPE_MAX
} VAR_TYPE;

name
  [in]  Specifies the name of the variable. Specify a unique and descriptive name for the variable, such as "gaugename.variablename".

Return Values

This function does not return a value.

Example

Remarks

You can use named variables to enable communication between two or more gauges. To establish communication between gauges, a “server” and “client” gauge needs to be defined. The terms “server” and “client” just distinguish between variable ownership and variable usage:

• The server gauges provides one or more named variables for other gauges to access.
• The client gauges accesses one or more named variables from the server gauges.

A single gauge can be both a server (by providing one or more variables) and a client (by accessing another gauge's variables) at the same time. Use the register_var_by_name, unregister_var_by_name, and initialize_var_by_name functions with named variables. The server gauge uses the register_var_by_name function to register a named variable with the panel system at startup, so create a callback for your gauge as part of the gauge_header structure. You can set this so it performs at startup, on shutdown, etc.

When using named variables, don’t call the lookup_var function (as you would with the standard panel system variables). After initialize_var_by_name is called, the var_ptr field of the MODULE_VAR structure contains a pointer to the named variable. The panel system doesn’t recognize named variables, per se, but the system does maintain the name to the pointer link for gauges to query. As a result, you can’t use a named variable as a controlling variable for an ELEMENT structure directly. Instead, use a MODULE_VAR_NONE structure and provide a callback function that can query the variable’s value using the var_ptr field of the MODULE_VAR structure.

Because named variables work via direct pointers between gauges, make sure that the server gauge is loaded before, or at the same time as, the client gauge. You can make sure this happens by either putting both gauges on the same panel window or by putting the server gauge on the main panel window. This ensures that the server gauge is loaded and the named variable is registered before the client gauge tries to connect to it. Alternatively, you can check the returned var_ptr for NULL and the returned var_type (both in the MODULE_VAR structure) for VAR_TYPE_NONE and execute (in the ELEMENT callback function) the initialize_var_by_name function until it returns valid information. (You can also call the initialize_var_by_name function every time you want to access the variable, but this approach is a little slower than caching the information once it's received.). The server gauge must keep checking the current value of the variable(s) it has made available, if the current state/value of that variable has any effect.

You can use named variables at any point in the simulation when you want to pass information between two or more gauges. Because named variables are shared by direct pointer access, you can also share out an entire data structure using one named variable, as long as the server and client gauges interpret the same data format.

You can place these gauges anywhere on a panel, as long as the server gauge is guaranteed to load before or at the same time as the client gauge.

See Also

• C++ Gauges Function Reference
• initialize_var_by_name
• unregister_var_by_name

send_key_event

The send_key_event function transmits a WM_COMMAND application event.

Syntax

Parameters

event_id
  [in]  Specifies a WM_COMMAND event ID.
value
  [in]  Specifies a value to be transmitted along with the event ID. Can be set to zero.

Return Values

This function does not return a value.

Remarks

This function transmits a message with the following syntax:

See Also

• C++ Gauges Function Reference
• trigger_key_event

set_gauge_flags

The set_gauge_flags function is used to specify the flags for a gauge.

Syntax

Parameters

name
  [in]  Specifies the name of the gauge.
newflags
  [in]   One or more of the following flags:

Return Values

This function does not return a value.

Remarks

None.

See Also

• get_gauge_flags
• C++ Gauges Function Reference

set_named_variable_typed_value

The set_named_variable_typed_value function specifies a local variable should be set to the given value with the given units.

Syntax

Parameters

id
  [in]  Specifies the ID of the variable.
value
  [in]  Specifies the value the variable should be set to.
units
  [in]  Specifies the units of the value.

Return Values

This function does not return a value.

Remarks

None.

See Also

• get_named_variable_typed_value
• get_named_variable_value
• set_named_variable_value
• C++ Gauges Function Reference

set_named_variable_value

The set_named_variable_value function sets a local variable to a given value.

Syntax

Parameters

id
  [in]  Specifies the ID of the variable.
value
  [in]  Specifies the value the variable should be set to.

Return Values

This function does not return a value.

Remarks

None.

See Also

• get_named_variable_typed_value
• get_named_variable_value
• set_named_variable_typed_value
• C++ Gauges Function Reference

tooltip_units_getset

The tooltip_units_getset function specifies or retrieves the tooltip units (metric or US).

Syntax

Parameters

action
  [in]  Specifies the action. If this value is less than zero, the units are toggled (between metric and US imperial). If this value equals zero, the enum value for the units is returned. If this value is greater than zero, the units are set to the value of the type parameter.
type
  [in]  The enum value to set the tooltip units to, one of:

Return Values

The function returns one member of the TOOLTIPS_UNITS_TYPE enumeration.

Remarks

None.

See Also

• C++ Gauges Function Reference

trigger_key_event

The trigger_key_event function initiates the action of a key event.

Syntax

Parameters

event_id
  [in]  Specifies the event ID. Refer to the list of key events in the EventIDs document, and the #define KEY_events in gauges.h.
value
  [in]  Specifies an additional integer value. Set this to zero if it is not required.

Return Values

The function returns an ERR, which is usually ignored. If the event requested is not appropriate, it simply will not happen.

Example

static MODULE_VAR nav_light;
lookup_var( &nav_light);
trigger_key_event( KEY_TOGGLE_NAV_LIGHTS, 0 );

Also see the SDK.Fuel_Selector.cpp sample.

Remarks

None.

See Also

• C++ Gauges Function Reference
• send_key_event

unregister_all_named_vars

The unregister_all_named_vars function unregisters all token variables, and frees up the memory used.

Syntax

Parameters

This function takes no parameters.

Return Values

This function does not return a value.

Remarks

None.

See Also

• C++ Gauges Function Reference

unregister_key_event_handler

The unregister_key_event_handler function unregisters the key event handler.

Syntax

Parameters

handler
  [in]  Specifies the handler function.
userdata
  [in]  Specifies the user data value specified when creating the handler function.

Return Values

This function does not return a value.

Remarks

None.

See Also

• C++ Gauges Function Reference
• register_key_event_handler

unregister_var_by_name

The unregister_var_by_name function unregisters a named variable from another gauge, and frees up the memory used.

Syntax

Parameters

name
  [in]  Specifies the name of the variable.

Return Values

This function does not return a value.

Example

See register_var_by_name for an example of the use of this function.

Remarks

None.

See Also

• C++ Gauges Function Reference
• register_var_by_name

Structures

The following structures are useful when creating gauges.

MOUSERECT

The MOUSERECT structure defines a mouse rectangle, with associated cursor, help ID, and actions.

Syntax

Members

rect_type
   Type of mouse rectangle, one of:

typedef enum
{
    MOUSE_RECT_EOL,
    MOUSE_RECT_PARENT,
    MOUSE_RECT_CHILD,
    MOUSE_RECT_END_PARENT,
    MOUSE_RECT_USER,


} MOUSE_RECT_TYPE;

relative_box
   relative sense rectangle (relative to parameter to register function) .
cursor
   Cursor to display when over this window.
help_id
   Pop-up Help Id.
mouse_flags
  One or more mouse flags.
event_id
   Event to generate if mouse_flags conditions met.
mouse_function
   Function to call if mouse_flags conditions met.
api_data
  Unused.

Example

See SDK.Attitude.cpp for an example of the use of this structure.

Remarks

None.

See Also

• C++ Gauges Function Reference
• Structures

Creating a Gauge using XML and C++

The Cabin Comfort sample demonstrates how to link an XML definition of a gauge, with underlying C++ code.

Running the Cabin Comfort sample

To get the sample to work go through the following steps:

1. Navigate to the Panels and Gauges SDK\Mixed Mode Sample folder.
2. Open up the Cabin_Comfort solution in Visual Studio, and build the project. Copy the CabinComfort.dll from the Release or Debug folder (whichever you selected to build) to the Flight Simulator X root folder.
3. Copy the CabinComfort cabinet file to the Flight Simulator X\Gauges folder.
4. Copy the panel file to the Flight Simulator X\SimObjects\Airplanes\Lear45\panel folder.
5. Either copy the dll.xml file to the Documents and Settings\<user>\Application Data\Microsoft\FSX folder, or, if the dll.xml file already contains information on dlls you wish to keep, edit the dll.xml file by adding the following:

Now the sample is ready to run. Load up Flight Simulator X, select the Lear 45, and Fly Now! Open up the Cabin panel from the menus, and you should see a screen similar to the following image:

The sample is a very simple gauge, evaluating how comfortable the passengers are based on the cabin temperature, bank angle, activity of the attendants, and state of the restroom. The cabin temperature is controlled from the gauge, click the red rectangle to increase the temperature, and the blue rectangle to decrease it.

Key Steps in Creating the Cabin Comfort sample

The steps in building a gauge system combining XML and C++ can be done in a different order than described here, but the following steps provide a logical process to go about creating such a gauge. One of the advantages of combining XML and C++ is that the gauge graphics can be created with the assistance of the ACE tool, described in the Creating XML Gauges document, which considerably speeds up the trial and error process.

Step 1: Create the XML component of the gauge

Use the ACE tool to help create a great looking gauge. The only parts of the XML gauge that communicate with the C++ component are the evaluated strings. A name for the C++ component needs to be decided upon (the word "CABIN" in the sample), and also names for the variables that are going to be communicated (either read or write). For the Cabin Comfort sample, the evaluated strings are the following:

Test and refine the XML as much as possible before coding the C++ component.

Step 2: Creating a property table for the gauge variables

In the code snippets shown below, from the Cabin_Comfort.cpp file, note the definition of the callback name "CABIN", and the names of all the variables, exactly match those in the XML code from Step 1.

Step 3: Initialize the variables and the property table

Examine the CABINGaugeCallback class, which inherits the IGaugeCCallback class defined in gauges.h. The simplest way of initializing any variables is to do it in the creation function of this class.

Notice though that the property table defined in Step 2 is initialized in the creation function for CABINPanelCallback. If a string is the units of a variable, set the value to UNITS_STRING in the property table, otherwise set it to UNITS_UNKNOWN. The following code then finds all the unknown units and finds the enumeration value for the units. This is necessary as the actual enumeration values for any units are not exposed, and may change in future versions. By calling get_units_enum this initialization code is made more robust.

Step 4: Getting and Setting variables

Notice there are two methods for both getting and setting property table values. One method handles strings, the other numerical values. The CabinTemperature property is the only one that can be set from the gauge controls in the Cabin Comfort sample, and the code to do this follows:

Step 5: Updating Variables

The CABINGaugeCallback::Update() method is called optimally on a cycle of 18Hz (18 times per second), however it should be pointed out that the actual frequency can be somewhat lower than this, as optimizations are made to maintain frame rates. This function is the right place to put code to change variables that is not dependant on a get or set call. For some gauges this method may well not contain any code at all.

Step 6: Handle the modules initialization and termination

Two very important methods are module_init and module_deinit. The code for these is shown below. These methods are called when the dll is created and removed respectively. Notice in particular the Panels pointer, shown in bold, that is set to NULL. This value is set by the DLL launch code.

Step 7: Export the initialization, termination and Panels pointer correctly

A key component of the gauge project is the Cabin_Comfort_Def.def definition file. This contains the following:

This small piece is vital, as it exports the initialization and termination method names in an undecorated format, and provides the pointer to the Panels data that is absolutely required to be set when the dll is loaded.

Step 8: Compile, Run and Test the DLL gauge

The C++ project should compile into a dll. Follow the steps for running the Cabin Comfort sample to test your own gauge, including adding a <Launch.Addon> section for it to the DLL.XML file. Make sure to place all the different components in the correct folders.