The Histo-Scope Widget Set is a collection of six Motif widgets for graphing
and plotting.  It features the high performance and screen stability necessary
for animation, and includes interactive controls for direct manipulation with
the mouse.  The widgets were developed for an interactive data browsing tool
called Histo-Scope, but are very general and easy to incorporate into other
Motif applications.


BUILDING

The two directories called plot_widgets and util contain the sources for the
widgets.  Actually, most of the code in util is not actually used by the
widgets.  If you are having trouble building the code in util, just build
psutils.o and (VMS only) vmsUtils.o.  The rest of the routines are either not
used, or used only by some of the example programs.  Util should be built
first, followed by plot_widgets.  The makefile in this directory can be used to
build both in sequence, followed by the example programs, if your system is one
of the supported machines and no modifications are necessary to the makefiles. 
To build the plot widgets from this directory, issue the command: "make
<machine-type>"; where <machine-type> is one of the supported machine
types: sgi, ultrix, sunos, solaris, hp, osf, or ibm.  For example, to build the
Silicon Graphics (IRIX 5) version, type:

	make sgi

If everything works properly, this will produce a library called libPlotW.a
in the plot_widgets directory, and two example programs for each widget in the
examples directory.


The Source Directories

The makefiles in the util directory build a library file called libNUtil.a,
which is used mostly for the example programs, but contains one module required
by all of the wigets.  Unless you re-arrange the libraries, you will need to
include libNUtil.a in any link to use the plotting widgets.  However, most of
the real widget code is in the plot_widgets directory.

The plot_widgets directory builds libPlotW.a, which contains the object code
for the widgets themselves.  The directory also contains the include files
necessary to use the widgets in a program.

The examples directory builds two example programs for each widget, a simple
one, which just creates a widget with simple data, and a demo program which
exercises more of the features of the widget.

The makefiles in all three source directories consist of two parts, a machine
dependent part and a machine independent part.  The machine dependent makefiles
contain machine specific header information and invoke a common machine
independent part called Makefile.common.  To compile the files in any of
these directories, issue the command: "make -f Makefile.<machine-type>"; where
<machine type> is one of the supported machine types.  For example, on a
Silicon Graphics machine, you would type:

	make -f Makefile.sgi

To add a new machine type or configuration, copy one of the existing machine
dependent makefiles and give it the name of the new system, for example:
Makefile.sony.  Then, make any required changes in the new makefile.

 
Building on VMS Systems

Command files are provided for compiling and linking files in all three
directories.  comutil.com compiles the files in the util directory and produces
two library files, vmsutils.olb and libutil.olb.  comwidgets.com compiles the
files in the plot_widgets directory, and comexamples.com compiles and links the
files in the examples directory to produce the example executables.


USING THE WIDGETS IN A PROGRAM

To link your own programs with the widgets, you need both libPlotW.a from the
plot_widgets directory, and libNUtil.a from the util directory, as well as some
of the include files from plot_widgets.  The file widgets.doc (or the separate
PostScript version in ps_docs.tar) explains the resources and subroutine
interfaces to the widgets, but it is also expected that users already know how
to use Motif and widgets in general.

Since we most users are interested in source code for just one or two of the
widgets, we haven't gone to any particular trouble to package the libraries or
arrange the directories nicely.  They are just arranged as they are in our own
source directory tree for our own software products.


DOCUMENTATION

The plain-text document widgets.doc and its PostScript equivalent in
ps_docs.tar, explain the resources and subroutine interfaces to the widgets. 
It is expected that users already know how to use Motif and widgets in general.

ps_docs.tar contains the same text as widgets.doc in this kit.  The PostScript
version in ps_docs.tar has a number of additional illustrations, but at 10MB it
is quite bulky, and may not print on some printers.


LICENSE AND SUPPORT

Information on licensing and support can be found in the files LICENSE and
SUPPORT in distribution tar or backup savesets.


PROBLEMS, QUESTIONS, OR COMMENTS

If you have problems, questions, or comments, send mail to:
histoscope_support@fnal.gov.

Before reporting a problem, please check the file: RELEASE_NOTES to make sure
the problem is not already known.

Mark Edel
edel@fnal.gov
Fermi National Accelerator Laboratory
P.O. Box 500
Batavia, IL 60148
