autogui - Tool

Postscript file available

Tool to build and operate a graphical form interface

include "autogui.g"

Description

This tool is an extremely useful one which builds a ``form-like'' graphical user interface (GUI) from a simple record whose fields describe individual parameters which the user may be allowed to edit. The GUI is displayed with the various parameters arranged vertically. Some of the parameters may be stored in rollup widgets. Each parameter is displayed with a text label, a widget (from the widgets module) to display the current value and optionally allow the user to edit it, a ``spanner'' menu (see guientry), and optionally an ``auto-apply'' check-button.

Generally, an autogui tool will be used to show the state of some ``parent'' tool to the user, and/or allow them to edit the state. Consequently, the autogui tool is a subsequence, allowing the tool to emit events, and catch inbound events. These events can be used to ensure that the GUI and any parent tool remain synchronised as the user modifies widgets in the GUI. Furthermore, if the autogui is used in this way, multiple (duplicate) autogui tools can be used to control one and the same underlying parent. This is done, for example, in the viewerdisplaydata tool. An obvious use of this capability would be to display identical autogui tools on separate desktops (or even screens!) for a given tool.

In addition to the event interface, the autogui tool provides a small number of functions to control its behaviour.

Parameter description

Most transactions of the autogui tool involve a ``parameter record.'' This is a Glish record containing one or more top-level fields. In full form, each top-level field contains a Glish record which completely describes a particular parameter in terms of its name, parameter type, default value, current value, its possible values (for 'choice' or 'range' parameters), whether it can be 'unset', whether it can be 'auto-apply' and whether it is editable by the user. In short form, each top-level field simply contains the value for its parameter.

The standard fields in a (full) single parameter record are:

dlformat: a string giving the name of the field of the parameter record in which this particular parameter is found.
listname: a string giving the name of this parameter which should be displayed in the GUI to identify it.
ptype: a string giving the type of the widget to be used for this parameter. If this field is not included, no widget will be created. Leaving this field blank will create a default entry box.
value: the present value of this parameter.
default: the default value of this parameter.

The optional fields in a (full) single parameter record are:

context: if present, this parameter will be placed in a rollup widget having as its name the string contained in this field of the record.
autoapply: if the autogui tool was constructed with autoapply=T [default], then a check-button will be placed next to this parameter. When this button is checked, any modification to this parameter will be immediately emitted from the autogui tool in a setoptions event (see below). This optional field, if present, indicates the initial state of this auto-apply button.
dir: if present, and is 'out', then this parameter is considered to be output-only, so the user will be unable to edit it.
allowunset: if present, and is T, then the constructed widget will allow this parameter to be 'unset'.
dependency_group: if present, this specifies a tag which identifies this as a parameter which has a dependency on other parameters with the same tag. At present, all this means is that parameters with the same dependency_group tag must be mutually exclusive.

We now list the available parameter types (ptype), and their additional required record fields:

boolean: a boolean guientry widget is provided with two choices: T or F. No additional required fields.
choice: a choice guientry widget is provided for selection from a set list of items. Additional required record fields are:
- popt: a vector of strings which are the valid options.
directory: a file guientry widget is provided for selecting a directory. No additional required fields.
file: a file guientry widget is provided for selecting a file. No additional required fields.
floatrange: a range guientry widget is provided for selecting a single float or double from a range. Additional required record fields are:
- pmin: minimum allowed real value
- pmax: maximum allowed real value
- presolution: resolution of provided scale widget
Additional optional record fields are:
- provideentry: if present, and is T, then an entry widget will be provided alongside the scale widget to allow the user to type a specific value. In this case, the scale will be ``extendable'' so that values outside the initial acceptable range will cause the scale to resize itself, and the allowed minimum and maximum to expand to accomodate the new specific value.
intrange: a range guientry widget widget is provided for selecting a single integer from a given range. Additional required record fields are:
- pmin: minimum allowed integer value
- pmax: maximum allowed integer value
Additional optional record fields are:
- provideentry: if present, and is T, then an entry widget will be provided alongside the scale widget to allow the user to type a specific value. In this case, the scale will be ``extendable'' so that values outside the initial acceptable range will cause the scale to resize itself, and the allowed minimum and maximum to expand to accomodate the new specific value.
measure: a measure widget is provided for selecting an AIPS++ measure. No additional required options.
quantity: a quantity guientry widget widget is provided for selecting an AIPS++ quantity. No additional required fields.
region: a region guientry widget is provided for selection an AIPS++ region. No additional required fields.
scalar: a scalar guientry widget is provided for entering a scalar (integer, double, or complex). No additional required fields.
table: a file guientry widget is provided for selecting an AIPS++ table. No additional required fields.
userchoice: an extendoptionmenu is used for selection from a user-extendable list of items. Additional required record fields are:
- popt: a vector of strings which are the initial valid options.
minmaxhist: a minmaxhist guientry widget is provided for selection of minimum and maximum in a graphical way. Additional required record fields are:
- minvalue The lower limit of the range.
- maxvalue The upper limit of the range.
Additional optional record fields are:
- default The default range.
- histarray The array containing a histogram to draw.
- imageunits The brightness units used as labels.

Event description

Two important events are emitted by the autogui tool, to which well-written Glish code will respond! The setoptions event is emitted whenever an ``auto-apply'' parameter is modified in the GUI. Its $value is a short-form parameter record, where the top-level fields simply contain the values of each parameter. It is also emitted when the action button is pressed, if the autogui tool was constructed without a parent frame (parent=F), and the actionlabel argument was a valid string.

The newuserchoicelist event is emitted whenever the extendoptionmenu widget for a parameter of ptype='userchoice' was extended by the user. This simply allows the programmer to detect when this happens, and modify their own local copy of the parameter set accordingly. This might be useful, for example, when they will create another autogui tool later on, and would like it to contain the additions the user made to any extendoptionmenus. The $value of this event has two fields:

param: the internal name of the parameter which whose option list was extended (ie. dlformat)
newvalue: the new value added to the choice list

Example
In the example below, we build a simple autogui tool with three parameters.

include 'autogui.g'

# we will put a "parameter set" into "parameters":
parameters := [=];

# an example of the floatrange parameter type.  Its auto-apply 
# button will be unchecked, and this parameter cannot be 'unset':
parameters.power := [=];
parameters.power.dlformat    := 'power';
parameters.power.listname    := 'Scaling power';
parameters.power.ptype       := 'floatrange';
parameters.power.pmin        := -5.0;
parameters.power.pmax        := +5.0;
parameters.power.presolution := 0.1;
parameters.power.default     := 0.0;
parameters.power.value       := 1.5;
parameters.power.autoapply   := F;
parameters.power.allowunset  := F;

# an example of the userchoice parameter type.  Its auto-apply
# button will be checked, and it also cannot be 'unset':
parameters.color := [=];
parameters.color.dlformat   := 'color';
parameters.color.listname   := 'Line color';
parameters.color.ptype      := 'userchoice';
parameters.color.popt       := "black white red yellow green";
parameters.color.default    := 'black';
parameters.color.value      := 'black';
parameters.color.autoapply  := T;
parameters.color.allowunset := F;

# an example of the region parameter type.  Its auto-apply 
# button will be checked, and it CAN be 'unset':
parameters.region := [=];
parameters.region.dlformat   := 'region';
parameters.region.listname   := 'Displayed region';
parameters.region.ptype      := 'region';
parameters.region.default    := unset;
parameters.region.value      := unset;
parameters.region.autoapply  := T;
parameters.region.allowunset := T;

# construct an autogui.  We will put auto-apply=T since some of 
# our parameters are auto-apply, and ask for a button with label
# 'Go!'.

myautogui := autogui(parameters, 'Demo autogui', actionlabel='Go!',
                     autoapply=T);

# and respond to the events it emits:
whenever myautogui->setoptions do {
  # do something more interesting than this though!
  print "New options for ", field_names($value), "emitted ...";
}

If you run this code, you should see a GUI like that shown in 1.10. Modifying either the 'Displayed region' or 'Line color' widgets should result in information being printed at the command line by the whenever statement at the end of the example. Likewise, pressing the 'Go!' button will emit all parameters.

**Figure 1.10:** A simple autogui `tool`
$\begin{figure} \begin{center} \epsfig{file=agintro.ps,width=3.6in}\end{center}\end{figure}$

Next: autogui - Constructor Up: widgets - Module Previous: autocli.get - Function Contents Index

	Package	display
	Module	widgets