Creating XML Gauges

Artykuł
06/26/2008

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.

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.

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.
Create a directory, under My Documents, called something appropriate like New Gauges.
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.
Have your artwork creation tools handy, though for this tutorial Paint will suffice.
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:

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

Specify a transparent area in a static image that also displays other things (for example, tick marks and other graphics associated with a gauge)
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 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.

Udostępnij za pośrednictwem

Creating XML Gauges

Overview

See Also

Table of Contents

XML Gauge Tutorial

Step 1: Setup

Step 2: Specify the Gauges

Step 3: Add the new Panel

Note

Step 4: Create a simple Fuel Pressure Gauge

Add Background Art to the Fuel Pressure Gauge

Add Elements to the Fuel Pressure Gauge

Properties of the Fixed Text element

Properties of the Output box element

Properties of the Display text element

Previewing the Fuel Pressure Gauge

Step 5: Create a Stopwatch Gauge

The Stopwatch Elements

The Stopwatch Rim

The Stopwatch numerals

The Start/Stop button

The Reset button

The Needle

The Main MouseArea

The start/stop MouseArea

The reset MouseArea

The MouseClick objects

The Stopwatch Expression Logic

Previewing the Stopwatch

Testing the Stopwatch in Preview mode

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

Custom Parameters (C:)

Gauge Parameters (G:)

Key Parameters (K:)

Note

Local Parameters (L:)

Note

Mouse Parameters (M:)

Resource strings (R:)

Reverse Polish Notation

Expression Operators

Notes

Expression Evaluation Examples

Aircraft Script Examples

Notes

The Infix2Postfix Tool

Note

Gauge Objects

Comment Objects

Element Objects

Arc Objects

Gauge Colors

Gauge Color Scripts

Circle Objects

ClipRect Objects

CustomDraw Objects

CustomDrawParam Objects

Ellipse Objects

GaugeText Objects

AlternateColor

AlternateFont

Formatting Numbers

Examples of Number Formatting

Conditional Gauge Strings

Escape Codes

Examples of GaugeStrings

HorizontalLine Objects

MaskImage Objects

Pie Objects

Polygon Objects

Point Objects

Polyline Objects

Rectangle Objects

Rotation Objects