From 3991ac24508ecc767213435eea759bc8b2b94b76 Mon Sep 17 00:00:00 2001 From: david Date: Mon, 20 Jan 2003 20:00:56 +0000 Subject: [PATCH] Basic information for creating menus and dialogs in FlightGear. --- docs-mini/README.gui | 341 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100644 docs-mini/README.gui diff --git a/docs-mini/README.gui b/docs-mini/README.gui new file mode 100644 index 000000000..2f6dfe63f --- /dev/null +++ b/docs-mini/README.gui @@ -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: + + + + + + + + + + exit + + + + + +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: + + + + hello + + 150 + 100 + false + + + 10 + 50 + + + + + + + +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: + + + + sample + 500 + 210 + false + + + ... + + + + + + + +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: + + + 0 + 50 + + + ... + + + + ... + + + + + + + +input +----- + +A simple editable text field. + +Example: + + + 10 + 60 + 200 + 25 + + /environment/temperature-sea-level-degc + + + +text +---- + +A non-editable text label. + +Example: + + + 10 + 200 + + + + +checkbox +-------- + +A checkbox, useful for linking to boolean properties. + +Example: + + + 150 + 200 + 12 + 12 + /autopilot/locks/heading + + + + +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. + + + + + +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: + + + 10 + 50 + 200 + 25 + /environment/clouds/layer[0]/type + clear + mostly-sunny + mostly-cloudy + overcast + cirrus + + + +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: + + + 10 + 50 + 200 + /environment/visibility-m + 5 + 50000 + + + +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: + + + 10 + 50 + 20 + /environment/wind-from-direction-deg + 0 + 360 + + + +__end__ -- 2.39.5