]> git.mxchange.org Git - flightgear.git/blob - docs-mini/README.commands
Simplify fgValidatePath + minor fix (requires simgear update)
[flightgear.git] / docs-mini / README.commands
1 FlightGear Commands Mini-HOWTO
2
3 David Megginson
4 Started: 2002-10-25
5 Last revised: 2007-12-01
6
7
8 In FlightGear, a *command* represents an action, while a *property*
9 represents a state.  The trigger for a command can be any kind of user
10 input, including the keyboard, mouse, joystick, GUI, instrument panel,
11 or a remote network client.
12
13
14 XML Command Binding Markup
15 --------------------------
16
17 Most of the command-binding in FlightGear is handled through static
18 XML configuration files such as $FG_ROOT/keyboard.xml for the
19 keyboard, $FG_ROOT/mice.xml for the mouse, and
20 $FG_ROOT/gui/menubar.xml for the menubar.  In all of these files, you
21 reference a command through a binding.  This binding advances the
22 first throttle by 1%, up to a maximum value of 1.0:
23
24   <binding>
25    <command>property-adjust</command>
26    <property>/controls/throttle[0]</property>
27    <step type="double">0.01</step>
28    <max>1.0</max>
29   </binding>
30
31 A command binding always consists of the XML 'binding' element, with
32 one subelement named 'command' containing the command name (such as
33 'property-adjust').  All other subelements are named parameters to the
34 command: in this case, the parameters are 'property', 'step', and
35 'max'.  Here is a simpler binding, with no parameters:
36
37   <binding>
38    <command>exit</command>
39   </binding>
40
41 Bindings always appear inside some other kind of markup, depending on
42 the input type.  For example, here is the binding from keyboard.xml
43 that links the ESC key to the 'exit' command:
44
45  <key n="27">
46   <name>ESC</name>
47   <desc>Prompt and quit FlightGear.</desc>
48   <binding>
49     <command>exit</command>
50   </binding>
51  </key>
52
53 Usually, more than one binding is allowed for a single input trigger,
54 and bindings are executed in order from first to last. Bindings support
55 conditions (see README.conditions):
56
57  <key n="113">
58   <name>q</name>
59   <desc>Test</desc>
60
61   <binding>
62    <condition>
63     <property>/devices/status/mice/mouse/button[0]</property>
64    </condition>
65    <command>nasal</command>
66    <script>print("mouse button 0 pressed")</script>
67   </binding>
68  </key>
69
70 Keyboard definitions can embed bindings in tags <mod-up> (key released),
71 <mod-shift>, <mod-ctrl>, <mod-alt>, <mod-meta>, <mod-super>, and <mod-hyper>.
72 Nesting is supported. Meta, Super, and Hyper modifier tags are for local
73 use only, and must be supported by the operating system to work.
74
75  <key n="113">
76   <name>q</name>
77   <desc>Test</desc>
78   <binding>
79    <command>nasal</command>
80    <script>print("q pressed")</script>
81   </binding>
82
83   <mod-alt>
84    <binding>
85     <command>nasal</command>
86     <script>print("Alt-q pressed")</script>
87    </binding>
88
89    <mod-super>
90     <binding>
91      <command>nasal</command>
92      <script>print("Alt-Super-q pressed")</script>
93     </binding>
94
95     <mod-meta>
96      <binding>
97       <command>nasal</command>
98       <script>print("Alt-Super-Meta-q pressed")</script>
99      </binding>
100
101     </mod-meta>
102    </mod-super>
103   </mod-alt>
104  </key>
105
106
107
108 Built-in Commands
109 -----------------
110
111 As of the last revision date, the following commands were available
112 from inside FlightGear; the most commonly-used ones are the commands
113 that operate on property values (FlightGear's internal state):
114
115
116 null - do nothing
117
118 script - execute a PSL script
119   script: the PSL script to execute
120
121 exit - prompt and quit FlightGear
122
123 load - load properties from an XML file
124   file: the name of the file to load, relative to the current
125     directory (defaults to "fgfs.sav")
126
127 save - save properties to an XML file
128   file: the name of the file to save, relative to the current
129     directory (defaults to "fgfs.sav").
130
131 loadxml - load XML file into property tree
132   filename: the path & filename of the file to load
133   targetnode: the target node within the property tree where to store the XML
134   file's structure. If targetnode isn't defined, then the data will be stored
135   in a node "data" under the argument branch.
136
137 savexml - save property tree node to XML file
138   filename: the path & filename for the file to be saved
139   sourcenode: the source node within the property tree where the XML file's
140   structure is assembled from. If sourcenode isn't defined, then savexml will
141   try to save data stored in a node "data" in the argument branch.
142
143 panel-load - (re)load the 2D instrument panel
144   path: the path of the XML panel file, relative to $FG_ROOT (defaults
145     to the value of /sim/panel/path if specified, or
146     "Panels/Default/default.xml" as a last resort.
147
148 panel-mouse-click - pass a mouse click to the instrument panel
149   button: the number of the mouse button (0-based)
150   is-down: true if the button is down, false if it is up
151   x-pos: the x position of the mouse click
152   y-pos: the y position of the mouse click
153
154 preferences-load - (re)load preferences
155   path: the file name to load preferences from, relative to $FG_ROOT.
156     Defaults to "preferences.xml".
157
158 view-cycle - cycle to the next viewpoint
159
160 screen-capture - capture the screen to a file
161
162 tile-cache-reload - reload the scenery tile cache
163
164 lighting-update - update FlightGear's lighting
165
166 property-toggle - swap a property value between true and false
167   property: the name of the property to toggle
168
169 property-assign - assign a value to a property
170   property[0]: the name of the property that will get the new value.
171   value: the new value for the property; or
172   property[1]: the name of the property holding the new value.
173
174 property-adjust - adjust the value of a property
175   property: the name of the property to increment or decrement
176   step: the amount of the increment or decrement (defaults to 0)
177   offset: input offset distance (used for the mouse; multiplied by
178     factor)
179   factor: factor for multiplying offset distance (used for the mouse;
180     defaults to 1)
181   min: the minimum allowed value (default: no minimum)
182   max: the maximum allowed value (default: no maximum)
183   mask: 'integer' to apply only to the left of the decimal point;
184     'decimal' to apply only to the right of the decimal point; 'all'
185     to apply to the full value (defaults to 'all')
186   wrap: true if the value should be wrapped when it passes min or max;
187     both min and max must be specified (defaults to false)
188
189 property-multiply - multiply the value of a property
190   property: the name of the property to multiply
191   factor: the amount by which to multiply (defaults to 1.0)
192   min: the minimum allowed value (default: no minimum)
193   max: the maximum allowed value (default: no maximum)
194   mask: 'integer' to apply only to the left of the decimal point;
195     'decimal' to apply only to the right of the decimal point; 'all'
196     to apply to the full value (defaults to 'all')
197   wrap: true if the value should be wrapped when it passes min or max;
198     both min and max must be specified (defaults to false)
199
200 property-swap - swap the values of two properties
201   property[0]: the name of the first property
202   property[1]: the name of the second property
203
204 property-scale - set the value of a property based on an axis
205   property: the name of the property to set
206   setting: the current input setting (usually a joystick axis from -1
207     or 0 to 1)
208   offset: the offset to shift by, before applying the factor (defaults
209     to 0)
210   factor: the factor to multiply by (use negative to reverse; defaults
211     to 1.0)
212   squared: if true will square the resulting value (same as power=2)
213   power: the resulting value will be taken to the power of this integer
214     value (overrides squared; default=1)
215
216 property-cycle - cycle a property through a set of values
217   property: the name of the property to cycle
218   value[*]: all of the allowed values
219
220 dialog-new - create new dialog from the argument branch
221
222 dialog-show - show an XML-configured dialog box
223   dialog-name - the name of the dialog to show
224
225 dialog-close - close the active dialog box
226
227 dialog-update - copy values from FlightGear to the active dialog box
228   object-name: the name of the GUI object to update (defaults to all
229     objects)
230
231 dialog-apply - copy values from the active dialog box to FlightGear
232   object-name: the name of the GUI object to apply (defaults to all
233     objects)
234
235 presets-commit - commit preset values from /sim/presets
236
237
238 The following commands are temporary, and will soon disappear or be
239 renamed; do NOT rely on them:
240
241 old-save-dialog - offer to save a flight
242
243 old-load-dialog - offer to load a flight
244
245 old-reinit-dialog - offer to reinit FlightGear
246
247 old-hires-snapshot-dialog - save a hires screen shot
248
249 old-snapshot-dialog - save a screenshot
250
251 old-print-dialog - print the screen (Windows only)
252
253 old-pilot-offset-dialog - set pilot offsets graphically
254
255 old-hud-alpha-dialog - set the alpha value for the HUD
256
257 old-properties-dialog - display the property browser
258
259 old-preset-airport-dialog - set the default airport
260
261 old-preset-runway-dialog - set the default runway
262
263 old-preset-offset-distance-dialog - set the default offset distance
264
265 old-preset-altitude-dialog - set the default altitude
266
267 old-preset-glidescope-dialog - set the default glidescope
268
269 old-preset-airspeed-dialog - set the default airspeed
270
271 old-preset-commit-dialog - commit preset values
272
273 old-ap-add-waypoint-dialog - add a waypoint to the current route
274
275 old-ap-pop-waypoint-dialog - remove a waypoint from the current route
276
277 old-ap-clear-dialog - clear the current route
278
279 old-ap-adjust-dialog - adjust the autopilot settings
280
281 old-lat-lon-format-dialog - toggle the lat/lon format in the HUD
282
283 old-help-dialog - offer online help
284
285
286 Adding New Commands in C++
287 --------------------------
288
289
290 To add a new command to FlightGear, you first need to create a
291 function that takes a single SGPropertyNode const pointer as an
292 argument:
293
294   void
295   do_something (SGPropertyNode * arg)
296   {
297     something();
298   }
299
300 Next, you need to register it with the command manager:
301
302   globals->get_commands()->addCommand("something", do_something);
303
304 Now, the command "something" is available to any mouse, joystick,
305 panel, or keyboard bindings.  If the bindings pass any arguments, they
306 will be children of the SGPropertyNode passed in:
307
308   void
309   do_something (const SGPropertyNode * arg)
310   {
311     something(arg->getStringValue("foo"), arg->getDoubleValue("bar"));
312   }
313
314 That's pretty-much it.  Apologies in advance for not making things any
315 more complicated.
316
317