PropertyList XML files: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
No edit summary
m (courtesy of David Megginson (11 years ago): http://www.mail-archive.com/flightgear-devel@flightgear.org/msg10798.html)
Line 7: Line 7:


Most configuration files in FlightGear are XML-encoded property lists. PropertyList-encoded XML files use a subset of XML to map the property tree to XML space and vice versa. PropertyList-XML files are the main mechanism to populate the FlightGear property tree (or a sub branch of it) from XML files, but also to serialize (save) property tree/branch state to an XML file. XML attributes are mainly used as meta-directives for the property tree.
Most configuration files in FlightGear are XML-encoded property lists. PropertyList-encoded XML files use a subset of XML to map the property tree to XML space and vice versa. PropertyList-XML files are the main mechanism to populate the FlightGear property tree (or a sub branch of it) from XML files, but also to serialize (save) property tree/branch state to an XML file. XML attributes are mainly used as meta-directives for the property tree.
Not everything that is read from an XML file resides in the main property tree; some subsystems also use XML files for initial configuration information. There are different kinds of data. The property tree is meant to represent the shared state of the program; when a subsystem happens to use an XML file to set up its internal state -- information that is of no use to the rest of the program and that cannot be changed without a reinit. Temporary trees are usually deleted as soon as the subsystem is set up (i.e. they exist for perhaps 0.1 sec).  We could just as easily use another format for internal initialization, but since the XML support is already available, it was the easiest route.


To work with PropertyList-XML files, you can use various means, such as:
To work with PropertyList-XML files, you can use various means, such as:

Revision as of 13:35, 24 March 2013

This article is a stub. You can help the wiki by expanding it.

This page is meant is introduce new FlightGear users to the PropertyList XML file format, this is basically an XML based file format specifically created for use by the FlightGear Property Tree.

For additional background information, you'll also want to refer to $FG_ROOT/Docs/README.introduction.

Most configuration files in FlightGear are XML-encoded property lists. PropertyList-encoded XML files use a subset of XML to map the property tree to XML space and vice versa. PropertyList-XML files are the main mechanism to populate the FlightGear property tree (or a sub branch of it) from XML files, but also to serialize (save) property tree/branch state to an XML file. XML attributes are mainly used as meta-directives for the property tree.

Not everything that is read from an XML file resides in the main property tree; some subsystems also use XML files for initial configuration information. There are different kinds of data. The property tree is meant to represent the shared state of the program; when a subsystem happens to use an XML file to set up its internal state -- information that is of no use to the rest of the program and that cannot be changed without a reinit. Temporary trees are usually deleted as soon as the subsystem is set up (i.e. they exist for perhaps 0.1 sec). We could just as easily use another format for internal initialization, but since the XML support is already available, it was the easiest route.

To work with PropertyList-XML files, you can use various means, such as:

  • fgcommands
  • Nasal (props.nas, io.nas)
  • C++ APIs

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>. The exception is the tag representing an aliased property. In this case a slash is prepended to the closing angle bracket.

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

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

Property typing is optional, all properties are by default string/unspecified and are transparently converted by the property tree:

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

Indexing happens implicitly for identically named properties:

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

so that the three foo tags become foo[0], foo[1], foo[2] in the property tree.


Indexing happens implicitly for identically named properties:

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

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

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


For further information please refer to $FG_ROOT/Docs/README.introduction and $FG_ROOT/Docs/README.properties.

Also see