18. The XODUS Graphical Interface
18.1.
Introduction and Overview of XODUS
The graphical interface to GENESIS is provided by XODUS, the X-windows
Output and Display Utility for Simulations. This interface is
provided by graphical objects (called ``widgets'') which can be used
to create elements that are treated like other GENESIS elements.
These are discussed in detail in ``The Book of GENESIS'' and in the
documentation for the individual XODUS objects and commands, so we
will give only a brief overview here.
18.2.
Basic Widgets
The table below lists the basic XODUS widgets used to create labels,
buttons, toggles, dialog boxes, and for the display of bitmapped
images and text.
-------------------------------------------------------------------------Object
Description
-------------------------------------------------------------------------xform
The window containing other graphical elements.
xlabel
A rectangular label containing a text string.
xbutton
A button which executes script actions from mouse clicks.
xtoggle
Maintains toggle state and executes actions from mouse
clicks.
xdialog
A dialog box containing a text string.
ximage
Displays a GIF format bitmapped image inside a form.
xtext
A widget for the display and editing of text.
-------------------------------------------------------------------------The form, created from the xform object, is the container for all
other graphical elements.
Although the position of an element in the
element hierarchy is arbitrary for other GENESIS elements, widgets
which are to be displayed in a form must be children of the parent
form. The following example creates a graph and three buttons within
a form:
create
create
create
create
create
xform /data
xgraph /data/voltage
xbutton /data/RESET -script reset
xbutton /data/RUN -script "step 100"
xbutton /data/QUIT -script quit
As described in ``Messages'' (Messages.doc), a message from another
element would be used to send values to the graph for plotting.
Note the use of the ``-script'' option to set the ``script'' field of
the xbutton to the string representing the statement to be executed
when the button is clicked upon. Most of the XODUS widgets (except
for xform) also execute script actions in response to mouse clicks.
These are described under ``XODUS Mouse Clicks'' (Clicks.doc).
Other fields (described in the documentation for the particular widget
or listed with the showobject command) are used for setting background
and foreground colors, label strings, fonts, and other properties of
the widget. In addition, there are fields for specifying the geometry
of the widget, i.e. its location and size. In the example above, the
default values were used.
18.3.
Specifying Widget Geometries
The horizontal and vertical positions and the width and height of an
XODUS widget are specified by the four geometry fields ``xgeom'',
``ygeom'', ``wgeom'' and ``hgeom''. These fields may be set at any
time with the setfield command. You may also set them when the widget
is created, by using the options ``-xgeom'', ``-ygeom'', ``-wgeom''
and ``-hgeom''. As a shorthand notation, and for backwards
compatibility with previous versions of GENESIS, these four geometry
values may be given in square brackets as
``[xgeom,ygeom,wgeom,hgeom]'' at the time the widget is created. For
example,
create xform /form [10,10,400,100]
create xbutton /form/QUIT [0,20,,50] -script quit // use default
wgeom
When given as numbers, these values represent the (x,y) coordinates
and the width and height of the widget, measured in pixels. For
forms, the coordinates are measured relative to the upper left-hand
corner of the screen. For other widgets, they are measured relative
to the interior upper left-hand corner of the form which contains
them. The ``ygeom'' coordinate is measured downwards. A percent sign
may be used after a number to indicate that it represents a percentage
of the screen or form dimension, instead of a pixel value.
These conventions are used for the basic widgets described above, as
well as for the draw widget varieties described below.
18.3.1.
Reference Edges
It is also possible to specify the geometry of a widget with respect
to that of the parent form or another sibling widget using a notation
of the form ``offset:reference.edge''. Here, ``offset'' is a pixel
value or percentage, as before. ``reference'' may be ``parent''
(meaning the parent element -- usually the form), ``last'' (the most
recently created widget), or the name of a sibling widget. The
``edge'' may be ``left'', ``right'', ``top'', ``bottom'', ``width'',
or ``height''.
When used with ``xgeom'' or ``ygeom'' and a parent reference, left,
right, top and bottom will place the child's corresponding edge a
given distance in from the given edge of the parent. For a sibling,
the child's opposite edge is placed a given distance away from the
given edge of the sibling.
When specifying a ``wgeom'' or ``hgeom'', and giving a parent
reference, left, right, top and bottom will set the dimension of the
child such that the widget right or bottom edge will be the given
distance from the given edge of the parent. A width edge sets the
dimension to the value given while a height edge sets it to the parent
height less the given value. For a sibling, left, right, top and
bottom will set the dimension of the child such that the opposite edge
of the widget will be a given distance from the given edge of the
sibling. For width and height edges the dimension is set to the sum
of the siblings width/height and the given value.
Note that some combinations of references and edges result in
nonsensical geometry specifications which may cause errors.
In cases where a complete geometry value is not given, default values
are assumed. When no geometry is present the defaults are:
xgeom
ygeom
wgeom
hgeom
0:parent.left
0:last.bottom
100%:parent.width
<default height for widget>
When a value is given, then the reference widget defaults to parent
and the reference edge defaults to:
xgeom
ygeom
wgeom
hgeom
left for a parent ref, right for a sibling ref
top for a parent ref, bottom for a sibling ref
width
height
These combinations are best explained with some examples:
create xform /form [10,10,400,200]
xshow /form
// make it visible
// make a 100 x 50 pixel label, 100 pixels from the form left edge
create xlabel /form/label -xgeom 100:parent.left -wgeom 100 -hgeom
50
create xbutton /form/button // full width button below the label
(default)
// put button's right edge 10 pixels left of the label and reduce
width
setfield /form/button xgeom 10:label.left wgeom 70
// increase the height of the button to 80% of the label height
setfield /form/button hgeom 80%:label // ".height" is assumed
// change the button height to 30% of the label width
setfield /form/button hgeom 30%:label.width
// put bottom of button 50 pixels below top of label
setfield /form/button ygeom -50:label.top
// add a toggle 5 pixels to the right of the button
create xtoggle /form/toggle -xgeom 5:last.right -wgeom 100
18.4.
The Draw Widget Family
In addition to the basic widgets described above, XODUS provides a set
of more advanced graphical objects based upon the draw widget. A draw
widget may be thought of as a window into a three dimensional space
for the display of graphical objects called pixes. Draw widgets are
displayed inside of forms, and pixes are displayed inside of draws,
using the element hierarchy ``form/draw/pix''. The draw widget
provides for coordinate transformations of the pixes, including pan,
zoom, two dimensional projections into a given plane, orthographic and
perspective projections. These transformations may be controlled by
keyboard commands as well as by setting fields of the draw widget.
Further details are given in the documentation for xdraw.
The graph widget (described in the documentation for xgraph) is a
specialized form of draw widget for the display of plots and axes. In
addition to the transformations provided for draw widgets, it allows
additional transformations for rescaling axes and the displayed plots.
The table below summarizes the varieties of draws and pixes which are
currently available.
----------------------------------------------------------------------------Object
Description
----------------------------------------------------------------------------xdraw
Main object class for the display of pixes, with
transforms.
xcoredraw
The core class from which other draw widgets are
subclassed.
xdumbdraw
Simple example window for the display of pixes.
xgraph
xaxis
xplot
xgraph.
Specialized draw widget for the display of plots.
Makes axis for plots -- automatically created by xgraph.
Displays plots within a graph -- created by messages to
xpix
space.
xshape
xsphere
xgif
Basic object for drawing graphical objects (pixes) in 3-D
Pix used for drawing shapes -- often used for icons.
Example pix which draws a filled circle.
Draws GIF format images as a pix inside a draw.
xvar
Uses shapes to display numerical values with color, size,
etc.
xview
Like an array of xvars, displaying multiple points in 3-D
space.
xcell
Similar to xview, but specialized for compartmental cell
display.
xtree
Displays and manipulates elements and their messages.
----------------------------------------------------------------------------18.5.
XODUS Commands
When a form is first created, it is not visible. GENESIS has several
commands affecting the display of forms. Other commands are specific
to certain XODUS widgets. The table below lists the commands used
with XODUS.
----------------------------------------------------------------------------Routine
Description
----------------------------------------------------------------------------xhide
Hides a form and its contents.
xshow
Shows (displays) a form and its contents.
xmap
Like xshow, but does not put form on top if it is not
hidden.
xlower
Moves a form below any other forms or windows.
xraise
Moves a form on top of any other forms or windows.
xshowontop
Alias for xshow (for backwards compatibility).
xgetstat
Returns 0 if XODUS has not been initialized.
xcolorscale
Sets the color scale for mapping numerical values to
color.
xflushevents
Forces XODUS to go through the queue of pending events.
xpixflags
Describes set of flags which determine properties of
pixes.
pixflags
Alias for xpixflags.
xps
Sets parameters for postscript output of widgets.
setpostscript
Alias for xps.
xsimplot
Plots data from a file to a graph.
xtextload
Loads muliple lines of text into a text widget.
xupdate
Forces an update of the display of pixes within a draw.
-----------------------------------------------------------------------------