register_var_by

register_var_by_name

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

Syntax

void register_var_by_name(
    PVOID  var,
    VAR_TYPE  var_type,
    PSTRINGZ  name
    );

Members

Parameters	Description
`var`	Specifies the address of the variable.
`var_type`	Specifies the type of the variable, one of the enum listed below.
`name`	Specifies the name of the variable. Specify a unique and descriptive name for the variable, such as " `gaugename.variablename`".

var_type 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;

Return Values

This function does not return a value.

Example

static GPS_INFO gps_data;
static TVector<GPS_WP_INFO> *gps_wps;
static GPS_INFO gps_data_request;
static GPS_WP_INFO gps_wps_request[MAX_GPS_WAYPOINTS];
 
if (!gps_wps)
    gps_wps = new TVector<GPS_WP_INFO>;
 
init_gps_var (&gps_data, gps_wps->Address ());
init_gps_var (&gps_data_request, gps_wps_request);
register_var_by_name (&gps_data, TYPE_PVOID, GPS_INFO_PANEL_VARIABLE_NAME);
register_var_by_name (&gps_data_request, TYPE_PVOID, GPS_REQUEST_PANEL_VARIABLE_NAME);
 
unregister_var_by_name (GPS_REQUEST_PANEL_VARIABLE_NAME);
unregister_var_by_name (GPS_INFO_PANEL_VARIABLE_NAME);
if (gps_wps) {
    delete gps_wps;
    gps_wps = NULL;
    }

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.