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 font - a subgroup to specify a specific font type
127 name - the name of the font (excluding it's .txf extension)
128 size - size of the font
129 slant - the slant of the font (in pixels)
131 legend - the text legend to display in the object.
133 label - the text label to display near the object.
135 property - the name of the FlightGear property whose value will
136 be displayed in the object (and possibly modified through it).
138 binding - a FlightGear command binding that will be fired when the
139 user activates this object (more than one allowed).
141 default - true if this is the default object for when the user
142 presses the [RETURN] key.
144 Objects may appear nested within the top-level dialog or a "group"
145 object. Here are all the object types allowed, with their special
152 The top-level dialog box; the name does not actually appear in the
153 file, since the root element is named PropertyList.
155 name - (REQUIRED) the unique name of the dialog for use with the
156 "dialog-show" command.
158 modal - true if the dialog is modal (it blocks the rest of the
159 program), false otherwise. The default is false.
161 draggable - false if the dialog is not draggable. The default is true.
186 A group of subobjects. This object does not draw anything on the
187 screen, but all of its children specify their coordinates relative to
188 the group; using groups makes it easy to move parts of a dialog
215 A simple editable text field.
224 <label>sea-level temperature (degC)</label>
225 <property>/environment/temperature-sea-level-degc</property>
232 A non-editable text label.
239 <label>Heading</label>
245 <label>-9.9999</label> <!-- placeholder for width -->
246 <format>%-0.4f m</format>
247 <property>/foo/altitude</property>
254 A checkbox, useful for linking to boolean properties.
263 <property>/autopilot/locks/heading</property>
271 A push button, useful for firing command bindings.
273 one-shot - true if the button should pop up again after it is
274 pushed, false otherwise. The default is true.
281 <command>dialog-apply</command>
284 <command>dialog-close</command>
286 <default>true</default>
294 A pop-up list of selections.
296 value - one of the selections available for the combo. There may be
297 any number of "value" fields.
306 <property>/environment/clouds/layer[0]/type</property>
308 <value>mostly-sunny</value>
309 <value>mostly-cloudy</value>
310 <value>overcast</value>
311 <value>cirrus</value>
319 A scrollable list of selections.
321 selection - a path in the property tree which holds the selectable items.
330 <property>/sim/aircraft</property>
331 <selection>/sim/aircraft-types</selection>
339 A horizontal or vertical slider for setting a value.
341 vertical - true if the slider should be vertical, false if it should
342 be horizontal. The default is false.
344 min - the minimum value for the slider. The default is 0.0.
346 max - the maximum value for the slider. The default is 1.0.
354 <property>/environment/visibility-m</property>
363 A circular dial for choosing a direction.
365 wrap - true if the dial should wrap around, false otherwise. The
368 min - the minimum value for the dial. The default is 0.0.
370 max - the maximum value for the dial. The default is 1.0.
378 <property>/environment/wind-from-direction-deg</property>
386 The text will be retrieved/buffered from/within a specified
398 <property>/gui/path-to-text-node/contents</property>
400 <slider>15</slider> <!--width for slider -->
401 <wrap>false</wrap> <!-- don't wrap text; default: true -->
403 <editable>true</editable> <!-- whether the puLargeInput is supposed to be editable -->