PropertyList XML files: Difference between revisions

Jump to navigation Jump to search

PropertyList XML files (view source)

Revision as of 16:24, 30 January 2015

3,175 bytes added ,  30 January 2015
Documenting aliases
m (Johan G moved page PropertyList XML File to PropertyList XML files: Plural form and less camel case)
(Documenting aliases)
Line 25: Line 25:
== The PropertyList format ==
== The PropertyList format ==
The root element of each file is always named <PropertyList>. Tags are almost always found in pairs, with the closing tag having a slash prefixing the tag name, i.e </PropertyList>, just like in any other XML dialect. The exception is the tag representing an aliased property. In this case a slash is prepended to the closing angle bracket:
The root element of each file is always named <PropertyList>. Tags are almost always found in pairs, with the closing tag having a slash prefixing the tag name, i.e </PropertyList>, just like in any other XML dialect. The exception is the tag representing an aliased property. In this case a slash is prepended to the closing angle bracket:
<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<prop alias="/sim/foo"/>
<prop alias="/sim/foo"/>
</syntaxhighlight>
</syntaxhighlight>


=== Minimal example ===
A minimal example of a complete property list encoded XML file, looks like this:
A minimal example of a complete property list encoded XML file, looks like this:


<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
 
 
<PropertyList>
</PropertyList>
</PropertyList>
</syntaxhighlight>
</syntaxhighlight>


=== Property node tags and attributes ===
Each node in a tree is specified using a single tag that can take attributes describing various things about it:
Each node in a tree is specified using a single tag that can take attributes describing various things about it:


<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<PropertyList>
  <welcome type="string">Welcome to FlightGear! This is a string as a property</welcome>
<welcome type="string">Welcome to FlightGear! This is a string as a property</welcome>
</PropertyList>
</PropertyList>
</syntaxhighlight>
</syntaxhighlight>


=== Property type attributes ===
Property typing is optional, all properties are by default string/unspecified and are transparently converted by the property tree, but it never hurts, especially when including spaces around numbers:
Property typing is optional, all properties are by default string/unspecified and are transparently converted by the property tree, but it never hurts, especially when including spaces around numbers:


<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<PropertyList>
  <foo type="string">Hello</foo>
<foo type="string">Hello</foo>
  <pi type="float"> 3.14 </pi>
<pi type="float"> 3.14 </pi>
  <boo type="bool">true</boo>
<boo type="bool">true</boo>
</PropertyList>
</PropertyList>
</syntaxhighlight>
</syntaxhighlight>


=== Indexed nodes ===
Indexing happens implicitly for identically named properties:
Indexing happens implicitly for identically named properties:


<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<PropertyList>
  <foo>Hello</foo>  
<foo>Hello</foo>  
  <foo>Hello</foo>
<foo>Hello</foo>
  <foo>Hello</foo>
<foo>Hello</foo>
</PropertyList>
</PropertyList>
</syntaxhighlight>
</syntaxhighlight>


Line 72: Line 77:


<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<PropertyList>
  <foo n="0">Hello</foo>  
<foo n="0">Hello</foo>  
  <foo n="1">Hello</foo>
<foo n="1">Hello</foo>
  <foo n="2">Hello</foo>
<foo n="2">Hello</foo>
</PropertyList>
</PropertyList>
</syntaxhighlight>
</syntaxhighlight>


Though the above two examples are equivalent, we tend often to include "n" anyway, just to help people keep track of where they are.  That's most important when there are a lot of subproperties, not in a simple list like the above.
Though the above two examples are equivalent, we tend often to include "n" anyway, just to help people keep track of where they are.  That's most important when there are a lot of subproperties, not in a simple list like the above.


=== Archived properties ===
To make property settings persistent in between FlightGear sessions, use the userarchive attribute:
To make property settings persistent in between FlightGear sessions, use the userarchive attribute:


<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<PropertyList>
  <foo userarchive="y">Hello</foo>  
<foo userarchive="y">Hello</foo>  
</PropertyList>
</PropertyList>
</syntaxhighlight>
</syntaxhighlight>


 
=== Including external PropertyList files ===
We can also create new PropertyList files by subtyping existing ones using the include attribute. For example, if someone made a DC-3 model for JSBSim, we could subclass from the YASim config file like this:
We can also create new PropertyList files by subtyping existing ones using the include attribute. For example, if someone made a DC-3 model for JSBSim, we could subclass from the YASim config file like this:


<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
  <PropertyList include="dc3-yasim-set.xml">
<PropertyList include="dc3-yasim-set.xml">
  <sim>
<sim>
    <description>DC-3 (JSBSim).</description>
  <description>DC-3 (JSBSim).</description>
    <flight-model archive="y">jsb</flight-model>
  <flight-model archive="y">jsb</flight-model>
  </sim>
</sim>
  </PropertyList>
</PropertyList>
</syntaxhighlight>
</syntaxhighlight>


Emmanuel Baranger's models tend to use this technique lot and often have several XML files: the first (the -set.xml) contains very basic information, often just author and version number, and includes the next; the second is for FDM-specific properties (the -yasim-cnf or -jsbsim-cnf); and the last has FDM-independent things like flap settings (the -base.xml). This structuring allows for maximum reusability between FDMs and makes it easier for someone to come along and add another FDM to a model.
Emmanuel Baranger's models tend to use this technique lot and often have several XML files: the first (the -set.xml) contains very basic information, often just author and version number, and includes the next; the second is for FDM-specific properties (the -yasim-cnf or -jsbsim-cnf); and the last has FDM-independent things like flap settings (the -base.xml). This structuring allows for maximum reusability between FDMs and makes it easier for someone to come along and add another FDM to a model.


For further information please refer to [[$FG_ROOT]]/Docs/README.introduction and [[$FG_ROOT]]/Docs/README.properties.
=== Aliased properties ===
Properties can alias other properties, in a similar way to symbolic links in Unix.  When the value of a target property changes, the value of an aliased property changes as well.
 
For example will
 
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<foo>46</foo>
<bar alias="/foo"/>
</PropertyList>
</syntaxhighlight>
 
be functionally identical to
 
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<foo>46</foo>
<bar>46</bar>
</PropertyList>
</syntaxhighlight>
 
except that bar will always be identical to foo.
 
A PropertyList file can begin with a property subtree that are aliased later in the file.
 
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<params>
  <comm-freq-prop>/radios/comm1/frequencies/selected</comm-freq-prop>
  <nav-freq-prop>/radios/nav1/frequencies/selected</comm-freq-prop>
</params>
<chunk>
  <type>number-value</type>
  <property alias="/params/nav-freq-prop"/>
</chunk>
</PropertyList>
</syntaxhighlight>
 
=== Aliasing combined with inclusion ===
The combination of aliasing and inclusion allows for parameterization, which can be of great help both for debugging and mainenance.  The above example could for example instead be split up into
 
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<params>
  <comm-freq-prop>/radios/comm1/frequencies/selected</comm-freq-prop>
  <nav-freq-prop>/radios/nav1/frequencies/selected</comm-freq-prop>
</params>
</PropertyList>
</syntaxhighlight>
 
and
 
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<params include="MyParams.xml"/>
<chunk>
  <type>number-value</type>
  <property alias="/params/nav-freq-prop"/>
</chunk>
</PropertyList>
</syntaxhighlight>
 
The parameters can be overridden at inclusion
 
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<instrument include="../Instruments/navcomm.xml">
  <params>
  <comm-freq-prop>/radios/comm1/frequencies/selected</comm-freq-prop>
  <nav-freq-prop>/radios/nav1/frequencies/selected</comm-freq-prop>
  </params>
</instrument>
</PropertyList>
</syntaxhighlight>
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<instrument include="../Instruments/navcomm.xml">
  <params>
  <comm-freq-prop>/radios/comm2/frequencies/selected</comm-freq-prop>
  <nav-freq-prop>/radios/nav2/frequencies/selected</comm-freq-prop>
  </params>
</instrument>
</PropertyList>
</syntaxhighlight>


== CDATA ==
== CDATA ==
Line 167: Line 264:


== Related content ==
== Related content ==
=== Readme files ===
: ''These files can also be found in [[$FG_ROOT]]/Docs.''
* {{Git link|gitorious|fg/fgdata|master|Docs/README.introduction|text=README.introduction}}
* {{Git link|gitorious|fg/fgdata|master|Docs/README.properties|text=README.properties}}
* {{Git link|gitorious|fg/fgdata|master|Docs/README.xmlsyntax|text=README.xmlsyntax}} – XML in 15 minutes or less
* {{Git link|gitorious|fg/fgdata|master|Docs/README.xmlpanel|text=README.xmlpanel}} – Contains valuable information on the PropertyList format
=== Forum ===
* http://forum.flightgear.org/viewtopic.php?f=18&t=19503
* http://forum.flightgear.org/viewtopic.php?f=18&t=19503
=== Developer mailing list ===
* {{cite web |url=http://sourceforge.net/p/flightgear/mailman/flightgear-devel/thread/4E79A5CC.80906@t3r.de/ |title=<nowiki>[</nowiki>Flightgear-devel<nowiki>]</nowiki> Property Tree Question: How to save an aircraft specific property between sessions.}}
* {{cite web |url=http://sourceforge.net/p/flightgear/mailman/flightgear-devel/thread/4E79A5CC.80906@t3r.de/ |title=<nowiki>[</nowiki>Flightgear-devel<nowiki>]</nowiki> Property Tree Question: How to save an aircraft specific property between sessions.}}


[[Category:XML]]
[[Category:XML]]
[[Category:Property Tree]]
[[Category:Property Tree]]
Retrieved from "https://wiki.flightgear.org/Special:MobileDiff/79484"

Navigation menu