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