diff --git a/docs-mini/README.xmlpanel b/docs-mini/README.xmlpanel new file mode 100644 index 000000000..bb524aef8 --- /dev/null +++ b/docs-mini/README.xmlpanel @@ -0,0 +1,92 @@ +Users Guide to FlightGear panel configuration +First Draft +Author: John Check + +This document is an attempt to describe the configuration via +XML of FlightGear flight simulator's aircraft panel display. +The information was culled from the fgfs-devel@flightgear.org +mailing list. I'd like to say thanks to all the developers who +make FGFS happen and forgive me for any errors with regards to +who did what. I'd like to reguest that anybody who should be +mentioned give me a heads up so I can credit them properly. +Corrections and additions are encouraged. + +History: +Older versions of FGFS had a hardcoded display of instruments. +This was a less than ideal state of affairs due to FGFS ability +to use different aircraft models. Being primarily developed on +UNIX type systems, a modular approach is taken towards the +aircraft modeling. To date, most alternatatives to the default +Cessna 172 aircraft are the product of research institutions +interested in the flight characteristics and not cosmetics. +The result of this was that one could fly the X-15 or a Boeing 747 +but be limited to C172 instrumentation. + +A rewrite of the panel display code was done around v0.7.5 by +developer David Megginson allowing for configuration of the panel +via XML to address this limitation. + +The Basics: + +David Megginson wrote: + +> To get started, here's a basic, mostly-architectural outline: +> +> 1. All configuration files are XML-encoded property lists. The root +> element is always named . None of the properties is +> mixed in with the main FlightGear properties (they're all separate +> lists). +> +> 2. There is a single, top-level configuration file for each panel. +> There is also a top-level configuration file for each instrument (I +> may also add configuration files for cropped textures, to enabled +> better reuse of common textures like needles and knobs). +> +> 3. A panel is composed of a background texture and zero or more +> instruments. The panel sets the position of each instrument and may +> also override the instrument's preferred size (the default panel does +> not do so, but if you want an altimeter covering a quarter of the +> screen, go for it!). +> +> 4. An instrument consists of a preferred width and height, one or more +> stacked layers, and zero or more actions. It is defined in a separate +> file. +> +> 5. A layer can be a texture (with alpha areas so that lower textures +> show through), text (static, generated, or both), or a switch between +> two other layers based on a boolean property. Each layer contains +> zero or more transformations. +> +> NOTE: There is one built-in layer -- for the mag compass ribbon -- +> and all other layers are defined in the XML files. In the future, +> there may also be built-in layers for special things like a +> weather-radar display or a GPS (though the GPS could be handled with +> text properties). +> +> 6. A transformation is a rotation, an x-shift, or a y-shift. +> Transformations can be static (rotate 90 degrees) or they can be based +> on properties (rotate the number of degrees equal to the airspeed +> times something plus something else, etc.). +> +> 7. An action is a hotspot on an instrument where something will happen +> when the user clicks the left or centre mouse button. Actions are +> always tied to properties: they can toggle a boolean property, adjust +> the value of a numeric property, or swap the values of two properties. +> +> 8. You can find panel configuration files under $FG_ROOT/Panels/ and +> instrument configuration files under $FG_ROOT/Instruments/. +> +> 9. If there are *any* XML parsing errors, the panel will fail to load +> (them's the XML rules), so it's worth downloading a parser like Expat +> (http://www.jclark.com/xml/) so that you can check your XML. +> FlightGear will print the location of errors, but the messages are a +> little cryptic right now. +> +> 10. You can set the relative location of the top-level XML panel file +> (under $FG_ROOT) using the "/sim/panel" property. The default is +> $FG_ROOT/Panels/Default/default.xml. + +To do: + +Add some examples. +Integrate additonal questions and answers from the list.