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:
81 <label>Hello, world</label>
87 <legend>Close</legend>
89 <command>dialog-close</command>
95 The dialog contains two sub-objects: a text field and a button. The
96 button contains one binding, which closes the active dialog when the
97 user clicks on the button.
99 Coordinates are pseudo-pixels. The screen is always assumed to be
100 1024x768, no matter what the actual resolution is. The origin is the
101 bottom left corner of the screen (or parent dialog or group); x goes
102 from left to right, and y goes from bottom to top.
104 All objects, including the top-level dialog, accept the following
105 properties, though they will ignore any that are not relevant:
107 x - the X position of the bottom left corner of the object, in
108 pseudo-pixels. The default is to center the dialog.
110 y - the Y position of the bottom left corner of the object, in
111 pseudo-pixels. The default is to center the dialog.
113 width - the width of the object, in pseudo-pixels. The default is
114 the width of the parent container.
116 height - the height of the object, in pseudo-pixels. The default is
117 the width of the parent container.
119 color - a subgroup to specify the dialogs color:
120 red - specify the red color component of the color scheme.
121 green - specify the green color component of the color scheme.
122 blue - specify the blue color component of the color scheme.
123 alpha - specify the alpha color component of the color scheme.
125 legend - the text legend to display in the object.
127 label - the text label to display near the object.
129 property - the name of the FlightGear property whose value will
130 be displayed in the object (and possibly modified through it).
132 binding - a FlightGear command binding that will be fired when the
133 user activates this object (more than one allowed).
135 default - true if this is the default object for when the user
136 presses the [RETURN] key.
138 Objects may appear nested within the top-level dialog or a "group"
139 object. Here are all the object types allowed, with their special
146 The top-level dialog box; the name does not actually appear in the
147 file, since the root element is named PropertyList.
149 name - (REQUIRED) the unique name of the dialog for use with the
150 "dialog-show" command.
152 modal - true if the dialog is modal (it blocks the rest of the
153 program), false otherwise. The default is false.
178 A group of subobjects. This object does not draw anything on the
179 screen, but all of its children specify their coordinates relative to
180 the group; using groups makes it easy to move parts of a dialog
207 A simple editable text field.
216 <label>sea-level temperature (degC)</label>
217 <property>/environment/temperature-sea-level-degc</property>
224 A non-editable text label.
231 <label>Heading</label>
237 <label>-9.9999</label> <!-- placeholder for width -->
238 <format>%-0.4f m</format>
239 <property>/foo/altitude</property>
246 A checkbox, useful for linking to boolean properties.
255 <property>/autopilot/locks/heading</property>
263 A push button, useful for firing command bindings.
265 one-shot - true if the button should pop up again after it is
266 pushed, false otherwise. The default is true.
273 <command>dialog-apply</command>
276 <command>dialog-close</command>
278 <default>true</default>
286 A pop-up list of selections.
288 value - one of the selections available for the combo. There may be
289 any number of "value" fields.
298 <property>/environment/clouds/layer[0]/type</property>
300 <value>mostly-sunny</value>
301 <value>mostly-cloudy</value>
302 <value>overcast</value>
303 <value>cirrus</value>
311 A scrollable list of selections.
313 selection - a path in the property tree which holds the selectable items.
322 <property>/sim/aircraft</property>
323 <selection>/sim/aircraft-types</selection>
331 A horizontal or vertical slider for setting a value.
333 vertical - true if the slider should be vertical, false if it should
334 be horizontal. The default is false.
336 min - the minimum value for the slider. The default is 0.0.
338 max - the maximum value for the slider. The default is 1.0.
346 <property>/environment/visibility-m</property>
355 A circular dial for choosing a direction.
357 wrap - true if the dial should wrap around, false otherwise. The
360 min - the minimum value for the dial. The default is 0.0.
362 max - the maximum value for the dial. The default is 1.0.
370 <property>/environment/wind-from-direction-deg</property>
378 The text will be retrieved/buffered from/within a specified
390 <property>/gui/path-to-text-node/contents</property>
392 <slider>15</slider> <!--width for slider -->
393 <wrap>false</wrap> <!-- don't wrap text; default: true -->
395 <editable>true</editable> <!-- whether the puLargeInput is supposed to be editable -->