]> git.mxchange.org Git - flightgear.git/blob - docs-mini/README.gui
Merge branch 'ehofman/atc-sound' into next
[flightgear.git] / docs-mini / README.gui
1 FlightGear GUI Mini-HOWTO
2
3 David Megginson
4 Started: 2003-01-20
5 Last revised: 2003-01-20
6
7
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.
12
13 All of the XML files use the standard FlightGear PropertyList format.
14
15
16 MENUBAR
17 -------
18
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.
26
27 Here's a simplified grammar:
28
29   [menubar] : menu*
30
31   menu : label, item*
32
33   item : label, binding*
34
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.
38
39 Here's an example of a simple menubar with a "File" drop-down menu and
40 a single "Quit" item:
41
42   <PropertyList>
43
44    <menu>
45     <label>File</label>
46  
47     <item>
48      <label>Quit</label>
49      <binding>
50       <command>exit</command>
51      </binding>
52     </item>
53
54   </PropertyList>
55
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.
60
61
62 DIALOGS
63 -------
64
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:
69
70   <PropertyList>
71
72    <name>hello</name>
73
74    <width>150</width>
75    <height>100</height>
76    <modal>false</modal>
77    <draggable>true</draggable>
78
79    <text>
80     <x>10</x>
81     <y>50</y>
82     <label>Hello, world</label>
83     <color>
84      <red>1.0</red>
85      <green>0.0</green>
86      <blue>0.0</blue>
87     </color>
88    </text>
89
90    <button>
91     <x>40</x>
92     <y>10</y>
93     <legend>Close</legend>
94     <binding>
95      <command>dialog-close</command>
96     </binding>
97    </button>
98
99   </PropertyList>
100
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.
104
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.
109
110 All objects, including the top-level dialog, accept the following
111 properties, though they will ignore any that are not relevant:
112
113  x - the X position of the bottom left corner of the object, in
114    pseudo-pixels.  The default is to center the dialog.
115
116  y - the Y position of the bottom left corner of the object, in
117    pseudo-pixels.  The default is to center the dialog.
118
119  width - the width of the object, in pseudo-pixels.  The default is
120    the width of the parent container.
121
122  height - the height of the object, in pseudo-pixels.  The default is
123    the width of the parent container.
124
125  border - the border thickness, in pseudo-pixels.  The default is 2.
126
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.
132
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)
137
138  legend - the text legend to display in the object.
139
140  label - the text label to display near the object.
141
142  property - the name of the FlightGear property whose value will
143    be displayed in the object (and possibly modified through it).
144
145  binding - a FlightGear command binding that will be fired when the
146    user activates this object (more than one allowed).
147
148  default - true if this is the default object for when the user
149    presses the [RETURN] key.
150
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
153 special properties:
154
155
156 dialog
157 ------
158
159 The top-level dialog box; the name does not actually appear in the
160 file, since the root element is named PropertyList.
161
162   name - (REQUIRED) the unique name of the dialog for use with the
163     "dialog-show" command.
164
165   modal - true if the dialog is modal (it blocks the rest of the
166     program), false otherwise.  The default is false.
167
168   draggable - false if the dialog is not draggable. The default is true.
169
170 Example:
171
172 <PropertyList>
173
174  <name>sample</name>
175  <width>500</width>
176  <height>210</height>
177  <modal>false</modal>
178
179  <text>
180   ...
181  </text>
182
183  <button>
184   ...
185  </button>
186
187 </PropertyList>
188
189
190 group and frame
191 ---------------
192
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
196 around.
197
198 A frame is a visual representation of a group and has  a border and an
199 adjustable background color.
200
201 Example:
202
203   <group>
204    <x>0</x>
205    <y>50</y>
206
207    <text>
208     ...
209    </text>
210
211    <input>
212     ...
213    </input>
214
215    <button>
216     ...
217    </button>
218
219   </group>
220
221
222 input
223 -----
224
225 A simple editable text field.
226
227 Example:
228
229   <input>
230    <x>10</x>
231    <y>60</y>
232    <width>200</width>
233    <height>25</height>
234    <label>sea-level temperature (degC)</label>
235    <property>/environment/temperature-sea-level-degc</property>
236   </input>
237
238
239 text
240 ----
241
242 A non-editable text label.
243
244 Example:
245
246   <text>
247    <x>10</x>
248    <y>200</y>
249    <label>Heading</label>
250   </text>
251
252   <text>
253    <x>10</x>
254    <y>200</y>
255    <label>-9.9999</label> <!-- placeholder for width -->
256    <format>%-0.4f m</format>
257    <property>/foo/altitude</property>
258   </text>
259
260
261 checkbox
262 --------
263
264 A checkbox, useful for linking to boolean properties.
265
266 Example:
267
268   <checkbox>
269    <x>150</x>
270    <y>200</y>
271    <width>12</width>
272    <height>12</height>
273    <property>/autopilot/locks/heading</property>
274   </checkbox>
275
276
277
278 button
279 ------
280
281 A push button, useful for firing command bindings.
282
283   one-shot - true if the button should pop up again after it is
284     pushed, false otherwise.  The default is true.
285
286   <button>
287    <x>0</x>
288    <y>0</y>
289    <legend>OK</legend>
290    <binding>
291     <command>dialog-apply</command>
292    </binding>
293    <binding>
294     <command>dialog-close</command>
295    </binding>
296    <default>true</default>
297   </button>
298
299
300
301 combo
302 -----
303
304 A pop-up list of selections.
305
306   value - one of the selections available for the combo.  There may be
307   any number of "value" fields.
308
309 Example:
310
311   <combo>
312    <x>10</x>
313    <y>50</y>
314    <width>200</width>
315    <height>25</height>
316    <property>/environment/clouds/layer[0]/type</property>
317    <value>clear</value>
318    <value>mostly-sunny</value>
319    <value>mostly-cloudy</value>
320    <value>overcast</value>
321    <value>cirrus</value>
322   </combo>
323
324
325
326 select
327 ------
328
329 A scrollable list of selections.
330
331   selection - a path in the property tree which holds the selectable items.
332
333 Example:
334
335   <select>
336    <x>10</x>
337    <y>50</y>
338    <width>200</width>
339    <height>25</height>
340    <property>/sim/aircraft</property>
341    <selection>/sim/aircraft-types</selection>
342   </select>
343
344
345
346 slider
347 ------
348
349 A horizontal or vertical slider for setting a value.
350
351   vertical - true if the slider should be vertical, false if it should
352     be horizontal.  The default is false.
353
354   min - the minimum value for the slider.  The default is 0.0.
355
356   max - the maximum value for the slider.  The default is 1.0.
357
358 Example:
359
360   <slider>
361    <x>10</x>
362    <y>50</y>
363    <width>200</width>
364    <property>/environment/visibility-m</property>
365    <min>5</min>
366    <max>50000</max>
367   </slider>
368
369
370 dial
371 ----
372
373 A circular dial for choosing a direction.
374
375   wrap - true if the dial should wrap around, false otherwise.  The
376     default is true.
377
378   min - the minimum value for the dial.  The default is 0.0.
379
380   max - the maximum value for the dial.  The default is 1.0.
381
382 Example:
383
384   <dial>
385    <x>10</x>
386    <y>50</y>
387    <width>20</width>
388    <property>/environment/wind-from-direction-deg</property>
389    <min>0</min>
390    <max>360</max>
391   </dial>
392
393 textbox
394 -------
395
396 The text will be retrieved/buffered from/within a specified
397 property tree, like:
398
399 <textbox>
400     <!-- position -->
401     <x>100</x>
402     <y>100</y>
403
404     <!-- dimensions -->
405     <width>200</width> 
406     <height>400</height>
407
408     <property>/gui/path-to-text-node/contents</property>
409
410     <slider>15</slider> <!--width for slider -->
411     <wrap>false</wrap> <!-- don't wrap text; default: true -->
412
413     <editable>true</editable> <!-- whether the puLargeInput is supposed to be editable -->
414 </textbox>  
415
416 __end__