Basic information for creating menus and dialogs in FlightGear.
This commit is contained in:
david
parent
40bed0a3f1
commit
3991ac2450
1 changed files with 341 additions and 0 deletions
341
docs-mini/README.gui
Normal file
341
docs-mini/README.gui
Normal file
|
|
@ -0,0 +1,341 @@
|
|||
FlightGear GUI Mini-HOWTO
|
||||
|
||||
David Megginson
|
||||
Started: 2003-01-20
|
||||
Last revised: 2003-01-20
|
||||
|
||||
|
||||
FlightGear creates its drop-down menubar and dialog boxes from XML
|
||||
configuration files under $FG_ROOT/gui. This document gives a quick
|
||||
explanation of how to create or modify the menubar and dialogs. The
|
||||
toolkit for the FlightGear GUI is PUI, which is part of plib.
|
||||
|
||||
All of the XML files use the standard FlightGear PropertyList format.
|
||||
|
||||
|
||||
MENUBAR
|
||||
-------
|
||||
|
||||
FlightGear reads the configuration for its menubar from
|
||||
$FG_ROOT/gui/menubar.xml. The file consists of a series of top-level
|
||||
elements named "menu", each of which defines on of the drop-down
|
||||
menus, from left to right. Each menu contains a series of items,
|
||||
representing the actual items a user can select from the menu, and
|
||||
each item has a series of bindings that FlightGear will activate when
|
||||
the user selects the item.
|
||||
|
||||
Here's a simplified grammar:
|
||||
|
||||
[menubar] : menu*
|
||||
|
||||
menu : label, item*
|
||||
|
||||
item : label, binding*
|
||||
|
||||
The bindings are standard FlightGear bindings, the same as the ones
|
||||
used for the keyboard, mouse, joysticks, and the instrument panel.
|
||||
Any commands allowed in those bindings are allowed here as well.
|
||||
|
||||
Here's an example of a simple menubar with a "File" drop-down menu and
|
||||
a single "Quit" item:
|
||||
|
||||
<PropertyList>
|
||||
|
||||
<menu>
|
||||
<label>File</label>
|
||||
|
||||
<item>
|
||||
<label>Quit</label>
|
||||
<binding>
|
||||
<command>exit</command>
|
||||
</binding>
|
||||
</item>
|
||||
|
||||
</PropertyList>
|
||||
|
||||
PUI menus do not allow advanced features like submenus or checkmarks.
|
||||
The most common command to include in a menu item binding is the
|
||||
'dialog-show' command, which will open a user-defined dialog box as
|
||||
described in the next section.
|
||||
|
||||
|
||||
DIALOGS
|
||||
-------
|
||||
|
||||
The configuration files for XML dialogs use a nested structure to set
|
||||
up dialog boxes. The top-level always describes a dialog box, and the
|
||||
lower levels describe the groups and widgets that make it up. Here is
|
||||
a simple, "hello world" dialog:
|
||||
|
||||
<PropertyList>
|
||||
|
||||
<name>hello</name>
|
||||
|
||||
<width>150</width>
|
||||
<height>100</height>
|
||||
<modal>false</modal>
|
||||
|
||||
<text>
|
||||
<x>10</x>
|
||||
<y>50</y>
|
||||
<label>Hello, world</label>
|
||||
</text>
|
||||
|
||||
<button>
|
||||
<x>40</x>
|
||||
<y>10</y>
|
||||
<legend>Close</legend>
|
||||
<binding>
|
||||
<command>dialog-close</command>
|
||||
</binding>
|
||||
</button>
|
||||
|
||||
</PropertyList>
|
||||
|
||||
The dialog contains two sub-objects: a text field and a button. The
|
||||
button contains one binding, which closes the active dialog when the
|
||||
user clicks on the button.
|
||||
|
||||
Coordinates are pseudo-pixels. The screen is always assumed to be
|
||||
1024x768, no matter what the actual resolution is. The origin is the
|
||||
bottom left corner of the screen (or parent dialog or group); x goes
|
||||
from left to right, and y goes from bottom to top.
|
||||
|
||||
All objects, including the top-level dialog, accept the following
|
||||
properties, though they will ignore any that are not relevant:
|
||||
|
||||
x - the X position of the bottom left corner of the object, in
|
||||
pseudo-pixels. The default is 0.
|
||||
|
||||
y - the Y position of the bottom left corner of the object, in
|
||||
pseudo-pixels. The default is 0.
|
||||
|
||||
width - the width of the object, in pseudo-pixels. The default is
|
||||
the width of the parent container.
|
||||
|
||||
height - the height of the object, in pseudo-pixels. The default is
|
||||
the width of the parent container.
|
||||
|
||||
legend - the text legend to display in the object.
|
||||
|
||||
label - the text label to display near the object.
|
||||
|
||||
property - the name of the FlightGear property whose value will
|
||||
be displayed in the object (and possibly modified through it).
|
||||
|
||||
binding - a FlightGear command binding that will be fired when the
|
||||
user activates this object (more than one allowed).
|
||||
|
||||
default - true if this is the default object for when the user
|
||||
presses the [RETURN] key.
|
||||
|
||||
Objects may appear nested within the top-level dialog or a "group"
|
||||
object. Here are all the object types allowed, with their special
|
||||
properties:
|
||||
|
||||
|
||||
dialog
|
||||
------
|
||||
|
||||
The top-level dialog box; the name does not actually appear in the
|
||||
file, since the root element is named PropertyList.
|
||||
|
||||
name - (REQUIRED) the unique name of the dialog for use with the
|
||||
"dialog-show" command.
|
||||
|
||||
modal - true if the dialog is modal (it blocks the rest of the
|
||||
program), false otherwise. The default is false.
|
||||
|
||||
Example:
|
||||
|
||||
<PropertyList>
|
||||
|
||||
<name>sample</name>
|
||||
<width>500</width>
|
||||
<height>210</height>
|
||||
<modal>false</modal>
|
||||
|
||||
<text>
|
||||
...
|
||||
</text>
|
||||
|
||||
<button>
|
||||
...
|
||||
</button>
|
||||
|
||||
</PropertyList>
|
||||
|
||||
|
||||
group
|
||||
-----
|
||||
|
||||
A group of subobjects. This object does not draw anything on the
|
||||
screen, but all of its children specify their coordinates relative to
|
||||
the group; using groups makes it easy to move parts of a dialog
|
||||
around.
|
||||
|
||||
Example:
|
||||
|
||||
<group>
|
||||
<x>0</x>
|
||||
<y>50</y>
|
||||
|
||||
<text>
|
||||
...
|
||||
</text>
|
||||
|
||||
<input>
|
||||
...
|
||||
</input>
|
||||
|
||||
<button>
|
||||
...
|
||||
</button>
|
||||
|
||||
</group>
|
||||
|
||||
|
||||
input
|
||||
-----
|
||||
|
||||
A simple editable text field.
|
||||
|
||||
Example:
|
||||
|
||||
<input>
|
||||
<x>10</x>
|
||||
<y>60</y>
|
||||
<width>200</width>
|
||||
<height>25</height>
|
||||
<label>sea-level temperature (degC)</label>
|
||||
<property>/environment/temperature-sea-level-degc</property>
|
||||
</input>
|
||||
|
||||
|
||||
text
|
||||
----
|
||||
|
||||
A non-editable text label.
|
||||
|
||||
Example:
|
||||
|
||||
<text>
|
||||
<x>10</x>
|
||||
<y>200</y>
|
||||
<label>Heading</label>
|
||||
</text>
|
||||
|
||||
|
||||
checkbox
|
||||
--------
|
||||
|
||||
A checkbox, useful for linking to boolean properties.
|
||||
|
||||
Example:
|
||||
|
||||
<checkbox>
|
||||
<x>150</x>
|
||||
<y>200</y>
|
||||
<width>12</width>
|
||||
<height>12</height>
|
||||
<property>/autopilot/locks/heading</property>
|
||||
</checkbox>
|
||||
|
||||
|
||||
|
||||
button
|
||||
------
|
||||
|
||||
A push button, useful for firing command bindings.
|
||||
|
||||
one-shot - true if the button should pop up again after it is
|
||||
pushed, false otherwise. The default is true.
|
||||
|
||||
<button>
|
||||
<x>0</x>
|
||||
<y>0</y>
|
||||
<legend>OK</legend>
|
||||
<binding>
|
||||
<command>dialog-apply</command>
|
||||
</binding>
|
||||
<binding>
|
||||
<command>dialog-close</command>
|
||||
</binding>
|
||||
<default>true</default>
|
||||
</button>
|
||||
|
||||
|
||||
|
||||
combo
|
||||
-----
|
||||
|
||||
A pop-up list of selections.
|
||||
|
||||
value - one of the selections available for the combo. There may be
|
||||
any number of "value" fields.
|
||||
|
||||
Example:
|
||||
|
||||
<combo>
|
||||
<x>10</x>
|
||||
<y>50</y>
|
||||
<width>200</width>
|
||||
<height>25</height>
|
||||
<property>/environment/clouds/layer[0]/type</property>
|
||||
<value>clear</value>
|
||||
<value>mostly-sunny</value>
|
||||
<value>mostly-cloudy</value>
|
||||
<value>overcast</value>
|
||||
<value>cirrus</value>
|
||||
</combo>
|
||||
|
||||
|
||||
slider
|
||||
------
|
||||
|
||||
A horizontal or vertical slider for setting a value.
|
||||
|
||||
vertical - true if the slider should be vertical, false if it should
|
||||
be horizontal. The default is false.
|
||||
|
||||
min - the minimum value for the slider. The default is 0.0.
|
||||
|
||||
max - the maximum value for the slider. The default is 1.0.
|
||||
|
||||
Example:
|
||||
|
||||
<slider>
|
||||
<x>10</x>
|
||||
<y>50</y>
|
||||
<width>200</width>
|
||||
<property>/environment/visibility-m</property>
|
||||
<min>5</min>
|
||||
<max>50000</max>
|
||||
</slider>
|
||||
|
||||
|
||||
dial
|
||||
----
|
||||
|
||||
A circular dial for choosing a direction.
|
||||
|
||||
wrap - true if the dial should wrap around, false otherwise. The
|
||||
default is true.
|
||||
|
||||
min - the minimum value for the dial. The default is 0.0.
|
||||
|
||||
max - the maximum value for the dial. The default is 1.0.
|
||||
|
||||
Example:
|
||||
|
||||
<dial>
|
||||
<x>10</x>
|
||||
<y>50</y>
|
||||
<width>20</width>
|
||||
<property>/environment/wind-from-direction-deg</property>
|
||||
<min>0</min>
|
||||
<max>360</max>
|
||||
</dial>
|
||||
|
||||
|
||||
__end__
|
||||
Loading…
Reference in a new issue