Reference

XML Gauges

Contents
Related Links

Overview

The XML Gauge References provides further details on XML Gauge properties.


XML Gauge Reference

This section lists all the elements and objects that can make up a gauge, and describes how to write scripts when dynamic calculations are needed.

Accessing Variables

There are many different systems in the Prepar3D simulation from which variables can be retrieved and set to new values or even created. Accessing variables is crucial for scripting as it is one of the sole ways that the script can interact with the Prepar3D simulation and perform useful tasks. See the Variable Overview for more information about which systems support variable access and the string format that is required to access them.

Scripting

Values of some elements require calculated expressions, or scripts. Typically these expressions define what a needle or numeric display shows. In their simple form, these expressions are the names of simulation parameters and the units in which the element requires the value, enclosed in parentheses. In the following example, a Reverse Polish Notation (RPN) expression returns the value of the INDICATED ALTITUDE parameter, in feet:


(A:INDICATED ALTITUDE, feet)

The "A" before the semicolon indicates that this parameter is an aircraft variable.

See the Scripting Overview article to see what types of scripting that Prepar3D supports.

Playing Sounds

Sound playback is available in any script, but only in lua. The three sound related lua functions are soundOneShot, soundCreate, and soundSetProperties. Sounds can be played from the vehicle's sound folder or any folder listed in the sound.cfg contained in ProgramData.
For documentation about these sound functions with examples, see the Lua Scripting documentation.

Gauge Objects

Gauge objects are used to specify a complete gauge, including the relevant bitmaps, background, mouse areas, tooltips, and the math to calculate the readings that the gauge should be showing. The actual position of a gauge on the screen is determined in the panel.cfg file.

Property Description
id A string that can be edited to help identify the object.
ArtDirectory The absolute or relative path to the directory containing all the images for the gauge. Note that this is just for the purposes of the tool, not the simulation. The art should be cabbed up along with the XML files when completed.
Element A list of Elements.
FloatPosition Unused.
Image A list of Images.
KeyMap A list of KeyMaps.
Macro A list of Macros.
MouseArea A list of Mouse areas.
Size Two integers, giving the width and height of the gauge in pixels. This is often the exact size of the background image loaded directly using an Image object.
Update A list of Updates.
Update_When_Hidden Set to True if the gauge should be updated even if it is hidden from view.

Gauge objects can be the parent of Comment objects, Element objects, Image objects, Macro objects, MouseArea objects and Update objects.


Comment Objects

Comment objects are used to add information to the design of the gauge,  to help in the design or maintenance of that gauge, the text will not appear anywhere to a user.

Property Description
id A string that can be edited to help identify the object.
Value The comment string.

Comment objects cannot be the parent of any other object.


Element Objects

Element objects are the most important sub-objects of gauges, and are used to specify all the components of the gauge.

Property Description
id A string that can be edited to help identify the object.
FloatPosition Two floating point numbers, giving the top left hand position of the element relative to the top left hand position (0,0) of the gauge, in pixels.
LeftScript An optional script that evaluates the top left hand X position of the element, and overrides the FloatPosition. (Only called when the gauge is first loaded)
TopScript An optional script that evaluates the top left hand Y position of the element, and overrides the FloatPosition. (Only called when the gauge is first loaded)
Visibility An optional script to evaluate the visibility. For example:
(A:PARTIAL PANEL ELECTRICAL, enum)!
The enum for this variable is (0 = OK, 1= fail, 2 = blank), so in this case the result is inverted by the "!" operator to give 1 = OK and 0 = fail. See the Simulation Variables document for details of all the variables.
SizeScale Float value to scale the size of the element, default is 1.000.
EnablePositionUpdate Optional parameter default to FALSE. When enabled [TRUE], the LeftScript and TopScript of the Element Object will be evaluated on every update.

Element objects can be the parent of  Comment objects, Arc objects, Circle objects, ClipRect objects, CustomDraw objects, Element objects, Ellipse objects, Image objects, GaugeText objects, HorizontalLine objects, MaskImage objects, Pie objects, Polygon objects, PolyLine objects, Rectangle objects, Rotation objects, Select objects, Shift objects, Texture objects, and VerticalLine objects.


Arc Objects

Arc objects are used to draw arcs (curved lines) as part of the gauge.

Property Description
id A string that can be edited to help identify the object.
Axis
The x and y co-ordinates of the center of the arc, in pixels.
Bright Set to True if the graphic remains at its normal color at night, otherwise it will be darkened.
Radius Integer radius of the arc, in pixels.
LineWidth Integer line width, in pixels.
LineColor See Gauge Colors.
LineColorScript If used, this overrides LineColor. See Gauge Color Scripts.
StartAngle The integer start angle of the arc, in degrees.
EndAngle The integer end angle of the arc, in degrees.
StartAngleScript Optional script to evaluate the start angle, overriding StartAngle.
EndAngleScript Optional script to evaluate the end angle, overriding EndAngle.
SizeScaleScript Optional script to evaluate the size scale of the object. Acceptable evaluated values are between [0-1].
LineWidthScript Optional script to evaluate the line width scale of the object. Acceptable evaluated values are between [0-1].

Arc objects can be the parent of Comment objects.


Gauge Colors

Simple line, text and fill colors can be entered as RGB hex values (such as 0xFFFFFF) or text strings. Do not use quotes. See the XML Gauge Colors file for a full list of colors. Note that colors are entered in the format 0xBBGGRR.

Gauge Color Scripts

Scripts can be used to evaluate a color. The same expression evaluation is used as for numerical values, but in this case the script must evaluate to a string containing either the name of the color, or the RGB hex value of the color. In this case strings must be enclosed in single quotes. 

For example, the following scripts evaluate to red if the indicated airspeed is greater than 300 knots, otherwise to blue.

See the XML Gauge Colors file for a full list of colors. And refer to Scripting for full details on writing scripts.


Circle Objects

Circle objects are used to draw circles as part of the gauge.

Property Description
id A string that can be edited to help identify the object.
Axis
The x and y co-ordinates of the center of the circle, in pixels.
Bright Set to True if this component is not to be dimmed at night time.
Radius Integer radius of the circle, in pixels.
FillColor See Gauge Colors. If no fill color is set, only the outline of the circle will be drawn.
FillColorScript If used, this overrides FillColor. See Gauge Color Scripts.
LineWidth Integer line width, in pixels.
LineColor See Gauge Colors.
LineColorScript If used, this overrides LineColor. See Gauge Color Scripts.
SizeScaleScript Optional script to evaluate the size scale of the object. Acceptable evaluated values are between [0-1].
LineWidthScript Optional script to evaluate the line width scale of the object. Acceptable evaluated values are between [0-1].

Circle objects can be the parent of Comment objects.


ClipRect Objects


Property Description
id A string that can be edited to help identify the object.
FloatPosition
Two floating point numbers, giving the top left hand position of the rectangle relative to the top left hand position (0,0) of the parent object, in pixels.
Size Two integers, the width and height of the box in pixels.


CustomDraw Objects

CustomDraw objects are used to provide input to specially written library code (a C or C++ dll) that is to calculate the updating of the gauge element. The GPS system is an example of a complex instrument that requires many CustomDraw objects.

Property Description
id A string that can be edited to help identify the object.
Size
Name
CustomDrawParam List of CustomDrawParam objects.
Bright Set to True if this component is not to be dimmed at night time.

CustomDraw objects can be the parent of Comment objects and CustomDrawParam objects.


CustomDrawParam Objects

CustomDrawParam objects provide name-value pairs to be provided as input to custom gauge library code.

Property Description
id A string that can be edited to help identify the object.
Name

Value

CustomDraw objects can be the parent of Comment objects.


Ellipse Objects

Ellipse objects are used to draw ellipses as part of the gauge.

Property Description
id A string that can be edited to help identify the object.
Axis
The x and y co-ordinates of the center of the ellipse,  in pixels.
Bright Set to True if this component is not to be dimmed at night time.
Height The height of the ellipse in pixels.
Width The width of the ellipse in pixels.
FillColor See Gauge Colors.  If no fill color is set, only the outline of the ellipse will be drawn.
FillColorScript If used, this overrides FillColor. See Gauge Color Scripts.
LineWidth The line width in pixels.
LineColor See Gauge Colors.
LineColorScript If used, this overrides LineColor. See Gauge Color Scripts.
SizeScaleScript Optional script to evaluate the size scale of the object. Acceptable evaluated values are between [0-1].
LineWidthScript Optional script to evaluate the line width scale of the object. Acceptable evaluated values are between [0-1].

Ellipse objects can be the parent of Comment objects.


GaugeText Objects

GaugeText objects are used to write specific text to appear as a reading on the gauge. This is used, for example, with the selected frequency for Com and Nav, with the selected font being Digital.


Property Description
id A string that can be edited to help identify the object.
Alpha Set to True if the image should be interpreted as having an alpha channel.
Axis The x and y co-ordinates of the center of the text, in pixels. If rotation is applied to the text, then this is the point that it will rotate around.
BackgroundColor See Gauge Colors. If a background color is not set, and Transparent is set to True, then the text will be drawn without any surrounding rectangle. The default background color is black.
BackgroundColorScript If used, this overrides BackgroundColor. See Gauge Color Scripts.
BlinkCode Script that evaluates how the text should blink. Note that the blinking will not occur in the tool.
Bold Set to True for bold text.
Bright Set to True if this component is not to be dimmed at night time.
Caption Unused.
Charset One of: DEFAULT, ANSI, SYMBOL or OEM.
DegreesPointsTo The starting value for a rotation, in degrees.
FontFace Text font to use, for example: ARIAL, HELVETICA, COURIER NEW, TIMES NEW ROMAN.
FontFaceLocalize Set to True to indicate that a localized (local language) font should be searched for.
FontColor See Gauge Colors.
FontColorScript If used, this overrides FontColor. See Gauge Color Scripts.
FontHeight Height of the characters in pixels.
FontHeightScript If used, overrides FontHeight. Script to evaluate the font height.
FontWeight Integer, 0 for normal text. Increase for bolder text.
GaugeString The text to be displayed. If the text is to be shown as-is, do not put it in quotes, just enter the text. This can also be a script, in which case precede the script with a  % mark to indicate that the contained text should be evaluated as a normal script. For example,
%(A:GENERAL ENG RMP:1, rpm)%!d!
The %!d! at the end specifies that the result should be interpreted as a decimal number. There should not be a space between the % and the !.
The other options are !f! for a float and !s! for a string. Decimal and floating point numbers can be formatted further, see the examples below.
The standard escape codes, such as \n for newline and \t for tab, work in gauge strings, along with a number of special escape codes.
See the table of examples below.
HorizontalAlign One of:
LEFT
CENTER
RIGHT
Italic Set to True for italic text.
LineSpacing Line spacing in pixels.
Luminous Set to True if the text illuminates at night.
PointsTo One of:
NORTH
EAST
SOUTH
WEST
ScrollY An optional script that is used to determine by how many pixels the text should be scrolled.
Size Two integers, the width and height of the text box in pixels.
HeightScript Optional script that overrides Size, calculating the height of the text box.
WidthScript Optional script that overrides Size, calculating the width of the text box.
StrikeThrough Set to True for strikethrough text, for example STRIKETHROUGH
Tabs Describes the location of tab stops for the string.
Transparent Set to True if the text is not to be displayed with a surrounding rectangle of the background color.
Underline Set to True for underlined text.

GaugeText objects can be the parent of AlternateColor and AlternateFont objects, and Comment and Image objects.


AlternateColor

Changes a section of the text to a different color. Refer to the Escape Codes section on the codes to use to turn an alternate font color on and off.

Property Description
id A string that can be edited to help identify the object.
FontColor New color for the text. See Gauge Colors.

AlternateColor objects can be the parent of Comment objects.


AlternateFont

Changes a section of the text to a different font. Refer to the Escape Codes section on the codes to use to turn an alternate font on and off. Note that there can be several alternate fonts.

Property Description
id A string that can be edited to help identify the object.
Charset One of: DEFAULT, ANSI, SYMBOL or OEM.
FontFace Text font to use, for example: ARIAL, HELVETICA, COURIER NEW, TIMES NEW ROMAN.
FontFaceLocalize Set to True to indicate that a localized (local language) font should be searched for.
FontHeight Height of the characters in pixels.
FontWeight Integer, 0 for normal text. Increase for bolder text.
Bold Set to True for bold text.
Ital Set to True for italic text.

AlternateFont objects can be the parent of Comment objects.


HorizontalLine Objects

HorizontalLine objects are used to draw horizontal lines as part of the gauge.

Property Description
id A string that can be edited to help identify the object.
Axis
The x and y co-ordinates of the center of the line, in pixels. If rotation is applied to the line, then this is the point that it will rotate around.
Bright Set to True if this component is not to be dimmed at night time.
Width Width of the line in pixels.
LineWidth Line thickness in pixels.
LineColor See Gauge Colors.
LineColorScript If used, this overrides LineColor. See Gauge Color Scripts.
SizeScaleScript Optional script to evaluate the size scale of the object. Acceptable evaluated values are between [0-1].
LineWidthScript Optional script to evaluate the line width scale of the object. Acceptable evaluated values are between [0-1].

HorizontalLine objects can be the parent of Comment objects.


MaskImage Objects

MaskImage objects are used to provide see-through effects. If the pixel within a mask image is set to 0x000000 then the background image pixel will be displayed. If the pixel of the mask image is set to 0x010101 then the pixel from the associated image will be displayed. If the pixel of the mask image is set to anything else, then it will be the pixel displayed (in the format 0xRRGGBB, not the 0xBBGGRR format used for gauge color scripts).

Property Description
id A string that can be edited to help identify the object.
Axis The x and y co-ordinates of the center of the mask, in pixels. If rotation is applied to the mask, then this is the point that it will rotate around.
Name Filename of the image to use as the mask
Transparent Set to True if the color black (0x000000) is to be treated as transparent.

MaskImage objects can be the parent of Comment objects.

Mask images allow a gauge designer to create a hole in a layer so that a piece of the gauge can be seen through another piece.  Through the window in the gauge background the rotating airspeed card is visible. There are two ways to generate the hole:


  1. Specify a transparent area in a static image that also displays other things (for example, tick marks and other graphics associated with a gauge)
  2. Create a mask image that is used purely to specify which area of its associated element to display.  This is similar to specifying a transparent area in a static image, except that no visible graphics need to be associated with this type of mask. For example (note black is transparent in all images):

Note that the magenta used in the Mask Image is actually of RGB value 1,1,1 (which is very close to black). When you see these images in drawing programs, they appear completely black. The apparent advantage of using method 2 is size savings. A monochrome bitmap can be used to generate the two color mask image.

The following shows a simple example of the XML generated by including a mask image. The <MaskImage> element is used as a sub-element of a gauge <Element>. In other words, the <MaskImage> and <Image> elements are siblings.


<Element>
  <Position X="18" Y="18"/>
  <MaskImage Name="ap_ahi_window.bmp">
    <Axis X="61.5" Y="61.5"/>
  </MaskImage>
  <Image Name="ap_ahi_dial.bmp" PointsTo="North">
    <Axis X="59" Y="59"/>
  </Image>
  <Rotate>
    <Value Minimum="-90" Maximum="90">(A:Attitude indicator bank degrees:1,degrees) -90 max 90 min</Value>
  </Rotate>
</Element>

Pie Objects

Pie objects are used to draw pies as part of the gauge.

Property Description
id A string that can be edited to help identify the object.
Axis
The x and y co-ordinates of the center of the pie, in pixels.
Bright Set to True if this component is not to be dimmed at night time.
Radius Radius of the pie in pixels.
LineWidth Width of the line in pixels.
FillColor See Gauge Colors. If no fill color is set, only the outline of the pie will be drawn.
FillColorScript If used, this overrides FillColor. See Gauge Color Scripts.
LineColor See Gauge Colors.
LineColorScript If used, this overrides LineColor. See Gauge Color Scripts.
StartAngle The integer start angle of the arc, in degrees.
EndAngle The integer end angle of the arc, in degrees.
StartAngleScript Optional script to evaluate the start angle, overriding StartAngle.
EndAngleScript Optional script to evaluate the end angle, overriding EndAngle.
SizeScaleScript Optional script to evaluate the size scale of the object. Acceptable evaluated values are between [0-1].
LineWidthScript Optional script to evaluate the line width scale of the object. Acceptable evaluated values are between [0-1].

Pie objects can be the parent of Comment objects.


Polygon Objects

Polygon objects are used to draw polygons as part of the gauge. The shape of the polygon is determined by any number of Points

Property Description
id A string that can be edited to help identify the object.
Axis
The x and y co-ordinates of the center of the polygon, in pixels. If rotation is applied to the polygon, then this is the point that it will rotate around.
Bright Set to True if this component is not to be dimmed at night time.
Point List of Points.
FillColor See Gauge Colors. If no fill color is set, only the outline of the polygon will be drawn.
FillColorScript If used, this overrides FillColor. See Gauge Color Scripts.
LineWidth Line width in pixels.
LineColor See Gauge Colors.
LineColorScript If used, this overrides LineColor. See Gauge Color Scripts.
LineWidthScript Optional script to evaluate the line width scale of the object. Acceptable evaluated values are between [0-1].

Polygon objects can be the parent of Comment objects, and Point objects.


Point Objects

Point objects are used to specify the outline of a Polygon or Polyline object.

Property Description
id A string that can be edited to help identify the object.
FloatPosition Two floating point numbers identifying the point relative to the top left hand corner of the parent object.

Point objects can be the parent of Comment objects.


Polyline Objects

Polyline objects are used to draw polylines as part of the gauge. The shape of the polyline is determined by any number of Points. The polyline is not filled in with the fill color. If  filling is required, use a Polygon object.

Property Description
id A string that can be edited to help identify the object.
Axis
The x and y co-ordinates of the center of the polyline, in pixels. If rotation is applied to the polyline, then this is the point that it will rotate around.
Bright Set to True if this component is not to be dimmed at night time.
Point List of Points.
LineWidth Line width in pixels.
LineColor See Gauge Colors.
LineColorScript If used, this overrides LineColor. See Gauge Color Scripts.
LineWidthScript Optional script to evaluate the line width scale of the object. Acceptable evaluated values are between [0-1].

Polyline objects can be the parent of Comment objects, and Point objects.


Rectangle Objects

Rectangle objects are used to draw rectangles as part of the gauge.

Property Description
id A string that can be edited to help identify the object.
Axis
The x and y co-ordinates of the center of the rectangle, in pixels. If rotation is applied to the rectangle, then this is the point that it will rotate around.
LineWidth Line width in pixels.
Bright Set to True if this component is not to be dimmed at night time.
Width Width of the rectangle in pixels.
WidthScript Optional script to calculate the width of the rectangle, overriding Width.
Height Height of the rectangle in pixels.
HeightScript Optional script to calculate the height of the rectangle, overriding Height.
LineColor See Gauge Colors.
LineColorScript If used, this overrides LineColor. See Gauge Color Scripts.
FillColor See Gauge Colors.  If no fill color is set, only the outline of the rectangle will be drawn.
FillColorScript If used, this overrides FillColor. See Gauge Color Scripts.
Transparency A value between 0 and 1, used for alpha-blending.
LineWidthScript Optional script to evaluate the line width scale of the object. Acceptable evaluated values are between [0-1].

Rectangle objects can be the parent of Comment objects.


Rotation Objects

Rotation objects are used to display readings that rotate in nature, such as dials. If the movement of the needle of the dial is not linear, then add a NonlinearityTable object as a child of this object.

Property Description
id A string that can be edited to help identify the object.
Expression One Expression. This evaluates to the number of radians to rotate the element.
FailureTable Optional FailureTable.
PointsTo
The starting position, often of a needle.
One of:
NORTH
EAST
SOUTH
WEST
DegreesPointsTo should not be used if this is specified.
DegreesPointsTo If PointsTo is not specified, this gives the starting point for the rotation, in degrees.

Rotation objects can be the parent of Comment objects, Delay objects, Expression objects, FailureTable objects, and NonlinearityTable objects.


Delay Objects

Delay objects are used to ensure the movement of a needle (or other indicator) is smooth, and does not jump. The DelayValue in effect represents the maximum speed of the movement. For example, if DelayValue is set to 120, and DelayUnits to DEGREES_PER_SECOND, then a needle can only move 120 degrees per second (or 4 degrees per frame at a frame rate of 30 fps), even if the evaluated value jumps from 0 to 180 in one calculation.

Property Description
id A string that can be edited to help identify the object.
DelayValue The length of the delay.
DelayUnits One of:
PIXELS_PER_SECOND
VALUE_PER_SECOND
DEGREES_PER_SECOND
RADIANS_PER_SECOND

Delay objects can be the parent of Comment objects.


Expression Objects

Expression objects are used to evaluate expressions, often giving the actual reading that should be displayed. Simple instruments like the altimeter require very simple evaluation scripts, but complex instruments like a GPS system will require complex scripts and a very good understanding of  the scripting languages and their semantics, described in Scripting.

Property Description
id A string that can be edited to help identify the object.
Minimum A fixed minimum value, which will be the result if the script evaluates to a lower value than this. The default value of -9999999 indicates that this values is not being used.
Maximum A fixed maximum value, which will be the result if the script evaluations to a higher value than this. The default value of -9999999 indicates that this values is not being used.
Script
The evaluation script. See Scripting for a full explanation of how to write scripts. A full list of internal simulation variables names that can be used within scripts can be found in the Simulation Variables document.

Expression objects can be the parent of Comment objects.


FailureTable Objects

FailureTable objects are used to contain the list of failures, with the appropriate actions, that apply to an element of the gauge.

Property Description
id A string that can be edited to help identify the object.
Failure List of Failures.

FailureTable objects can be the parent of Failure objects.


Failure Objects

Failure objects are used to link failure keys with a certain action. Failures can be initiated by the user through the Failures dialogs of Prepar3D, or can come from actions set by Scenarios (see the Scenario creation document).

Property Description
id A string that can be edited to help identify the object.
Fail_Key
One of:
NONE
SYSTEM_ENGINE

SYSTEM_PITOT_STATIC

SYSTEM_VACUUM
GAUGE_ADF

GAUGE_AIRSPEED

GAUGE_ALTIMETER,
GAUGE_COMMUNICATIONS

GAUGE_FUEL_INDICATORS

GAUGE_GYRO_HEADING
GAUGE_MAGNETIC_COMPASS
GAUGE_NAVIGATION_VOR1
GAUGE_NAVIGATION_VOR2

GAUGE_TRANSPONDER
GAUGE_TURN_COORDINATOR
GAUGE_VERTICAL_SPEED
GAUGE_ELECTRICAL_PANEL
GAUGE_ELECTRICAL_AVIONICS
GAUGE_COMMUNICATIONS
Fail_Action
One of:
None
Freeze,
Zero
Cover
NoDraw

Failure objects cannot be the parent of other objects.


NonLinearityTable Objects

NonLinearityTable objects are used to describe the readings from instruments where there is not a linear relationship between the value and the display. For example, higher speeds on airspeed indicators are often much closer together on the dial than lower speeds. Nonlinearity tables can apply to both Rotation objects and Shift objects.

Property Description
id A string that can be edited to help identify the object.
NonLinearityEntry
List of NonlinearityEntry objects.

NonLinearityTable objects can be the parent of NonlinearityEntry objects.


NonlinearityEntry Objects

NonLinearityEntry objects are used to link one value of the related expression to one position of the element (for example, the airspeed indicator needle). If the expression result falls exactly on the ExpressionResult, then the position from this entry object is taken. If the expression result falls between the results for two NonlinearityEntry objects then the position of the needle is calculated linearly between these two positions. For this reason, to get the most accurate needle positioning, enter a good number of NonlinearityEntry objects.

Non-linearity values should be listed as they appear on the gauge, clockwise around the face, or left to right. If gauge values increase when rotating clockwise (or moving left to right), values in the non-linearity table should start at the minimum and increase. If gauge values decrease when rotating clockwise, then values in the table should start with the maximum and decrease.

Only one of Degrees, Radians or FloatPosition should be used.

Property Description
id A string that can be edited to help identify the object.
ExpressionResult The value of the related Expression.
Degrees Rotation of the element in degrees, or -99999.00 if this is not used.
Radians
Rotation of the element in radians, or -99999.00 if this is not used.
FloatPosition The X and Y offset, that defines the slope for the indicator to take, or 0,0 if this is not used.

NonLinearityEntry objects can be the parent of Comment objects.


Select Objects

Select objects are used to select one from a range of cases, depending on the evaluation of the expression. A simple example of this are displays that change when a setting is on or off (the image used for a light switch, for example).

Property Description
id A string that can be edited to help identify the object.
Expression The Expression to evaluate.
Case A list of usually two or more Case objects.

Select objects can be the parent of Comment, Expression, FailureTable and Case objects.


Case Objects

Case objects are used to provide the individual cases to the parent Select object. Each Case object will usually have an associated Image or GaugeText object, to be displayed if this particular case applies.

Property Description
id A string that can be edited to help identify the object.
ExpressionResult The value of the related Expression. Can be as simple as 0 or 1, for off and on.
Minimum  
Maximum

Case objects can be the parent of Comment objects, Image objects and GaugeText objects.


Shift Objects

Shift objects are used to display readings that are linear in nature, the bounds being set by the Minimum and Maximum values for the Expression.

Property Description
id A string that can be edited to help identify the object.
Minimum The minimum value that the Expression can evaluate to.
Maximum The maximum value that the Expression can evaluate to.
Script The script to be used to calculate the shift value.

Shift objects can be the parent of Comment objects, Delay objects, NonlinearityTable objects, Expression objects, and FailureTable objects.


VerticalLine Objects

VerticalLine objects are used to draw vertical lines as part of the gauge.

Property Description
id A string that can be edited to help identify the object.
Axis If rotation is applied this is the point that it will rotate around.
Height
Height of the line in pixels.
LineWidth Width of the line in pixels.
LineColor See Gauge Colors.
LineColorScript If used, this overrides LineColor. See Gauge Color Scripts.
SizeScaleScript Optional script to evaluate the size scale of the object. Acceptable evaluated values are between [0-1].
LineWidthScript Optional script to evaluate the line width scale of the object. Acceptable evaluated values are between [0-1].

VerticalLine objects can be the parent of Comment objects.


Texture Objects

Texture Objects are used to insert existing render-to-texture onto the gauge.

Property Description
id A string that can be edited to help identify the object.
Name Identify the texture to be inserted.
Width Width of the texture
Height Height of the texture

Point objects can be the parent of Comment objects.


Image Objects

Image objects are used to add graphics from image files to the gauge.

Property Description
id A string that can be edited to help identify the object.
Transparent Set to True if the color black (0x000000) is to be treated as transparent.
Alpha Set to True if the image has an alpha channel.
Axis The x and y co-ordinates of the center of the image, in pixels. If rotation is applied to the image, then this is the point that it will rotate around.
Bright Set to True if this component is not to be dimmed at night time.
Luminous Set to True if a luminosity factor is to be applied to the image. The alpha channel of the image is used, in this case, to determine what section of the image is to be illuminated when panel lights are on. An alpha value of 0 gives the maximum luminosity. To clarify, lighting effects are applied to the entire panel, but the luminous color is applied to the section of the gauges specified by this alpha channel. The luminous colors are specified in the panel.cfg file, see the Panel Configuration File document ([color] section) for more details and an example of luminous colors.
Bilinear Set to True if a bilinear algorithm is to be applied to the image (this is similar to anti-aliasing).
Name The filename for the image (which should be in the ArtDirectory specified by the Gauge object).

Image objects can be the parent of Comment objects.


KeyMap Objects

Key map objects contain a number of Trigger objects, mapping key strokes or key events to scripts.

Property Description
id A string that can be edited to help identify the object.

KeyMap objects can be the parent of one or more Trigger objects.


Trigger Objects

Trigger objects activate a script if a certain key is pressed or key event occurs. Typically only one of KeyEvent or KeyboardKey would be specified.

Property Description
id A string that can be edited to help identify the object.
KeyEvent One of the KEY_.... events defined in gauges.h.
KeyboardKey Can be one of ASCII or AlphaNumeric, or any of of the keys defined in Key Strings.
Visibility An expression that should evaluate to True or False.
Script The script to be run when the key event occurs.

Trigger objects cannot be the parent of any other object.


Macro Objects

Macro objects are used to provide an efficient method of re-using common scripts. They are particularly useful in complex instruments such as a GPS system.

Property Description
id A string that can be edited to help identify the object.
Name The name of the macro to be used within scripts. This name can be used within evaluated expressions, and should be unique.
MacroValue The script of the macro.

Macro objects can be the parent of Macro objects and Comment objects.

Macro Examples

The following example defines a template for a generic switch by uses a macro.  This switch toggles the engine primer for engine one, but by simply changing the MacroValue line, this XML could be reused to toggle any Gauge, Local, or Simulation Variable.

<?xml version="1.0" encoding="UTF-8"?>
<SimBase.Document Type="AceXML" version="1,0" id="MSwitch">
    <Descr>AceXML Document</Descr>
    <Filename>Switch.xml</Filename>
    <SimGauge.Gauge id="Gauge" Name="Switch">
        <Size>25,25</Size>
       <Macro Name="SWITCH_FLIPPED">
            <MacroValue>A:RECIP ENG PRIMER:1,bool</MacroValue>
       </Macro>
        <Element id="Element">
            <Select id="Select">
                <Expression id="Expression">
                    <Script>(@SWITCH_FLIPPED)</Script>
                </Expression>
                <Case id="Case">
                    <ExpressionResult>0.000</ExpressionResult>
                    <Image id="sw_down.bmp" Name="sw_down.bmp">
                        <Transparent>True</Transparent>
                    </Image>
                </Case>
                <Case id="Case">
                    <ExpressionResult>1.000</ExpressionResult>
                    <Image id="sw_up.bmp" Name="sw_up.bmp">
                        <Transparent>True</Transparent>
                    </Image>
                </Case>
            </Select>
        </Element>
        <MouseArea id="MouseArea">
          <FloatPosition>0.000,0.000</FloatPosition>
          <CursorType>Hand</CursorType>
          <HelpId>HELPID_GAUGE_AVIONICS_SWITCH</HelpId>
          <MouseClick id="MouseClick">
             <Script>(@SWITCH_FLIPPED) ! (>@SWITCH_FLIPPED)</Script>
          </MouseClick>
        </MouseArea>
    </SimGauge.Gauge>
</SimBase.Document>

Macros can also take parameters and can be nested within macros:

<Macro id="Macro" Name="Var1">
   <MacroValue> L:Var1, number </MacroValue>
</Macro>
<Macro id="Macro" Name="Var2">
   <MacroValue> L:Var2, number </MacroValue>
</Macro>
<Macro id="Macro" Name="Var3">
   <MacroValue> L:Var3, number </MacroValue>
</Macro>
<Macro id="Macro" Name="MAX">
   <MacroValue> @1 @2 > if { @1 quit } @2  </MacroValue>
</Macro>
<Macro id="Macro" Name="STORE_MAX_INTO_VAR3">
   <MacroValue> @MAX((@Var1),(@Var2))(>@Var3)) </MacroValue>
</Macro>

MouseArea Objects

MouseArea objects are used to define a rectangular area where the mouse button can be used to link to an event through a MouseClick object. MouseArea objects can be the parent of other MouseArea objects, so it can be useful to define a large area for the help ID text to appear, and smaller areas that cover the use of controls of the gauge. There should be only one high level MouseArea for a gauge.

Property Description
id A string that can be edited to help identify the object.
Visibility Expression that evaluates to True or False, determining the visibility of the element.
FloatPosition The x any y position of the top left hand corner of the mouse area, relative to the top left hand corner of the mouse area's parent object.
Size The width and height of the mouse area, in pixels.
CursorType The cursor image to display when the user's mouse cursor is within the area. One of:
None
Normal
UpArrow
DownArrow
LeftArrow
RightArrow
Hand
Crosshair
Grab
HelpId The ID string that identifies the help text to display when the user's mouse cursor is within the area. For example, HELPID_GAUGE_KOHLSMAN_KNOB. See the Help IDs document for a full list of IDs and details on the strings displayed.

MouseArea objects can be the parent of Comment objects, MouseArea objects, Tooltip objects and MouseClick objects.


Tooltip Objects

Tooltip objects are used to display text to help the user when they mouse over certain areas.

Property Description
id A string that can be edited to help identify the object.
DefaultId
The ID of the tooltip text when the user has not selected a units of measure preference. For example: TOOLTIPTEXT_ALTIMETER_FEET. A full list of tooltip text IDs can be found in the Tooltips document, along with details of the strings that are displayed.
MetricId
The ID of the tooltip text when the user has selected a preference for Metric measurements. For example, TOOLTIPTEXT_ALTIMETER_METERS. If this is left blank the DefaultID applies.
EnglishId
The ID of the tooltip text when the user has selected a preference for Imperial measurements. For example, TOOLTIPTEXT_ALTIMETER_FEET. If this is left blank the DefaultID applies.
DefaultScript A default script to use for the tooltip, if DefaultID is not defined.
EnglishScript Tooltip script, if user has selected English units.
MetricScript Tooltip script, if user has selected Metric units.

Tooltip objects can be the parent of Comment objects.


MouseClick Objects

MouseClick objects are used to link mouse clicks with simulation key events, so enabling a user to control the instrument.

Property Description
id A string that can be edited to help identify the object.
KeyEvent The key event that is to occur when the mouse is clicked. For example, KOHLSMAN_DEC or KOHLSMAN_INC. For a full list of key events, see the String name column in the Event IDs document.
Script If used, overrides KeyEvent. A script that evaluates to a single key event.
ClickType One of:
LeftAll
RightAll
MiddleAll
RightSingle
MiddleSingle
LeftSingle
RightDouble
MiddleDouble
LeftDouble
RightDrag
MiddleDrag
LeftDrag
Move
RightRelease
MiddleRelease
LeftRelease
WheelUp
WheelDown
Leave
MouseWheelFlip Set to True if flipping the mouse wheel will trigger the event.
ClickRepeat Set to True if holding the mouse button down will repeat the key event. When ClickRepeat is False, Leave events won't fire until the mouse is released.

MouseClick objects can be the parent of Comment objects. MouseClick events and scripts will be fired for all applicable MouseAreas regardless of nesting order.


Update Objects

Update objects are used to provide time based updates to a gauge. The GPS system is an example of a complex instrument requiring the use of Update objects.

Property Description
id A string that can be edited to help identify the object.
Frequency Integer value indicating how often the update should be run, in updates per second. Enter 1 for the slowest frequency of updates (one per second).
Script The expression script to be evaluated at the time of the update. This script might examine the status of various switches, for example, that change how the instrument works.

Update objects can be the parent of Update objects and Comment objects.


Creating an SPB file

XML gauges, Scenarios and some Autogen files can either be in XML or SPB (Sim-Prop Binary) format. If an XML version of a file is found in the same folder as an SPB file, the SPB file will be loaded in preference to the XML file as the binary format is faster to load that its XML equivalent. Because of this it makes sense to move an SPB file out of the folder where editing work is being done on its XML equivalent.

To create an SPB file, run the simpropcompiler.exe tool, which is in the SDK's root folder. This is a command-line tool, so open a command window and navigate to the SDK\bin folder. If Prepar3D is installed, then enter the following command:

> Simpropcompiler 2spb –symbols C:\Program Files\Lockheed Martin\Prepar3D v4\propdefs\*.xml yourFile.xml yourFile.spb

If Prepar3D is not installed, then enter the following command:


> Simpropcompiler 2spb –symbols <Lockheed Martin\Prepar3D v4 SDK *>\Panels Gauges User Interface\Panels\propdefs\*.xml yourFile.xml yourFile.spb

Note that the full path to the symbols files in the propdefs folder is required (the above examples assume that Prepar3D and the SDK are installed to their default folders), and as the "*.xml" wildcard is used no other XML files should be moved to or created in the propdefs folder. File extensions are required for both the input and output filenames as they can be entered in any order.

To simply validate an XML file without creating an output file, change the keyword 2spb to validate.