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