source: trunk/third/wcl/README23 @ 8837

SccsID: @(#) README 1.12 92/11/02 08:43:42

Widget Creation Library Version 2.03 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 which many programs
need.

See README20 for general information about Wcl version 2, and README22
for additional features introduced in Wcl version 2.2 and version 2.1.

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

Resource File Loading   - Resource files named on the command line and
                          with wclResFiles resources are now loaded using
                          a more useful file search algorithm.  See below.
Late Binding            - All callbacks bound with Wcl are now late-bound.
                          This means the application can change the string
                          to callback mapping at any time, and from then
                          on, the new callback procedure will be called.
                          This also means that callbacks do NOT need to
                          be registered before widgets which will invoke the
                          callback are created.  The callback should still
                          be registered before being invoked, of course.
WcAddLateBinderHook,
WcRemoveLateBinderHook  - **Experimental External Interfaces to WcLateBinder**
                          is now provided, intended for use by people building
                          interpretive environments which use Wcl for the UI,
                          and some interpretor (like perl) for the callbacks.
                          See WcCreateP.h and WcLateBind.c for information.
WcInitialSizeIsMinimum  - a creation time callback, very useful for shells.
WcFullNameToWidget      - Enhanced to find direct descendents of the reference
                          widget, and optionally uses slower but tighter name
                          scoping algorithm of Xaw string-to-widget converter.
                          New relative naming operator `/' which means "the
                          nearest shell ancestor which is known to the window
                          manager."  The operator `~' remains "the nearest
                          shell ancestor."  Therefore, it is now easy to find
                          the top level shell from nested menus by using `/'.
WcCvtStringToWidgetList - A useful converter.

Bug Fixes
---------
MapAg.c                 - Free method now set properly for dynamically created
                          mapping agents.
MapAg.h, WcCreate*h     - now wrapped by #ifdef __cplusplus { }
XtVa...                 - no longer used, so everything ports to X11R3
#ifdef sun              - why don't they just use X from mit!?!
WcHomeDirectory         - Now can handle case where user has no home dir.
WcGetResourceType       - no longer dumps core if no parent widget.
-rf on command line     - There is now no problem with loading additional
                          resource files when -rf was used to load the
                          initial file.
Wcl Lib Resources       - These resources are now ALWAYS fetched after all
                          resource files have been loaded.

Seemingly Unfixable Bug
-----------------------

realizeCallback, destroyCallback, popupCallback, and popdownCallback
MUST NOT be specified using resource values for shell widgets derived
from Motif Vendor Shell in most releases of Motif.  Sorry, there is no
way I can see for Wcl to work around this bug in the list of resources
fetched by the Motif Vendor Shell Extension VendorExtInitialize()
procedure.

If you want to specify these resources, specifiy a wcCallback resource
and add the callbacks using WcAddCallbacks().

Explanation for Xt and Motif gurus with source code: Xt has fetched
these resources for the shell, and compiled the XtCallbackRec array
generated by WcCvtStringToCallback into the
InternalCallbackRec/XtCallbackRec "thang."  This happens in
Xt'Create.c'_XtCreate in R5.  _XtCreate then allows the widget to
initialize itself, calling CallInitialize().  This eventually invokes
the Motif Vendor Shell initialization, which invokes the Motif Vendor
Shell Extension initialization.  Here, Motif incorrectly fetches again
the above callback resources, applying the resources straight into the
"new" widget with its already compiled callback lists.  This causes the
compiled callback list storage to be overwritten with the original,
uncompiled form previously generated by WcCvtStringToCallback.  The
next XtAddCallback or XtCallAllCallbacks or XtSetValues on these
resources will (or should!) fail due to mis-interpreting the callback
list (the first element will again be an XtCallbackRec instead of an
InternalCallbackRec).  The fix is messy:  somehow treat the callback
resources as uniquely as Xt does everywhere else: fetch into a
different (local) Widget instead of new, and then traverse the list of
callbacks, invoking XtAddCallback( new, <callbackName>, cb->callback,
cb->closure ), and then free up that locally allocated dummy widget.
Yuck!

New Resources Used by Wcl 2.03
------------------------------

Wcl fetches three different groups of resources from the Xrm resource
database:  Library Wide resources, Pre-Creation widget instance
resources, and Post-Creation widget instance resources.  Each of these
groups are discussed below.


Library Wide Resources
----------------------

These resources are fetched once when the Wcl library is initialized
(before any widgets are created by Wcl).  They provide attributes for
Wcl, and control some of the behavior of Wcl.

   wclInitResFile:              This is a resource which is ONLY set
                                by the command line switch "-rf".  You
                                should never need to use this resource
                                in any direct fashion.  It simply allows
                                the "-rf" option to never collide with
                                wcResFiles specifications in resource files.

   wclTraceResFiles:            Traces to stderr the files loaded by Wcl.
                                This does NOT trace files loaded by Xt or
                                Xrm during XtInitialize.  By default, this
                                is False.  Can be set True by the new command
                                line flag `-trrf'
                                

   wclSlowTightNames:           Boolean, "True" or "False".
                                Default is "False".  


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

Major changes to the geometry management algorithm have been made to
eliminate a "shudder" which one would see when children requested
resizing, especially with nested XmpTables and XmScrolledWindows.
Resizing is faster as well as being better.

Build Instructions
------------------

See README_BUILD for detailed instructions on how to build the
distribution.

If you are using imake, you MUST look at Wc.tmpl and make the necessary
edits.  The distribution provides several versions of this file,
probably NONE are exactly what you need:

 Wc.tmpl        My machine, an IPX with X11R5 patch level 12, Motif 1.1.0
                with HUNDREDS of fixes, OpenLook widgets, and debugged Xt 
                library with memory tracing enabled and file tracing hacks.

 Wc.tmpl.irix   Should work as-is on Irix (Silicon Graphics) machines with
                SGI X (R4) and Motif installations.


If you are using make, you MUST look at WcMake1.tmpl and WcMake2.tmpl.
Again, a couple of different versions of these files are provided, but
you almost certainly must do something to make it build on your
platform.

 WcMake1.tmpl   These work on my machine
 WcMake2.tmpl

 WcMake1.svr4   These work on SVR4 machines with X11R4 and Motif 1.1.
 WcMake2.svr4

 WcMake1.sco    These work on SCO Open Desk Top machines.  Whew!  Also,
 WcMake2.sco    installable man pages (*S.z, *C.z) are now provided.

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