Property browser: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
m (Robot: Cosmetic changes)
mNo edit summary
(25 intermediate revisions by 8 users not shown)
Line 1: Line 1:
[[File:Property_Browser.jpg|thumb|270px|The property browser window]]
[[File:Property_Browser.jpg|thumb|270px|The property browser window]]
The [[FlightGear]] '''property browser''' is a dialog used to browse, in-simulator, through all properties (internal, runtime state variables in FlightGear). The property browser can be opened with / (forward slash) or through the [[menubar|menu]]: <tt>File > Browse Internal Properties</tt> or (as of [[Git]]) <tt>Debug > Browse Internal Properties</tt>.
{{PropertyTree}}


* To set a property to a new value, select the property, fill the new value in the form below and click the Set button. To toggle values (like true/false), click on them while holding the Ctrl key.
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.  
* Holding the Shift key while pressing a property in the browser will print the property (and update it) to the topleft of the screen. The property can be removed from the screen by clicking at another property, while holding Ctrl-Shift.
* Clicking the square in the left top of the window will copy the property browser. The right square closes the current browser.


== Opening the property browser ==
The property browser can be opened while FlightGear is running either:
* By pressing the {{key press|/}} key (forward slash)
* Through the main [[menubar|menu]]: <tt>Debug > Browse Internal Properties</tt> (in older version: <tt>File > Browse Internal Properties</tt>).
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.
Alternatively, if you have enabled the corresponding "development extension" (see the menu item in the Debug menu), after typing {{key press|/}} you can type in a path (e.g. <tt>/fdm/jsbsim</tt>) and type {{key press|:}} to open the property browser at that path or {{key press|!}} to display it in the list of properties. This method also features tab-completion similar to bash: it will cycle through a list of existing properties that match what has been typed already. See {{fg root file|path=Nasal/prop_key_handler.nas}} for more information.
== Tied properties ==
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:
* To ''toggle boolean values'' (like true/false), ctrl-click a boolean property.
* To ''display a property'' in the top left corner of the screen, shift-click the property in the property bowser. To ''remove the property'' ctrl-shift-click another property.
* To ''clone the property browser window'' click the square in the ''left'' top of the window. The ''right'' square closes the current browser.
* To ''go to the root'' ctrl-click an "<tt>..</tt>" entry.
* To toggle ''verbose/developer mode'' ctrl-click an "<tt>.</tt>" entry.
== Verbose mode ==
In verbose mode, toggled by ctrl-clicking an "<tt>.</tt>" entry or toggling <code>/sim/gui/dialogs/property-browser/show-flags</code>, some additional information is shown as flags like this
<code>foo = '123.456' (double; AT)</code>. 
{| class="wikitable" border="1" cellspacing="0"
! 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 || rowspan="2" | In <code>--log-level=info</code> create log line with TRACE prefix on write/read operation; set with <code><foo trace-write="y"></code>.
|-
| 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. <!-- When FlightGear starts? -->
|-
| 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
|-
|}
{{FGCquote
|1= <pre>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
</pre>
|2= {{cite web
  | url    = http://sourceforge.net/p/flightgear/mailman/message/15645291/
  | title  = <nowiki>Re: [Flightgear-devel] FlightGear/Plib periodic stutter notes</nowiki>
  | author = <nowiki>Melchior FRANZ</nowiki>
  | date  = Oct 21st, 2007
  | added  = Oct 21st, 2007
  | script_version = 0.25
  }}
}}
== 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:
You can force the browser to open on startup, through the following command:
  --prop:browser=/sim/path/that/you/want/to/show  
  --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 <code>gui.property_browser(<path>)</code> 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:
 
<syntaxhighlight lang="nasal">
settimer(func {
    gui.property_browser("/position");
    gui.property_browser("/orientation");
}, 0);
</syntaxhighlight>


The property browser is a very powerful tool when working in FlightGear, it has several very advanced and useful features that are not yet covered here which may however be useful during debugging sessions (there's for example support to trace properties and inspect registered listeners) .
=== Displaying On-Screen property values through nasal ===
So, for debugging or development purposes in general, you may want to refer to this article's "[http://wiki.flightgear.org/index.php/Talk:Property_browser discussion]" page, where we are collecting additional resources about the property browser, please do feel free to add new links or integrate existing ones into this article!
Create a file (let's call it display-props.nas) with instructions such below
 
<syntaxhighlight lang="nasal">
# 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();
</syntaxhighlight>
 
Add the path/to/display-props.nas in your aircraft -set.xml,
 
or in your $FG_HOME/ inside a Nasal/ folder.


== Related content ==
== Related content ==
* [[Property Tree]]
=== Source code ===
 
* {{fgdata source|path=gui/dialogs/property-browser.xml}}
[[Category:Menubar]]
[[Category:Menubar]]
[[Category:Property Tree]]

Revision as of 15:16, 31 March 2020

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.

Alternatively, if you have enabled the corresponding "development extension" (see the menu item in the Debug menu), after typing / you can type in a path (e.g. /fdm/jsbsim) and type : to open the property browser at that path or ! to display it in the list of properties. This method also features tab-completion similar to bash: it will cycle through a list of existing properties that match what has been typed already. See $FG_ROOT/Nasal/prop_key_handler.nas for more information.

Tied properties

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:

  • To toggle boolean values (like true/false), ctrl-click a boolean property.
  • To display a property in the top left corner of the screen, shift-click the property in the property bowser. To remove the property ctrl-shift-click another property.
  • To clone the property browser window click the square in the left top of the window. The right square closes the current browser.
  • To go to the root ctrl-click an ".." entry.
  • To toggle verbose/developer mode ctrl-click an "." entry.

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">.
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
Cquote1.png
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)
Cquote2.png

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

Source code