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