1 FlightGear GUI Mini-HOWTO
5 Last revised: 2003-01-20
8 FlightGear creates its drop-down menubar and dialog boxes from XML
9 configuration files under $FG_ROOT/gui. This document gives a quick
10 explanation of how to create or modify the menubar and dialogs. The
11 toolkit for the FlightGear GUI is PUI, which is part of plib.
13 All of the XML files use the standard FlightGear PropertyList format.
19 FlightGear reads the configuration for its menubar from
20 $FG_ROOT/gui/menubar.xml. The file consists of a series of top-level
21 elements named "menu", each of which defines on of the drop-down
22 menus, from left to right. Each menu contains a series of items,
23 representing the actual items a user can select from the menu, and
24 each item has a series of bindings that FlightGear will activate when
25 the user selects the item.
27 Here's a simplified grammar:
33 item : label, binding*
35 The bindings are standard FlightGear bindings, the same as the ones
36 used for the keyboard, mouse, joysticks, and the instrument panel.
37 Any commands allowed in those bindings are allowed here as well.
39 Here's an example of a simple menubar with a "File" drop-down menu and
50 <command>exit</command>
56 PUI menus do not allow advanced features like submenus or checkmarks.
57 The most common command to include in a menu item binding is the
58 'dialog-show' command, which will open a user-defined dialog box as
59 described in the next section.
65 The configuration files for XML dialogs use a nested structure to set
66 up dialog boxes. The top-level always describes a dialog box, and the
67 lower levels describe the groups and widgets that make it up. Here is
68 a simple, "hello world" dialog:
77 <draggable>true</draggable>
82 <label>Hello, world</label>
88 <legend>Close</legend>
90 <command>dialog-close</command>
96 The dialog contains two sub-objects: a text field and a button. The
97 button contains one binding, which closes the active dialog when the
98 user clicks on the button.
100 Coordinates are pseudo-pixels. The screen is always assumed to be
101 1024x768, no matter what the actual resolution is. The origin is the
102 bottom left corner of the screen (or parent dialog or group); x goes
103 from left to right, and y goes from bottom to top.
105 All objects, including the top-level dialog, accept the following
106 properties, though they will ignore any that are not relevant:
108 x - the X position of the bottom left corner of the object, in
109 pseudo-pixels. The default is to center the dialog.
111 y - the Y position of the bottom left corner of the object, in
112 pseudo-pixels. The default is to center the dialog.
114 width - the width of the object, in pseudo-pixels. The default is
115 the width of the parent container.
117 height - the height of the object, in pseudo-pixels. The default is
118 the width of the parent container.
120 color - a subgroup to specify the dialogs color:
121 red - specify the red color component of the color scheme.
122 green - specify the green color component of the color scheme.
123 blue - specify the blue color component of the color scheme.
124 alpha - specify the alpha color component of the color scheme.
126 legend - the text legend to display in the object.
128 label - the text label to display near the object.
130 property - the name of the FlightGear property whose value will
131 be displayed in the object (and possibly modified through it).
133 binding - a FlightGear command binding that will be fired when the
134 user activates this object (more than one allowed).
136 default - true if this is the default object for when the user
137 presses the [RETURN] key.
139 Objects may appear nested within the top-level dialog or a "group"
140 object. Here are all the object types allowed, with their special
147 The top-level dialog box; the name does not actually appear in the
148 file, since the root element is named PropertyList.
150 name - (REQUIRED) the unique name of the dialog for use with the
151 "dialog-show" command.
153 modal - true if the dialog is modal (it blocks the rest of the
154 program), false otherwise. The default is false.
156 draggable - false if the dialog is not draggable. The default is true.
181 A group of subobjects. This object does not draw anything on the
182 screen, but all of its children specify their coordinates relative to
183 the group; using groups makes it easy to move parts of a dialog
210 A simple editable text field.
219 <label>sea-level temperature (degC)</label>
220 <property>/environment/temperature-sea-level-degc</property>
227 A non-editable text label.
234 <label>Heading</label>
240 <label>-9.9999</label> <!-- placeholder for width -->
241 <format>%-0.4f m</format>
242 <property>/foo/altitude</property>
249 A checkbox, useful for linking to boolean properties.
258 <property>/autopilot/locks/heading</property>
266 A push button, useful for firing command bindings.
268 one-shot - true if the button should pop up again after it is
269 pushed, false otherwise. The default is true.
276 <command>dialog-apply</command>
279 <command>dialog-close</command>
281 <default>true</default>
289 A pop-up list of selections.
291 value - one of the selections available for the combo. There may be
292 any number of "value" fields.
301 <property>/environment/clouds/layer[0]/type</property>
303 <value>mostly-sunny</value>
304 <value>mostly-cloudy</value>
305 <value>overcast</value>
306 <value>cirrus</value>
314 A scrollable list of selections.
316 selection - a path in the property tree which holds the selectable items.
325 <property>/sim/aircraft</property>
326 <selection>/sim/aircraft-types</selection>
334 A horizontal or vertical slider for setting a value.
336 vertical - true if the slider should be vertical, false if it should
337 be horizontal. The default is false.
339 min - the minimum value for the slider. The default is 0.0.
341 max - the maximum value for the slider. The default is 1.0.
349 <property>/environment/visibility-m</property>
358 A circular dial for choosing a direction.
360 wrap - true if the dial should wrap around, false otherwise. The
363 min - the minimum value for the dial. The default is 0.0.
365 max - the maximum value for the dial. The default is 1.0.
373 <property>/environment/wind-from-direction-deg</property>
381 The text will be retrieved/buffered from/within a specified
393 <property>/gui/path-to-text-node/contents</property>
395 <slider>15</slider> <!--width for slider -->
396 <wrap>false</wrap> <!-- don't wrap text; default: true -->
398 <editable>true</editable> <!-- whether the puLargeInput is supposed to be editable -->