``<command>``
===============

The ``<command>`` tag represents an *action* within FlightGear XML files. It is typically used as a
child element, such as in :doc:`<binding> <binding>`, to map an action to a user input
(e.g., a keyboard key or joystick button).

Because of the large number of values that can be passed to the ``<command>`` element, it is quite a
powerful command that is used across many different aspects of the simulator.

``open-browser``
~~~~~~~~~

**Description**:
The ``open-browser`` command is used to open a URL in the users web browser, typically for providing
easy access to online documentation.

**Syntax**:

.. code-block:: xml

  <binding>
    <command>open-browser</command>
    <path></path>
  </binding>

.. code-block:: xml

  <binding>
    <command>open-browser</command>
    <url></url>
  </binding>

``null``
~~~~~~~~

**Description**:
The ``null`` command does nothing. It is useful when no action is required.

**Syntax**:

.. code-block:: xml

    <command>null</command>

---

``exit``
~~~~~~~~

**Description**:
The ``exit`` command exits the simulator when triggered.

**Syntax**:

.. code-block:: xml

    <command>exit</command>

---

``pause``
~~~~~~~~~

**Description**:
The ``pause`` command pauses the simulator when triggered.

**Syntax**:

.. code-block:: xml

    <command>pause</command>

---

``nasal``
~~~~~~~~~

**Description**:
The ``nasal`` command triggers execution of Nasal code.

**Usage**:

A :doc:`<script> <script>` element must be used alongside the <command> element. The <script>
element must be provided a value containing the Nasal code to be executed.

**Syntax**:

.. code-block:: xml

    <command>nasal</command>

**Example**:

.. code-block:: xml

    <binding>
        <command>nasal</command>
        <script>print("Hello from Nasal!")</script>
    </binding>

load - load properties from an XML file
  file: the name of the file to load, relative to the current
    directory (defaults to "fgfs.sav")

save - save properties to an XML file
  file: the name of the file to save, relative to the current
    directory (defaults to "fgfs.sav").

loadxml - load XML file into property tree
  filename: the path & filename of the file to load
  targetnode: the target node within the property tree where to store the XML
  file's structure. If targetnode isn't defined, then the data will be stored
  in a node "data" under the argument branch.

savexml - save property tree node to XML file
  filename: the path & filename for the file to be saved
  sourcenode: the source node within the property tree where the XML file's
  structure is assembled from. If sourcenode isn't defined, then savexml will
  try to save data stored in a node "data" in the argument branch.

panel-load - (re)load the 2D instrument panel
  path: the path of the XML panel file, relative to $FG_ROOT (defaults
    to the value of /sim/panel/path if specified, or
    "Panels/Default/default.xml" as a last resort.

preferences-load - (re)load preferences
  path: the file name to load preferences from, relative to $FG_ROOT.
    Defaults to "preferences.xml".

``view-cycle``
~~~~~~~~~~~~~~

**Description**:
The ``view-cycle`` command cycles to the next view, for example, changing from the "Helicopter View"
to the "Chase View".

screen-capture - capture the screen to a file

tile-cache-reload - reload the scenery tile cache

``property-toggle``
~~~~~~~~~~~~~~~~~~~

**Description**:
The ``property-toggle`` command toggles a boolean property value - if the property was previously
``false``, it will be toggled to ``true``, and vice-versa.

**Usage**:
When a ``<command>`` element is passed a value of ``property-toggle``, there must be an accompanying
``<property>`` element to indicate the property that should be toggled.

**Example**:

One common usecase for the ``property-toggle`` command is in the creation of bindings for input
devices such as joysticks. Assuming we are creating an XML configuration for an input device, and
wanted to create a binding that would toggle the parking brake, the XML would look like:

.. code-block:: xml

  <binding>
    <command>property-toggle</command>
    <property>/controls/gear/brake-parking</property> <!-- Note the included property element -->
  </binding>

``property-assign``
~~~~~~~~~~~~~~~~~~~

**Description**:
The ``property-assign`` command pauses the simulator when triggered.

 - assign a value to a property
  property[0]: the name of the property that will get the new value.
  value: the new value for the property; or
  property[1]: the name of the property holding the new value.

``property-interpolate``
~~~~~~~~~~~~~~~~~~~~~~~~

**Description**:
The ``property-interpolate`` command pauses the simulator when triggered.

 - assign a value to a property, interpolated
                       over time
  property[0]: the name of the property that will get the new value
               and defines the starting point of the interpolation
  value:       the new value for the property; or
  property[1]: the name of the property holding the new value.
  time:        the time in seconds it takes for the transition from the
               old value to the new value of property[0]; or
  rate:        the ammount of change per second the value of property[0] changes
               to transition to the new value

``property-adjust``
~~~~~~~~~~~~~~~~~~~

**Description**:
The ``pause`` command pauses the simulator when triggered.

 - adjust the value of a property
  property: the name of the property to increment or decrement
  step: the amount of the increment or decrement (defaults to 0)
  offset: input offset distance (used for the mouse; multiplied by
    factor)
  factor: factor for multiplying offset distance (used for the mouse;
    defaults to 1)
  min: the minimum allowed value (default: no minimum)
  max: the maximum allowed value (default: no maximum)
  mask: 'integer' to apply only to the left of the decimal point;
    'decimal' to apply only to the right of the decimal point; 'all'
    to apply to the full value (defaults to 'all')
  wrap: true if the value should be wrapped when it passes min or max;
    both min and max must be specified (defaults to false)

``property-multiply``
~~~~~~~~~~~~~~~~~~~~~

**Description**:
The ``pause`` command pauses the simulator when triggered.

 - multiply the value of a property
  property: the name of the property to multiply
  factor: the amount by which to multiply (defaults to 1.0)
  min: the minimum allowed value (default: no minimum)
  max: the maximum allowed value (default: no maximum)
  mask: 'integer' to apply only to the left of the decimal point;
    'decimal' to apply only to the right of the decimal point; 'all'
    to apply to the full value (defaults to 'all')
  wrap: true if the value should be wrapped when it passes min or max;
    both min and max must be specified (defaults to false)

``property-swap``
~~~~~~~~~~~~~~~~~

**Description**:

``property-scale``
~~~~~~~~~~~~~~~~~~

**Description**:

``property-cycle``
~~~~~~~~~~~~~~~~~~

**Description**:

``dialog-show``
~~~~~~~~~~~~~~~

**Description**:

``dialog-close``
~~~~~~~~~~~~~~~~

**Description**:

``dialog-update``
~~~~~~~~~~~~~~~~~

**Description**:

``dialog-apply``
~~~~~~~~~~~~~~~~

**Description**:

presets-commit - commit preset values from /sim/presets

.. todo::
  A grep across all repos for any value inside of a <command> returns the following.
  Need to filter out which are aircraft specific and which are built-ins and therefore which we
  should be documenting and which we shouldn't. If a value is listed above in the old documentation
  but not used once anywhere in any FlightGear code, it's probably a safe assumption that it was
  removed at some point and should not be documented.

  adc_autoconf
  addon-reload
  ATC-dialog
  ATC-freq-search

  cpdlc-compose
  cpdlc-connect
  cpdlc-dialog
  cpdlc-disconnect
  cpdlc-next-message
  cpdlc-send

  cycle-mouse-mode
  dialog-apply
  dialog-close
  dialog-show
  dialog-toggle
  dialog-update
  dismiss-error-report
  dump-scenegraph
  emesary-transmit

  FG1000HardKeyPushed
  FG1000SoftKeyPushed

  fgcamera-adjust
  fgcamera-next-category
  fgcamera-next-in-category
  fgcamera-prev-category
  fgcamera-prev-in-category
  fgcamera-reset-view
  fgcamera-select

  goflight-mcp-button

  illuminator-adjust

  kln89_alt_pressed
  kln89_clr_pressed
  kln89_crsr_pressed
  kln89_dto_pressed
  kln89_ent_pressed
  kln89_gps_apr_pressed
  kln89_knob1left1
  kln89_knob1right1
  kln89_knob2left1
  kln89_knob2right1
  kln89_msg_pressed
  kln89_nrst_pressed
  kln89_obs_pressed

  lighting-update
  load-aircraft
  multiplayer-disconnect
  nasal-module-reload
  nasal-reload
  panel-load
  preferences-load
  press-cockpit-button
  print-visible-scene
  property-adjust
  property-assign
  property-assign/adjust/toggle/swap
  property-cycle
  property-interpolate
  property-multiply
  property-randomize
  property-scale
  property-swap
  property-update
  reinit
  release-cockpit-button
  reload-compositor
  reload-materials
  reload-shaders
  replay
  reposition
  reset
  save
  save-error-report-data
  screen-capture
  set-tooltip
  show-error-report
  show-message
  tile-cache-reload
  timeofday
  toggle-fullscreen
  view-clone
  view-last-pair
  view-last-pair-double
  view-push

.. admonition:: Attribution
   :class: attribution

   Based on documentation originally created by David Megginson