Howto:Add multi-key commands to an aircraft

From FlightGear wiki
Jump to navigation Jump to search
The on-screen help for the multi-key commands.

This tutorial will guide you through how to add multi-key commands to an aircraft and how they work.

The multi-key commands are vi-like key sequences that begin with : and is followed by other keys.

Define the multi-key commands

  • Begin the aircraft-specific sequences with :A.
  • If for example an instrument have many bindings, begin its sequences with :A and a uppercase letter specific for that instrument followed by the rest of the sequence.

The multikey.xml file

The multi-key commands are defined in a property-list xml file, named for example aircraft-multikey.xml. 

<?xml version="1.0" encoding="UTF-8"?>
 
<!--
    This file defines vi-like key sequences which are started with the ':'-key.
    It's evaluated by $FG_ROOT/Nasal/multikey.nas.

    - <Esc> always aborts.
    - <Return>/<Enter> executes and terminates the command mode, given that
      <binding>s exist (use "null" if there's nothing else to do) and <no-exit/>
      isn't defined.
    - Keys with defined <exit/> property execute their bindings immediately,
      that is: without having to press <Return>/<Enter>.
    - Format placeholder values are available to Nasal code via arg[].
    - Nasal code can set the dialog title by assignment to the _ variable.
    - <key> indices aren't used by the system, but are recommended to allow
      reliable overwriting by aircraft or user xml files.
    - Cursor keys are equivalent to characters <, >, ^, _.
-->

<PropertyList>

    <key n="65">               <!-- "65" is the key code -->
        <name>A</name>
        <desc>Aircraft</desc>  <!-- reserved for aircraft extensions -->


        <!--
            List of keys.

            - Due to the key sequences, keys can also be nested.
            - Only the leaf nodes have bindings.
        -->

    </key>

</PropertyList>

Syntax

The syntax builds up like a tree where the leaf nodes have bindings.

Non-leaf nodes

        <key n="n">         <!-- n is a key code -->
            <name><name>    <!-- Name of the key -->
            <desc></desc>   <!-- Short description of what the key will do -->

            <key n="n">     <!-- n is a key code -->
                <!-- ... -->
            </key>

            <key n="n">     <!-- n is a key code -->
                <!-- ... -->
            </key>

            <!-- ... -->

        </key>

Leaf nodes

        <key n="n">         <!-- n is a key code -->
            <name><name>    <!-- Name of the key -->
            <desc></desc>   <!-- Short description of what the key will do -->
            <exit/>         <!-- If added the binding will be executed immediately instead of when enter is pressed -->
            <binding>       <!-- Key bindings -->
                <!-- ... -->
            </binding>
            <binding>       <!-- One key can have more than one binding -->
                <!-- ... -->
            </binding>
        </key>

Key codes

See Howto:Reassign keyboard keys#Finding keycodes.

Name and description

It is a very good idea to use the key name and a short but meaningful description as those are used by the multi-key command on-screen help dialog (when it is toggled on with :Tab ↹).

Bindings

The bindings uses the same syntax as described in Bindings and Howto:Reassign keyboard keys#Adding or modifying key assignments.

Include the commands into the aircraft-set.xml file

Add this line to the aircraft-set.xml file: 

  <!-- ... -->

  <input>
    <keyboard n="0">
      <multikey include="aircraft-multikey.xml"/>  <!-- Does not have to specifically be "aircraft-multikey.xml" -->

      <!-- ... -->
    </keyboard>
  </input>

  <!-- ... -->

Technical details

This section is a stub. You can help the wiki by expanding it.

Among the nasal files in $FGDATA/Nasal that are loaded when FlightGear starts is multikey.nas that will load a number of Nasal functions. The keyboard configuration file $FGDATA/keyboard.xml will call multikey.start() when the : key is used.

Related content

Wiki articles

Source code

fgdata files

F-14B files

These are a good example of how one can do.

Retrieved from "https://wiki.flightgear.org/w/index.php?title=Howto:Add_multi-key_commands_to_an_aircraft&oldid=135083"