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
  78    <text>
  79     <x>10</x>
  80     <y>50</y>
  81     <label>Hello, world</label>
  82    </text>
  83
  84    <button>
  85     <x>40</x>
  86     <y>10</y>
  87     <legend>Close</legend>
  88     <binding>
  89      <command>dialog-close</command>
  90     </binding>
  91    </button>
  92
  93   </PropertyList>
  94
  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.
  98
  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.
 103
 104 All objects, including the top-level dialog, accept the following
 105 properties, though they will ignore any that are not relevant:
 106
 107  x - the X position of the bottom left corner of the object, in
 108    pseudo-pixels.  The default is to center the dialog.
 109
 110  y - the Y position of the bottom left corner of the object, in
 111    pseudo-pixels.  The default is to center the dialog.
 112
 113  width - the width of the object, in pseudo-pixels.  The default is
 114    the width of the parent container.
 115
 116  height - the height of the object, in pseudo-pixels.  The default is
 117    the width of the parent container.
 118
 119  legend - the text legend to display in the object.
 120
 121  label - the text label to display near the object.
 122
 123  property - the name of the FlightGear property whose value will
 124    be displayed in the object (and possibly modified through it).
 125
 126  binding - a FlightGear command binding that will be fired when the
 127    user activates this object (more than one allowed).
 128
 129  default - true if this is the default object for when the user
 130    presses the [RETURN] key.
 131
 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
 134 properties:
 135
 136
 137 dialog
 138 ------
 139
 140 The top-level dialog box; the name does not actually appear in the
 141 file, since the root element is named PropertyList.
 142
 143   name - (REQUIRED) the unique name of the dialog for use with the
 144     "dialog-show" command.
 145
 146   modal - true if the dialog is modal (it blocks the rest of the
 147     program), false otherwise.  The default is false.
 148
 149 Example:
 150
 151 <PropertyList>
 152
 153  <name>sample</name>
 154  <width>500</width>
 155  <height>210</height>
 156  <modal>false</modal>
 157
 158  <text>
 159   ...
 160  </text>
 161
 162  <button>
 163   ...
 164  </button>
 165
 166 </PropertyList>
 167
 168
 169 group
 170 -----
 171
 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
 175 around.
 176
 177 Example:
 178
 179   <group>
 180    <x>0</x>
 181    <y>50</y>
 182
 183    <text>
 184     ...
 185    </text>
 186
 187    <input>
 188     ...
 189    </input>
 190
 191    <button>
 192     ...
 193    </button>
 194
 195   </group>
 196
 197
 198 input
 199 -----
 200
 201 A simple editable text field.
 202
 203 Example:
 204
 205   <input>
 206    <x>10</x>
 207    <y>60</y>
 208    <width>200</width>
 209    <height>25</height>
 210    <label>sea-level temperature (degC)</label>
 211    <property>/environment/temperature-sea-level-degc</property>
 212   </input>
 213
 214
 215 text
 216 ----
 217
 218 A non-editable text label.
 219
 220 Example:
 221
 222   <text>
 223    <x>10</x>
 224    <y>200</y>
 225    <label>Heading</label>
 226   </text>
 227
 228
 229 checkbox
 230 --------
 231
 232 A checkbox, useful for linking to boolean properties.
 233
 234 Example:
 235
 236   <checkbox>
 237    <x>150</x>
 238    <y>200</y>
 239    <width>12</width>
 240    <height>12</height>
 241    <property>/autopilot/locks/heading</property>
 242   </checkbox>
 243
 244
 245
 246 button
 247 ------
 248
 249 A push button, useful for firing command bindings.
 250
 251   one-shot - true if the button should pop up again after it is
 252     pushed, false otherwise.  The default is true.
 253
 254   <button>
 255    <x>0</x>
 256    <y>0</y>
 257    <legend>OK</legend>
 258    <binding>
 259     <command>dialog-apply</command>
 260    </binding>
 261    <binding>
 262     <command>dialog-close</command>
 263    </binding>
 264    <default>true</default>
 265   </button>
 266
 267
 268
 269 combo
 270 -----
 271
 272 A pop-up list of selections.
 273
 274   value - one of the selections available for the combo.  There may be
 275   any number of "value" fields.
 276
 277 Example:
 278
 279   <combo>
 280    <x>10</x>
 281    <y>50</y>
 282    <width>200</width>
 283    <height>25</height>
 284    <property>/environment/clouds/layer[0]/type</property>
 285    <value>clear</value>
 286    <value>mostly-sunny</value>
 287    <value>mostly-cloudy</value>
 288    <value>overcast</value>
 289    <value>cirrus</value>
 290   </combo>
 291
 292
 293
 294 select
 295 ------
 296
 297 A scrollable list of selections.
 298
 299   selection - a path in the property tree which holds the selectable items.
 300
 301 Example:
 302
 303   <select>
 304    <x>10</x>
 305    <y>50</y>
 306    <width>200</width>
 307    <height>25</height>
 308    <property>/sim/aircraft</property>
 309    <selection>/sim/aircraft-types</selection>
 310   </select>
 311
 312
 313
 314 slider
 315 ------
 316
 317 A horizontal or vertical slider for setting a value.
 318
 319   vertical - true if the slider should be vertical, false if it should
 320     be horizontal.  The default is false.
 321
 322   min - the minimum value for the slider.  The default is 0.0.
 323
 324   max - the maximum value for the slider.  The default is 1.0.
 325
 326 Example:
 327
 328   <slider>
 329    <x>10</x>
 330    <y>50</y>
 331    <width>200</width>
 332    <property>/environment/visibility-m</property>
 333    <min>5</min>
 334    <max>50000</max>
 335   </slider>
 336
 337
 338 dial
 339 ----
 340
 341 A circular dial for choosing a direction.
 342
 343   wrap - true if the dial should wrap around, false otherwise.  The
 344     default is true.
 345
 346   min - the minimum value for the dial.  The default is 0.0.
 347
 348   max - the maximum value for the dial.  The default is 1.0.
 349
 350 Example:
 351
 352   <dial>
 353    <x>10</x>
 354    <y>50</y>
 355    <width>20</width>
 356    <property>/environment/wind-from-direction-deg</property>
 357    <min>0</min>
 358    <max>360</max>
 359   </dial>
 360
 361
 362 __end__