GENESIS Reference ManualMay 5, 2001: The XODUS Graphical Interface

Previous Next Table of Contents

## 19. The XODUS Graphical Interface

## 19.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.

## 19.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
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.

## 19.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.

### 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 | 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

## 19.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 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.

## 19.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
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.

Previous Next Table of Contents