Creating XML Gauges


Contents
Related Links

Overview

The ACE resource tool can be used to build a number of components for Prepar3D, this document explains how to use the tool to help build gauges. The term gauge is used to describe all the instruments in an aircraft's cockpit.

The document is divided into two sections, a tutorial for new users of the gauge system, and a reference containing information on all the options available.


XML Gauge Tutorial

This tutorial goes through all the steps required to add a panel to an aircraft, and add existing and new gauges to that panel. The tutorial also covers creating a cabinet file for the gauges, and finally testing them.


Step 1: Setup

The building and testing of gauges requires a lot of trial and error, so it is a good idea to set up the tools required to be very convenient for frequent use. You will find that you will be building gauges, testing them in the simulation, finding many errors, then repeating this process for some time. The following set up makes this process reasonably quick.

  1. Check the ACE.exe tool runs from the Panels and Gauges SDK folder. It requires the simpropace.dll, which should be in the same folder, and the latest version of the DirectX® 9 runtime (install this from the Microsoft DirectX website if necessary). Close the tool for now, it is not needed until Step 4.
  2. Create a directory, under Documents, called something appropriate like New Gauges.
  3. Create a subdirectory of New Gauges, with the name of the cabinet file you will eventually create containing the gauges and their artwork, for this tutorial call this subdirectory Test Gauges. Place the cabbing tools handy (see the Creating Cabinet Files documentation), perhaps under New Gauges, but not under Test Gauges.
  4. Have your artwork creation tools handy, though for this tutorial Paint will suffice.
  5. In order to receive run-time error messages on gauge scripts add the following line to the [Panels] section of the Prepar3D.cfg file (found in the C:\Users\%username%\Application Data\Lockheed Martin\Prepar3D v3 folder):
    [Panels]
    GaugeDevDebug=1

Step 2: Specify the Gauges

For this tutorial we are going to implement the following, for the basic Mooney Bravo aircraft:

The artwork for these gauges is not going to look great. One method of approaching gauge development is to complete the gauge mechanics first, using simple rectangles and circles as artwork, and then when the gauge works correctly, replace the simple art with carefully drawn images.


Step 3: Add the new Panel

Unlike gauges, panels are particular to an aircraft. Go into the SimObjects\Aircraft folder, then find the Mooney Bravo, then in the panel directory, open up the panel configuration file (panel.cfg) in a text editor (Notepad is quite sufficient for this). For full details of the panel configuration file refer to the Panel Configuration Files document (though you will not need to for this tutorial).

In order to add a new panel we must first make a single entry under Window titles, so add the line shown in bold below, so that the first lines of the configuration file now look like this:

// Panel Configuration file
// Mooney Bravo
// Copyright (c) 2009-2015 Lockheed Martin Corporation.  All rights reserved.


[Window titles]
Window00=Main Panel
Window01=Radio Stack
Window02=GPS
Window03=Annunciator
Window04=Overhead Panel
Window05=Mini Panel
Window06=Test Panel

[VIEWS]
VIEW_FORWARD_DIR=2.000, 0.000, 0.000

The name Test Panel will now appear in Prepar3D. To add the panel itself , find the entry for Mini Panel, and add the lines shown in bold below:

[Window05]
Background_color=0,0,0
size_mm=550,90
windowsize_ratio=1.6
position=7
visible=1 ident=MINIPANEL
no_luminous=1 child_3d=1

gauge00=Mooney_Bravo!Airspeed, 0,6, 81,78
gauge01=Mooney_Bravo!Turn Coordinator, 90, 6, 78,76
gauge02=Mooney_Bravo!Attitude, 180, 0, 93,87
gauge03=Mooney_Bravo!HSI, 283,0, 91,85
gauge04=Mooney_Bravo!Altimeter, 386,5, 73,76
gauge05=Mooney_Bravo!Vertical Speed, 470,6,77,77

[Window06]
file=Test_Panel_Background.bmp
position=6
size_mm=240,240
visible=00
ident=10001
gauge00=Mooney_Bravo!Airspeed, 5, 5, 81,78
gauge01=TestGauges!FuelPressure,     100, 5
gauge02=TestGauges!Stopwatch,        75,95

[VCockpit01]]
ffile=Mooney_Panel_G1000_Decals_Gray.bmp
size_mm=1024,1024

The position simply refers to the default position where the panel will appear on the screen (6 is bottom left). The size_mm field is a misnomer, it does not represent millimeters, but arbitrary design units. However as it is so much easier to create panels where these units are identical to the size of the elements in pixels, it is recommended that this entry is the pixel size of the panel background bitmap (240 by 240 for our tutorial). With visible set to 0 the panel will not appear until the user requests it, and the ident code can either be one of the preset panels (such as MAIN_PANEL, or THROTTLE_PANEL) or be any number above 10000. Lower codes are reserved for use by the simulation itself.

The three gauge entries give the gauge number, cabinet file, gauge name, and then x and y co-ordinates relative to the top left hand corner of the panel, and optional width and height parameters (which will scale the gauge if they are not identical to the gauge sizes).

This completes the changes to the configuration file, so save it off.

Artwork needs to be created that fits the entries we have just made in the panel configuration file, namely a file called Test_Panel_Background.bmp, with a size of 240 by 240 pixels. For this tutorial, create a colored square using Paint, and save it to the same directory as the panel configuration file.

This is all that is necessary to add a panel for the 2D cockpit view.

Note

Comment marks ("//") work in the panel configuration files. You could test the panel we have just created by commenting out the two lines beginning with gauge01 and gauge02, and then running Prepar3D. You should be able to turn the panel on and off, and notice that the airspeed indicator responds exactly as the one in the main panel. If this does not happen, carefully go over this step again.


Step 4: Create a simple Fuel Pressure Gauge

The fuel pressure gauge is certainly the simplest of the two we plan to build. All it is doing is displaying a single reading that is readily available in the simulator.
Start up the ACE tool, and select New Document. Right click on the new entry in the Property Sets column, and select Insert. An Insert dialog should appear, and select SimGauge in the Namespace box. Then scroll down and click on Gauge in the long list of properties. A gauge icon should now appear in the Property Sets column. Clicking on one of these entries will bring up all the object's properties. However, first save off the file, calling it FuelPressure.xml, to the folder: %USERPROFILE%\Documents\New Gauges\Test Gauges. If you then re-open it, you will see that the parent node properties includes Filename and id. Change the id to any string that helps identify the gauge, such as "Fuel Pressure Gauge" in this case.

In the properties for the Gauge entry, change the ArtDirectory to the location %USERPROFILE%\Documents\New Gauges\Test Gauges for this tutorial. This is the location of the artwork for the tool, not for Prepar3D (which requires the art to be cabbed up with the XML gauge). However, if you set this location to be %USERPROFILE%\Documents\New Gauges\Test Gauges  then the artwork is in the right location, both for the ACE tool and for creating the cabinet files (which we do as the penultimate step).

Add Background Art to the Fuel Pressure Gauge

Next, right click on the Gauge and select Image. This will be the background image for the gauge. Open up the properties for this image, and make an entry for Name (the filename), such as FuelPressureBackground.bmp.
We need to create artwork for this background, so open up Paint again, and save off a solid rectangular block of color, 100 pixels wide by 80 pixels in height. Call this file, FuelPressureBackground.bmp, and save it in the Test Gauges directory.

Add Elements to the Fuel Pressure Gauge

Right click on the Gauge node again, and add an Element. Do this three times to add three elements. Click on the first element to bring up its properties. You will notice that the id entry for each element is simply "Element". Click on these and change the ids to Fixed Text for the first element, Output box for the second element, and Display text for the third element. This text is simply there to help in gauge development, and does not appear anywhere in the simulator. It is good to get into the practice of changing the ids to meaningful names, as some gauges will contain many elements. Each element is used to describe a small area of functionality of the gauge.

Properties of  the Fixed Text element

The location of elements is relative to their parent object in the design of the gauge. So for the Fixed Text element, change FloatPosition to 5,10. This will start the text 5 pixels in, 10 pixels down, on the gauge background.
This element describes no more than the words "Fuel Pressure" on the gauge. To do this right click on the element, select Insert then GaugeText, and then change just a few properties of the GaugeText object.:

Property Entry
FontFace Arial
FontColor gold
FontHeight 13
GaugeString Fuel Pressure
Size 90, 15

Properties of the Output box element

The output box is simply a rectangle where the display text is to appear within. Change its FloatPosition to 5, 40. Then insert a Rectangle object as a child of this element. Change the Rectangle properties to those shown below:

Property Entry
LineWidth 1
Width 90
Height 24
LineColor darkslateblue
FillColor black

The colors for text, lines and shapes can be entered either as names, or as hex RGB values (in the format 0xBBGGRR). The document XML Gauge Colors contains the full list.

Properties of the Display text element

This is the third and final element in the gauge. Set its FloatPosition to 10, 44. Then insert another GaugeText object as a child of this element. There is one important difference between this text and that for the first element, in that for this element we need to display the value of a simulation variable, not fixed text. Make the following entries in the new GaugeText object:

Property Entry
FontFace Courier
FontColor red
FontHeight 16
GaugeString %( (A:GENERAL ENG FUEL PRESSURE:1, psi) )%!09d!
HorizontalAlign LEFT
Size 90, 16
VerticalAlign CENTER

The key here is the GaugeString. The A:GENERAL ENG FUEL PRESSURE, is a simulation variable (there are many hundreds of these, listed in the Simulation Variables document). The index :1 is necessary as the fuel pressure is measured per engine, and psi requests that the result be returned as pounds per square inch. Simulation variables must be enclosed by parentheses. The % signs indicate that the contents should be evaluated rather than output as a string. The %!09d! indicate that nine digits should be output, that leading 0s should be included (up to nine of them!), and that the result should be treated as a decimal integer.  The section on Scripting goes over the full process for evaluating gauge scripts, which can be quite long and complex. Be very careful to enter the text exactly as shown (perhaps cut and paste it from this document), as a wrong space or missing parentheses can cause the expression evaluation to fail (it is not very flexible or forgiving in this regard).

Previewing the Fuel Pressure Gauge

The fuel pressure gauge is now complete and ready for testing. The tree structure of the gauge, when fully expanded, should look like this:

In the View menu, select Preview, then click on one of the gauge elements to view a preview in the right pane. It should look something like this.

Make sure to save off the XML document reasonably frequently. Before we test the fuel pressure gauge, we will build the stopwatch.


Step 5: Create a Stopwatch Gauge

The specification of our panel requires: "The stopwatch will show a rotary dial of seconds, and have an active start/stop toggle button, and an active reset button".

This makes the gauge considerably more complex than the simple text display of our fuel pressure gauge. The stopwatch will require handling of a rotation (the seconds needle), active mouse clicks (the two buttons), but also the task of persisting information about the gauge from one mouse click to the next, this is necessary in the simplest case for the toggle button -- its state must be recorded in order for it to be changed from start to stop, or vice versa.

In order to keep things a little bit simpler, we are not going to use prepared artwork, but will build the stopwatch from simple graphics primitives, and the stopwatch will have a single second hand.

The Stopwatch Elements

Create the following stopwatch elements.

The Stopwatch Rim

Insert an element, change the id to Rim, and give it a FloatPosition of 50, 60. Then insert a Circle object with the following properties.

Property Entry
Axis 50, 50
Radius 50
FillColor black
LineWidth 3
LineColor steelblue

The Stopwatch numerals

For our tutorial we will limit the stopwatch to 4 numerals: 60, 30, 45 and 15. If you want to develop the stopwatch fully, you would probably want to replace these elements with background art, with the numerals appearing on that art.

Create four elements, change their ids to 60,  30, 45 and 15, and give them FloatPositions of :

Numeral FloatPosition
60 40, 14
30 40, 96
45 4, 55
15 84, 55

Next, insert GaugeText entries for all four elements, with the following properties:

Property Entry
FontFace Arial
FontColor gold
FontHeight 12
GaugeString 15, 30, 45 and 60 (appropriately for each gauge element)
HorizontalAlign CENTER
Size 20, 20
VerticalAlign CENTER

The Start/Stop button

Add another element, change its id to Start/Stop button, and give it a FloatPosition of  44, 1. Then insert a Rectangle object with the following properties:

Property Entry
LineWidth 1
Width 12
Height 10
LineColor silver
FillColor silver

The Reset button

Add another element, change its id to Reset button, and give it a FloatPosition of  17,17. Then insert a Rectangle object with the following properties:

Property Entry
Axis 5, 5
LineWidth 1
Width 10
Height 10
LineColor silver

Note the entry in the Axis property, so that the rectangle will rotate about its center. As we need the button to look as if it is attached to the stopwatch rim, insert a Rotation object as a child of the Reset button element, and delete the automatically created sub-objects, except Expression. Do not change any of the Rotation objects properties, and simply add the number -0.7 as the entry for the Script property of the expression (this will rotate the rectangle minus 0.7 radians, which is about right).

The Needle

Add another element, change its id to Needle, and give it a FloatPosition of 50,60. The insert a Polygon object, and give it the following properties:

Property Entry
Axis 50, 60
FillColor red
LineWidth 1
LineColor red

A polygon consists of a list of Points, so insert three points with the following FloatPosition entries (to define a simple triangle):

Point FloatPosition
1 48, 62
2 50, 12
3 52, 62

The needle will also need a rotation object, so insert a Rotation, and entries for Rotation, Expression, FailureTable and Failure, will all appear. Leave this objects for now, except change the following in the Failure object (this indicates that if the user fails the electrical system, the stopwatch should freeze).

Property Entry
Fail_Key SYSTEM_ELETRICAL_PANELS
Fail_Action Freeze

We will come back to the all-important expression object, after first creating the MouseArea and MouseClick objects, as the logic of the expressions are all connected and complicated.

The Main MouseArea

There can only be one main mouse area for a gauge, so insert a MouseArea object, and give it the following properties (which simply indicate it covers the full area of the stopwatch, with a normal cursor).

Property Entry
id
MouseArea all
FloatPosition
0, 0
Size 100, 110
CursorType normal

The start/stop MouseArea

Insert another MouseArea as a child of the main mouse area. This area is to be active, and related to a mouse click.

Property Entry
id
start/stop
FloatPosition
41, 1
Size 12, 10
CursorType Hand

The reset MouseArea

Insert yet another MouseArea as a child of the main mouse area, and a peer of the start/stop area. This area is also to be active, and related to a mouse click.

Property Entry
id
reset
FloatPosition
14, 14
Size 10, 10
CursorType Hand

The MouseClick objects

MouseClick objects should be inserted for both the start/stop and reset mouse areas. Both should have their ClickType properties set to:

LeftSingle+LeftRelease

The only other property to change is the Script, which is complex and explained next.

The Stopwatch Expression Logic

Now comes the hard part, entering expression logic for both the mouse clicks and the needle rotation. Expression logic is entered using reverse polish notation (though refer to the Infix2Postfix tool that can assist in creating and understanding this notation).

Starting with the reset button, enter the following text for the mouse click Script:

(M:Event) 'LeftSingle' scmp 0 == if{ 1 (>L:RST Pressed,bool) 0 (>L:TotalRunning,seconds) 0 (>L:Running,bool) } (M:Event) 'LeftRelease' scmp 0 == if{ 0 (>L:RST Pressed,bool) }

The logic here is based around local variables, three of which have been used here:

Note also the use of the M:Event mouse variable. The (M:Event) 'LeftSingle' scmp 0 == if{ entry is processed as if the mouse event and the text string 'LeftSingle' are compared, and are equal, then the contents of the if statement block is processed. Similarly for the mouse button release.

Reverse polish notation is explained in more detail in the article on RPN Scripting.

Next enter the Script for the mouse click of the start/stop button. This is a bit more complicated as the button has two functions, starting or stopping the stopwatch depending on its current state.


(M:Event) 'LeftSingle' scmp 0 == if{ 1 (>L:STSTP Pressed,bool) (L:Running,bool) ! (>L:Running,bool) } (L:Running, bool) ! if{ (P:Absolute time, seconds) (>L:Offset, seconds) } (M:Event) 'LeftRelease' scmp 0 == if{ 0 (>L:STSTP Pressed,bool) }

Notice how the first if statement toggles the L:Running local variable: (L:Running,bool) ! (>L:Running,bool) assigns the NOT value of the boolean back to the variable. The second if statement then tests the value of L:Running and if it is false (the stopwatch is not running) the absolute time in seconds is assigned to another local variable L:Offset. This variable is used to calculate the rotation of the needle. The variable P:Absolute time can be found along with all the other program variables, in the Simulation Variables document.

Again there is a local variable L:STSTP Pressed to handle different graphic images for the button, should you wish to implement them.

Finally, we need to enter the Expression for the needle element's rotation, enter:

(L:Running,bool) if{ (P:Absolute time, seconds) (L:Offset,seconds) - (>L:TotalRunning,seconds) } els{ (P:Absolute time, seconds) (L:TotalRunning,seconds) - (>L:Offset,seconds) } (L:TotalRunning, seconds) 0.104719 *

The logic here is that if the stopwatch is running (L:Running is true) then the total running time is the absolute time in seconds, minus the offset (the absolute time when the stopwatch was last stopped). If the stopwatch is not running then the absolute time in seconds, minus the running time in seconds, is assigned to the offset. Finally the value of L:TotalRunning is applied to the rotation. To do this, this value (in seconds) is converted to radians by multiplying by 0.104719 (which is 2 * pi -- one full circle -- divided by 60, or the number of radians per sixtieth of a full rotation).

The stopwatch is now ready for testing, but first preview it to ensure the various elements are in the right place.

Previewing the Stopwatch

When completed, the stopwatch component tree should look like this:

And in the Preview window the stopwatch should appear.

Testing the Stopwatch in Preview mode

It is possible to do some limited testing within the tool by overriding the complex scripts we have entered. For example, to test the rotation of the needle select the Expression of the Rotation of the Needle element -- this expression begins with (L:Running,bool).....

We do not want to delete any of the text we have entered, but we can add some text to the beginning of the script, to test the rotation, and then delete it. Change the expression by adding the following text:

pi quit (L:Running,bool)....

The quit entry forces all evaluation to stop, so the value pi is used for the rotation. The stopwatch in the preview screen should show the needle hand pointing at 30 (pi radians is 180 degrees). Next change the entry to:

1.5 pi * quit (L:Running,bool)

The needle should now point at 45. If you get this, all is well so delete the testing text. If not, re-examine all the entries for the Needle element, checking you have entered them correctly.

Both the new gauges are now complete, the next steps are to cab them up and test them in Prepar3D.


Step 6: Create a Cabinet file

Run the cabdir tool on the New Gauges/TestGauges directory. This will compress the three files, FuelPressure.xml, Stopwatch.xml and FuelPressureBackground.xml into one .cab file, called TestGauges.cab. You can run the cabdir tool in a number of ways:

  1. Drag the TestGauges directory and drop it onto the Cabdir icon (in the Cabdir_SDK folder in the SDK installation). This is the simplest way, but does not allow you to change any of cabdir's parameters (which in most cases is fine). The cab file will be located in the root directory of the TestGauges directory.
  2. Go to the Cabdir SDK folder in the command line, and run cabdir from the command line (see the Creating Cabinet Files documentation).

Copy the cab file (which has a cabinet style icon) into the ..\Prepar3D\Gauges directory. These gauges are independent of the simulation aircraft, so can be used in any panel of any of the aircraft. For this tutorial though, we have simply added them to the Mooney Bravo.

The process of creating a panel, new gauges and adding them to the simulation is now complete. The next stage is to test them.

Note:  This step is included in the tutorial because cab files are recommended for final release and distribution.  While developing and debugging, the uncompressed folder can be placed in the Prepar3D/Gauges directory.   If a gauge is not intended to be shared between aircraft, the folder or cab file can also be placed in the same folder as the panels.cfg file that references it.


Step 7: Testing the new Gauges

Run Prepar3D, and select the Mooney_Bravo (which is the default aircraft) to load up your new gauges. You should be able to select the panel from the Instrument Panel menu, and then watch the fuel pressure gauge rise slowly as you increase speed, and be able to click on the stopwatch buttons and watch the needle rotate.

If all goes perfectly, which it rarely does, you will have completed your project. However, it is far more common for the gauges not to appear, be positioned, or work quite as you intended, so this is simply the start of an iterative process in getting the gauges just right.


Step 8: Adding Artwork to the Stopwatch

The stopwatch includes local variables that indicate the status of the start/stop and reset buttons. This allows you to extend this gauge so that you can see these button being depressed as you select them. This involves a new gauge element we have not yet used, the Select element, with two child Case objects ( representing the buttons in an up and down state).

For this tutorial, we will replace the start/stop rectangle with one of two small images, which one depending on whether the button is being pressed or not. The first thing to do is to create these two images. Using any appropriate image editing tool, create two bitmaps 12 pixels wide by 10 pixels in height, which look like a button extended and depressed. For example:

Extended Image
StartStopUpGraphic.jpg
Depressed Image
StartStopDownGraphic.jpg

Note that pure black is the transparent color. Make sure both these images are saved to the TestGauges directory.

Next delete the rectangle of the Start/Stop button element, and then insert a Select element. This will automatically add an Expression and two Case objects to the gauge. Now edit the objects as follows:

The Select element in the tree view of the gauge should now look like this:

Now, go back to step 6, update the gauges, and test the new action. You could replace all the simple art with images, and slowly build a great looking stopwatch!

When you have the images working correctly, you have finished the tutorial. Good work!


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.

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.
Fixed Set to True if all text should be on a single line.
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 GaugeString examples below.
HilightColor The color to use when the text is highlighted. See Gauge Colors.
HorizontalAlign One of:
LEFT
CENTER
RIGHT
Italic Set to True for italic text.
Length The maximum number of characters in the string to display.
LineSpacing Line spacing in pixels.
Luminous Set to True if the text illuminates at night.
Multiline Set to True if there can be more than one line of text.
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.
VerticalAlign One of:
TOP
CENTER
BOTTOM
WidthFit Set to True if the text should be expanded to fit the width of the text box.

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.


Formatting Numbers

The format for numbers is contained within the !...! marks.

The last letter is required and is case-sensitive, is the formatting of the variable, where:

The formatting letter can be preceded by a number, which is the minimum number of digits to display, and is optional. For decimal numbers the following rules apply:

For floating point numbers, the following rule applies:

Examples of Number Formatting


String Result Description
%( 12.34 )%!4.3f! 12.340 The 4 in 4.3 is ignored.
%( 12.34 )%!04.3f! 12.340 Leading "0"s are not added to floating point numbers.
%( 12345.6789 )%!4.3f! 12345.679 The number before decimal point does not limit the number of digits displayed before decimal point.
%( 34.56 )%!+d! +35 Rounding, not truncation, has occurred.
%(234)%!5d!   234 Two leading spaces have been prefixed to the number.
%( "foo" )%!5s!  foo Two leading spaces have been prefixed to the string
%( 234 )%!3s! 234 The number is output as a string, with a minimum of three digits.

Conditional Gauge Strings

The format of conditions (if, then, else, and case statements) in gauge strings is different from that in other scripts. In gauge strings use the %{if}, %{else}, and %{end} constructs to choose which text to display.  Note that these keywords are case-sensitive and must be typed in lowercase. Also, there must not be a space between the "%" and the "{". An if statement can be used without a corresponding else, in which case nothing is displayed if the result of the condition is false. The syntax for usage is one of the following:

For example: %( 1 )%{if}ON%{else}OFF%{end} would give the output ON. Whereas %( 0 )%{if}The value is true%{else}The value is false%{end} would give the output :The value is false.

In the Example of Gauge Strings below, note also the case and loop statements.

Escape Codes

It is also possible to insert escape code sequences into gauge strings.

Escape code Translation
\{tabs=50R,60C, 244L} Set 3 tab stops; the first is right-aligned, the second is centered, and last is left-aligned.
\{fnt1} Switch to the first alternate font specified as a child of the gauge text element
\{fnt} Return to the default font
\{up} Superscript
\{dn} Subscript
\{md} Normal (neither superscript nor subscript)
\{bo} Bold
\{ul} Underline
\{itl} Italic
\{strk} Strikeout
\{blnk} Blink
\{rev} Reverse background/foreground color for text
\{nr} Normal -- clear all properties previously set.
\{lcl} Line color
\{blc} Background line color
\{clr} Color
\{bck} Background color
\{dplo=X} Put a degrees symbol above the next character after the ?=?
\{dpl=XY} Make X superscript and Y subscript
\{lsp=23} Set line spacing to 23
\{lsp} Set line spacing to default
\{ladj=L} Set horizontal text alignment to left. (use ?C? for center or ?R? for right)
\{line=240} Draw a horizontal line with width 240
\{lmrg=20} Set the left margin to 20
\{rmrg=30} Set the right margin to 30
\{img1} Insert image #1 (a text element can have image children)

Examples of GaugeStrings

Gauge string Description
Fuel Pressure The text will appear exactly as entered: Fuel Pressure
Fuel Capacity: %(A:FUEL TOTAL CAPACITY)%!1.2f! The fuel capacity of the aircraft will be given as a floating point number accurate to two decimal places, following the initial string, such as:
Fuel Capacity: 80.55
%(A:ENG ON FIRE:1 A:ENG ON FIRE:2 ! if{ 'Warning: Engine Fire' } ) The text string "Warning: Engine Fire" will appear if either or both of the engines are on fire.
%( 1 )%{if}ON%{else}OFF%{end} The text ON would be rendered. If there is no {else} statement, then no text will be displayed if the condition evaluates to false.
%( 3 )%{case}%{ :0 }AIRPORT%{ :1 }INTERSECTION%{ :2 }NDB%{ :3 }VOR%{ :4 }MARKER%{end} A case statement can be used to select a text string from a group of strings. The case numbers do not have to be sequential. The example would produce the result:
VOR
%((C:Mission:OnScreenTimerValue) 60 / 60 / flr )%!02d!:
%((C:Mission:OnScreenTimerValue) 60 / flr 60 %)%!02d!:
%((C:Mission:OnScreenTimerValue) flr 60 %)%!02d!.
%((C:Mission:OnScreenTimerValue) 10 * flr 10 % )%!01d!
Takes the custom on-screen timer value and displays the time in hours, minutes, seconds and tenths of a second.
The !02d! indicates that the text output should be displayed with two digits (for example, 06). The % signs inside the string refer to the modulus operator, and the colons and period between the statements will appear on the screen as text, for example:
01 : 14: 08 . 2
85 %% To output the percent character, use two percent signs in the script:
85 %
%(10 s2 1 s1)%{loop}%( l1 )%!s! %( l1 ++ s1 l2 <)%{next} This statement sets up two registers s1 and s2, with the numbers 1 and 10, then loops to print out:
1 2 3 4 5 6 7 8 9
Whatever value is on top of the stack when the %(next) statement is reached is evaluated as a boolean to determine if execution of the loop should continue.
\b        Indented Text The parser will strip leading whitespace.  A backspace '\b' can be used to override this behavior if indented text is required.


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\Utilities\SimProp folder. This is a command-line tool, so open a command window and navigate to the SDK\Utilities\SimProp folder. If Prepar3D is installed, then enter the following command:

> Simpropcompiler 2spb –symbols C:\Program Files (x86)\Lockheed Martin\Prepar3D v3\propdefs\*.xml yourFile.xml yourFile.spb

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


> Simpropcompiler 2spb –symbols C:\Program Files (x86)\Lockheed Martin\Prepar3D v3 SDK *\SimObject SDK\Panels and Gauges SDK\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.