source: trunk/third/wcl/README20 @ 8837

SccsID: @(#) README20 1.5 93/01/28 13:05:14

Widget Creation Library Version 2.0 Distribution
------------------------------------------------

The distribution contains files which make up the Widget Creation
Library (Wcl or libWc.a), and resource interpreters and utility
libraries (which include Table widgets) for each of the following
widget sets: Athena, Cornell, Motif, and OpenLook.

Wcl is completely widget set independent.  It provides mechanisms to
allow an entire user interface to be specified in resource files.
Basically, this amounts to providing new resources for specifying the
types of the widgets and the widget heirarchy.  In addition, Wcl
provides several callbacks and action functions whicc many programs
need.

New Features of Wcl
-------------------

        Mapping Agents  - map arbitrary data to widgets.
        Templates       - constructors defined in resource files.
        Argv Parsing    - easier to set resource file, AppShell class.
        Error Database  - all messages can be tailored.
        New WcCreate()  - much faster, more consistent, better creation
                          ordering, better creation time callbacks.
        UndefinedCB     - Useful for prototypign and incremental development.
        WcInitialize()  - so Wcl can be used even if it does not create the
                          initial widget tree.
        Dynamic Creation- New functions: WcCreateChild(), WcCreatePopup()
                          and WcCreateRoot() return new child Widget.
        Invoke*()       - WcInvokeAction(), WcInvokeNamedAction(), and
                          WcInvokeCallback() make it easy to implement
                          application behaviors as either CB or Action
                          procedures, yet make the behaviors available
                          as both CB and Actions.
        WcSetValue      - Multiple resource values can be set from String
                          specifications.  Three interfaces: WcSetValue(),
                          WcSetValueFromString(), WcSetValueFromStringAndType().
        Dynamic Binding - Callbacks and actions can be invoked from shared
                          libraries on SVR4 and SunOS machines when you
                          use the new WcDynamicAction() and WcDynamicCallback()
                          actions and callbacks.
        New CBs & ACTs  - WcMap(), WcUnmap(), WcInstallAccelerators(),
                          WcInstallAllAccelerators(), WcCreateRoot(),
                          WcSpawn(), WcPrintTree(), WcPositionTransient(),
                          WcSetValues(*re-worked*), WcOnceOnly(),
                          WcAddCallbacks(), WcRemoveCallbacks(),
                          WcTranslations()


The Future of Wcl
-----------------

I am planning on a regular 3 month revision cycle.  There are several
capabilities and new widgets which are in development and scheduled for
future releases:

 1. The ability to specify resourceName, ResourceClass, ResourceType for
    resources of widgets which are not reported by XtGetResourceList() and
    XtGetConstraintResourceList(), such as TextSrc and TextSink resources
    of Athena derived text widgets like XmText.

 2. SetState: The ability to change resources of many widgets in part of
    a widget tree.

 3. The ability to set Wcl resources on widgets via editres.

 4. Resource database consistency checking (like "lint") following widget
    tree creation, triggered by Wcl callbacks or actions.

 5. Extension of the Dynamic Binding concept

Documentation is currently being re-written.  Viewgraphs, a tutorial,
and an updated reference manual are well underway, but nor quite finished.


Table Widget
------------

Two versions of the Table widget are provided: the XpTable widget which
is derived from Xt base classes and therefore can be used by all the
widget sets, and the XmpTable widget which is derived from the Motif
XmBulletinBoard widget, and therefore can only be used with Motif.  The
XpTable implementation is shared via links by each of the Xp, Xcp, and
Xop library subdirectories.

This complete re-write of the Table widget provides some added
functionality and more consistent behavior.  Children widgets can now
be easily, efficiently, and correctly placed at any col/row/span within
the table.  Margins (top/bottom and left/right) between the edge of the
table and the children can now be specified.  Primitive widgets now
shrink!  Several minor bugs in the original table which causes
inconsistent behavior have been eliminated.


Demonstration Resource Files
----------------------------

Demonstration application resource files are now installed in subdirectories
of XAPPLOADDIR (usually /usr/X11R5/lib/X11/app-defaults) to keep from 
cluttering up this increasingly important directory.

The Motif demonstration resource files are pre-processed by cpp to get
rid of inconsistencies between Motif 1.0 and Motif 1.1 shell naming
conventions.

I use Mri for regression and path testing of Wcl, and so there are
several specific resource files named Wc* in the Mri directory.  These
are not installed, and are normally interpreted by Mri/Test, which
is a slightly modified version of Mri specifically for testing.

I would be grateful if somebody would provide similar resource files and
test programs for the other widget sets.


For Athena
----------

This distribution provides Ari (the Athena Resource Interpreter), and
the Xp library.  The Xp library includes the table widget and a
convenience procedure which registers all Athena widgets (including the
new ones in R5).  The same set of Athena demo resource files are
provided, which now install in a subdirectory of
.../lib/X11/app-defaults/Ari

For Cornell
-----------

The Cri and libXcp originally provided by Kim Gillies has been
upgraded very slightly, but it is still the least mature.  The Athena
version of the Table widget (XpTable) is built into the Xcp library.

For Motif
---------

Xmp provides Motif specific functions and the Table widget derived from
Motif manager widgets so it works nicely within Motif user interfaces.
This version of Table is named XmpTable.

Mri can be considered a prototype program for any Motif application.
Many example resource files are provided which act as a tutorial to the
use of Mri and Motif.  There is also a program called Test along with
some additional resource files.  I use Test to do complete path testing
and capability testing of this distribution.  You can too in order to
ensure everything works on your platform.

For OpenLook (OLIT) Widgets
---------------------------

If you have a Sun, you should have fun with Ori and libXop.  Again, the
Athena version of the Table widget (XpTable) is built into the Xop
library.  Kim Gillies has provided many very useful tutorials for
using Ori.  I like this stuff!


Incompatible Changes With Earlier Versions of Wcl
-------------------------------------------------

This is version 2.x not 1.x - there are things which are different, and
you will have to change some of your C code and your resource files.


CHANGED: The Creation Logic
---------------------------

There is now a distinction between the resources which must be fetched
before a widget can be created, and those resources which may be
fetched afterwards.  This may require you to change some resource
specifications for widgets created using some of the Motif widget
constructors which create additional widgets, like XmCreatePulldownMenu
or XmCreateScrolledWindow.

Also, there is now a new creation resource, wcPopups, which should be
used to create popup children of widgets.

Note that this will no longer work with Wcl 2.0:

        *foo.wcChildren:        first second third

        *third.wcConstructor:   XmCreatePulldownMenu
        *third.wcManaged:       False
        *third.wcChildren:      one two three

The problem is that with Wcl 1.x the wcManaged and wcChildren resources
were incorrectly fetched before the widget was created.  This is no longer
the case.  You can either change the specification to be like this:

        *third.wcConstructor:   XmCreatePulldownMenu
        *third*wcManaged:       False
        *third*wcChildren:      one two three

Or more correctly, change them to look like this:

        *foo.wcPopups:          first
        *foo.wcChildren:        second third

        *third.wcConstructor:   XmCreatePulldownMenu
        *third*wcChildren:      one two three

When using Motif, the symptom of this problem is seen if 10x10 shells
show up on the screen which (usually) do not have window manager
provided decoration, and which go away when you click the mouse
anywhere.  The symptom looks like this because the *foo.wcManaged and
*foo.wcChildren resources are not seen.

Note that the children named in wcPopups resources are created before
children in wcChildren resources.


ENHANCED: Creation Time Callbacks
---------------------------------

There are now several creation time callbacks.  The original wcCallback
is still supported, and is still invoked before any children of the widget
are created.  The full set of creation time callbacks are listed below:

   *foo.wcCallback:             Invoked after foo is created, but before
                                any of its children are created.
   *foo.wcAfterPopups:          Invoked only if foo has popup children,
                                after the popup children are created.
   *foo.wcAfterChildren:        Invoked only if foo has normal children,
                                after the normal children are created.
   *foo.wcAfterManageChildren:  Invoked only if foo has normal children,
                                after the normal children have been managed,
                                even if all of the normal children have their
                                *wcManaged resource set false.

Note that all of these callback resources are post-creation resources,
so you need to be aware of phantom widgets which may be spliced into
the widget tree when you use widget constructors like XmCreatePopupMenu.


CHANGED: Include File Installation Location
-------------------------------------------

Wcl include files should be installed in a subdirectory of the X11
include files, just like Xaw and Xmu include files.  Therefore,
you should change your include directives to look like this:

        #include <X11/Wc/WcCreate.h>
        #include <X11/Xmp/Xmp.h>

This conforms to the X11R5 conventions.  Note that many eariler
versions of Wcl actually installed the include files in subdirectories
of X11 already, so you probably already use compile flags to tell the
compiler to look in .../X11 for Wcl includes.


REMOVED: WcSetTypeValue
-----------------------

WcSetTypeValue is not longer supported.  Instead, use WcSetValue with a
parenthesized type following the resource name and preceeding the `:'
like this:

        WcSetTypeValue( *msgWindow.fontList: FontList, *courier-*--10-* )

should be replaced with

        WcSetValue( *msgWindow.fontList(FontList): *courier-*--10-* )


CHANGED: WcSetValue
-------------------

WcSetValue now uses a more rational algorithm for converting values
into widgets.  The new scheme allows code to be cut and pasted from
normal resource specifications into the arguments for WcSetValue.
Specifically, I had to change this specification:

        *fileMenu.wcCallback:      WcSetValue(*file.subMenuId: this)

to be

        *fileMenu.wcCallback:      WcSetValue(*file.subMenuId: ^*fileMenu)

Why?  Because in the previous version, the `this' widget implied the
widget which invoked the callback.  In all other cases of resource
specifications, the `this' widget implies the widget whose resource
value is being set.  Therefore, I eliminated this inconsitency: now
whenever `this' shows up in a resource specification value, it always
means the widget whose resource is being specified.  In the above case,
it is now possible to cut and paste a resource specification from and
to the WcSetValue arguments.


ENHANCED: WcSetValue
--------------------

As an enhancement, WcSetValue can now handle multiple specifications by
parenthesizing each separate specification like this:

        WcSetValue( (*file.subMenuId: *fileMenu) (*help.subMenuId: *helpMenu) )


NO-OPS: WcAllowDuplicate*Registration
-------------------------------------

Duplicate registrations are now always allowed: they always replace
previous registrations.  These functions are now all no-ops.


CHANGED AND INCOMPATIBLE WITH 1.06: Templates
---------------------------------------------

The entire principle and mechanism for templates has been re-done.
Your existing templates will NOT work, but they can be made to work
with minor edits.  This implementation uses a Wcl library resource to
identify a file which contains only resource specifications for
templates.  See the files Mri/PerTem, Mri/PT_DisplayBox, and
Mri/PT_ColumnLable to see how I changed Mri/Periodic to use templates
(also note the use of WcDynamicCallback and WcDynamicAction).

Templates absolutely REQUIRE the X11R5 Xlib and Xt.  You do not need
anything else from X11R5.


CHANGED: WcResFile now WclResFiles
----------------------------------

Intensive path coverage testing of Wcl 2.0 using Saber-C uncovered a
serious bug in the concept of wcResFile.  Some users of the data in
the resource database do not make copies of values, but instead
expect the resource database to remain constant.  WcResFile causes
resource values which change TO BE FREE'd, which of course is dangerous
if anyone is using the storage (actually, Xrm does the freeing, and
Wcl cannot avoit causing this to happen).

Therefore, the wcResFile resource is no longer recognized as a widget
instance resource.

Instead, a new resource, WclResFiles, has been added.  This resource
allows all resource files to be loaded when Wcl is initialized (usually
the first time WcWidgetCreation is called).  This is a LOT safer.

CHANGED: WcLoadResourceFiles() 
------------------------------

This procedure should not be used to load widget resource values.  It
is still safe to use for application resources, but you need to be careful
about the possibility of resource values being free'd if they are changed
due to new resource specifications.

Also, this procedure now takes a Widget, rather than a Display* as its
argument.  It can tell the difference, so this is actually a binary
compatible, but strong-type-checking source level incompatibility!

RENAMED: Motif Table now XmpTable
---------------------------------

The Motif derived Table widget is now named XmpTable in order to allow
both the Athena and Motif versions to co-exist in the same application,
and to follow the de-facto naming conventions.  This name change was
done in Wcl 1.05, so you may have already incorporated the effects.

RENAMED: Athena, Cornell, and OpenLook Tables now XpTable
---------------------------------------------------------


***** End of incompatibilities *****


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

Postscript documentation is no longer distributed with Wcl due to the
size of such files.  The distribution now contains several useful
man pages.  The Postscript documentation is being re-worked, and
will be available shortly via ftp from export, and via the other
source archives.

In addition, the resource files in the Ari, Cri, Mri, and Ori
directories contain a lot of comments,  and are intended to illuminate
many subtle techniques which you will find useful.  All of the C source
files are also heavily commented.


Imakefiles and MakeByHand Makefiles
-----------------------------------

Both Imakefiles and hand-built (MakeByHand) Makefiles are provided.

See the file README_BUILD for specific build instructions.



Passing Wcl on to others
------------------------

As mentioned in the Wcl copyright (see the COPY include file) the entire
Wcl distribution can be given to others.  In order to make this easy, the
hand-built Makefile has targets for making compressed tarfiles:

        % make -f MakeByHand tar.Z


Acknowledgements
----------------

Martin Brunecky (marbru@auto-trol.com), at Auto-trol Technology
Corporation, Denver, CO must be given alot of credit for any release of
Wcl.  He provided the original proof of concept, and has since provided
many useful suggestions and criticisms.  He filled in to support and
boost Wcl when my network connectivity was virtually non-existent for
several months.

David Harrison originally developed the Table widget when he was at the
University of California, Berkeley in 1989.  Martin, Kee Hinckley
(nazgul@alphalpha.com) and others have provided bug fixes and
enhancements over the years.

Many, many other people have provided ideas, fixes, feedback, and
support during the life of Wcl.  There is no way I could make a
reasonably exhaustive list, but certainly Wcl would not be what it is
without Andrew Peebles (peebles@mips.com), Andrew Wason
(aw@bae.bellcore.com), Kim Gillies (gillies@noao.edu), Ronald P. Hughes
(ron@xwind.com), Adrian Nye (adrian@ora.com), Richard Hesketh
(rlh2@ukc.ac.uk), Ron Newman (rnewman@bbn.com), Bo Thide <bt@irfu.se>,
Gary Gu (ggu@maxine.WPI.EDU), John Mackin (john@cs.su.oz.au), Jim
Ludwig (jludwig@encore.com), Thomas Wolf (wolf@mink.att.com), Randy
Brown (erik!randy@uunet.UU.NET), Art Poley <media!arthur@uunet.UU.NET>,
Rod Whitby (rwhitby@research.canon.oz.au), David B. Lewis, Mike Yee,
David Elliott, and Niels Mayer (mayer@hplabs.hp.com).

And of course nothing would have been done without the encouragement,
leeway, and funding by "Suits" including Joe Kahr, John Diehl, Steve
Wright, and Dr. Andreas Wnuk.

And of course, everyone currently or once with the X Consortium,
especially Chris D. Peterson, Donna Converse (who saved my last
vacation), Paul Asente, Ralph Swick, and Mark Ackerman, must be
given credit: the best way to become great is to stand on the
shoulders of giants.

------------------------------------------------------------
David E. Smyth                David.Smyth@sniap.mchp.sni.de
Object/X Researcher           david@ap542.uucp
Esprit Research               david%ap542@ztivax.siemens.com
Funding provided by: Siemens Nixdorf Informationssysteme AG
                     AP 154, Carl-Wery-Str 22, Munich 83 Germany