Property browser

The property browser window

The FlightGear property browser is a dialog used to browse, in-simulator, through all properties. Properties are internal, runtime state variables in FlightGear. The property browser cannot only be used to inspect all sorts of internal variables at runtime, but it can also be used to change the values of most properties easily (some being conceputally read-only, i.e. because they're exclusively written-to by a certain subsystem such as the FDM). For instance, you cannot change your frame rate by changing the frame counter obviously.

Opening the property browser

The property browser can be opened while FlightGear is running either:

• By pressing the / key (forward slash)
• Through the main menu: Debug > Browse Internal Properties (in older version: File > Browse Internal Properties).

Browse around to see the different data fields that are available. Just about everything interesting/useful is published in the property system. The browser allows you to inspect and even change values in the live running copy of FG.

Property Key Handler

The property key handler provides a better experience for developers when using the property tree and is suited to keyboard operations. See Property Key Handler for more information.

Tied properties

Note  The origin of tied properties was largely to address "hypothetical" performance concerns in the early days. Coders could continue to use native compiled variables and simultaneously expose them to the property system. Early property system skepticism included issues like performance and use of global structures. Those have largely not proven out to be actual issues. So without looking deep into how much effort/change/impact this would require, I think for the most part the whole tied property aspect of the api could go away and the property system api would simplify quite a bit.

Some properties are so called tied properties which are directly mapped to internal C++ variables and they cannot be modified using the property browser, we are currently trying to get rid of tied properties, see Howto:Use_Property_Tree_Objects for details.

In addition, even some non-tied properties cannot be modified because they are by default constantly written/modified by another subsystem (in C++/Nasal space), possibly updating properties at frame rate, this applies for example to the frame rate counter, which is constantly updated by C++ code - so trying to set it from Nasal would be kind of pointless.

Also certain properties are only read/applied during initialization/re-initialization (startup/reset) of the sim, while others require the corresponding subsystems to be reinitialized.

Tips and tricks

Apart from setting a property by clicking it and using the text field and Set button, there is many things that can be done through the property browser:

Mouse click while holding on keyboard	Function	Comment
ctrl	on '.' toggle verbose mode on '..' goto root on any bool property: toggle true/false value	Verbose mode is explained below
shift	on '.' dump properties to console display property in top left corner of the flightgear screen	To remove the property ctrl-shift-click another property
alt	toggle trace_write attribute of the selected property	Since 04/2024 on 'next'; details below in 'verbose mode'
ctrl+alt	toggle trace_read attribute of the selected property	Since 04/2024 on 'next'; details below in 'verbose mode'

Verbose mode

In verbose mode, toggled by ctrl-clicking an "." entry or toggling /sim/gui/dialogs/property-browser/show-flags, some additional information is shown as flags like this

foo = '123.456' (double; AT).  

Flag	Meaning	Comment
r	Read protected	Showing that a property can not be read.
w	Write protected	Showing that a property can not be written to.
R	Trace read operations	In --log-level=info create log line with TRACE prefix on write/read operation; set with <foo trace-write="y">. Since 04/2024 on next R and W flag can be set on the fly via the property browser (see above)
W	Trace write operations
A	Archive bit set	Makes writeProperties() also save this property in restricted mode ("save flight"), while all others are only saved in full mode.
U	User archive bit set	Saved into ~/.fgfs/autosave.xml, and restored next time.
T	Tied property	Only the C/C++ code that owns a tied property can write to it. Also, listeners will not be triggered.
L<N>	Number of listeners
=> <path>	Alias target	This prop is an alias for <path> (since 04/2024 on 'next')

props.globals.getNode("/sim/aircraft").getAttribute("references") does now return the reference counter -- the number of co-owners of the shared pointer. This is really only useful for debugging. And here's again a summary of all the attribute names: children ... returns number of children (faster than size(n.getChildren()!) listeners ... return number of attached listeners references ... returns number of co-owners (+ 2 for own consumption) tied ... returns whether a node is "tied" (in which case listeners might not get triggered) alias ... whether the node is an alias to another node read ... whether the node is read-protected write ... whether the node is write-protected archive ... whether the "archive" flag is set, which makes the node saved with "Save Flight" in the menu trace-read ... whether the node is being traced for read operations trace-write ... whether the node is being traced for write operations userarchive ... whether the node will be saved to ~/.fgfs/autosave.xml on exit — Melchior FRANZ (Oct 21st, 2007). Re: [Flightgear-devel] FlightGear/Plib periodic stutter notes. (powered by Instant-Cquotes)

Other ways to open the property browser

Forcing open the browser on startup

You can force the browser to open on startup, through the following command:

--prop:browser=/sim/path/that/you/want/to/show

More than one property browser can be opened like this.

--prop:browser=position --prop:browser[1]=orientation

Opening the property browser through nasal

Calling gui.property_browser(<path>) opens a property browser for <path>. While it can be called more than once, though all the dialogues will be drawn on top of each other in the centre of the screen. Example:

settimer(func {
    gui.property_browser("/position");
    gui.property_browser("/orientation");
}, 0);

Displaying On-Screen property values through nasal

Create a file (let's call it display-props.nas) with instructions such below

# On-screen displays
var enableOSD = func {
    var left  = screen.display.new(20, 10);
    var right = screen.display.new(-300, 10);
    
    left.add("/orientation/heading-deg");
    left.add("/environment/wind-from-heading-deg");
    left.add("/environment/wind-speed-kt");
    right.add("/controls/flight/rudder");
}
enableOSD();

Add the path/to/display-props.nas in your aircraft -set.xml,

or in your $FG_HOME/ inside a Nasal/ folder.

Related content

Wiki articles

• Property Key Handler

Source code

• flightgear/fgdata/next/gui/dialogs/property-browser.xml