Creating a Gauge File, the Gauge DLL

A gauge file is a Windows DLL with the extension .gau. The gauge DLL is loaded by the Panel system. The Panel system interacts with each gauge using the exported interface defined by the gauge header file. The interface used by the gauge consists of a list of drawing elements and the exported functions used to manage the gauge.

To compile a fully functioning gauge

  1. Create a gauge file.
    This step includes creating the drawing elements; specifying other actions (such as failures, mouse events, highlighting, and so on); creating functions that interact with the Panel system, including the appropriate callbacks; and creating a gauge header.

  2. Create a drawing element list that includes at least one drawing element (see the topic Using Drawing Elements).

  3. Call the exported functions you need to manage your gauge (see the topic Using Exported Functions).

The gauge header is a GAUGEHDR structure that defines the interface used by the Panel system to control the gauge DLL. Each gauge DLL must define a gauge header. The following is the structure definition of a gauge header:

typedef structGAUGEHDR

{

UINT32gauge_header_version;

char*gauge_name;

PPELEMENT_HEADERelements_list;

PQUERY_ROUTINEquery_routine;

PINSTALL_ROUTINEinstall_routine;

PINITIALIZE_ROUTINEinitialize_routine;

PUPDATE_ROUTINEupdate_routine;

PGENERATE_ROUTINEgenerate_routine;

PDRAW_ROUTINEdraw_routine;

PKILL_ROUTINEkill_routine;

PVOIDresource_file_handle;

UINT32size_x_mm;

UINT32size_y_mm;

floatx_adjust;

floaty_adjust;

PAWINDwindow;

PPANEL_WNDpanel_window_info;

PIXPOINTposition;

} GAUGEHDR, *PGAUGEHDR, **PPGAUGEHDR;

You must export the gauge header to expose the gauge interface to the Panel system. Use the GAUGE_HEADER macro to create and export the GAUGEHDR. The GAUGE_HEADER macro creates the GAUGEHDR, filling in the unique members of the structure. 

The following is the syntax for the GAUGE_HEADER macro:

#define GAUGE_HEADER(version, size, name, element_list)

The GAUGE_HEADER macro has these members:

Member Description
version Must be set to GAUGE_HEADER_VERSION.
size Specifies the X-axis size of the gauge, in millimeters.
name Specifies the name of the gauge.
element_list Pointer to the first drawing element in the list of elements. See the topic Using Drawing Elements.

The GAUGE_HEADER 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.

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

chargauge_name[] = "Cessna_182.OMI\0";

'List will be defined later in this file.

extern PELEMENT_HEADER list;

GAUGE_HEADER(GAUGE_HEADER_VERSION, 49, gauge_name, &list);

To use the GAUGE_HEADER macro, you must include the exported functions listed in the topic Using Exported Functions, in your C implementation.

The other GAUGE_HEADER macro fields are set automatically at load-time based on panel information and other factors. You can't set these fields at compile-time because they'll be overwritten with new values when the gauge is loaded.