Howto:Add multi-key commands to an aircraft
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
<?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>
The syntax builds up like a tree where the leaf nodes have bindings.
<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>
<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>
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 ↹).
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
<!-- ... --> <input> <keyboard n="0"> <multikey include="aircraft-multikey.xml"/> <!-- Does not have to specifically be "aircraft-multikey.xml" --> <!-- ... --> </keyboard> <input> <!-- ... -->
|This section is a stub. You can help the wiki by|
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.
- $FG_ROOT/keyboard.xml#l634 Lines 634-641 of the keyboard configuration file delegates handling to multikey.start()
- $FG_ROOT/Nasal/multikey.nas The global Nasal multi-key handler.
These are a good example of how one can do.
- $FG_AIRCRAFT/Aircraft/f-14b/f-14-common.xml#l1367 Line 1367 delegates the handling to Systems/instruments-multikey.xml.