The ACE resource tool can be used to build a number of components for
Prepar3D, this document explains how to use the tool to help build
gauges. The term gauge is used to
describe all the instruments in an aircraft's cockpit.
The document is divided into two sections, a tutorial for new users of
the gauge system, and a reference containing information on all the
options available.
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.
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.
[Panels]
GaugeDevDebug=1
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.
Unlike gauges, panels are particular to an aircraft. Go into the SimObjects\Aircraft folder, then find the Mooney Bravo, then in the panel directory, open up the panel configuration file (panel.cfg) in a text editor (Notepad is quite sufficient for this). For full details of the panel configuration file refer to the Panel Configuration Files document (though you will not need to for this tutorial).
In order to add a new panel we must first make a single entry under
Window Titles, so add the line shown in bold below, so that the first
lines of the configuration file now look like this:
// Panel Configuration file
// Mooney Bravo
// Copyright (c) 2009-2010 Lockheed Martin Corporation. All rights
reserved.
[Window Titles]
Window00=Main Panel
Window01=Radio Stack
Window02=GPS
Window03=Annunciator
Window04=Overhead Panel
Window05=Mini Panel
Window06=Test Panel
[VIEWS]
VIEW_FORWARD_DIR=2.000, 0.000, 0.000
[Window05]
Background_color=0,0,0
size_mm=550,90
windowsize_ratio=1.6
position=7
visible=1 ident=MINIPANEL
no_luminous=1 child_3d=1
gauge00=Mooney_Bravo!Airspeed, 0,6, 81,78
gauge01=Mooney_Bravo!Turn Coordinator, 90, 6, 78,76
gauge02=Mooney_Bravo!Attitude, 180, 0, 93,87
gauge03=Mooney_Bravo!HSI, 283,0, 91,85
gauge04=Mooney_Bravo!Altimeter, 386,5, 73,76
gauge05=Mooney_Bravo!Vertical Speed, 470,6,77,77
[Window06]
file=Test_Panel_Background.bmp
position=6
visible=00
gauge00=Mooney_Bravo!Airspeed, 5, 5, 81,78
gauge01=TestGauges!FuelPressure,
100, 5
gauge02=TestGauges!Stopwatch,
75,95
[VCockpit01]]
ffile=Mooney_Panel_G1000_Decals_Gray.bmp
size_mm=1024,1024
The 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 Prepar3D (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).
Property | Entry |
FontFace | Arial |
FontColor | gold |
FontHeight | 13 |
GaugeString | Fuel Pressure |
Size | 90, 15 |
Property | Entry |
LineWidth | 1 |
Width | 90 |
Height | 24 |
LineColor | darkslateblue |
FillColor | black |
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).
Make sure to save off the XML document reasonably frequently. Before we test the fuel pressure gauge, we will build the stopwatch.
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.
Property | Entry |
Axis | 50, 50 |
Radius | 50 |
FillColor | black |
LineWidth | 3 |
LineColor | steelblue |
Numeral | FloatPosition |
60 | 40, 14 |
30 | 40, 96 |
45 | 4, 55 |
15 | 84, 55 |
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 |
Property | Entry |
LineWidth | 1 |
Width | 12 |
Height | 10 |
LineColor | silver |
FillColor | silver |
Property | Entry |
Axis | 5, 5 |
LineWidth | 1 |
Width | 10 |
Height | 10 |
LineColor | silver |
Property | Entry |
Axis | 50, 60 |
FillColor | red |
LineWidth | 1 |
LineColor | red |
Point | FloatPosition |
1 | 48, 62 |
2 | 50, 12 |
3 | 52, 62 |
Property | Entry |
Fail_Key | SYSTEM_ELETRICAL_PANELS |
Fail_Action | Freeze |
Property | Entry |
id |
MouseArea
all |
FloatPosition |
0, 0 |
Size | 100, 110 |
CursorType | normal |
Property | Entry |
id |
start/stop |
FloatPosition |
41, 1 |
Size | 12, 10 |
CursorType | Hand |
Property | Entry |
id |
reset |
FloatPosition |
14,
14 |
Size | 10, 10 |
CursorType | Hand |
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.
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.
Extended Image StartStopUpGraphic.jpg |
Depressed Image StartStopDownGraphic.jpg |
Now, go back to step 6, update the gauges, and test the new action. You could replace all the simple art with images, and slowly build a great looking stopwatch!
When you have the images working correctly, you have finished the tutorial. Good work!
Parameter | Stands for... | Description |
A | Aircraft, including helicopters | Gets the specified parameter of the aircraft. |
C | Custom parameter | Custom variable created for Prepar3D. |
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 Prepar3D. |
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. |
The following table lists all the defined custom parameters that can be used within XML gauges:
Module |
Variable |
Units |
Settable |
Description |
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.
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 |
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.
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 |
# | 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. |
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.
This tool is for educational purposes only, there are some scripts that it will not convert correctly.
Converting from infix to postfix |
Converting from postfix to infix |
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. |
Property | Description |
id | A string that can be edited to help identify the object. |
Value | The comment string. |
Property | Description |
id | A string that can be edited to help identify the object. |
FloatPosition | Two floating point numbers, giving the top left hand position of the element relative to the top left hand position (0,0) of the gauge, in pixels. |
LeftScript | An optional script that evaluates the top left hand X position of the element, and overrides the FloatPosition. (Only called when the gauge is first loaded) |
TopScript | An optional script that evaluates the top left hand Y position of the element, and overrides the FloatPosition. (Only called when the gauge is first loaded) |
Visibility | An
optional script
to evaluate the visibility. For example: (A:PARTIAL PANEL ELECTRICAL, enum)! The enum for this variable is (0 = OK, 1= fail, 2 = blank), so in this case the result is inverted by the "!" operator to give 1 = OK and 0 = fail. See the Simulation Variables document for details of all the variables. |
SizeScale | Float value to scale the size of the element, default is 1.000. |
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.
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.
See the XML Gauge Colors file for a full list of colors. And refer to Expression Evaluation for full details on writing 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 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.
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. |
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.
Property | Description |
id | A string that can be edited to help identify the object. |
Name |
|
Value |
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. |
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.
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.
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.
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. |
The format of conditions (if, then, else, and case statements) in gauge strings is different from that in other scripts. In gauge strings use the %{if}, %{else}, and %{end} constructs to choose which text to display. Note that these keywords are case-sensitive and must be typed in lowercase. Also, there must not be a space between the "%" and the "{". An if statement can be used without a corresponding else, in which case nothing is displayed if the result of the condition is false. The syntax for usage is one of the following:
For example: %( 1 )%{if}ON%{else}OFF%{end} would give the output ON. Whereas %( 0 )%{if}The value is true%{else}The value is false%{end} would give the output :The value is false.
In the Example of Gauge Strings below, note also the case and loop statements.
It is also possible to insert escape code sequences into gauge strings.
Escape code |
Translation |
\{tabs=50R,60C, 244L} | Set 3 tab stops; the first is right-aligned, the second is centered, and last is left-aligned. |
\{fnt1} | Switch to the first alternate font specified as a child of the gauge text element |
\{fnt} | Return to the default font |
\{up} | Superscript |
\{dn} | Subscript |
\{md} | Normal (neither superscript nor subscript) |
\{bo} | Bold |
\{ul} | Underline |
\{itl} | Italic |
\{strk} | Strikeout |
\{blnk} | Blink |
\{rev} | Reverse background/foreground color for text |
\{nr} | Normal -- clear all properties previously set. |
\{lcl} | Line color |
\{blc} | Background line color |
\{clr} | Color |
\{bck} | Background color |
\{dplo=X} | Put a degrees symbol above the next character after the ?=? |
\{dpl=XY} | Make X superscript and Y subscript |
\{lsp=23} | Set line spacing to 23 |
\{lsp} | Set line spacing to default |
\{ladj=L} | Set horizontal text alignment to left. (use ?C? for center or ?R? for right) |
\{line=240} | Draw a horizontal line with width 240 |
\{lmrg=20} | Set the left margin to 20 |
\{rmrg=30} | Set the right margin to 30 |
\{img1} | Insert image #1 (a text element can have image children) |
Gauge string | Description |
Fuel Pressure | The text will appear exactly as entered: Fuel Pressure |
Fuel Capacity: %(A:FUEL TOTAL CAPACITY)%!1.2f! | The
fuel
capacity of the aircraft will be given as a floating point number
accurate to two decimal places, following the initial string, such as: Fuel Capacity: 80.55 |
%(A:ENG ON FIRE:1 A:ENG ON FIRE:2 ! if{ 'Warning: Engine Fire' } ) | The text string "Warning: Engine Fire" will appear if either or both of the engines are on fire. |
%( 1 )%{if}ON%{else}OFF%{end} | The text ON would be rendered. If there is no {else} statement, then no text will be displayed if the condition evaluates to false. |
%( 3 )%{case}%{ :0 }AIRPORT%{ :1 }INTERSECTION%{ :2 }NDB%{ :3 }VOR%{ :4 }MARKER%{end} | A
case
statement can be used to select a text string from a group of strings.
The case numbers do not have to be sequential. The example would
produce the result: VOR |
%((C:Mission:OnScreenTimerValue)
60 / 60 / flr )%!02d!: %((C:Mission:OnScreenTimerValue) 60 / flr 60 %)%!02d!: %((C:Mission:OnScreenTimerValue) flr 60 %)%!02d!. %((C:Mission:OnScreenTimerValue) 10 * flr 10 % )%!01d! |
Takes
the custom on-screen timer value and displays the time in hours,
minutes, seconds and tenths of a second. The !02d! indicates that the text output should be displayed with two digits (for example, 06). The % signs inside the string refer to the modulus operator, and the colons and period between the statements will appear on the screen as text, for example: 01 : 14: 08 . 2 |
85 %% | To
output the percent character, use two percent signs in the script: 85 % |
%(10 s2 1 s1)%{loop}%( l1 )%!s! %( l1 ++ s1 l2 <)%{next} | This
statement sets up two registers s1 and s2, with the numbers 1 and 10,
then loops to print out: 1 2 3 4 5 6 7 8 9 Whatever value is on top of the stack when the %(next) statement is reached is evaluated as a boolean to determine if execution of the loop should continue. |
\b Indented Text | The parser will strip leading whitespace. A backspace '\b' can be used to override this behavior if indented text is required. |
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. |
Property | Description |
id | A string that can be edited to help identify the object. |
Axis | The x and y co-ordinates of the center of the mask, in pixels. If rotation is applied to the mask, then this is the point that it will rotate around. |
Name | Filename of the image to use as the mask |
Transparent | Set to True if the color black (0x000000) is to be treated as transparent. |
MaskImage objects can be the parent of Comment objects.
Mask images allow a gauge designer to create a hole in a layer so that a piece of the gauge can be seen through another piece. Through the window in the gauge background the rotating airspeed card is visible. There are two ways to generate the hole:
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>
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. |
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. |
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. |
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. |
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. |
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. |
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 |
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. |
Property | Description |
id | A string that can be edited to help identify the object. |
Failure | List of Failures. |
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 |
Property | Description |
id | A string that can be edited to help identify the object. |
NonLinearityEntry |
List of NonlinearityEntry objects. |
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. |
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. |
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 |
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. |
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. |
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.
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 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.
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. |
<?xml version="1.0" encoding="UTF-8"?>
<SimBase.Document Type="AceXML" version="1,0" id="MSwitch">
<Descr>AceXML Document</Descr>
<Filename>Switch.xml</Filename>
<SimGauge.Gauge id="Gauge" Name="Switch">
<Size>25,25</Size>
<Macro Name="SWITCH_FLIPPED">
<MacroValue>A:RECIP ENG PRIMER:1,bool</MacroValue>
</Macro>
<Element id="Element">
<Select id="Select">
<Expression id="Expression">
<Script>(@SWITCH_FLIPPED)</Script>
</Expression>
<Case id="Case">
<ExpressionResult>0.000</ExpressionResult>
<Image id="sw_down.bmp" Name="sw_down.bmp">
<Transparent>True</Transparent>
</Image>
</Case>
<Case id="Case">
<ExpressionResult>1.000</ExpressionResult>
<Image id="sw_up.bmp" Name="sw_up.bmp">
<Transparent>True</Transparent>
</Image>
</Case>
</Select>
</Element>
<MouseArea id="MouseArea">
<FloatPosition>0.000,0.000</FloatPosition>
<CursorType>Hand</CursorType>
<HelpId>HELPID_GAUGE_AVIONICS_SWITCH</HelpId>
<MouseClick id="MouseClick">
<Script>(@SWITCH_FLIPPED) ! (>@SWITCH_FLIPPED)</Script>
</MouseClick>
</MouseArea>
</SimGauge.Gauge>
</SimBase.Document>
<Macro id="Macro" Name="Var1">
<MacroValue> L:Var1, number </MacroValue>
</Macro>
<Macro id="Macro" Name="Var2">
<MacroValue> L:Var2, number </MacroValue>
</Macro>
<Macro id="Macro" Name="Var3">
<MacroValue> L:Var3, number </MacroValue>
</Macro>
<Macro id="Macro" Name="MAX">
<MacroValue> @1 @2 > if { @1 quit } @2 </MacroValue>
</Macro>
<Macro id="Macro" Name="STORE_MAX_INTO_VAR3">
<MacroValue> @MAX((@Var1),(@Var2))(>@Var3)) </MacroValue>
</Macro>
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. |
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. |
MouseClick objects are used to link mouse clicks with simulation key events, so enabling a user to control the instrument.
Property | Description |
id | A string that can be edited to help identify the object. |
KeyEvent | The key event that is to occur when the mouse is clicked. For example, KOHLSMAN_DEC or KOHLSMAN_INC. For a full list of key events, see the String name column in the Event IDs document. |
Script | If used, overrides KeyEvent. A script that evaluates to a single key event. |
ClickType |
One of: LeftAll RightAll MiddleAll RightSingle MiddleSingle LeftSingle RightDouble MiddleDouble LeftDouble RightDrag MiddleDrag LeftDrag Move RightRelease MiddleRelease LeftRelease WheelUp WheelDown Leave |
MouseWheelFlip | Set to True if flipping the mouse wheel will trigger the event. |
ClickRepeat | Set to True if holding the mouse button down will repeat the key event. When ClickRepeat is False, Leave events won't fire until the mouse is released. |
MouseClick objects can be the parent of Comment objects. MouseClick events and scripts will be fired for all applicable MouseAreas regardless of nesting order.
Update objects 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.
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 Prepar3D is installed, then enter the following command:
> Simpropcompiler 2spb –symbols C:\Program Files\Lockheed Martin\Prepar3D\propdefs\*.xml
yourFile.xml yourFile.spb
If Prepar3D is not installed, then enter the following command:
> Simpropcompiler 2spb –symbols C:\Program Files\Lockheed Martin\Prepar3D\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 Prepar3D and the SDK are installed to their default folders), and as the "*.xml" wildcard is used no other XML files should be moved to or created in the propdefs folder. File extensions are required for both the input and output filenames as they can be entered in any order.
To simply validate an XML file without creating an output file, change the keyword 2spb to validate.