Property Tree Intro

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

FG Home >> Developer Portal >> Property Tree >> Intro

(Inspired by and somewhat based on [1])

Note: If you find anything particularly unclear, missing or just hard to understand please feel free to ask specific questions on this article's talk page, this will help improve this introduction.

!! Work in Progress !!

This needs more work, namely:

• terminology
• examples
• screenshots
• usage scenarios (telnet, property browser, XML files, nasal ...)
• wikipedia links to more technical descriptions
• links to source/implementation code
• links to example source code to interface with the props interface
• we might want to convert something like this into some sort of presentation or PDF handout?
• topics to cover:
  • history of the property tree

Intro

The so called "Property Tree" in FlightGear is generally considered FlightGear's "central nervous system" and one of FlightGear greatest assets, if not even its greatest asset of all!

This is because the Property Tree system can be used to provide access to lowlevel runtime state variables via a very intuitive tree-like hierarchy, so that FlightGear behavior can be easily controlled and modified/customized at runtime.

So the FlightGear Property Tree is the common denominator for crucial runtime state and also the interface to these internal state variables.

However, getting to grips with the concepts and mechanisms behind the "Property Tree" may not be easy for FlightGear beginners. This page is meant to help newcomers familiarize themselves with the FlightGear property tree.

An abstract View

The Property Tree System in FlightGear is generally spoken, used by pretty much all FlightGear subsystems that are basically tied together by it, in other words: it is the property tree that is the enabling mechanism to "share" important runtime data between different components of FlightGear.

While this doesn't necessarily apply to all FlightGear data structures, it does mostly apply to those variables that may need to be modified at runtime, be it for customization purposes or other uses. In addition, it is made very straightforward to publish/expose new variables from C++ space to the property tree.

But the Property Tree is also used by other FlightGear-related software (such as Atlas), where the Property Tree's purpose is extended to being that of an network-based "Inter Process Communications (IPC)"-mechanism/enabler, so that other software (open source or or not) can easily interface with and "look into" FlightGear, and inspect/modify runtime state variables (in a peek/poke manner).

This makes it for example possible, to basically "remote control" FlightGear, but also to modify environmental settings easily at runtime, from a different process, computer, network or even continent!

Access to the Property Tree is provided via well-defined means, such as C++ APIs, network protocols, XML files and scripting interfaces (via Nasal).

Furthermore, the Property Tree has been designed to directly map to XML files, specifically to "PropertyList-encoded" XML files, these follow a key/value structure that can be directly translated to the hierarchy used in the Property Tree.

In fact, most of the contents of the FlightGear Property Tree that you get to see at runtime is dynamically composed from such PropertyList-encoded XML files, that are directly loaded into the property tree.

Property Tree: Step by Step

A dump space for your data

For starters, it's probably sufficient to imagine the property tree as a very powerful global (process-wide) "dump space" for simple variables, such as numbers and strings.

Key/Value pairs

The property tree stores variables as "key/value" pairs, so that you can easily refer to a variable by using its "key" (such as for example "altitude") and query the property tree for the value that it has stored for this key (variable).

Hierarchical Storage / where the tree part comes in

To provide support for hierarchically/logically grouped variable storage, the property tree is implemented as a tree-like structure of nested key/value pairs, this can be imagined pretty much like a virtual file system where you have folders (locations) and files (data).

Categories for your data

This approach is powerful because it supports the concept of "categories" for data storage, so that you can place -by convention- certain "data" in a specific place (think "drawer"), pretty much like storing work-related stuff in a "work" folder on your computer, or storing your media files (video/audio) in a distinct "media" folder, too.

So, this system allows for logical groups or "categories" of data items, so that you know where to search for certain data. On the other hand, this is based purely on conventions - there's nothing that enforces things to be placed in a certain location.

Property Tree Paths

In fact, the file system analogy previously used pretty much also applies to accessing (writing/reading) values: Values (or data items) in the property tree can be referred to via a "path" which acts as the "key" to the data, this path pretty much looks like a conventional file system path, for example something like "/private/settings/foo" could be an imaginary path/key to access a property tree variable stored at that place. So, from a syntactic point of view this is pretty much similar to file system paths, like they are used on Linux/Unix computers (i.e. no drive letters or backslashes are used).

Naming Properties

In addition, some naming restrictions apply as well: in general, you should only use lower-case, alphanumeric ASCII characters in these paths, and only use the hyphen to separate words or append a suffix. These conventions simplify working with properties and make them more intuitive.

Naming Conventions

To ensure that keys (paths) to variables are not simply named arbitrarily, some naming conventions apply, these can be mostly deduced from existing properties, such as for example appending a suffix to make properties more self-explanatory by indicating what unit the properties is provided in (e.g. "deg", "rad", "hz", "ft", "nm").

Typing

In general, the property tree is pretty much untyped, that is it can easily work with untyped properties (stored as strings) that can be dynamically converted to different representations (such as numbers like int, float, double or boolean values) at runtime.

However, when creating your own properties, it is generally considered good practice to also chose the most suitable data type, as well.

It is important to keep in mind that storing a property without its type (i.e. untyped), will inevitably result in a conversion being performed to convert the data to a non-string representation.

So, to avoid unnecessary performance penalties it's always a good idea to also define valid types for your properties. Likewise, using the proper access means to avoid unnecessary conversions, is also important.