docs-mini/README.commands

   1 FlightGear Commands Mini-HOWTO
   2
   3 David Megginson
   4 Started: 2002-10-25
   5 Last revised: 2003-01-20
   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.
  55
  56
  57 Built-in Commands
  58 -----------------
  59
  60 As of the last revision date, the following commands were available
  61 from inside FlightGear; the most commonly-used ones are the commands
  62 that operate on property values (FlightGear's internal state):
  63
  64
  65 null - do nothing
  66
  67 script - execute a PSL script
  68   script: the PSL script to execute
  69
  70 exit - prompt and quit FlightGear
  71
  72 load - load properties from an XML file
  73   file: the name of the file to load, relative to the current
  74     directory (defaults to "fgfs.sav")
  75
  76 save - save properties to an XML file
  77   file: the name of the file to save, relative to the current
  78     directory (defaults to "fgfs.sav").
  79
  80 loadxml - load XML file into property tree
  81   filename: the path & filename of the file to load
  82   targetnode: the target node within the property tree where to store the XML
  83   file's structure
  84
  85 savexml - save property tree node to XML file
  86   filename: the path & filename for the file to be saved
  87   sourcenode: the source node within the property tree where the XML file's
  88   structure is assembled from.
  89
  90 panel-load - (re)load the 2D instrument panel
  91   path: the path of the XML panel file, relative to $FG_ROOT (defaults
  92     to the value of /sim/panel/path if specified, or
  93     "Panels/Default/default.xml" as a last resort.
  94
  95 panel-mouse-click - pass a mouse click to the instrument panel
  96   button: the number of the mouse button (0-based)
  97   is-down: true if the button is down, false if it is up
  98   x-pos: the x position of the mouse click
  99   y-pos: the y position of the mouse click
 100
 101 preferences-load - (re)load preferences
 102   path: the file name to load preferences from, relative to $FG_ROOT.
 103     Defaults to "preferences.xml".
 104
 105 view-cycle - cycle to the next viewpoint
 106
 107 screen-capture - capture the screen to a file
 108
 109 tile-cache-reload - reload the scenery tile cache
 110
 111 lighting-update - update FlightGear's lighting
 112
 113 property-toggle - swap a property value between true and false
 114   property: the name of the property to toggle
 115
 116 property-assign - assign a value to a property
 117   property[0]: the name of the property that will get the new value.
 118   value: the new value for the property; or
 119   property[1]: the name of the property holding the new value.
 120
 121 property-adjust - adjust the value of a property
 122   property: the name of the property to increment or decrement
 123   step: the amount of the increment or decrement (defaults to 0)
 124   offset: input offset distance (used for the mouse; multiplied by
 125     factor)
 126   factor: factor for multiplying offset distance (used for the mouse;
 127     defaults to 1)
 128   min: the minimum allowed value (default: no minimum)
 129   max: the maximum allowed value (default: no maximum)
 130   mask: 'integer' to apply only to the left of the decimal point;
 131     'decimal' to apply only to the right of the decimal point; 'all'
 132     to apply to the full value (defaults to 'all')
 133   wrap: true if the value should be wrapped when it passes min or max;
 134     both min and max must be specified (defaults to false)
 135
 136 property-multiply - multiply the value of a property
 137   property: the name of the property to multiply
 138   factor: the amount by which to multiply (defaults to 1.0)
 139   min: the minimum allowed value (default: no minimum)
 140   max: the maximum allowed value (default: no maximum)
 141   mask: 'integer' to apply only to the left of the decimal point;
 142     'decimal' to apply only to the right of the decimal point; 'all'
 143     to apply to the full value (defaults to 'all')
 144   wrap: true if the value should be wrapped when it passes min or max;
 145     both min and max must be specified (defaults to false)
 146
 147 property-swap - swap the values of two properties
 148   property[0]: the name of the first property
 149   property[1]: the name of the second property
 150
 151 property-scale - set the value of a property based on an axis
 152   property: the name of the property to set
 153   setting: the current input setting (usually a joystick axis from -1
 154     or 0 to 1)
 155   offset: the offset to shift by, before applying the factor (defaults
 156     to 0)
 157   factor: the factor to multiply by (use negative to reverse; defaults
 158     to 1.0)
 159
 160 property-cycle - cycle a property through a set of values
 161   property: the name of the property to cycle
 162   value[*]: all of the allowed values
 163
 164 dialog-show - show an XML-configured dialog box
 165   dialog-name - the name of the dialog to show
 166
 167 dialog-close - close the active dialog box
 168
 169 dialog-update - copy values from FlightGear to the active dialog box
 170   object-name: the name of the GUI object to update (defaults to all
 171     objects)
 172
 173 dialog-apply - copy values from the active dialog box to FlightGear
 174   object-name: the name of the GUI object to apply (defaults to all
 175     objects)
 176
 177 presets-commit - commit preset values from /sim/presets
 178
 179
 180 The following commands are temporary, and will soon disappear or be
 181 renamed; do NOT rely on them:
 182
 183 old-save-dialog - offer to save a flight
 184
 185 old-load-dialog - offer to load a flight
 186
 187 old-reinit-dialog - offer to reinit FlightGear
 188
 189 old-hires-snapshot-dialog - save a hires screen shot
 190
 191 old-snapshot-dialog - save a screenshot
 192
 193 old-print-dialog - print the screen (Windows only)
 194
 195 old-pilot-offset-dialog - set pilot offsets graphically
 196
 197 old-hud-alpha-dialog - set the alpha value for the HUD
 198
 199 old-properties-dialog - display the property browser
 200
 201 old-preset-airport-dialog - set the default airport
 202
 203 old-preset-runway-dialog - set the default runway
 204
 205 old-preset-offset-distance-dialog - set the default offset distance
 206
 207 old-preset-altitude-dialog - set the default altitude
 208
 209 old-preset-glidescope-dialog - set the default glidescope
 210
 211 old-preset-airspeed-dialog - set the default airspeed
 212
 213 old-preset-commit-dialog - commit preset values
 214
 215 old-ap-add-waypoint-dialog - add a waypoint to the current route
 216
 217 old-ap-pop-waypoint-dialog - remove a waypoint from the current route
 218
 219 old-ap-clear-dialog - clear the current route
 220
 221 old-ap-adjust-dialog - adjust the autopilot settings
 222
 223 old-lat-lon-format-dialog - toggle the lat/lon format in the HUD
 224
 225 old-help-dialog - offer online help
 226
 227
 228 Adding New Commands in C++
 229 --------------------------
 230
 231
 232 To add a new command to FlightGear, you first need to create a
 233 function that takes a single SGPropertyNode const pointer as an
 234 argument:
 235
 236   void
 237   do_something (SGPropertyNode * arg)
 238   {
 239     something();
 240   }
 241
 242 Next, you need to register it with the command manager:
 243
 244   globals->get_commands()->addCommand("something", do_something);
 245
 246 Now, the command "something" is available to any mouse, joystick,
 247 panel, or keyboard bindings.  If the bindings pass any arguments, they
 248 will be children of the SGPropertyNode passed in:
 249
 250   void
 251   do_something (const SGPropertyNode * arg)
 252   {
 253     something(arg->getStringValue("foo"), arg->getDoubleValue("bar"));
 254   }
 255
 256 That's pretty-much it.  Apologies in advance for not making things any
 257 more complicated.
 258
 259