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>
93 <legend>Close</legend>
95 <command>dialog-close</command>
101 The dialog contains two sub-objects: a text field and a button. The
102 button contains one binding, which closes the active dialog when the
103 user clicks on the button.
105 Coordinates are pseudo-pixels. The screen is always assumed to be
106 1024x768, no matter what the actual resolution is. The origin is the
107 bottom left corner of the screen (or parent dialog or group); x goes
108 from left to right, and y goes from bottom to top.
110 All objects, including the top-level dialog, accept the following
111 properties, though they will ignore any that are not relevant:
113 x - the X position of the bottom left corner of the object, in
114 pseudo-pixels. The default is to center the dialog.
116 y - the Y position of the bottom left corner of the object, in
117 pseudo-pixels. The default is to center the dialog.
119 width - the width of the object, in pseudo-pixels. The default is
120 the width of the parent container.
122 height - the height of the object, in pseudo-pixels. The default is
123 the width of the parent container.
125 border - the border thickness, in pseudo-pixels. The default is 2.
127 color - a subgroup to specify the dialogs color:
128 red - specify the red color component of the color scheme.
129 green - specify the green color component of the color scheme.
130 blue - specify the blue color component of the color scheme.
131 alpha - specify the alpha color component of the color scheme.
133 font - a subgroup to specify a specific font type
134 name - the name of the font (excluding it's .txf extension)
135 size - size of the font
136 slant - the slant of the font (in pseudo-pixels)
138 legend - the text legend to display in the object.
140 label - the text label to display near the object.
142 property - the name of the FlightGear property whose value will
143 be displayed in the object (and possibly modified through it).
145 binding - a FlightGear command binding that will be fired when the
146 user activates this object (more than one allowed).
148 default - true if this is the default object for when the user
149 presses the [RETURN] key.
151 Objects may appear nested within the top-level dialog or a "group"
152 or a "frame" object. Here are all the object types allowed, with their
159 The top-level dialog box; the name does not actually appear in the
160 file, since the root element is named PropertyList.
162 name - (REQUIRED) the unique name of the dialog for use with the
163 "dialog-show" command.
165 modal - true if the dialog is modal (it blocks the rest of the
166 program), false otherwise. The default is false.
168 draggable - false if the dialog is not draggable. The default is true.
193 A group of subobjects. This object does not draw anything on the
194 screen, but all of its children specify their coordinates relative to
195 the group; using groups makes it easy to move parts of a dialog
198 A frame is a visual representation of a group and has a border and an
199 adjustable background color.
225 A simple editable text field.
234 <label>sea-level temperature (degC)</label>
235 <property>/environment/temperature-sea-level-degc</property>
242 A non-editable text label.
249 <label>Heading</label>
255 <label>-9.9999</label> <!-- placeholder for width -->
256 <format>%-0.4f m</format>
257 <property>/foo/altitude</property>
264 A checkbox, useful for linking to boolean properties.
273 <property>/autopilot/locks/heading</property>
281 A push button, useful for firing command bindings.
283 one-shot - true if the button should pop up again after it is
284 pushed, false otherwise. The default is true.
291 <command>dialog-apply</command>
294 <command>dialog-close</command>
296 <default>true</default>
304 A pop-up list of selections.
306 value - one of the selections available for the combo. There may be
307 any number of "value" fields.
316 <property>/environment/clouds/layer[0]/type</property>
318 <value>mostly-sunny</value>
319 <value>mostly-cloudy</value>
320 <value>overcast</value>
321 <value>cirrus</value>
329 A scrollable list of selections.
331 selection - a path in the property tree which holds the selectable items.
340 <property>/sim/aircraft</property>
341 <selection>/sim/aircraft-types</selection>
349 A horizontal or vertical slider for setting a value.
351 vertical - true if the slider should be vertical, false if it should
352 be horizontal. The default is false.
354 min - the minimum value for the slider. The default is 0.0.
356 max - the maximum value for the slider. The default is 1.0.
364 <property>/environment/visibility-m</property>
373 A circular dial for choosing a direction.
375 wrap - true if the dial should wrap around, false otherwise. The
378 min - the minimum value for the dial. The default is 0.0.
380 max - the maximum value for the dial. The default is 1.0.
388 <property>/environment/wind-from-direction-deg</property>
396 The text will be retrieved/buffered from/within a specified
408 <property>/gui/path-to-text-node/contents</property>
410 <slider>15</slider> <!--width for slider -->
411 <wrap>false</wrap> <!-- don't wrap text; default: true -->
413 <editable>true</editable> <!-- whether the puLargeInput is supposed to be editable -->