Udostępnij za pośrednictwem


Creating XML Gauges

Overview

The ACE resource tool can be used to build a number of components for ESP, 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.

See Also

Table of Contents

  • XML Gauge Tutorial
    • Step 1: Setup
    • Step 2: Specify the Gauges
    • Step 3: Add the new Panel
    • Step 4: Create a simple Fuel Pressure Gauge
      • Add Background Art to the Fuel Pressure Gauge
      • Add Elements to the Fuel Pressure Gauge
      • Previewing the Fuel Pressure Gauge
    • Step 5: Create a Stopwatch Gauge
      • The Stopwatch Elements
      • The Stopwatch Expression Logic
      • Previewing the Stopwatch
    • Step 6: Create a Cabinet file
    • Step 7: Testing the new Gauges
    • Step 8: Adding Artwork to the Stopwatch
  • XML Gauge Reference
    • Expression Evaluation
      • Expression Parameters
      • Reverse Polish Notation
      • Expression Operators
      • Expression Evaluation Examples
      • The Infix2Postfix Tool
    • Gauge Objects
    • Comment Objects
    • Element Objects
      • Arc Objects
      • Gauge Colors
      • Circle Objects
      • CustomDraw Objects
      • Ellipse Objects
      • GaugeText Objects
      • HorizontalLine Objects
      • MaskImage Objects
      • Pie Objects
      • Polygon Objects
      • Polyline Objects
      • Rectangle Objects
      • Rotation Objects
      • Select Objects
      • Shift Objects
      • VerticalLine Objects
    • Image Objects
    • Macro Objects
    • MouseArea Objects
      • Tooltip Objects
      • MouseClick Objects
    • Update Objects
  • Creating an SPB File

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
  • Step 2: Specify the Gauges
  • Step 3: Add the new Panel
  • Step 4: Create a simple Fuel Pressure Gauge
  • Step 5: Create a Stopwatch Gauge
  • Step 6: Creating a Cabinet File
  • Step 7: Testing the new Gauges
  • Step 8: Adding Artwork to the Stopwatch

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 My 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 ESP.cfg file (found in the Documents and Settings\<username>\Application Data\Microsoft\ESP folder):
    [Panels] GaugeDevDebug=1

Step 2: Specify the Gauges

For this tutorial we are going to implement the following, for the basic Cessna 172 aircraft:

  • A new panel that is to appear on the Instrument Panel menu, called Test Panel, that can be selected to be visible or not.
  • The panel will contain one existing gauge, the airspeed indicator.
  • The panel will contain two new gauges, a fuel pressure indicator, and a stopwatch.
  • The fuel pressure indicator will do no more than display the current fuel pressure.
  • The stopwatch will show a rotary dial of seconds, and have an active start/stop toggle button, and an active reset button.

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 Cessna 172, 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
// Cessna 172sp
// Copyright (c) 2001-2003 Microsoft Corporation.  All rights reserved.

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

[Window00]
file=panel_background_640.bmp
file_1024=panel_background_1024.bmp
size_mm=640
position=7
visible=1
no_luminous=1
ident=MAIN_PANEL

gauge00=Cessna!ADF,545,86
gauge01=Cessna172!Airspeed,145,56
gauge02=Cessna!Altimeter,347,57
gauge03=Cessna!Attitude,246,56
gauge04=Cessna!Avionics Switch,240,286
gauge06=Cessna!DME,544,49
gauge07=Cessna!Flaps,598,286
gauge08=Cessna!Fuel_Selector, 451, 287

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

[Window05]
position=7
size_mm=631,100
child_3d=1
background_color=0,0,0
ident=MINIPANEL

gauge00=Cessna172!Airspeed,            0, 1
gauge01=Cessna!Turn_Indicator,       102, 0
gauge02=CessnaWAlpha!Attitude_Alpha, 207, 0
gauge03=Cessna!Heading_Indicator,    312, 0
gauge04=Cessna!Altimeter,            417, 0
gauge05=Cessna!Vertical_Speed,       531, 0

[Window06]
file=Test_Panel_Background.bmp
position=6
size_mm=240,240
visible=0
ident=10001

gauge00=Cessna172!Airspeed,          5, 5, 90, 90
gauge01=TestGauges!FuelPressure,     105, 5
gauge02=TestGauges!Stopwatch,        70,100

[VCockpit01]
size_mm=512,512
pixel_size=512,512

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 ESP. 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: My 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 My Documents\New Gauges\Test Gauges for this tutorial. This is the location of the artwork for the tool, not for ESP (which requires the art to be cabbed up with the XML gauge). However, if you set this location to be My 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 Expression Evaluation 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:

  • L:TotalRunning holds the time the stopwatch has run, in seconds, since the last time start was pressed. As the user has pressed the reset button, this is set back to 0. The entry 0 (>L:TotalRunning, seconds) does the assignment. Greater than signs preceding variables indicate an assignment.
  • L:Running is simply a boolean indicating whether the stopwatch is running or not. The assignment 0 (>L:Running, bool) sets this to false.
  • L:RST Pressed is a boolean we do not use in this implementation of a stopwatch, but will be used if you add graphical images to the stopwatch, showing the reset button being pressed when the mouse area is clicked. This local variable can be checked, and a different image drawn, with the use of a Select object.

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.

The full range of variables and statements that can make up expressions, and Reverse polish notation is explained in more detail in the section on Evaluating Expressions.

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 ESP.

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 ../ESP/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 Cessna C172.
The process of creating a panel, new gauges and adding them to the simulation is now complete. The next stage is to test them.

Step 7: Testing the new Gauges

Run ESP, and select the Cessna C172 (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 object should be left unchanged.
  • The expression object should have its script entered: (L:STSTP Pressed, bool). Remember we entered the local variable STSTP Pressed, that is set to true if the button is being pressed (clicked on with the mouse), or false otherwise.
  • The first case object should have its id changed to Case 0 and its expression should be entered as 0. With this case object selected click on Insert, and add an image. Insert the image name, StartStopUpGraphic.jpg.
  • The second case object should have its id changed to Case 1 and its expression should be entered as 1. With this case object selected click on Insert, and add an image. Insert the image name, StartStopDownGraphic.jpg.

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

Now, go back to step 6, cab up 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 all the operators that can be used in scripts and expressions when dynamic calculations are needed.

Expression Evaluation

  • Expression Parameters
  • Reverse Polisth Notation
  • Expression Operators
  • Expression Evaluation Examples
  • The Infix2Postfix Tool

Gauge Objects

Comment Objects

Element Objects

Image Objects

Macro Objects

MouseArea Objects

Update Objects

Expression Evaluation

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 the 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 parameter. INDICATED ALTITUDE is a simulation variable (see the Simulation Variables document for a full list of variables) and feet are the units of measure in which the aircraft parameter will display.

Expression Parameters

The following table describes all the types of parameters.

Parameter Stands for... Description
A Aircraft, including helicopters Gets the specified parameter of the aircraft.
C Custom parameter Custom variable created for ESP.
E Environment Gets environment variables, such as current time.
G Gauge parameter Gets a variable that is local to the gauge
K Key code Variables of this kind are key codes that are sent from gauges to ESP.
L Local parameter Gets a variable that is defined by the developer
M Mouse parameter Gets the state of the mouse for use in mouse click handlers.
P Program related Gets program variables, such as simulation rate
R Resource strings Retrieves a string from the resource file.

For more information on possible parameters for “A”, “E” and “P” see the Simulation Variables document. A unit name (feet, meters, inHg etc.) is required after the parameter name. For the list of recognizable unit names refer to the Units of Measurement section.

Custom Parameters (C:)

The following table lists all the defined custom parameters that can be used within XML gauges:

         
Mission OnScreenTimerValue seconds No The on screen timer used in the mission system.
Mission RaceUserCurrentLapNumber number No  
Mission RaceTotalLaps number No  
Mission RaceUserLastLapSpeed mph No  
Mission RaceUserDeltaToLeader seconds No  
Mission RaceUserCurrentLapTime seconds No  
Mission RaceUserLastLapTime seconds No  
Mission RaceTotalTime seconds No  
Mission RaceUserTotalPenalties seconds No  
Mission RaceMapInitialZoomLevel number No A value from 0 to 23. 23 is maximum zoom.
Mission RaceNextManeuver enum No One of the following:
NONE
HALFCUBAN8
VERTICAL
VERTICAL180
VERTICAL360
INSIDELOOP
CLOVERLEAF
TURN15LEFT
TURN15RIGHT
TURN45LEFT
TURN45RIGHT
TURN90LEFT
TURN90RIGHT
TURN135LEFT
TURN135RIGHT
TURN180LEFT
TURN180RIGHT
TURN270LEFT
TURN270RIGHT
SPIN
AVALANCHE
OUTSIDELOOP
TAILSIDE
LAZYEIGHT
WINGOVER
HAMMERHEAD
IMMELMAN
INVERTEDFLIGHT
KNIFEEDGE
TAKEOFF
LAND
TOUCHANDGO
SLOWROLL
SNAPROLL
SPLIT_S
2POINTROLL
4POINTROLL
6POINTROLL
8POINTROLL
STRAIGHT
Mission RaceUserDisqualified bool No  
Mission RaceUserFinished bool No  
         
POI SelectedTargetMSLAltitude meters No The current Point of Interest.
POI SelectedTargetName string No  
POI SelectedTargetDistance meters No  
POI SelectedTargetBearing degrees No  
POI NumberOfTargets number No  
         
ITrafficInfo Radius meters Yes The radius from the user aircraft (or tower) to use to collect data on nearby aircraft or vehicles.
ITrafficInfo Filter enum Yes One or more of the following values combined:
TRAFFIC_FILTER_AIRCRAFT = 1,
TRAFFIC_FILTER_GROUND_VEHICLES = 2,
TRAFFIC_FILTER_TOWER_CONTROLLERS = 4,
TRAFFIC_FILTER_ON_GROUND = 8,
TRAFFIC_FILTER_IN_AIR = 16,
TRAFFIC_FILTER_SLEEPING = 32,
TRAFFIC_FILTER_AWAKE = 64
ITrafficInfo Latitude radians Yes The latitude of the point the search is to be made from.
ITrafficInfo Longitude radians Yes The longitude of the point the search is to be made from.
ITrafficInfo SortOrder enum n/a Not implemented.
ITrafficInfo CurrentVehicle number Yes An index number into the list of aircraft/vehicles.
ITrafficInfo SelectedVehicle number Yes An index number into the list of aircraft/vehicles.
ITrafficInfo SelectedVehicleID number No The internal ID of the SelectedVehicle. This could be passed, for example, to the SelectedVehicle variable of the GPS system to display specific information on this aircraft. Refer to the XML Gauge Maps document.
ITrafficInfo CurrentPlayerName string No Multiplayer only. The player's name if the CurrentVehicle is being piloted by a user, or the empty string if not.
ITrafficInfo SelectedPlayerName string No Multiplayer only. The player's name if the SelectedVehicle is being piloted by a user, or the empty string if not.
ITrafficInfo ListSize number No The length of the list of vehicles returned after a search. The index numbers of the returned list will be from 0 to ListSize - 1.
ITrafficInfo MaxVehicles number Yes The maximum length of the list of vehicles requested for a search.
ITrafficInfo CurrentDistance meters No The distance the CurrentVehicle is away from the center of the search.
ITrafficInfo SelectedFlightPlan string No The flight plan of the SelectedVehicle. If the flight plan consists of one to three waypoints, the string returned will be in the format "A", "A,B" or "A, B, C" -- where A, B and C are ICAO waypoints. If the flight plan consists of four or more waypoints, the format will be "A, B, ... Z", where Z is the last waypoint of the flightplan.
         
FS9VIEW On bool Yes Turn an auxiliary view on or off.
FS9VIEW Zoom float Yes  
FS9VIEW Pitch float Yes Pitch of the view in degrees.
FS9VIEW Bank float Yes  
FS9VIEW Heading float Yes  
FS9VIEW OffsetRight float Yes Offsets in meters from the normal viewpoint.
FS9VIEW OffsetUp float Yes  
FS9VIEW OffsetForward float Yes  
         

To use a custom variable, precede it with C:<module name>: , for example:

C:POI:SelectedTargetName

There is a special use of the ITrafficInfo module custom variables. These can be followed by any of the variables above, or any Simulation Variable, preceded by the code C (for current aircraft) or S (for selected aircraft), for example:

C:ITrafficInfo:S:ATC FLIGHT NUMBER, string
C:ITrafficInfo:C:ATC AIRLINE, string

To set the current or selected aircraft, use a statement such as:

>C:ITrafficInfo:CurrentVehicle N

where N is a value between 0 and ListSize-1.

For the units, the Simulation Variables are all treated as number, except the following, which are string:

ATC ID, ATC MODEL, ATC TYPE, ATC AIRLINE, ADF NAME, NAV NAME, ATC FLIGHT NUMBER, and PAYLOAD STATION NAME.

Gauge Parameters (G:)

Parameters of the “G” kind have names from Var1 to Var9. These are used by gauge developers to store and retrieve variables across gauge elements. These values are unitless so do not put unit names after them. The default value of a gauge parameter is 0.
To get a gauge variable:
(G:Var1)
To set a gauge variable (to 5 in this example):
5 (>G:Var1)

Key Parameters (K:)

Key parameters can be used to trigger key events. Key parameters must be used if a value needs to be sent with the key event. For example, to set the ADF card to a specific value of 200, use the following syntax:
200 (>K:KEY_ADF_CARD_SET)
For more a list of events that can be used with Key Parameters see the Event IDs document. Note that unit names are not used with these parameters, however the > is still required even it the key event does not take a numeric parameter.
Key events can also be triggered by setting the KeyEvent parameter of MouseClick objects.

Note

The > sign is not a legal character in XML, and will appear as &gt in XML documents.

Local Parameters (L:)

When a local parameter is first referenced, it is created and its value is set to zero. Use your own names for these parameters, but care should be taken that these names are unique. Use unit names when referencing them, for example:

(L:Stopwatch Toggle Position: bool)

Note

When ESP is running in the shared cockpit scenario of multi-player mode, local (L:) and gauge (G:) parameters are synchronized between the two aircraft. Note also that local and gauge parameters are available to all other gauges in an aircraft panel, so information can be shared among gauges, though care should be taken to name each variable uniquely and clearly.

Mouse Parameters (M:)

Parameters of the “M” kind are:
•    “X” — the X coordinate of the mouse pointer.
•    “Y” — the Y coordinate of the mouse pointer.
•    “Event” — the string representation of the event which triggered the mouse handler, such as “LeftSingle” or “RightDouble”. The table below gives the full list of mouse events.
For the most part, you will not need to use mouse parameters, as the ACE tool handles these for you with MouseArea and MouseClick objects.

Event Name User action
RightSingle Single-clicks right mouse button
MiddleSingle Single-clicks middle mouse button
LeftSingle Single-clicks left mouse button
RightDouble Double-clicks right mouse button
MiddleDouble Double-clicks middle mouse button
LeftDouble Double-clicks left mouse button
RightDrag Moves mouse while holding down right mouse button
MiddleDrag Moves mouse while holding down middle mouse button
LeftDrag Moves mouse while holding down left mouse button
Move Moves mouse
Down_Repeat Holds down mouse button
RightRelease Releases right mouse button
MiddleRelease Releases middle mouse button
LeftRelease Releases left mouse button
Wheel_Flip Changes the direction the mouse wheel is rotating
Wheel_Skip Indicates that the two statements following the one containing the "Wheel_Skip" specify the mouse wheel events.
Wheel_Up Rolls the mouse wheel “up”
Wheel_Down Rolls the mouse wheel “down”
Move_Repeat Called repeatedly during click and drag mouse movements.
Leave Triggers the event when the mouse leaves the mouserect.
GetAll Triggers any mouse event
LeftAll Either single-clicks the left button, releases the left button, or moves the mouse while holding down the left mouse button
RightAll Either single-clicks the right button, releases the right button, or moves the mouse while holding down the right mouse button
MiddleAll Either single-clicks the middle button, releases the middle button, or moves the mouse while holding down the middle mouse button
Wheel Scrolls wheel up or down

Resource strings (R:)

The R parameter is used to retrieve strings from the resource file. These strings will be localized into the selected language of the user. For example,
(R: HELPID_AUTOPILOT_AUTOTHROTTLE) will result in the text "Autothrottle switch" if English is the selected language.
Refer to the document, HelpIDs, for a full list of the names of resource variables.

Reverse Polish Notation

The evaluation of scripts is done using a stack and reverse polish notation. For example, if you want a gauge to show altitude in thousands of feet, divide the value of INDICATED ALTITUDE by 1000.

(A:INDICATD ALTITUDE, feet) 1000 / 

To execute an arithmetic operation, put both operands first in the script and then include the symbol of operation (the divide symbol in this case). This is how some programmable calculators performed arithmetic operations in the past.

This convention works the following way: When the script parser comes across a value, it pushes it onto the top of the stack. When the script parser comes across an operator, it pops from the stack the number of operands that the operator works on (usually one or two values).

Whatever value is left on top of the stack at the end of the execution is the result of the calculated expression. The Expression Evaluation Examples section provides a list of simple and more complex script examples.

Expression Operators

There is a long list of operators that can be done within scripts.

Operator Operation Arguments Example Result
Common Operator
+ addition 2 3 5 + 8
- subtraction. If the stack contains A B -, then the calculation is A - B. 2 (L:Value) 90 - The local value minus 90.
/ division. If the stack contains A B /, then the calculation is A / B. 2 5 2 / 2.5
* multiplication 2 pi 2 * 2 pi
% taking modulo 1 5.3 % 5
++ increment 1 4 ++ 5
-- decrement 1 4 -- 3
/-/
neg
negates a number 1 4 /-/ -4
Comparison Operators
== true if equal 2 (L:Value) 0 == if{ A } Operation A is carried out if Value is 0.
!= true if not equal 2 (L:Value) 0 != if{ A } Operation A is carried out if Value is not 0.
> true if greater than 2 (L:Value1) (L:Value2) > if{ A } els{ B } If Value1 is greater than Value2, operation A is carried out, otherwise operation B is carried out.
< true if less 2 (L:Value1) (L:Value2) < if{ A } els{ B } If Value1 is less than Value2, operation A is carried out, otherwise operation B is carried out.
>= true greater than or equal 2 (L:Value1) (L:Value2) >= if{ A } els{ B } If Value1 is greater than or equal to Value2, operation A is carried out, otherwise operation B is carried out.
<= true if less than or equal 2 (L:Value1) (L:Value2) <= if{ A } els{ B } If Value1 is less than or equal to Value2, operation A is carried out, otherwise operation B is carried out.
? The third operand determines whether the first (True) or second (False) is selected. 3 A B True ? This evaluates to A.
Bit Operators
& bitwise AND 2 5 3 & 1
| bitwise OR 2 5 3 | 7
^ bitwise XOR 2 5 3 ^ 6
~ bitwise NOT 1 5 ~ -6
>> shift right operand number of bits 2 5 3 >> 0
<< shift left operand number of bits 2 5 3 << 40
Logical Operators
!, NOT NOT 1 (L:Local) ! (>L:Local) Toggles the variable Local
&&, AND AND 2 (L:Local) 0xFF00 && (>L:Local) The variable Local is ANDed with hex 0xFF00
||, OR OR 2 (L:Local) 07777 OR (>L:Local) The variable Local is ORed with octal 7777.
Numerical Operators
abs Absolute value 1 -5 abs 5
int
flr
Calculates nearest integer number which is less than the source number 1 5.98 flr 5
rng Range; returns True if the third operand lies between values one and two. 3 4 7 6 rng True
cos Cosine (input in radians) 1 pi cos -1
lg Logarithm to base 10 1 10 lg 1
min Minimum 2 5 2 min 2
sin Sine (input in radians) 1 pi sin 0
acos Arc cosine (returns radians) 1 pi acos
ctg cotangent (input in radians) 1 pi ctg
ln Natural logarithm 1 2.718282 ln 1
sqr Square 1 5 sqr 25
asin arc sine 1 pi asin
eps Floating-point relative accuracy 1 1 eps 2^(-52)
log Logarithm of operand one, to the base of operand two. 2 8 2 log 3
pi Pi = 3.14159; puts pi on the stack 0 pi 3.14159
sqrt Square root 1 25 sqrt 5
atg2 arc tangent with two inputs (input in radians) 2
exp Exponent; e to the power of the operand 1 1 exp 2.718282
max Maximum 2 5 2 max 5
pow Power of; the first value to the power of the second 2 2 5 pow 32
tg Tangent (input in radians) 1 pi tg 0
atg arc tangent with one input 1 pi atg
Special Operators
div Divides integers; its result is always an integer 2 5 3 div 1
ceil Calculates nearest integer number which is bigger than the source 1 4.3 ceil 5
near Calculates the nearest integer number, rounding .5 up. 1 4.5 near 5
dnor
d360
rdeg
Normalizes an angle expressed in degrees. The result in an value between 0 and 360. 1 -15 dnor 345
rddg Converts radians to degrees 1 pi rddg 180
dgrd Converts degrees to radians 1 180 dgrd pi
rnor Normalizes an angle expressed in radians, the result of this operation is between 0 and 2 pi 1 5 pi 1.8584
if{ .... } If statement, note there is no space between the if and the { 1 (L:Value) 0 == if{ A } Operation A is carried out if Value is 0.
els{ .... } Else statement, note there is no space between the els and the { 1 (L:Value1) (L:Value2) <= if{ A } els{ B } If Value1 is less than or equal to Value2, operation A is carried out, otherwise operation B is carried out.
quit The quit statement allows expression evaluation to stop completely, and avoid the use of nesting if{ statements. 0 pi quit (L:Value1) (L:Value2) <= if{ A } els{ B } pi. The rest of the script is ignored.
g0...gn Goto label. Execution will jump to the specified label. Labels are set by entering a colon followed by the label number. 0 g4 Execution jump to :4
case Case statement 50 40 30 20 10 5 (L:value) case The "5" indicates there are five case values, which are selected depending on the evaluation of (L:value).
If the evaluation is equal to or greater than 0, but less than 1, the result is 10. If the evaluation is equal to or greater than 1, but less than 2, the result is 20, and so on.
String Operators
lc Converts a string to lowercase 1 'ABcd10' lc 'abcd10'
uc
cap
Converts a string to uppercase 1 'ABcd10' uc 'ABCD10'
chr Converts a number to a symbol 1 65 chr 'A'
ord Converts a symbol to an integer 1 'A' ord 65
scat Concatenates strings 2 'abc' 'red' scat 'abcred'
schr Finds a symbol in a string
scmp Compares strings, case sensitive 2 (M:Event) 'LeftSingle' scmp 0 == if{ A }els{ B } Performs A if the left mouse button has been pressed, otherwisse performs B
scmi Compares strings, ignoring case 2 'left' 'Left' scmi 0 == if{ 'yes' } 'yes'
sstr Finds a substring 2 'cd' 'abcde' sstr 2
ssub Extracts a substring 2 'ab' 'abcde' ssub 'cde'
symb Extracts a single character 2 'abc' 1 symb 'b'
Stack Operators
b Backup the stack 0
c Clears the stack 0 stack: 1 2 3 c stack:
d Duplicates the value that is on the top of the stack 1 stack: 5 d stack: 5 5
p Pops and discards the top value on the stack 1 stack: 1 2 3 p stack: 1 2
r Reverses the top and second values on the stack 2 stack: 1 2 3 r stack: 1 3 2
s0, s1, … s49 Stores the top value in an internal register, but does not pop it from the stack. 1 stack: 1 2 3 s0 stack: 1 2 3
s0: 3
l0, l1, … l49 Loads a value from a register to the top of the stack 1 stack: 1 2 3 s0 l0 stack: 1 2 3 3
sp0, sp1, … sp49 Stores the top value and pops it from the stack 1 stack: 1 2 3 sp0 stack: 1 2
sp0: 3
Notes
  • Formatted strings use a similar but slightly different syntax, see Example of Gauge Strings.
  • Strings should be entered using single quotes, for example: 'abcd'.
  • Hexadecimal numbers can be entered using the 0xf or 0xF convention (for example, 0xff or 0xFF00FF00)
  • Octal numbers can be entered by using a leading zero. For example, 022 is octal 18. Be careful not to enter leading zeros on decimal numbers.
  • Scientific notation can be used: 5E2 represents 5 x 10 squared (500), 5E-2 is 0.005

Expression Evaluation Examples

The table below gives a range of script examples that can be used for aircraft. See also the examples for the GaugeText object, and a few examples in the Gauge Color Scripts section.

Aircraft Script Examples
# Expression Gauge Description
1 (A:LIGHT NAV, bool) Navigation Lights Returns True (1) if the navigation light switch is on, False (0) otherwise.
2 (A:TRAILING EDGE FLAPS LEFT ANGLE, radians) 1.1 * Flaps Returns the left flaps angle in radians, multiplied by 1.1. Multiplications like this can help reduce rounding errors when making comparisons with integer settings.
3 (A:PARTIAL PANEL ELECTRICAL,enum) ! Electrical gauges 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.
4 (A:PLANE HEADING DEGREES GYRO, degrees) /-/ dgrd HSI Compass ring Returns the aircraft heading negated and converted to radians.
5 (A:NAV GSI:1,percent) 250 / HSI Glideslope deflection Returns the percentage for the GSI (Glideslope deviation indicator) for Nav1, divided by 250.
6 (P:Units of measure, enum) 2 == if{ (A:RADIO HEIGHT, meters) } els{ (RADIO HEIGHT, feet) } Radio Height (or Radar Altitude)  needle The Units of measure enum is:
0 = English
1 = Metric (with altitude in feet)
2 = Metric (with altitude in meters)
So if this enum value is 2, the If statement is evaluated, otherwise the Els statement is evaluated.
7 (A:PARTIAL PANEL ELECTRICAL,enum)! if{ 25 (A:GENERAL ENG FUEL PRESSURE:1, psi) - } els{ 25.5 } Fuel Pressure If the Partial Panel Electrical is OK (see Example 3 above) then 25 minus the fuel reading for engine 1 is returned, if not the fixed value of 25.5 is returned.
8 (A:FUEL TANK SELECTOR 1, enum) 0 ==
(A:FUEL TANK SELECTOR 1, enum) 3 == or
if { pi 2 / } els{ 0 }
Right Valve of Fuel Gauge If all the fuel tanks are selected (FUEL TANK SELECTOR enum value is 0) or the right fuel tank is selected (the enum value is 3) then the fuel valve is set at pi/2, otherwise it is set at zero.
9 (A:NAV1 OBS, degrees) d (A:PARTIAL PANEL HEADING, bool) (A:PARTIAL PANEL ELECTRICAL, bool) or 0 ==
if{ (A:PLANE HEADING DEGREES GYRO, degrees) 90 - - } dgrd
GPS element of HSI If the PARTIAL PANEL HEADING is false and the PARTIAL PANEL ELECTIRCAL is false, then this expression returns the NAV1 OBS reading  minus the (PLANE HEADING DEGREES GYRO reading minus 90), converted to radians.
10 (P:Units of measure, enum) 2 ==
if{ (A:INDICATED ALTITUDE, meters) } els{ (A:INDICATED ALTITUDE, feet) } 100000 / 360 * dgrd
Altimeter ten thousand foot needle Divides the altitude by one hundred thousand, then multiplies by 360, and converts the result from degrees to radians.
11 (L:Show Volts 1,bool)
    if{  (A:ELECTRICAL GENALT BUS VOLTAGE:1, volts) 2 *
       } els{
          (A:ELECTRICAL GENALT BUS AMPS:1, amps) }
Amps/Volts  If the local variable Show Volts 1 is true, the bus voltage for engine 1, multiplied by 2, is returned. Otherwise the bus amps for engine 1 is returned.
12 (A:ADF Radial:1,degrees) 360 +
d360 dgrd
ADF The ADF radial value in degrees is added to 360 and then normalized to a value between 0 and 360. It is then converted to radians.
Notes
  • Simulation variables are not case-sensitive, they can be all upper, all lower or a mix of upper and lower case in your scripts.

The Infix2Postfix Tool

The Infix2Postfix tool makes it easier to both understand the logic of existing postfix (often called reverse Polish) notation, and enables the writing of scripts in the more normal infix notation familiar to all programmers. The Infix2Posfix tool is in the Panels and Gauges SDK folder. Click on it to run it. The following screen shots show a conversion from infix to postfix, and vice versa. Use the Copy button to copy the postfix notation to the clipboard, so that it can be pasted into a gauge script. Alternatively use the File menu to select an existing XML gauge file, and you can then step through the scripts in the file, and examine the conversion to infix. The syntax for the infix notation is similar to C# or C++, and is available in a text file through an option in the Help menu.

Note

This tool is for educational purposes only, there are some scripts that it will not convert correctly.

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.
TopScript An optional script that evaluates the top left hand Y position of the element, and overrides the FloatPosition.
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.

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, 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.

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.

  • 'red' 'blue' (A:AIRSPEED INDICATED, knots) 300 > ?
  • '0x0000ff' '0xff0000' (A:AIRSPEED INDICATED, knots) 300 > ?
  • 0x0000ff 0xff0000 (A:AIRSPEED INDICATED, knots) 300 > ?

See the XML Gauge Colors file for a full list of colors. And refer to Expression Evaluation 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.

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.

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:

  • s = string. 
  • d = decimal number (integer).  If the number is not an integer, it is rounded to the nearest integer.  Note that rounding, not truncation occurs.
  • f = number (floating point)

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:

  • If d is preceded by the digit "0", then leading zeros are added if necessary.
  • If d is preceded by "-", text is left-aligned.
  • If d is preceded by "+",  a "+" symbol is indicated in front of the number when the number is greater than 0 (a "-" is always used to indicate numbers less than 0).
  • If d is preceded by " " (space), leading spaces are added if necessary.

For floating point numbers, the following rule applies:

  • If a decimal point is used in the formatting number, the digit after the decimal point specifies the number of digits to display after the decimal point.
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:

  • %(CONDITIONAL)%{if}TEXT TO DISPLAY IF TRUE%{else}TEXT TO DISPLAY IF FALSE%{end}
  • %(CONDITIONAL)%{if}TEXT TO DISPLAY IF TRUE%{end}

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.

\{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.

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.

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.  As an example, the airspeed indicator for the Cessna 172 has a TAS component.  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.

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.

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.

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 valuue between 0 and 1, used for alpha-blending.

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 syntax and semantics, described in Expression Evaluation.

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 Expression Evaluation, and Expression Evaluation Examples for a full explanation of how to write scripts. A full list of 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 ESP, or can come from actions set by Missions (see the Mission 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.

VerticalLine 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
Beech Baron Left Fuel Flow Indicator

In the following example the only differences between the left fuel flow indicator shown, and the right fuel flow indicator, are the scripts of the three macros. To change this example to the right fuel flow indicator, change the ENGINE_NUMBER script from 1 to 2, and change ENG1 to ENG2 in the two tooltip text macros. To refer to a macro from within a script, prefix the macro name with a @ symbol. Note that the XML listed in the example below is not compatible with the ACE tool.

  <?xml version="1.0" encoding="utf-8" ?>
 <Gauge Name="Left Fuel Flow Indicator" Version="1.0">
 <Macro Name="ENGINE_NUMBER">1</Macro>
 <Macro Name="TOOLTIP_ID">TOOLTIPTEXT_ENG1_FUEL_FLOW_GALLON_HOUR</Macro>
 <Macro Name="METRIC_TOOLTIP_ID">TOOLTIPTEXT_ENG1_FUEL_FLOW_LITER_HOUR</Macro>
 <Image Name="Fuel_Flow_Background.bmp" ImageSizes="53,52,82,82" />
 <Element>
    <Position X="26" Y="26" />
    <Image Name="Engine_Gauges_Needle.bmp" PointsTo="East" ImageSizes="13,5,20,8">
        <Axis X="-9" Y="2" />
    </Image>
    <Rotate>
         <Value Minimum="2" Maximum="30">(A:Eng fuel flow GPH:@ENGINE\_NUMBER,gallons per hour)</Value>
        <Nonlinearity>
            <Item Value="5" X="33" Y="5" />
            <Item Value="20" X="35" Y="46" />
            <Item Value="30" X="6" Y="36" />
        </Nonlinearity>
         <Delay DegreesPerSecond="12" />
    </Rotate>
 </Element>
 <Mouse>
    <Tooltip ID="@TOOLTIP_ID" MetricID="@METRIC_TOOLTIP_ID" />
 </Mouse>
 </Gauge>

Beech Baron GPS

The following table shows a small number of macro entries for the GPS system. Notice how the macro kOff is used simply as an identifying name for a value, the macro c refers to a custom variable, and the macro WaypointPagesInit reuses other macros many times, and itself is only used as a macro within another macro, PageInit. The GPS unit is one of the most complex instruments currently modelled.

  <<Macro Name="kOff">0</Macro>
  <<Macro Name="c">C:fs9gps</Macro>
<Macro Name="WaypointPagesInit">(@g:currentPageWPT) 0 == (@g:currentPageWPT) 1 == (@g:currentPageWPT) 2 == (@g:currentPageWPT) 3 == || || || if{ (C:fs9gps:WaypointAirportIdent) slen 0 == if{ 0 (>@c:NearestAirportCurrentLine) (@c:NearestAirportCurrentICAO) (>@c:WaypointAirportICAO) } } (@g:currentPageWPT) 4 == if{ (@c:WaypointIntersectionIdent) slen 0 == if{ 0 (>@c:NearestIntersectionCurrentLine) (@c:NearestIntersectionCurrentICAO) (>@c:WaypointIntersectionICAO) } } (@g:currentPageWPT) 5 == if{ (@c:WaypointNdbIdent) slen 0 == if{ 0 (>@c:NearestNdbCurrentLine) (@c:NearestNdbCurrentICAO) (>@c:WaypointNdbICAO) } } (@g:currentPageWPT) 6 == if{ (@c:WaypointVorIdent) slen 0 == if{ 0 (>@c:NearestVorCurrentLine) (@c:NearestVorCurrentICAO) (>@c:WaypointVorICAO) } } (@g:currentPageWPT) 3 == if{ @kOff (>@g:selectApproach) }</Macro>
<Macro Name="PageInit">(C:fs9gps:currentGroup) 4 == (C:fs9gps:group4currentPage) 0 == && if{ @ProcedurePageInit } (C:fs9gps:currentGroup) 1 == if{ @WaypointPagesInit } @RecalcSmallZoom\</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.

MouseClick objects can be the parent of Comment objects.

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

> Simpropcompiler 2spb –symbols C:\Program Files\Microsoft ESP\1.0\propdefs\*.xml yourFile.xml yourFile.spb

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

> Simpropcompiler 2spb –symbols C:\Program Files\Microsoft ESP\1.0\SDK\SimObject Creation Kit\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 ESP 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.