416 lines
8.9 KiB
Text
416 lines
8.9 KiB
Text
FlightGear GUI Mini-HOWTO
|
|
|
|
David Megginson
|
|
Started: 2003-01-20
|
|
Last revised: 2003-01-20
|
|
|
|
|
|
FlightGear creates its drop-down menubar and dialog boxes from XML
|
|
configuration files under $FG_ROOT/gui. This document gives a quick
|
|
explanation of how to create or modify the menubar and dialogs. The
|
|
toolkit for the FlightGear GUI is PUI, which is part of plib.
|
|
|
|
All of the XML files use the standard FlightGear PropertyList format.
|
|
|
|
|
|
MENUBAR
|
|
-------
|
|
|
|
FlightGear reads the configuration for its menubar from
|
|
$FG_ROOT/gui/menubar.xml. The file consists of a series of top-level
|
|
elements named "menu", each of which defines on of the drop-down
|
|
menus, from left to right. Each menu contains a series of items,
|
|
representing the actual items a user can select from the menu, and
|
|
each item has a series of bindings that FlightGear will activate when
|
|
the user selects the item.
|
|
|
|
Here's a simplified grammar:
|
|
|
|
[menubar] : menu*
|
|
|
|
menu : label, item*
|
|
|
|
item : label, binding*
|
|
|
|
The bindings are standard FlightGear bindings, the same as the ones
|
|
used for the keyboard, mouse, joysticks, and the instrument panel.
|
|
Any commands allowed in those bindings are allowed here as well.
|
|
|
|
Here's an example of a simple menubar with a "File" drop-down menu and
|
|
a single "Quit" item:
|
|
|
|
<PropertyList>
|
|
|
|
<menu>
|
|
<label>File</label>
|
|
|
|
<item>
|
|
<label>Quit</label>
|
|
<binding>
|
|
<command>exit</command>
|
|
</binding>
|
|
</item>
|
|
|
|
</PropertyList>
|
|
|
|
PUI menus do not allow advanced features like submenus or checkmarks.
|
|
The most common command to include in a menu item binding is the
|
|
'dialog-show' command, which will open a user-defined dialog box as
|
|
described in the next section.
|
|
|
|
|
|
DIALOGS
|
|
-------
|
|
|
|
The configuration files for XML dialogs use a nested structure to set
|
|
up dialog boxes. The top-level always describes a dialog box, and the
|
|
lower levels describe the groups and widgets that make it up. Here is
|
|
a simple, "hello world" dialog:
|
|
|
|
<PropertyList>
|
|
|
|
<name>hello</name>
|
|
|
|
<width>150</width>
|
|
<height>100</height>
|
|
<modal>false</modal>
|
|
<draggable>true</draggable>
|
|
|
|
<text>
|
|
<x>10</x>
|
|
<y>50</y>
|
|
<label>Hello, world</label>
|
|
<color>
|
|
<red>1.0</red>
|
|
<green>0.0</green>
|
|
<blue>0.0</blue>
|
|
</color>
|
|
</text>
|
|
|
|
<button>
|
|
<x>40</x>
|
|
<y>10</y>
|
|
<legend>Close</legend>
|
|
<binding>
|
|
<command>dialog-close</command>
|
|
</binding>
|
|
</button>
|
|
|
|
</PropertyList>
|
|
|
|
The dialog contains two sub-objects: a text field and a button. The
|
|
button contains one binding, which closes the active dialog when the
|
|
user clicks on the button.
|
|
|
|
Coordinates are pseudo-pixels. The screen is always assumed to be
|
|
1024x768, no matter what the actual resolution is. The origin is the
|
|
bottom left corner of the screen (or parent dialog or group); x goes
|
|
from left to right, and y goes from bottom to top.
|
|
|
|
All objects, including the top-level dialog, accept the following
|
|
properties, though they will ignore any that are not relevant:
|
|
|
|
x - the X position of the bottom left corner of the object, in
|
|
pseudo-pixels. The default is to center the dialog.
|
|
|
|
y - the Y position of the bottom left corner of the object, in
|
|
pseudo-pixels. The default is to center the dialog.
|
|
|
|
width - the width of the object, in pseudo-pixels. The default is
|
|
the width of the parent container.
|
|
|
|
height - the height of the object, in pseudo-pixels. The default is
|
|
the width of the parent container.
|
|
|
|
border - the border thickness, in pseudo-pixels. The default is 2.
|
|
|
|
color - a subgroup to specify the dialogs color:
|
|
red - specify the red color component of the color scheme.
|
|
green - specify the green color component of the color scheme.
|
|
blue - specify the blue color component of the color scheme.
|
|
alpha - specify the alpha color component of the color scheme.
|
|
|
|
font - a subgroup to specify a specific font type
|
|
name - the name of the font (excluding it's .txf extension)
|
|
size - size of the font
|
|
slant - the slant of the font (in pseudo-pixels)
|
|
|
|
legend - the text legend to display in the object.
|
|
|
|
label - the text label to display near the object.
|
|
|
|
property - the name of the FlightGear property whose value will
|
|
be displayed in the object (and possibly modified through it).
|
|
|
|
binding - a FlightGear command binding that will be fired when the
|
|
user activates this object (more than one allowed).
|
|
|
|
default - true if this is the default object for when the user
|
|
presses the [RETURN] key.
|
|
|
|
Objects may appear nested within the top-level dialog or a "group"
|
|
or a "frame" object. Here are all the object types allowed, with their
|
|
special properties:
|
|
|
|
|
|
dialog
|
|
------
|
|
|
|
The top-level dialog box; the name does not actually appear in the
|
|
file, since the root element is named PropertyList.
|
|
|
|
name - (REQUIRED) the unique name of the dialog for use with the
|
|
"dialog-show" command.
|
|
|
|
modal - true if the dialog is modal (it blocks the rest of the
|
|
program), false otherwise. The default is false.
|
|
|
|
draggable - false if the dialog is not draggable. The default is true.
|
|
|
|
Example:
|
|
|
|
<PropertyList>
|
|
|
|
<name>sample</name>
|
|
<width>500</width>
|
|
<height>210</height>
|
|
<modal>false</modal>
|
|
|
|
<text>
|
|
...
|
|
</text>
|
|
|
|
<button>
|
|
...
|
|
</button>
|
|
|
|
</PropertyList>
|
|
|
|
|
|
group and frame
|
|
---------------
|
|
|
|
A group of subobjects. This object does not draw anything on the
|
|
screen, but all of its children specify their coordinates relative to
|
|
the group; using groups makes it easy to move parts of a dialog
|
|
around.
|
|
|
|
A frame is a visual representation of a group and has a border and an
|
|
adjustable background color.
|
|
|
|
Example:
|
|
|
|
<group>
|
|
<x>0</x>
|
|
<y>50</y>
|
|
|
|
<text>
|
|
...
|
|
</text>
|
|
|
|
<input>
|
|
...
|
|
</input>
|
|
|
|
<button>
|
|
...
|
|
</button>
|
|
|
|
</group>
|
|
|
|
|
|
input
|
|
-----
|
|
|
|
A simple editable text field.
|
|
|
|
Example:
|
|
|
|
<input>
|
|
<x>10</x>
|
|
<y>60</y>
|
|
<width>200</width>
|
|
<height>25</height>
|
|
<label>sea-level temperature (degC)</label>
|
|
<property>/environment/temperature-sea-level-degc</property>
|
|
</input>
|
|
|
|
|
|
text
|
|
----
|
|
|
|
A non-editable text label.
|
|
|
|
Example:
|
|
|
|
<text>
|
|
<x>10</x>
|
|
<y>200</y>
|
|
<label>Heading</label>
|
|
</text>
|
|
|
|
<text>
|
|
<x>10</x>
|
|
<y>200</y>
|
|
<label>-9.9999</label> <!-- placeholder for width -->
|
|
<format>%-0.4f m</format>
|
|
<property>/foo/altitude</property>
|
|
</text>
|
|
|
|
|
|
checkbox
|
|
--------
|
|
|
|
A checkbox, useful for linking to boolean properties.
|
|
|
|
Example:
|
|
|
|
<checkbox>
|
|
<x>150</x>
|
|
<y>200</y>
|
|
<width>12</width>
|
|
<height>12</height>
|
|
<property>/autopilot/locks/heading</property>
|
|
</checkbox>
|
|
|
|
|
|
|
|
button
|
|
------
|
|
|
|
A push button, useful for firing command bindings.
|
|
|
|
one-shot - true if the button should pop up again after it is
|
|
pushed, false otherwise. The default is true.
|
|
|
|
<button>
|
|
<x>0</x>
|
|
<y>0</y>
|
|
<legend>OK</legend>
|
|
<binding>
|
|
<command>dialog-apply</command>
|
|
</binding>
|
|
<binding>
|
|
<command>dialog-close</command>
|
|
</binding>
|
|
<default>true</default>
|
|
</button>
|
|
|
|
|
|
|
|
combo
|
|
-----
|
|
|
|
A pop-up list of selections.
|
|
|
|
value - one of the selections available for the combo. There may be
|
|
any number of "value" fields.
|
|
|
|
Example:
|
|
|
|
<combo>
|
|
<x>10</x>
|
|
<y>50</y>
|
|
<width>200</width>
|
|
<height>25</height>
|
|
<property>/environment/clouds/layer[0]/type</property>
|
|
<value>clear</value>
|
|
<value>mostly-sunny</value>
|
|
<value>mostly-cloudy</value>
|
|
<value>overcast</value>
|
|
<value>cirrus</value>
|
|
</combo>
|
|
|
|
|
|
|
|
select
|
|
------
|
|
|
|
A scrollable list of selections.
|
|
|
|
selection - a path in the property tree which holds the selectable items.
|
|
|
|
Example:
|
|
|
|
<select>
|
|
<x>10</x>
|
|
<y>50</y>
|
|
<width>200</width>
|
|
<height>25</height>
|
|
<property>/sim/aircraft</property>
|
|
<selection>/sim/aircraft-types</selection>
|
|
</select>
|
|
|
|
|
|
|
|
slider
|
|
------
|
|
|
|
A horizontal or vertical slider for setting a value.
|
|
|
|
vertical - true if the slider should be vertical, false if it should
|
|
be horizontal. The default is false.
|
|
|
|
min - the minimum value for the slider. The default is 0.0.
|
|
|
|
max - the maximum value for the slider. The default is 1.0.
|
|
|
|
Example:
|
|
|
|
<slider>
|
|
<x>10</x>
|
|
<y>50</y>
|
|
<width>200</width>
|
|
<property>/environment/visibility-m</property>
|
|
<min>5</min>
|
|
<max>50000</max>
|
|
</slider>
|
|
|
|
|
|
dial
|
|
----
|
|
|
|
A circular dial for choosing a direction.
|
|
|
|
wrap - true if the dial should wrap around, false otherwise. The
|
|
default is true.
|
|
|
|
min - the minimum value for the dial. The default is 0.0.
|
|
|
|
max - the maximum value for the dial. The default is 1.0.
|
|
|
|
Example:
|
|
|
|
<dial>
|
|
<x>10</x>
|
|
<y>50</y>
|
|
<width>20</width>
|
|
<property>/environment/wind-from-direction-deg</property>
|
|
<min>0</min>
|
|
<max>360</max>
|
|
</dial>
|
|
|
|
textbox
|
|
-------
|
|
|
|
The text will be retrieved/buffered from/within a specified
|
|
property tree, like:
|
|
|
|
<textbox>
|
|
<!-- position -->
|
|
<x>100</x>
|
|
<y>100</y>
|
|
|
|
<!-- dimensions -->
|
|
<width>200</width>
|
|
<height>400</height>
|
|
|
|
<property>/gui/path-to-text-node/contents</property>
|
|
|
|
<slider>15</slider> <!--width for slider -->
|
|
<wrap>false</wrap> <!-- don't wrap text; default: true -->
|
|
|
|
<editable>true</editable> <!-- whether the puLargeInput is supposed to be editable -->
|
|
</textbox>
|
|
|
|
__end__
|