Bindings

Bindings define what happens when a user:

• Clicks an object in the scenery or in an aircraft.
• Presses a key/button on the keyboard or joystick.
• Clicks a menu item
• Interacts with a dialog

You can assign multiple bindings to one object, button or key. Bindings may contain conditions to make them conditionally executed. Each binding must specify a command node with its particular type, see below.

This article gives a small overview of frequently used bindings. Please refer to $FG_ROOT/Docs/README.commands for additional information and a complete list of available bindings.

All given codes are examples, found on various places in the FlightGear package.

Commands

Below are a number of useful commands. See for the complete list, see flightgear/src/Main/fg_commands.cxx (line 1425).

To learn more about adding your own custom fgcommands to the source code, see Howto:Add new fgcommands to FlightGear

dialog-close

Closes the active dialog.

<binding>
  <command>dialog-close</command>
</binding>

dialog-show

Shows a dialog, which should be present in $FG_ROOT/gui/dialogs. Starting with FlightGear 2.7, dialog files located in <aircraft directory>/gui/dialogs are also loaded. This should be used for dialogs specific to a certain aircraft.

<binding>
  <command>dialog-show</command>
  <dialog-name>location-in-air</dialog-name>
</binding>

• dialog-name: the name of the dialog, as designated in its .xml file.

nasal

Nasal is frequently used for complicated systems, because it can execute virtually any function and allows running previously-defined Nasal functions.

<binding>
  <command>nasal</command>
  <script>b777.afds.input(0,1);</script>
</binding>

The cmdarg function is often useful in these situations to extract offset values passed to the binding. It returns the specific <binding> node, which contains a <setting> node at runtime if used in a joystick axis that represents the value of that axis.

In joysticks and keyboard keys the script is run in a specific namespace; please refer to the documentation for what the namespace is.

property-adjust

Increases or decreases a property's value with a given step. Maximum and minimum values are optional.

<binding>
  <command>property-adjust</command>
  <property>/autopilot/settings/heading-bug-deg</property>
  <step>1</step>    <!-- will add 1 to /autopilot/settings/heading-bug-deg whenever this binding is called -->
  <min>000</min>    <!-- the property will never be allowed to go below 0 -->
  <max>360</max>    <!-- ...or above 360 -->
  <wrap>true</wrap> <!-- when we hit 361, wrap back to 0 and vice-versa -->
</binding>

property-assign

One of the most important commands. It sets a property to a predefined value.

<binding>
  <command>property-assign</command>
  <property>/autopilot/settings/target-speed-kt</property>
  <value>0</value>
</binding>

property-cycle

Cycles between a list of values and assigns one to a property. The value-list can vary in length. If the current value is "value1", it will change to "value2"; if it is "value2", it will change to "value3", and so on, wrapping around the end. If the current value is not in the list, it will jump to the first one.

<binding>
  <command>property-cycle</command>
  <property>/autopilot/autobrake/setting</property>
  <value type="string">ARM</value>
  <value type="string">DISARM</value>
  <value type="string">OFF</value>
</binding>

As of May 2013, the command supports additional behaviours to simplify use with the new knob and slider animations. The wrapping behaviour can be disabled by setting <wrap>0</wrap>, and the command uses the 'offset' argument to select a direction of movement. This means a property-cycle bound to a multi-position knob will function as expected for movement in both directions.

property-interpolate

Interpolates to a value with a given rate of change (per second).

<binding>
  <command>property-interpolate</command>
  <property>/controls/flight/aileron-trim</property>
  <value type="double">0</value>
  <rate>0.5</rate><!-- 2 seconds to 0 from 1 or -1 -->
</binding>

Instead of using <rate>, one could use , to specify the time (in seconds) it takes to go to the new value, independent of the current value.

<binding>
  <command>property-interpolate</command>
  <property>/controls/flight/aileron-trim</property>
  <value type="double">0</value>
  <time>2</time><!-- 2 seconds to 0 from 1, 0.5, -1 etc. -->
</binding>

You can also interpolate to a value given by a property.

<binding>
  <command>property-interpolate</command>
  <property>/controls/flight/aileron-trim</property>
  <property>/controls/flight/default-aileron-trim</property><!-- the value to interpolate to, is 0 -->
  <rate>0.5</rate><!-- 2 seconds to 0 from 1 or -1 -->
</binding>

property-multiply

Multiply the value of a property by a given factor.

<binding>
  <command>property-multiply</command>
  <property>/controls/flight/aileron</property>
  <factor>0.5</factor>
  <min>-1</min>
  <max>1</max>
  <mask>all</mask>
  <wrap>true</wrap>
</binding>

• factor: the amount to multiply by.
• min: minimum value.
• max: maximum value.
• mask:
  • integer: mutiply only left of the decimal point.
  • decimal: multiply only the right of the decimal point.
  • all: multiply the entire value.
• wrap: true if the value should be wrapped if it passes min/max. It is required to set both min and max in that case.

property-randomize

Assigns a random value (between min and max) to a property.

<binding>
  <command>property-randomize</command>
  <property>/orientation/pitch-deg</property>
  <min>0</min>
  <max>360</max>
</binding>

property-scale

Set the value of a property based on an axis, often used in joystick configuration files.

<binding>
  <command>property-scale</command>
  <property>/controls/flight/aileron</property>
  <offset>0.001</offset>
  <factor>-1</factor>
  <power>3</power>
</binding>

• offset: the offset to shift by, before applying the factor.
• factor: the factor to multiply by (use negative to reverse).
• squared: if true will square the resulting value (same as power=2).
• power: the resulting value will be taken to the power of this integer value (overrides squared).

Remember: ((property+offset)*factor)^power=result

property-swap

Swaps the values of two properties, useful for radio panels.

<binding>
  <command>property-swap</command>
  <property>/instrumentation/comm/frequencies/selected-mhz</property>
  <property>/instrumentation/comm/frequencies/standby-mhz</property>
</binding>

property-toggle

Toggles the value of a property on each click, between true (1) and false (0).

<binding>
  <command>property-toggle</command>
  <property>/controls/gear/gear-down</property>
</binding>

Or - if defined - it toggles between two custom values.

<binding>
  <command>property-toggle</command>
  <property>/controls/gear/gear-down</property>
  <value>2</value>
  <value>3</value>
</binding>

request-metar

fgcommand("request-metar", props.Node.new({"path": "/foo/mymetar", "station": "LOWI"})); If you pass an existing path, the station ID will be updated, and if you pass the same station ID as before, no additional request is made. As usual for metar-properties, there's a time-to-live and valid flags you can check, and the metar refreshes automatically every 900 seconds. You can also write to the station ID directly to change station, update the time-to-live, and wait for the valid signal. There's also an unregister command ('clear-metar') to cancel the binding into the property tree. — James Turner

Related content

• $FG_ROOT/Docs/README.commands
• Howto:Make a clickable panel
• Howto:Reassign keyboard bindings