bcc9fb1532
- add <condition> and <mod-{up,shift,ctrl,alt,meta,super}>
example to key definition description
317 lines
9.9 KiB
Text
317 lines
9.9 KiB
Text
FlightGear Commands Mini-HOWTO
|
|
|
|
David Megginson
|
|
Started: 2002-10-25
|
|
Last revised: 2007-12-01
|
|
|
|
|
|
In FlightGear, a *command* represents an action, while a *property*
|
|
represents a state. The trigger for a command can be any kind of user
|
|
input, including the keyboard, mouse, joystick, GUI, instrument panel,
|
|
or a remote network client.
|
|
|
|
|
|
XML Command Binding Markup
|
|
--------------------------
|
|
|
|
Most of the command-binding in FlightGear is handled through static
|
|
XML configuration files such as $FG_ROOT/keyboard.xml for the
|
|
keyboard, $FG_ROOT/mice.xml for the mouse, and
|
|
$FG_ROOT/gui/menubar.xml for the menubar. In all of these files, you
|
|
reference a command through a binding. This binding advances the
|
|
first throttle by 1%, up to a maximum value of 1.0:
|
|
|
|
<binding>
|
|
<command>property-adjust</command>
|
|
<property>/controls/throttle[0]</property>
|
|
<step type="double">0.01</step>
|
|
<max>1.0</max>
|
|
</binding>
|
|
|
|
A command binding always consists of the XML 'binding' element, with
|
|
one subelement named 'command' containing the command name (such as
|
|
'property-adjust'). All other subelements are named parameters to the
|
|
command: in this case, the parameters are 'property', 'step', and
|
|
'max'. Here is a simpler binding, with no parameters:
|
|
|
|
<binding>
|
|
<command>exit</command>
|
|
</binding>
|
|
|
|
Bindings always appear inside some other kind of markup, depending on
|
|
the input type. For example, here is the binding from keyboard.xml
|
|
that links the ESC key to the 'exit' command:
|
|
|
|
<key n="27">
|
|
<name>ESC</name>
|
|
<desc>Prompt and quit FlightGear.</desc>
|
|
<binding>
|
|
<command>exit</command>
|
|
</binding>
|
|
</key>
|
|
|
|
Usually, more than one binding is allowed for a single input trigger,
|
|
and bindings are executed in order from first to last. Bindings support
|
|
conditions (see README.conditions):
|
|
|
|
<key n="113">
|
|
<name>q</name>
|
|
<desc>Test</desc>
|
|
|
|
<binding>
|
|
<condition>
|
|
<property>/devices/status/mice/mouse/button[0]</property>
|
|
</condition>
|
|
<command>nasal</command>
|
|
<script>print("mouse button 0 pressed")</script>
|
|
</binding>
|
|
</key>
|
|
|
|
Keyboard definitions can embed bindings in tags <mod-up> (key released),
|
|
<mod-shift>, <mod-ctrl>, <mod-alt>, <mod-meta>, and <mod-super>. Nesting
|
|
is supported. Meta and Super modifier tags are for local use only, and
|
|
must be supported by the operating system to work.
|
|
|
|
<key n="113">
|
|
<name>q</name>
|
|
<desc>Test</desc>
|
|
<binding>
|
|
<command>nasal</command>
|
|
<script>print("q pressed")</script>
|
|
</binding>
|
|
|
|
<mod-alt>
|
|
<binding>
|
|
<command>nasal</command>
|
|
<script>print("Alt-q pressed")</script>
|
|
</binding>
|
|
|
|
<mod-super>
|
|
<binding>
|
|
<command>nasal</command>
|
|
<script>print("Alt-Super-q pressed")</script>
|
|
</binding>
|
|
|
|
<mod-meta>
|
|
<binding>
|
|
<command>nasal</command>
|
|
<script>print("Alt-Super-Meta-q pressed")</script>
|
|
</binding>
|
|
|
|
</mod-meta>
|
|
</mod-super>
|
|
</mod-alt>
|
|
</key>
|
|
|
|
|
|
|
|
Built-in Commands
|
|
-----------------
|
|
|
|
As of the last revision date, the following commands were available
|
|
from inside FlightGear; the most commonly-used ones are the commands
|
|
that operate on property values (FlightGear's internal state):
|
|
|
|
|
|
null - do nothing
|
|
|
|
script - execute a PSL script
|
|
script: the PSL script to execute
|
|
|
|
exit - prompt and quit FlightGear
|
|
|
|
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.
|
|
|
|
panel-mouse-click - pass a mouse click to the instrument panel
|
|
button: the number of the mouse button (0-based)
|
|
is-down: true if the button is down, false if it is up
|
|
x-pos: the x position of the mouse click
|
|
y-pos: the y position of the mouse click
|
|
|
|
preferences-load - (re)load preferences
|
|
path: the file name to load preferences from, relative to $FG_ROOT.
|
|
Defaults to "preferences.xml".
|
|
|
|
view-cycle - cycle to the next viewpoint
|
|
|
|
screen-capture - capture the screen to a file
|
|
|
|
tile-cache-reload - reload the scenery tile cache
|
|
|
|
lighting-update - update FlightGear's lighting
|
|
|
|
property-toggle - swap a property value between true and false
|
|
property: the name of the property to toggle
|
|
|
|
property-assign - 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-adjust - 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 - 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 - swap the values of two properties
|
|
property[0]: the name of the first property
|
|
property[1]: the name of the second property
|
|
|
|
property-scale - set the value of a property based on an axis
|
|
property: the name of the property to set
|
|
setting: the current input setting (usually a joystick axis from -1
|
|
or 0 to 1)
|
|
offset: the offset to shift by, before applying the factor (defaults
|
|
to 0)
|
|
factor: the factor to multiply by (use negative to reverse; defaults
|
|
to 1.0)
|
|
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; default=1)
|
|
|
|
property-cycle - cycle a property through a set of values
|
|
property: the name of the property to cycle
|
|
value[*]: all of the allowed values
|
|
|
|
dialog-new - create new dialog from the argument branch
|
|
|
|
dialog-show - show an XML-configured dialog box
|
|
dialog-name - the name of the dialog to show
|
|
|
|
dialog-close - close the active dialog box
|
|
|
|
dialog-update - copy values from FlightGear to the active dialog box
|
|
object-name: the name of the GUI object to update (defaults to all
|
|
objects)
|
|
|
|
dialog-apply - copy values from the active dialog box to FlightGear
|
|
object-name: the name of the GUI object to apply (defaults to all
|
|
objects)
|
|
|
|
presets-commit - commit preset values from /sim/presets
|
|
|
|
|
|
The following commands are temporary, and will soon disappear or be
|
|
renamed; do NOT rely on them:
|
|
|
|
old-save-dialog - offer to save a flight
|
|
|
|
old-load-dialog - offer to load a flight
|
|
|
|
old-reinit-dialog - offer to reinit FlightGear
|
|
|
|
old-hires-snapshot-dialog - save a hires screen shot
|
|
|
|
old-snapshot-dialog - save a screenshot
|
|
|
|
old-print-dialog - print the screen (Windows only)
|
|
|
|
old-pilot-offset-dialog - set pilot offsets graphically
|
|
|
|
old-hud-alpha-dialog - set the alpha value for the HUD
|
|
|
|
old-properties-dialog - display the property browser
|
|
|
|
old-preset-airport-dialog - set the default airport
|
|
|
|
old-preset-runway-dialog - set the default runway
|
|
|
|
old-preset-offset-distance-dialog - set the default offset distance
|
|
|
|
old-preset-altitude-dialog - set the default altitude
|
|
|
|
old-preset-glidescope-dialog - set the default glidescope
|
|
|
|
old-preset-airspeed-dialog - set the default airspeed
|
|
|
|
old-preset-commit-dialog - commit preset values
|
|
|
|
old-ap-add-waypoint-dialog - add a waypoint to the current route
|
|
|
|
old-ap-pop-waypoint-dialog - remove a waypoint from the current route
|
|
|
|
old-ap-clear-dialog - clear the current route
|
|
|
|
old-ap-adjust-dialog - adjust the autopilot settings
|
|
|
|
old-lat-lon-format-dialog - toggle the lat/lon format in the HUD
|
|
|
|
old-help-dialog - offer online help
|
|
|
|
|
|
Adding New Commands in C++
|
|
--------------------------
|
|
|
|
|
|
To add a new command to FlightGear, you first need to create a
|
|
function that takes a single SGPropertyNode const pointer as an
|
|
argument:
|
|
|
|
void
|
|
do_something (SGPropertyNode * arg)
|
|
{
|
|
something();
|
|
}
|
|
|
|
Next, you need to register it with the command manager:
|
|
|
|
globals->get_commands()->addCommand("something", do_something);
|
|
|
|
Now, the command "something" is available to any mouse, joystick,
|
|
panel, or keyboard bindings. If the bindings pass any arguments, they
|
|
will be children of the SGPropertyNode passed in:
|
|
|
|
void
|
|
do_something (const SGPropertyNode * arg)
|
|
{
|
|
something(arg->getStringValue("foo"), arg->getDoubleValue("bar"));
|
|
}
|
|
|
|
That's pretty-much it. Apologies in advance for not making things any
|
|
more complicated.
|
|
|
|
|