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 0.
110 y - the Y position of the bottom left corner of the object, in
111 pseudo-pixels. The default is 0.
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 legend - the text legend to display in the object.
121 label - the text label to display near the object.
123 property - the name of the FlightGear property whose value will
124 be displayed in the object (and possibly modified through it).
126 binding - a FlightGear command binding that will be fired when the
127 user activates this object (more than one allowed).
129 default - true if this is the default object for when the user
130 presses the [RETURN] key.
132 Objects may appear nested within the top-level dialog or a "group"
133 object. Here are all the object types allowed, with their special
140 The top-level dialog box; the name does not actually appear in the
141 file, since the root element is named PropertyList.
143 name - (REQUIRED) the unique name of the dialog for use with the
144 "dialog-show" command.
146 modal - true if the dialog is modal (it blocks the rest of the
147 program), false otherwise. The default is false.
172 A group of subobjects. This object does not draw anything on the
173 screen, but all of its children specify their coordinates relative to
174 the group; using groups makes it easy to move parts of a dialog
201 A simple editable text field.
210 <label>sea-level temperature (degC)</label>
211 <property>/environment/temperature-sea-level-degc</property>
218 A non-editable text label.
225 <label>Heading</label>
232 A checkbox, useful for linking to boolean properties.
241 <property>/autopilot/locks/heading</property>
249 A push button, useful for firing command bindings.
251 one-shot - true if the button should pop up again after it is
252 pushed, false otherwise. The default is true.
259 <command>dialog-apply</command>
262 <command>dialog-close</command>
264 <default>true</default>
272 A pop-up list of selections.
274 value - one of the selections available for the combo. There may be
275 any number of "value" fields.
284 <property>/environment/clouds/layer[0]/type</property>
286 <value>mostly-sunny</value>
287 <value>mostly-cloudy</value>
288 <value>overcast</value>
289 <value>cirrus</value>
296 A horizontal or vertical slider for setting a value.
298 vertical - true if the slider should be vertical, false if it should
299 be horizontal. The default is false.
301 min - the minimum value for the slider. The default is 0.0.
303 max - the maximum value for the slider. The default is 1.0.
311 <property>/environment/visibility-m</property>
320 A circular dial for choosing a direction.
322 wrap - true if the dial should wrap around, false otherwise. The
325 min - the minimum value for the dial. The default is 0.0.
327 max - the maximum value for the dial. The default is 1.0.
335 <property>/environment/wind-from-direction-deg</property>