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