                        Widget Creation Library,
                       Motif Resource Interpreter,
                      Athena Resource Interpreter:

                An Easier Way to Develop Applications
                    using Motif and Athena Widgets.

Window-based applications are notoriously difficult to program.  When
the Macintosh was introduced in early 1984, Bill Gates projected that
50% of Microsoft revenues would come from Mac application by October
1984.  In reality, the first Mac applications were only beginning to be
shipped by that date.  

When Steve Jobs left Apple and developed the NeXT computer, the window
environment was specifically designed to support a WYSIWYG interface
builder.  NextStep and the NeXT IB were the results of this effort.

The X developers at MIT and DEC also needed an easy way to develop
windowed applications.  Instead of developing a WYSIWYG tool like NeXT,
they developed a toolkit where interfaces were specified using C code,
and could be significantly modified via `resource files' using a
minimum number of attribute specifications. They provided an instance
attribute inheritance mechanism to propogate attributes throughout an
interface.  This allows such simple specification as the following to
alter every font in an interface:

        *font: 9x15

The toolkit is called the Xt Intrinsics.  The windows, buttons, menus,
scrollbars, etc., are called Widgets.  The Athena Widgets are one set
of user interface objects built upon the Xt Intrinsics.  Motif is
another set of widgets.

As time went on, developers of widget-based applications found the
resource files to be more and more useful.  For the fourth release of
the X11 window system, many of the example programs evolved to the
point that only the raw behavior of the applications were specified in
C, with most of the look and feel being specified using resource files.

At the fourth annual X Technical Conference, several people pointed
out that resource files could be used to specify everything about
a widget based user interface, except the actual "tree" of widgets,
their types, and bindings of behaviors to the user interface widgets.
Could the resource mechanism be enhanced to allow these to be specified
as well?

Martin Brunecky at Auto-Trol in Denver Colorado took up the challenge,
and posted a simple set of routines which he called WsXc, for "Window
System: Xrm Creation."

Xrm stands for X Resource Manager, which is a heirarchical database for
keeping arbitrary named data related to X window interfaces.  The Xt
Intrinsics use Xrm for widget resources.  The basic idea of WsXc is
to search the Xrm database, starting at the root, and pull out resources
which describe the widget heirarchy and bindings to callback functions.

Over the next several months, WsXc was repackaged as Mri (Motif
Resource Interpreter), and then Ari (Athena Resource Interpreter), and
finally generalized into the Widget Creation Library.  The result provides
several significant benefits to the developer and the user:

        o Rapid Prototyping: Arbitrarily complex widget interfaces
                may be specified, and many common behaviors (pop-up,
                change attributes, exit) can be specified for the
                interface.

        o Prototyping Environment is the Development Environment is
                the Delivery Environment: There is no specific breaking
                point between prototyping, developing, and tuning a
                delivered program.

        o Minimum Specifications: The Xrm and Xt Intrinsics instance
                attribute inheritance mechanism is fully utilized, so
                a minimum number of specifications can describe a
                complete user interface.

        o Extensible:  Adding new widget types and callback routines
                is trivial.

        o Widget Set Independent: The C code which provides the
                behavior of the application can frequently be
                written in a widget set independent manner.  This
                allows an application to be written which supports
                multiple look-and-feel definitions: Motif, OpenLook,
                and Athena interfaces can all be front-ends to the
                same underlying application.

        o The user can make any change to the interface: Deeply nested
                menus can be substituted for dialog boxes, or vice versa.
                Any label or image can be altered, which supports inter-
                nationalization.


The Widget Creation Library Distribution
----------------------------------------

The Widget Creation Library is a cleanup and enhancement of Martin
Brunecky's second posting of WsXc.

The emphasis of the cleanup was to provide a separation of functionality
and declarations between source and include files, to make the naming
concise and unique, and to reduce the complexity of the interface between
the library and the application (it was pretty darn good already).

The emphasis of the enhancements were to add clear(er) warning and
error messages, add more utility callbacks, and to provide a few simple
functions which make writing callbacks and converters a little easier.

One of the guiding principles was and is KISS.  This is intended to
be a very small library which provides very big gains in productivity
for programmers developing applications using the various widget
sets based on the Xt Intrinsics.  A large number of the total lines
of code provide error messages.  The rest is quite straight forward.

This directory contains files which make up libWc, the Widget Creation
Library, Ari, the Athena Resource Interpreter, and Mri, the Motif
Resource Interpreter.

Authors
-------

Martin Brunecky at Auto-trol Technology, Denver (marbru@auto-trol.UUCP)
wrote the initial code and posted it to comp.windows.x with the title
POOR MAN's UIL - WsXc.

David Harrison of the UC Berkeley Electronics Research Lab
(davidh@ic.Berkeley.EDU or ...!ucbvax!ucbcad!davidh) wrote a very
useful Table widget.  It is so good I've included it with this
distribution.  It is separately available from archive sites.  See
TableHEARYE and TableFIRST for information on this widget.  I made very
minor edits to make it work with Motif, and I fixed exactly one minor
bug.

Rod Whitby of Austek Microsystems Pty. Ltd. in Adelaide, Australia
(rwhitby@adl.austek.oz.au) wrote the WcRegXt.c file, and caught 
several bugs.

The rest was done by me, and here is my standard .sig:

-------------------------------------------------------------------------
David Smyth				david@jpl-devvax.jpl.nasa.gov
Senior Software Engineer,		seismo!cit-vax!jpl-devvax!david
X and Object Guru.			(818)393-0983
Jet Propulsion Lab, M/S 230-103, 4800 Oak Grove Drive, Pasadena, CA 91109
-------------------------------------------------------------------------

Many people helped alot by providing bug fixes, enhancements, suggestions,
and just plain feedback.  There are many who helped, including Andrew Peebles 
at MIPS, Randy Brown, Art Poley, Mike Yee of OSF, Richard Hesketh, and
our own Kaleb Keithley.


README Files and Documentation
------------------------------

The *README files provide minimal documentation.  I think you will
find the comments in the source files useful.  Also, several
example resource files are provided with extensive comments.

A paper which I presented at the European X User's Group meeting
in Guildford, Surrey, UK in September 1990 is available in Postscript
form.  The paper can be considered a reference or programmer's manual.
Slides from that talk are likewise available, also in Postscript.  The
slides provide several examples.

Makefiles
---------

An Imakefile and a makefile are provided.  As provided, they build on
our Sun and VAX machines which are still using Motif 1.0.  Commented
out lines are provided which work on Suns using Motif 1.1.1.  There are
comments at the beginning of the Imakefile and makefile which point out
the lines which you may have to change.  In order to avoid phase
errors, I'll add no details here.  See the Imakefile and makefile!

Building The Distribution using Imake
-------------------------------------

If you have Imake, you can build the distribution very simply.

    % make Makefile

You may then build the delivery using this Makefile:

    % make

Otherwise...
------------

Otherwise, you may have to edit the makefile to reflect your site's
configuration.  You may notice that the makefile and the Imakefile
are very similar, and the same types of edits will probably need to
be made to both.

The easiest thing to do is simply this:

    % make

which causes all the libraries and executables to be built.

Testing The Distribution
------------------------

I have included a simple test csh script which executes all of the
example programs.  After you build, the test program will execute
which ever or the executable targets it finds.  Just do the following:

    % test

Widget Creation Library
-----------------------

The makefiles build two versions of the library: one which works
with the Athena widgets, and one which works with the Motif widgets.
There really should be no difference between the two libraries,
especially after Motif 1.1 is widely used.  

Mri and Ari Widget Resource Interpreters
----------------------------------------

There are also two "interpreters" which allow widget based user
interfaces to be developed and to have a few useful behaviors.  These
interpreters are intended to be useful for prototyping.  

Ari is the Athena Resource Interpreter, and it knows about all the
Athena widgets.  Mri is the Motif Resource Interpreter, and is knows
about all the Motif widgets.  Both interpreters also know about the
very useful Table widget, which is described in the files Table*.

Each interpreter consists of a main() procedure, and a function which
registers all the known widget types.  Mri consists of Mri.c and
MriRegAll.c while Ari consists of Ari.c and AriRegAll.c.  The
registration files are intended to be independent.

It should be a simple task to build a single interpreter which knows
about every widget on earth, but if you don't have shared libs, the
resulting executable is HUGE.

Several resource files are provided for each of the interpreters.  They
are named A<nn>.<description> and M<nn>.<description>.  To try 
out the interpreters (after you build them), do the following:

    % alias se setenv XENVIRONMENT
    % se A08.ClkLogo
    % Ari
    % se M7.Periodic
    % Mri

The resource files are intended to be tutorials, so they are heavily
commented and they explore various topics you may find interesting.

Once an interface is prototyped using Mri or Ari, one can take the
Mri or Ari source files and makefiles and evolve them into applications.

Sample Applications
-------------------

The program App is exactly one such example application.  The 
files Ari.c and mk_Ari were gradually modified as additional
behaviors were defined, registered with the Wc library, and bound
to the appropriate widgets within the App01.All resource file.

If you look at App.c, you will notice that main() is very minimal.
The application is really defined by its resource file (the look
and feel) and the callbacks (the behavior).  Notice that the
callbacks use several routines provided by the Wc library.  They
will be introduced in another README file.

After you build App, you can try it out as follows:

    % se App01.All
    % App

Another sample application included with the distribution is MD, which
is built as two versions: MDathena and MDmotif.  The Motif version
currently does not work very well due buggy interactions between Motif
and the Intrinsics.  This application demonstrates how a single
application can support multiple display connections with multiple
widget heirarchies.  These may be executed like this:

    % se MD
    % MDathena
    % MDmotif

