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__