]> git.mxchange.org Git - flightgear.git/blob - docs-mini/README.conditions
Fix merge noise
[flightgear.git] / docs-mini / README.conditions
1 CONDITIONS IN FLIGHTGEAR PROPERTY FILES
2
3 Written by David Megginson, david@megginson.com
4 Last modified: $Date$
5
6 This document is in the Public Domain and comes with NO WARRANTY!
7
8
9 1. Introduction
10 ---------------
11
12 Some FlightGear property files contain conditions, affecting whether
13 bindings or animations are applied.  For example, the following
14 binding will apply only when the /sim/input/selected/engine[0]
15 property is true:
16
17   <binding>
18    <condition>
19     <property>/sim/input/selected/engine[0]</property>
20    </condition>
21    <command>property-assign</command>
22    <property>/controls/starter[0]</property>
23    <value type="bool">true</value>
24   </binding>
25
26 Conditions always occur within a property subtree named "condition",
27 which is equivalent to an "and" condition.
28
29
30 2. Comparison Operators
31 -----------------------
32
33 The simplest condition is "property".  It resolves as true when the
34 specified property has a boolean value of true (i.e. non-zero, etc.)
35 and false otherwise.  Here is an example:
36
37   <condition>
38    <property>/sim/input/selected/engine[0]</property>
39   </condition>
40
41 For more sophisticated tests, you can use the "less-than",
42 "less-than-equals", "greater-than", "greater-than-equals", "equals",
43 and "not-equals" comparison operators.  These all take two operands,
44 either two "property" operands or one "property" and one "value"
45 operand, and return true or false depending on the result of the
46 comparison.  The value of the second operand is always forced to the
47 type of the first; for example, if you compare a string and a double,
48 the double will be forced to a string and lexically compared.  If one
49 of the operands is a property, it is always assumed to be first.  Here
50 is an example of a comparison that is true only if the RPM of the
51 engine is less than 1500:
52
53   <condition>
54    <less-than>
55     <property>/engines/engine[0]/rpm</property>
56     <value>1500</value>
57    </less-than>
58   </condition>
59
60
61 3. Boolean Operators
62 --------------------
63
64 Finally, there are the regular boolean operators "and", "or", and
65 "not".  Each one surrounds a group of other conditions, and these can
66 be nested to arbitrary depths.  Here is an example:
67
68   <condition>
69    <and>
70     <or>
71      <less-than>
72       <property>/engines/engine[0]/rpm</property>
73       <value>1500</value>
74      </less-than>
75      <greater-than>
76       <property>/engines/engine[0]/rpm</property>
77       <value>2500</value>
78      </greater-than>
79     <or>
80     <property>/engines/engine[0]/running</property>
81    </and>
82   </condition>
83
84 The top-level "condition" is an implicit "and".
85
86
87 4. Approximating if...else
88 --------------------------
89
90 There is no equivalent to the regular programming 'else' statement in
91 FlightGear conditions; instead, each condition separately must take
92 the others into account.  For example, the equivalent of
93
94   if (x == 3) ... else if (y == 5) ... else ...
95
96 in FlightGear conditions is
97
98   <condition>
99    <equals>
100     <property>/x</property>
101     <value>3</value>
102    </equals>
103    <not>
104     <equals>
105      <property>/y</property>
106      <value>5</value>
107    </not>
108   </condition>
109
110 and then
111
112   <condition>
113    <equals>
114     <property>/y</property>
115     <value>5</value>
116    </equals>
117    <not>
118     <equals>
119      <property>/x</property>
120      <value>3</value>
121    </not>
122   </condition>
123
124 and then
125
126   <condition>
127    <not>
128     <equals>
129      <property>/x</property>
130      <value>3</value>
131     </equals>
132    </not>
133    <not>
134     <equals>
135      <property>/y</property>
136      <value>5</value>
137    </not>
138   </condition>
139
140 It's verbose, but it works nicely within existing property-based
141 formats and provides a lot of flexiblity.
142
143
144 5. Syntax Summary
145 -----------------
146
147 Here's a quick syntax summary:
148
149 * <and>...</and>
150
151   Contains one or more subconditions, all of which must be true.
152
153 * <condition>...</condition>
154
155   The top-level container for conditions, equivalent to an "and" group
156
157 * <equals>...</equals>
158
159   Contains two properties or a property and value, and is true if the
160   properties have equivalent values.
161
162 * <greater-than>...</greater-than>
163
164   Contains two properties or a property and a value, and is true if
165   the second property or the value has a value greater than the first
166   property.
167
168 * <greater-than-equals>...</greater-than-equals>
169
170   Contains two properties or a property and a value, and is true if
171   the second property or the value has a value greater than or equal
172   to the first property.
173
174 * <less-than>...</less-than>
175
176   Contains two properties or a property and a value, and is true if
177   the second property or the value has a value less than the first
178   property.
179
180 * <less-than-equals>...</less-than-equals>
181
182   Contains two properties or a property and a value, and is true if
183   the second property or the value has a value less than or equal
184   to the first property.
185
186 * <not>...</not>
187
188   Contains one subcondition, which must not be true.
189
190 * <not-equals>...</not-equals>
191
192   Contains two properties or a property and value, and is true if the
193   properties do not have equivalent values.
194
195 * <or>...</or>
196
197   Contains one or more subconditions, at least one of which must be
198   true.
199
200 * <property>...</property>
201
202   The name of a property to test.
203
204 * <value>...</value>
205
206   A literal value in a comparison.