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.
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 |
| xbutton | A button which executes script actions from mouse clicks. |
| xdialog | A dialog box containing a text string. |
| xform | The window containing other graphical elements. |
| ximage | Displays a GIF format bitmapped image inside a form. |
| xlabel | A rectangular label containing a text string. |
| xtext | A widget for the display and editing of text. |
| xtoggle | Maintains toggle state and executes actions from mouse clicks. |
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 xform /data
create xgraph /data/voltage
create xbutton /data/RESET -script reset
create xbutton /data/RUN -script "step 100"
create xbutton /data/QUIT -script quit
As described in Messages, 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.
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.
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.
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 | 0:parent.left |
| ygeom | 0:last.bottom |
| wgeom | 100%:parent.width |
| hgeom | <default height for widget> |
When a value is given, then the reference widget defaults to parent and the reference edge defaults to:
| xgeom | left for a parent ref, right for a sibling ref |
| ygeom | top for a parent ref, bottom for a sibling ref |
| wgeom | width |
| hgeom | 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
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 that are currently available.
| Object | Description |
| xaxis | Makes axis for plots -- automatically created by xgraph. |
| xcell | Similar to xview, but specialized for compartmental cell display. |
| xcoredraw | The core class from which other draw widgets are subclassed. |
| xdraw | Main object class for the display of pixes, with transforms. |
| xdumbdraw | Simple example window for the display of pixes. |
| xfastplot | High-speed graphic display similar to an oscilloscope |
| xgif | Draws GIF format images as a pix inside a draw. |
| xgraph | Specialized draw widget for the display of plots. |
| xpix | Basic object for drawing graphical objects (pixes) in 3-D space. |
| xplot | Displays plots within a graph -- created by messages to xgraph. |
| xshape | Pix used for drawing shapes -- often used for icons. |
| xsphere | Example pix which draws a filled circle. |
| xtree | Displays and manipulates elements and their messages. |
| xvar | Uses shapes to display numerical values with color, size, etc. |
| xview | Like an array of xvars, displaying multiple points in 3-D space. |
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 |
| pixflags | Alias for xpixflags. |
| setpostscript | Alias for xps. |
| xcolorscale | Sets the color scale for mapping numerical values to color. |
| xflushevents | Forces XODUS to go through the queue of pending events. |
| xgetstat | Returns 0 if XODUS has not been initialized. |
| xhide | Hides a form and its contents. |
| xinit | No longer necessary in GENESIS 2 (does nothing). |
| xlower | Moves a form below any other forms or windows. |
| xmap | Like xshow, but does not put form on top if it is not hidden. |
| xpixflags | Describes set of flags which determine properties of pixes. |
| xps | Sets parameters for postscript output of widgets. |
| xraise | Moves a form on top of any other forms or windows. |
| xshow | Shows (displays) a form and its contents. |
| xshowontop | Alias for xshow (for backwards compatibility). |
| 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. |