X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=docs-mini%2FREADME.commands;h=6df451b30c316513d6aae397650ac6db2d702105;hb=f07a83c73a4cb10c205586f8377fca78265bddff;hp=25b1543abc08718c1556d2c0010bf1e42802b96b;hpb=4497c6d9e996f9616c95844859d859237f1f2d42;p=flightgear.git diff --git a/docs-mini/README.commands b/docs-mini/README.commands index 25b1543ab..6df451b30 100644 --- a/docs-mini/README.commands +++ b/docs-mini/README.commands @@ -1,5 +1,290 @@ -Binding New Commands in FlightGear ----------------------------------- +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: + + + property-adjust + /controls/throttle[0] + 0.01 + 1.0 + + +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: + + + exit + + +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: + + + ESC + Prompt and quit FlightGear. + + exit + + + +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): + + + q + Test + + + + /devices/status/mice/mouse/button[0] + + nasal + + + + +Keyboard definitions can embed bindings in tags (key released), +, , , , , and . +Nesting is supported. Meta, Super, and Hyper modifier tags are for local +use only, and must be supported by the operating system to work. + + + q + Test + + nasal + + + + + + nasal + + + + + + nasal + + + + + + nasal + + + + + + + + + + +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