Usenet 1994 October

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / x / volume10 / wcl / part01 next >

Wrap

Internet Message Format | 1990-12-17 | 58KB

Path: uunet!cs.utexas.edu!sun-barr!newstop!exodus!jpl-devvax.jpl.nasa.gov From: david@jpl-devvax.jpl.nasa.gov (David E. Smyth) Newsgroups: comp.sources.x Subject: v10i049: wcl -- widget creation library, Part01/11 Message-ID: <4676@exodus.Eng.Sun.COM> Date: 18 Dec 90 02:02:07 GMT Sender: news@exodus.Eng.Sun.COM Lines: 1443 Approved: argv@sun.com Submitted-by: david@jpl-devvax.jpl.nasa.gov (David E. Smyth) Posting-number: Volume 10, Issue 49 Archive-name: wcl/part01 the README is below... # to unbundle, "sh" this file -- DO NOT use csh # SHAR archive format. Archive created Fri Oct 19 09:31:54 PDT 1990 echo x - 0thREADME sed 's/^X//' > 0thREADME <<'+FUNKY+STUFF+' XNext Projected Release Date: 1 Dec 1990. Send in Xyour comments, bug reports, and enhancement requests! X X XWidget Creation Library Release 1.04 (Patch Level 4) X==================================================== X XThis release still has NOT been extensively tested with Motif 1.1.1 XI did not want to wait any longer... There are a few bugs: If you Xrun the Periodic example, and resize the window using your window Xmanager, you will see one bug. If you run the multi-display demo Xusing Motif widgets, you'll see another (SEGV deep in Xt after Xa display connection has been closed and another is being opened). X XSince these bugs are seemingly completely unrelated to the Widget XCreation Library itself, I figured this release could go out. There Xare many things which are fixed and made alot better. X XEnhancements: X------------- X Xo Imakefile and makefile seem to be alot better now. There will be X some edits required to support Motif 1.1, these are indicated in X comments. It is quite easy now. X Xo Added WcMapACT, WcMapCB, WcUnmapACT, and WcUnmapCB. X Xo CvtStringToCallback() now uses the default client data which can X be registered with WcRegisterCallback(). In previous versions, this X data was registered, but thereafter always ignored. X X In this version, the client data is returned when no argument is X specified and client data is not NULL. If client data is NULL (by X far the most common case) then a NULL string ("") is returned when X no arguments are given in the resource file. X X NOTE that this means the client data is exactly the same as earlier X versions if the callback was registered with NULL client data. The X behavior is different (correct) when default client data has been X registered with the callback - now the callback gets the client data X if the resource database DOES NOT specify any client data. If the X resource database DOES specify client data, then that client data X gets passed to the callback as a null terminated string. X Xo Richard Hesketh (rlh2@ukc.ac.uk) found something missing in X WcFullNameToWidget: The function will now resolve the following X as expected: w = WcFullNameToWidget(ref_w, ".aChild"); X Xo Andrew Peebles (peebles@mips.com) also found something missing X in WcFullNameToWidget: The function will now resolve widget X names when the name starts in a completely different widget tree. X While providing this capability, the function was also optimized X for speed at the expense of a few additional lines of code. X Xo Also, Peeb noticed that WcPopupCB did not do what was intended, X (non-modal popups) so the grab kind has been changed from X XtGrabNonexclusive to XtGrabNone. X Xo A minor optimization was made in the recursive creation loop: X The parent's name is now only determined when a warning X message is to be generated, rather than every time. A typical X space-time tradeoff, changed to improve performance at a minor X increase in line count. X Xo The conditional compilation flags for old versions of Xt X used by Motif 1.0 has been changed from `#ifdef MOTIF' to X a more precise scheme where both major and minor version of X Motif is used. X Xo The conditional compilation flag MOTIF is still used in X special cases: X - the example program MD.c uses it to determine which widget X set gets registered, X - WcConvert.c provides a Motif specific converter X `CvtStringToMenuWidget' X - and WcCreateP.h uses it in concert with the DEBUG compilation X flag to include all Motif include files so that a debugger can X print the members of the Motif widgets. Not necessary, just a X programmer convenience. X XFixes: X------ X Xo Carl Witty (cwitty@cs.stanford.edu) discovered an obscure X bug in the XtIsShell macro definition which was causing grief. X Xo Some memory leaks were found and corrected: XtTblParseLayout(), X WcSetValuesCB() which was also made faster. X Xo A non-initialized return value in MatchWildChildren was fixed X (this fixes a bug which was in code borrowed from Xt). X Xo An implementation of strstr is provided for systems which do not X have ANSI C libraries. X Xo Gadgets are now detected using standard Xt functions rather X than Motif specific functions. X X XWidget Creation Library Release 1.03 (Patch Level 3) X==================================================== X XFixes: X------ X Xo Some memory leaks were found and corrected. X Xo Some unnessesary variables were removed. X Xo Root widgets are now deleted properly. X Xo Documented WcSystemCB() in the *README files. X Xo Trailing whitespace is now stripped in WcSetValueCB. X Xo WcSetValueCB now correctly checks to see the required type X of the resource being set, and performs conversions accordingly. X In previous versions, any time the value was `this' it would X be converted to the widget getting the callback. X Xo CvtStringToCallback was fixed so it handles multiple callback X functions correctly. Callback specifications which ended with two X consecutive closed parenthesis were mishandled. X Xo CvtStringToMenuWidget could cause core dumps in previous versions. X It now gives warning messages in such situations, and provides X a message for other misuses. X Xo WcCreateDatabaseChild now does a more accurate job of tracing names. X X@ Now, children created by Motif Constructors are handled MUCH better. X You will no longer get those stupid warnings from Xt saying: X "Not all widgets in XtManageChildren have the same parent" X Xo The message "No children defined in Xrm database" now provides X a useful suggestion as to what is probably wrong. X Xo Both constraint and widget resources can now be set via X WcSetValueFromString. X Xo An obscure bug in Table was fixed which caused divide-by-zero X errors with incorrect resource specifications. X XEnhancements: X------------- X Xo More and better examples. X Xo An additional Wc resource which allows the description of a widget and X its children to be in another resource file. My resource files were X getting too darn big. This allows separate resource files to describe X parts of the widget heirarchy. Of course, since everything is loaded X into the same Xrm database, you can reference widgets in other resource X files. In a sense, all widgets are "global." X Xo WcLoadResourceFileCB no longer messes with its incoming arguments, X and it keeps track of the resource files which have been loaded X so they are not loaded multiple times. X Xo Widget names passed to callback functions now support relative naming. X The special name `this' meaning the widget getting the callback is X still supported. Additional special characters `^' which means X the parent, and `~' which means the shell ancestor are now also X provided. X Xo A new registration routine has been added: WcRegisterAction. This X is basically a wrapper around XtAppAddActions(), which should still X be used if you are registering several actions. X Xo WcRegisterWcActions now uses the XtAppContext argument which is X passed to all the WcRegister* routines. In all others, the X XtAppContext argument continues to be ignored. X Xo All Xt widgets are now registered: Object, RectObject, Core, Composite, X Constraint, ApplicationShell, OverrideShell, Shell, TopLevelShell, X TransientShell, VendorShell, and WmShell. X Xo In order to facilitate using the Widget Creation Library within an X interactive and possibly interpretive user interface builder, it is now X possible to override the registrations of class pointers, class names, X constructors, and (probably most importantly) callbacks. By default, X the registration routines WcRegisterClassPtr, WcRegisterCallback, etc., X ignore attempts at re-registration. If WcAllowDuplicateRegistration X is called, then all the routines will allow re-registration. X X Re-registration over-writes existing registrations of the same name. X For completeness, the following new routines are provided: X WcAllowDuplicateRegistration(), WcAllowDuplicateClassPtrReg(), X WcAllowDuplicateClassNameReg(), WcAllowDuplicateConstructorReg(), X WcAllowDuplicateCallbackReg(), so the client may choose which X registration routines honor duplicate registration requests. X XWhat was NOT Done X----------------- X Xo The version of Table provided with this distribution is NOT X the same as that provided by Nazgul@alphalpha.com (Kee Hinckley). X Why? His is fully Motif-ized, including changing it so it is X a subclass of a Motif manager widget, has specific behaviors X to make up for obscure Motif widget mis-behaviors, and it uses X Motif specific functions. X X Kee has done good work: if you want a more Motif-ized version of X Table, send him mail, he will send it to you. The version of X Table provided herein refuses to work with Gadgets, and does not X work properly with XmText widgets due to an apparent bug in X XmText geometry handshaking. X Xo The libraries built do NOT include the MriRegAll.o nor AriRegAll.o X object files. I am considering including them next time. SEND X ME YOUR VOTES on if you think this is a good idea. X X The problem is that including them into the library would mean the X library could not be built _consistently_ unless BOTH widget sets are X available. This sometimes is not the case. I would rather keep X Wc strictly Xt Intrinsics dependent, and not widget set dependent. X X Also, I think that over time more and more widgets will be available X over the net, and so a given user, team, or site may want to register X more or different widgets. X Xo The resource file loading due to wcResFile resources and due to X invocations of the WcLoadResourceFileCB standard callback still X do not perform file name searches which conform to the X11R4 Xt X manual. This will be fixed in a release of Wc which follows the X wide availability of Motif 1.1, probably in about October 1990. X X XWidget Creation Library Release 1.02 (Patch Level 2) X==================================================== X XFixes: X------ X Xo A missing argument in a missing argument error message 8-} X Xo Extra tokens after #endif's are removed. X Xo File names shortened, and fixed in comments to match perfectly the file X names. X XEnhancements: X------------- X XWidget Creation Library Release 1.01 (Patch Level 1) X==================================================== X XFixes: X------ X Xo This version is reported to work with Motif 1.1 X Xo The Table widget has been fixed so it does not grow when column spacing X is non-zero and the table or the table's children are resized. X Xo A couple of bugs were discovered and fixed. X XEnhancements: X------------- X Xo There is an Imakefile. The makefile builds a Makefile using this X Imakefile. X Xo There are action functions provided for all the Wc standard callbacks. X Actions are more powerful than callbacks in the ways they can be X attached to widgets. X Xo There is another example program with resource file which demonstrates X the use of actions. X Xo The example resource files were changed so all have mechanisms to quit, X usually a quit button. X Xo There is a test program which executes all the programs within the X standard distribution, using all of the resource files. +FUNKY+STUFF+ echo '-rw-r--r-- 1 david 11240 Oct 18 17:15 0thREADME (as sent)' chmod u=rw,g=r,o=r 0thREADME ls -l 0thREADME echo x - 1stREADME sed 's/^X//' > 1stREADME <<'+FUNKY+STUFF+' X Widget Creation Library, X Motif Resource Interpreter, X Athena Resource Interpreter: X X An Easier Way to Develop Applications X using Motif and Athena Widgets. X XWindow-based applications are notoriously difficult to program. When Xthe Macintosh was introduced in early 1984, Bill Gates projected that X50% of Microsoft revenues would come from Mac application by October X1984. In reality, the first Mac applications were only beginning to be Xshipped by that date. X XWhen Steve Jobs left Apple and developed the NeXT computer, the window Xenvironment was specifically designed to support a WYSIWYG interface Xbuilder. NextStep and the NeXT IB were the results of this effort. X XThe X developers at MIT and DEC also needed an easy way to develop Xwindowed applications. Instead of developing a WYSIWYG tool like NeXT, Xthey developed a toolkit where interfaces were specified using C code, Xand could be significantly modified via `resource files' using a Xminimum number of attribute specifications. They provided an instance Xattribute inheritance mechanism to propogate attributes throughout an Xinterface. This allows such simple specification as the following to Xalter every font in an interface: X X *font: 9x15 X XThe toolkit is called the Xt Intrinsics. The windows, buttons, menus, Xscrollbars, etc., are called Widgets. The Athena Widgets are one set Xof user interface objects built upon the Xt Intrinsics. Motif is Xanother set of widgets. X XAs time went on, developers of widget-based applications found the Xresource files to be more and more useful. For the fourth release of Xthe X11 window system, many of the example programs evolved to the Xpoint that only the raw behavior of the applications were specified in XC, with most of the look and feel being specified using resource files. X XAt the fourth annual X Technical Conference, several people pointed Xout that resource files could be used to specify everything about Xa widget based user interface, except the actual "tree" of widgets, Xtheir types, and bindings of behaviors to the user interface widgets. XCould the resource mechanism be enhanced to allow these to be specified Xas well? X XMartin Brunecky at Auto-Trol in Denver Colorado took up the challenge, Xand posted a simple set of routines which he called WsXc, for "Window XSystem: Xrm Creation." X XXrm stands for X Resource Manager, which is a heirarchical database for Xkeeping arbitrary named data related to X window interfaces. The Xt XIntrinsics use Xrm for widget resources. The basic idea of WsXc is Xto search the Xrm database, starting at the root, and pull out resources Xwhich describe the widget heirarchy and bindings to callback functions. X XOver the next several months, WsXc was repackaged as Mri (Motif XResource Interpreter), and then Ari (Athena Resource Interpreter), and Xfinally generalized into the Widget Creation Library. The result provides Xseveral significant benefits to the developer and the user: X X o Rapid Prototyping: Arbitrarily complex widget interfaces X may be specified, and many common behaviors (pop-up, X change attributes, exit) can be specified for the X interface. X X o Prototyping Environment is the Development Environment is X the Delivery Environment: There is no specific breaking X point between prototyping, developing, and tuning a X delivered program. X X o Minimum Specifications: The Xrm and Xt Intrinsics instance X attribute inheritance mechanism is fully utilized, so X a minimum number of specifications can describe a X complete user interface. X X o Extensible: Adding new widget types and callback routines X is trivial. X X o Widget Set Independent: The C code which provides the X behavior of the application can frequently be X written in a widget set independent manner. This X allows an application to be written which supports X multiple look-and-feel definitions: Motif, OpenLook, X and Athena interfaces can all be front-ends to the X same underlying application. X X o The user can make any change to the interface: Deeply nested X menus can be substituted for dialog boxes, or vice versa. X Any label or image can be altered, which supports inter- X nationalization. X X XThe Widget Creation Library Distribution X---------------------------------------- X XThe Widget Creation Library is a cleanup and enhancement of Martin XBrunecky's second posting of WsXc. X XThe emphasis of the cleanup was to provide a separation of functionality Xand declarations between source and include files, to make the naming Xconcise and unique, and to reduce the complexity of the interface between Xthe library and the application (it was pretty darn good already). X XThe emphasis of the enhancements were to add clear(er) warning and Xerror messages, add more utility callbacks, and to provide a few simple Xfunctions which make writing callbacks and converters a little easier. X XOne of the guiding principles was and is KISS. This is intended to Xbe a very small library which provides very big gains in productivity Xfor programmers developing applications using the various widget Xsets based on the Xt Intrinsics. A large number of the total lines Xof code provide error messages. The rest is quite straight forward. X XThis directory contains files which make up libWc, the Widget Creation XLibrary, Ari, the Athena Resource Interpreter, and Mri, the Motif XResource Interpreter. X XAuthors X------- X XMartin Brunecky at Auto-trol Technology, Denver (marbru@auto-trol.UUCP) Xwrote the initial code and posted it to comp.windows.x with the title XPOOR MAN's UIL - WsXc. X XDavid Harrison of the UC Berkeley Electronics Research Lab X(davidh@ic.Berkeley.EDU or ...!ucbvax!ucbcad!davidh) wrote a very Xuseful Table widget. It is so good I've included it with this Xdistribution. It is separately available from archive sites. See XTableHEARYE and TableFIRST for information on this widget. I made very Xminor edits to make it work with Motif, and I fixed exactly one minor Xbug. X XRod Whitby of Austek Microsystems Pty. Ltd. in Adelaide, Australia X(rwhitby@adl.austek.oz.au) wrote the WcRegXt.c file, and caught Xseveral bugs. X XThe rest was done by me, and here is my standard .sig: X X------------------------------------------------------------------------- XDavid Smyth david@jpl-devvax.jpl.nasa.gov XSenior Software Engineer, seismo!cit-vax!jpl-devvax!david XX and Object Guru. (818)393-0983 XJet Propulsion Lab, M/S 230-103, 4800 Oak Grove Drive, Pasadena, CA 91109 X------------------------------------------------------------------------- X XMany people helped alot by providing bug fixes, enhancements, suggestions, Xand just plain feedback. There are many who helped, including Andrew Peebles Xat MIPS, Randy Brown, Art Poley, Mike Yee of OSF, Richard Hesketh, and Xour own Kaleb Keithley. X X XREADME Files and Documentation X------------------------------ X XThe *README files provide minimal documentation. I think you will Xfind the comments in the source files useful. Also, several Xexample resource files are provided with extensive comments. X XA paper which I presented at the European X User's Group meeting Xin Guildford, Surrey, UK in September 1990 is available in Postscript Xform. The paper can be considered a reference or programmer's manual. XSlides from that talk are likewise available, also in Postscript. The Xslides provide several examples. X XMakefiles X--------- X XAn Imakefile and a makefile are provided. As provided, they build on Xour Sun and VAX machines which are still using Motif 1.0. Commented Xout lines are provided which work on Suns using Motif 1.1.1. There are Xcomments at the beginning of the Imakefile and makefile which point out Xthe lines which you may have to change. In order to avoid phase Xerrors, I'll add no details here. See the Imakefile and makefile! X XBuilding The Distribution using Imake X------------------------------------- X XIf you have Imake, you can build the distribution very simply. X X % make Makefile X XYou may then build the delivery using this Makefile: X X % make X XOtherwise... X------------ X XOtherwise, you may have to edit the makefile to reflect your site's Xconfiguration. You may notice that the makefile and the Imakefile Xare very similar, and the same types of edits will probably need to Xbe made to both. X XThe easiest thing to do is simply this: X X % make X Xwhich causes all the libraries and executables to be built. X XTesting The Distribution X------------------------ X XI have included a simple test csh script which executes all of the Xexample programs. After you build, the test program will execute Xwhich ever or the executable targets it finds. Just do the following: X X % test X XWidget Creation Library X----------------------- X XThe makefiles build two versions of the library: one which works Xwith the Athena widgets, and one which works with the Motif widgets. XThere really should be no difference between the two libraries, Xespecially after Motif 1.1 is widely used. X XMri and Ari Widget Resource Interpreters X---------------------------------------- X XThere are also two "interpreters" which allow widget based user Xinterfaces to be developed and to have a few useful behaviors. These Xinterpreters are intended to be useful for prototyping. X XAri is the Athena Resource Interpreter, and it knows about all the XAthena widgets. Mri is the Motif Resource Interpreter, and is knows Xabout all the Motif widgets. Both interpreters also know about the Xvery useful Table widget, which is described in the files Table*. X XEach interpreter consists of a main() procedure, and a function which Xregisters all the known widget types. Mri consists of Mri.c and XMriRegAll.c while Ari consists of Ari.c and AriRegAll.c. The Xregistration files are intended to be independent. X XIt should be a simple task to build a single interpreter which knows Xabout every widget on earth, but if you don't have shared libs, the Xresulting executable is HUGE. X XSeveral resource files are provided for each of the interpreters. They Xare named A<nn>.<description> and M<nn>.<description>. To try Xout the interpreters (after you build them), do the following: X X % alias se setenv XENVIRONMENT X % se A08.ClkLogo X % Ari X % se M7.Periodic X % Mri X XThe resource files are intended to be tutorials, so they are heavily Xcommented and they explore various topics you may find interesting. X XOnce an interface is prototyped using Mri or Ari, one can take the XMri or Ari source files and makefiles and evolve them into applications. X XSample Applications X------------------- X XThe program App is exactly one such example application. The Xfiles Ari.c and mk_Ari were gradually modified as additional Xbehaviors were defined, registered with the Wc library, and bound Xto the appropriate widgets within the App01.All resource file. X XIf you look at App.c, you will notice that main() is very minimal. XThe application is really defined by its resource file (the look Xand feel) and the callbacks (the behavior). Notice that the Xcallbacks use several routines provided by the Wc library. They Xwill be introduced in another README file. X XAfter you build App, you can try it out as follows: X X % se App01.All X % App X XAnother sample application included with the distribution is MD, which Xis built as two versions: MDathena and MDmotif. The Motif version Xcurrently does not work very well due buggy interactions between Motif Xand the Intrinsics. This application demonstrates how a single Xapplication can support multiple display connections with multiple Xwidget heirarchies. These may be executed like this: X X % se MD X % MDathena X % MDmotif X +FUNKY+STUFF+ echo '-rw-r--r-- 1 david 11948 Oct 18 17:25 1stREADME (as sent)' chmod u=rw,g=r,o=r 1stREADME ls -l 1stREADME echo x - 2ndREADME sed 's/^X//' > 2ndREADME <<'+FUNKY+STUFF+' XWhat Every Application Needs X---------------------------- X XAll applications should include the public header file, should Xcreate the application shell, and should call WcCreateWidgets(). XThey should also include an external decl for either MriRegisterMotif Xor AriRegisterAthena(), depending on the widget set desired. X XHere is an absolute minimal Motif based application: X X/*************************** Cut Here ***************************/ X#include <Xm/Xm.h> X#include <WcCreate.h> X Xextern void MriRegisterMotif(); X Xmain( argc, argv ) X int argc; X char* argv[]; X{ X XtAppContext app; X Widget appShell; X X appShell = XtInitialize( "app", "App", NULL, 0, &argc, argv); X X app = XtWidgetToApplicationContext(appShell); X X MriRegisterMotif ( app ); X X WcWidgetCreation ( appShell ); X X XtRealizeWidget ( appShell ); X XtMainLoop ( ); X} X X/********************** That's all, folks! **********************/ X XA minimal Athena application differs slightly due to the different Xinclude files and the different widget registration routine: X X/*************************** Cut Here ***************************/ X#include <X11/Intrinsic.h> X#include <WcCreate.h> X Xextern void AriRegisterAthena(); X Xmain( argc, argv ) X int argc; X char* argv[]; X{ X XtAppContext app; X Widget appShell; X X appShell = XtInitialize( "app", "App", NULL, 0, &argc, argv); X X app = XtWidgetToApplicationContext(appShell); X X AriRegisterAthena ( app ); X X WcWidgetCreation ( appShell ); X X XtRealizeWidget ( appShell ); X XtMainLoop ( ); X} X/********************** That's all, folks! **********************/ X X XAs you can see, every application needs as a minimum to invoke either XMriRegisterMotif() or AriRegisterAthena(), and WcWidgetCreation(). +FUNKY+STUFF+ echo '-rw-r--r-- 1 david 1751 Aug 6 09:36 2ndREADME (as sent)' chmod u=rw,g=r,o=r 2ndREADME ls -l 2ndREADME echo x - 3rdREADME sed 's/^X//' > 3rdREADME <<'+FUNKY+STUFF+' XWidget Creation Resources X------------------------- X XThe Widget Creation Library allows user interfaces to be completely Xdefined within a resource file: the widget heirarchy, widget types, and Xbindings of widget callback lists and translations to application Xfunctions are specified in the resource file using Wc* resources. X XThe following is the complete set of resources which are Xinterpreted by the Widget Creation Library: X X ...widget.wcResFile: resourceFileName X ...widget.wcClass: classPointerName X ...widget.wcClassName: className X ...widget.wcConstructor: constructorFunctionName X ...widget.wcTrace: true/false (default = false) X ...widget.wcCallback: callback1(args), callback2(args), ... X ...widget.wcChildren: childName1, childName2, ... X ...widget.wcManaged: true/false (default = true) X ...widget.wcDeferred: true/false (default = false) X XIn all cases, the Widget Creation resource names can be specified as XWc<name> or wc<name>, with the capitalized form having looser binding X(representing the resource class). X XWcResFile Resource X------------------ X XThis resource allows you to put additional resource specifications Xrelated to a widget or its children in a separate file. Like all Xwidget creation resources, the WcResFile resource value is retrieved Xfrom the Xrm database at widget creation time. X XBefore the widget is created, the specified resource file is loaded Xinto the Xrm database, and then another query of the Xrm database is Xmade to obtain the other Wc resources. Therefore, all wc resources X(except of course the WcResFile resource) and other widget resources Xmay be specified in the new resource file. X XNOTE: XThe file search list rule used by WcResFile is a gross simplification Xof the R3 resource file search mechanism, without the $LANG provision. XSoon the R4 search algorithm will be used. The current version only Xlooks into two directories, which may be defined as environmental Xvariables: X X XAPPLRESDIR - defaults to "/usr/lib/X11/app-defaults/" X XUSERRESDIR - defaults to HOME directory X XWcClass, WcClassName, and WcConstructor Resources X------------------------------------------------- X XThese resources allow you to specify the type of the widget. Only one Xof these resources should be specified for each widget. If multiple Xspecifications are made, a warning will be given via XtWarning (the Xmessage prints on stderr). A WcClass specification overrides a XWcClassName specification which overrides a WcConstructor Xspecification. X XWcTrace Resource X---------------- X XThis resource is useful for debugging your user interface. When `True' Xthe full name and class name of the widget is printed to stderr right Xafter the widget is created. X XWcCallback Resource X------------------- X XThis resource allows you to specify a list of callback functions Xwhich are invoked after the widget is created, and before it is Xmanaged. The callback functions receive the newly created widget as Xtheir widget argument, and whatever is within the parenthesis following Xthe callback function name as a string argument as client data. For Xexample: X X *foo.wcCallback: FooSpecialCB( Hi there ) X XThis specification will cause the function `FooSpecialCB' to be Xcalled. The widget argument will be the newly created widget foo, and Xthe client_data argument will be the null terminated character array " XHi there ". The call_data is whatever was specified when the XFooSpecialCB callback function was registered with XWcRegisterCallback(). X XThis is generally how the interface can create related objects within Xthe application. For example, if your application has a storage Xobject, each widget which provides storage related behaviors or Xattribute displays might register themselves with your application's Xstorage object. X XWcChildren Resource X------------------- X XAfter a widget is created, but before it is managed, all of its Xchildren are created (and by default, managed). The names of children Xwidgets are specified by the WcChildren resource. The order of the Xnames in the resource value indicate the left-to-right order of Xwidget creation. The names of the widgets in the example below Ximply the order of creation: X X *foo.wcChildren: ONE, TWO, THREE X XSince each widget creation is recursive, the widgets are created depth Xfirst. I.e., the widget `ONE' and all of ONE's children will be Xcreated before widget `TWO' will be created. X XWcManaged Resource X------------------ X XThis resource allows you to specify that a widget should not be managed Xfollowing its creation. By default, widgets are managed together with Xtheir siblings after all siblings are created. Wc uses a single call Xto XtManageChildren when possible. X XObsolete Widget Creation Resources X---------------------------------- X XThe wcDeferred resource is maintained only for compatibility. It Xis never needed, and can simply be deleted from your existing resource Xfiles, along with the appearance of the widget's name from any XwcChildren list. I.e., if you have the following: X X *foobar.wcChildren: one, two, three, four X ... X *two.wcDeferred: true X XSimply drop `two' from the list of children of `foobar' and remove Xthe `*two.wcDeferred: true' line from your resource file. Widgets Xwhich are created dynamically have their parentage specified at Xcreation time, generally via WcCreateCB as follows: X X WcCreateChildrenCB( foobar, two ) X XSupport for wcDeferred resources will be removed in the near future, Xso try to purge their use. X X XHow the Application Interacts with the Widget Creation Library X-------------------------------------------------------------- X XThe typical Wc client application (including Ari and Mri) will create Xan application shell and load the Xrm database by calling XXtInitialize(). It will then register widgets, callbacks, and actions Xwith the Wc library, and then pass the application shell to the XWcWidgetCreation() function. This function returns when the entire Xconnected widget heirarchy specified in the Xrm database is created. XThe widget tree is realized, and then the XtMainLoop is entered. XBriefly: X X appShell = XtInitialize( ... ); X X /* Register widgets, callbacks, and actions */ X X WcWidgetCreation( appShell ); X XtRealizeWidget( appShell ); X XtMainLoop(); X XWhen Resources are Loaded Into the Xrm Database X----------------------------------------------- X XXtInitialize loads an initial set of resource files into the resource Xdatabase before any widgets are created. This initial database may Xcontain references to other resource files by way of WcResFile resource Xspecifications. If a widget `Foo' has a resource specification like Xthis: X X *Foo.wcResFile: FooResources X Xthen the resource file named FooResources will be merged into the Xresource database before the widget Foo is created. In fact, several Xfiles named FooResources may be loaded, as the standard Xt resource Xfile search and load is performed. See section 2.2 and 11.11 of the XX11R4 Xt Intrinsics - C Language Interface manual for more Xinformation. X XNOTE: XThe file search list rule used by this version of Wc is a gross Xsimplification of the R3 resource file search mechanism, without the X$LANG provision. Soon the R4 search algorithm will be used. The Xcurrent version only looks into two directories, which may be defined Xas environmental variables: X X XAPPLRESDIR - defaults to "/usr/lib/X11/app-defaults/" X XUSERRESDIR - defaults to HOME directory X X XWhen Resources are Retrieved from the Xrm Database X-------------------------------------------------- X XResources are retrieved from the Xrm resource database when widgets are Xcreated. If the resource database changes after widget `Foo' is Xcreated, subsequent changes to the database will have absolutely no Xeffect upon widget `Foo.' X XHow Widgets Are Created from the Xrm Database X--------------------------------------------- X XThe Widget Creation Library starts creating widgets when the XWcWidgetCreation() function is called. Here is the recursive Xscenario. The initial widget is usually the application shell: X X 1. Fetch the wcChildren resource from Xrm database for the X initial widget. This will be a list of widget names. X X 2. For each child: X X 3. Fetch the set of Wc resources. X X 3a. If wcResFile is specified, load that resource file and X fetch the Wc resources again. X X 3b. Using the wcClass, wcClassName, or wcConstructor resource, X create the new child widget. Widget creation uses other X resources defined in the Xrm database specific to the type X of the widget, such as labelString for XmLabels. X X 3c. If wcCallback resource is defined (specifying a list of X callback functions), invoke each callback in order. X X 3d. If wcTrace is True, then dump the name of the just created X widget to stdout. X X 3e. If wcManaged is True (the default), then this widget will be X managed along with all of its siblings, after they are all X created (a single call to XtManageChildren is invoked by Wc). X X 3f. If the newly created widget has wcChildren specified, then X recursively invoke step (2.) above. Note that this X implements a depth first creation policy, which is generally X optimal for widget trees with manager widget nodes. X X XThe resource files themselves have no explicit flow of control Xmechanisms. However, the order of events during widget creation causes Xthe resources to be evaluated in a deterministic and sometimes Xrepetitive pattern. X XThe most significant control over resource evaluation is the order that Xwidgets are created. Widget creation is ordered by the order of widget Xnames in wcChildren resource lists. The names of widgets in the Xexample below reflects the order these widgets will be created. The Xorder of the resource specifications themselves are irrelevent to the Xorder of creation: X X Mri.wcChildren: one, four X Mri.one.wcClassName: XmRowColumn X Mri.one.wcChildren: two, three X Mri.one.two.wcClassName: XmLabel X Mri.one.three.wcClassName: XmPushButton X Mri.four.wcConstructor: XmCreateWorkingDialog X XWidgets can also be created after the initial widget tree. For example, Xhelp dialogs may be dynamically created only when necessary, so an Xexperienced user does not need to suffer the additional start-up time Xof creating a large number of widgets which are not needed, nor is Xmemory or swap space consumed by the unnecessary widgets. X XHere are resources which demonstrate how a help dialog could be created Xdue to a button press. In this case, the newly created widget will Xbecome a child of the application shell (Mri if the resource file is Xbeing interpreted by Mri). The resources for the help dialog are Xsegregated into another set of resource files which are named X`HelpDialogResources.' The standard Xt resource file search path is Xused, so /usr/lib/X11/app-defaults/HelpDialogResources, ..., X~/apps-defaults/HelpDialogResources, may be loaded into the Xrm Xdatabase due to this one WcResFile specification: X X /* in initial resource file: */ X *helpButton.activateCallback: WcCreateChildrenCB( Mri, helpDialog ) X *helpDialog.wcResFile: HelpDialogResources X X /* in HelpDialogResources: */ X *helpDialog.wcConstructor: XmCreateMessageDialog X *helpDialog.messageLabel: Some help message... X *helpDialog.okCallback: WcDestroyCB( this ) X XFrequently, you probably want such dialogs to remain once they are Xcreated. See the M5.Dialogs resource file for one way to do this. X XIn the above example, notice that the resources specified in the XHelpDialogResources file are unknown to the Xrm database until an Xattempt is made to create the helpDialog widget. +FUNKY+STUFF+ echo '-rw-r--r-- 1 david 11630 Aug 17 16:09 3rdREADME (as sent)' chmod u=rw,g=r,o=r 3rdREADME ls -l 3rdREADME echo x - 4thREADME sed 's/^X//' > 4thREADME <<'+FUNKY+STUFF+' XWidget Creation Library Standard Callbacks X------------------------------------------ X XThe standard Wc callbacks are intended to map closely to existing Xt Xfunctions. They simply provide XtCallbackProc wrappers to many Xcommonly used Xt functions. These wrapper procs perform argument Xparsing: e.g., converting strings to widgets using WcFullNameToWidget. X XBelow is a complete list of callbacks which are registered by Wc Xwhenever you call WcWidgetCreation. The "arguments" below are Xprototypes of what one puts in a resouce file. The terms mean: X X parent name of widget, full path or wildcarded. X child name of child starting from the parent widget. X widget see parent X resLHS <widget path name> X resRHS <any legal resource value> X X WcCreateChildrenCB ( parent, child [, child] ... ) X WcManageChildrenCB ( parent, child [, child] ... ) X WcUnmanageChildrenCB ( parent, child [, child] ... ) X X WcManageCB ( widget [, widget] ... ) X WcUnmanageCB ( widget [, widget] ... ) X WcDestroyCB ( widget [, widget] ... ) X WcSetSensitiveCB ( widget [, widget] ... ) X WcSetInsensitiveCB ( widget [, widget] ... ) X X WcPopupCB ( widget ) X WcPopupGrabCB ( widget ) X WcPopdownCB ( widget ) X WcMapCB ( widget ) X WcUnmapCB ( widget ) X X WcSetValueCB ( resLHS: resRHS ) X X WcLoadResourceFileCB ( filename ) X X WcSystemCB ( shell command line ) X WcTraceCB ( annotation ) X X WcExitCB ( exitValue ) X XSee the file WcCallb.c for the implementations of all of these standard Xcallbacks. These callbacks are registered together in the function XWcRegisterWcCallbacks() which is at the bottom of the same source Xfile. Clients of Wc do not have to invoke WcRegisterWcCallbacks() Xdirectly, as it is called from WcWidgetCreation() in the WcCreate.c Xsource file. X X XWidget Naming in Callback Arguments X----------------------------------- X XIn all of these callbacks, the function WcFullNameToWidget is invoked Xto convert a string to a widget. WcFullNameToWidget allows relative Xwidget naming, relative to the widget which invoked the callback. The Xspecial characters are presented in examples below: X X this means: `the widget which invoked this callback' X ^foobar means: `a sibling widget named foobar' X ~foobar means: `a child of the shell ancestor named foobar' X ~^foobar means: `a sibling of the shell ancestor named foobar' X XThe relative naming characters `^' and `~' are parsed left to right. X XIn addition, normal wildcarding works as expected - as long as the Xfinal name component is a widget instance, and not a widget class Xname. For example: X X *foobar X *Table*XmRowColumn*foobar X X XWcCreateChildrenCB( parent, child [, child] ... ) X------------------------------------------------- X XThis callback causes new widgets to be created. The name of the parent Xcan include wildcards, or can be a relative pathname from the widget Xinvoking the callback. The names of the children widgets must be Xsingle widget names, not pathnames. For example: X X *danger.callback: WcCreateChildrenCB( *Panel, EmergencyControls) X XIn this case, pressing a danger button creates a new tree of widgets Xproviding emergency controls. The new tree is rooted at the existing XPanel widget. X X XWcManageChildrenCB( parent, child [, child] ... ) X------------------------------------------------- X XThis callback manages multiple children of a single parent. It is a Xwrapper around XtManageChildren. As with WcCreateChildrenCB, the Xparent name can include wildcards, or can be a relative pathname from Xthe widget invoking the callback. The names of the children widgets Xmust be single widget names, not pathnames. For example: X X *new.activateCallback: WcManageChildrenCB( *foo, one, two, three ) X X XWcUnmanageChildrenCB( parent, child [, child] ... ) X--------------------------------------------------- X XIdentical to WcManageChildrenCB, except that the child widgets are Xunmanaged rather than managed via a call to XtUnmanageChildren. X X XWcManageCB( widget [, widget] ... ) X----------------------------------- X XThis callback takes a list of widget names, each of which Xcan be wildcarded and/or relative widget pathname. After Xthe widget ID is resolved via the WcFullNameToWidget function, Xthe widgets are managed using XtManageChild(). X X XWcUnmanageCB( widget [, widget] ... ) X------------------------------------- X XThis callback is identical to WcManageCB, except that the Xwidgets are unmanaged using XtUnmanageChild(). X X XWcDestroyCB( widget [, widget] ... ) X------------------------------------ X XThis callback allows widgets to be destroyed using XtDestroyWidget(). X X XWcSetSensitiveCB( widget [, widget] ... ) X----------------------------------------- X XThis callback invokes XtSetSensitive( TRUE ) on each of the Xwidgets named by the argument. X X XWcSetInsensitiveCB( widget [, widget] ... ) X------------------------------------------- X XThis callback is identical to WcSetSensitiveCB, but the widgets Xare made insensitive. X X XWcPopupCB( widget ) X------------------- X XThis callback invokes XtPopup() with the XtGrabKind set to XXtGrabNonexclusive. The widget must be a pop-up shell widget. X X XWcPopupGrabCB( widget ) X----------------------- X XThis callback invokes XtPopup() with the XtGrabKind set to XXtGrabExclusive. The widget must be a pop-up shell widget. X X XWcPopdownCB( widget ) X--------------------- X XThis callback invokes XtPopdown(). The widget must be a pop-up shell Xwidget. X XWcMapCB( widget ) X--------------------- X XThis callback invokes XtMapWidget(). The widget must be a shell Xwidget. X XWcUnmapCB( widget ) X--------------------- X XThis callback invokes XtUnmapWidget(). The widget must be a shell Xwidget. X X XWcSetValueCB( resLHS: resRHS ) X------------------------------ X XWcSetValueCB maps very closely to XtSetValues(). An augmented resource Xfile syntax is accepted so you can cut and paste the arguments and Xnames. The widget path name can include wildcards, and it can also be Xa relative path from the invoking widget. Real examples: X X *push.activateCallback: WcSetValueCB( *push.activateCallback: WcExitCB(1) ), \ X WcSetValueCB( *push.labelString: Goodbye! ) X X *fileMenu.wcCallback: WcSetValueCB(*file.subMenuId: this) X X *Pink.armCallback: WcSetValueCB( ^^drawing.background: Pink ) X X XWcLoadResourceFileCB( filename ) X-------------------------------- X XThis callback loads specified resource file into application resource Xdatabase. It allows to load resources on as-needed basis, reducing the Xintitial resource file load overhead. The file to load is specified as Xclient data. The directory search for the file (should be) the same as Xfor application class resource file. X XTo prevent repeated loads of the same file, the callback keeps track of Xeach filename. Note that I do not allow a file to be re-loaded even if Xit is changed, or if a new file of the same name appears on the search Xpath. This was done for two reasons: first, it makes the code more Xportable, as I don't have to depend upon various system calls. Second, Xresources can't be un-written, so a user might get the wrong impression Xthat a resource specification can be deleted, and the resource file Xre-loaded, and something will happen. It just isn't so. X XNOTE: XThe file search list rule used by WcLoadResourceFileCB is a gross Xsimplification of the R3 resource file search mechanism, without the X$LANG provision. Soon the R4 search algorithm will be used. The Xcurrent version only looks into two directories, which may be defined Xas environmental variables: X X XAPPLRESDIR - defaults to "/usr/lib/X11/app-defaults/" X XUSERRESDIR - defaults to HOME directory X X XWcSystemCB( shell command line ) X-------------------------------- X XThis callback passes the entire string argument to you standard shell Xusing the system() C library function. X X XWcTraceCB( annotation ) X----------------------- X XThis callback can be used to assist in interface debugging. The Xcallback prints the invoking wiget pathname and a specified message on Xstdout. X X XWcExitCB( exitValue ) X--------------------- X XThis callback converts the argument string into a base 10 integer, and Xpasses the result to exit(), which of course terminates the Xapplication. +FUNKY+STUFF+ echo '-rw-rw-r-- 1 david 8283 Oct 16 14:41 4thREADME (as sent)' chmod u=rw,g=rw,o=r 4thREADME ls -l 4thREADME echo x - 5thREADME sed 's/^X//' > 5thREADME <<'+FUNKY+STUFF+' XWidget Creation Library Standard Action Routines X------------------------------------------------ X XAll of the standard callback functions have action routine Xcounterparts. Actions can be invoked via the translation manager, Xwhich provides a powerful and flexible mechanism for invoking functions Xfrom the user interface. X XBelow is the complete list of standard action routines, and their Xmapping to the standard Wc callback routines. See the section Xon `Widget Creation Library Standard Callbacks' for details on Xthe behaviors of the appropriate functions. X X WcCreateChildrenACT WcCreateChildrenCB X WcManageACT WcManageCB X WcUnmanageACT WcUnmanageCB X WcManageChildrenACT WcManageChildrenCB X WcUnmanageChildrenACT WcUnmanageChildrenCB X WcDestroyACT WcDestroyCB X WcSetValueACT WcSetValueCB X WcSetSensitiveACT WcSetSensitiveCB X WcSetInsensitiveACT WcSetInsensitiveCB X WcLoadResourceFileACT WcLoadResourceFileCB X WcTraceACT WcTraceCB X WcPopupACT WcPopupCB X WcPopupGrabACT WcPopupGrabCB X WcPopdownACT WcPopdownCB X WcMapACT WcMapCB X WcUnmapACT WcUnamapCB X WcSystemACT WcSystemCB X WcExitACT WcExitCB X XAll the standard action routines are registered with the translation Xmanager by the WcRegisterWcActions function. This function is called Xfrom WcWidgetCreation(), so applications usually never need to call XWcRegisterWcActions. X XThe file WcActions.c contains the implementations of all the action Xroutines along with the function WcRegisterWcActions. If your Xapplication wants to register mode actions, you should either use XWcRegisterAction(), or better yet, copy WcRegisterWcActions and modify Xto register your applications functions. Register your action Xfunctions before calling WcWidgetCreation. +FUNKY+STUFF+ echo '-rw-rw-r-- 1 david 1776 Oct 16 14:42 5thREADME (as sent)' chmod u=rw,g=rw,o=r 5thREADME ls -l 5thREADME echo x - 6thREADME sed 's/^X//' > 6thREADME <<'+FUNKY+STUFF+' XWidget Creation Functions X------------------------- X XThe widget creation Library provides several types of functions Xwhich are called by client applictions: X X 1. Registration Functions X 2. Creation Functions X 3. Callback Argument Parsing Utilities X XTwo include files are provided which declare the functions and Xsupporting data types used by the Widget Creation Library. Many Xapplications should only need to include WcCreate.h which Xcontains what can be considered "public" function declarations. X XIf you are writing additional resource converters, or sophisticated Xcallbacks, you will probably want to include WcCreateP.h which contains Xwhat can be considered "private" function declarations as well as Xtypedefs for several datatypes used by the Widget Creation Library. X XWidget Set Registration Functions X--------------------------------- X XTwo non-library functions are also provided in separate files: X XMriRegAll.c contains the single function MriRegisterMotif(). This Xfunction lets the Wc library know about all the Motif widget class Xnames (like XmPushButtonGadget), class pointers (like XxmPushButtonGadgetClass), and convenience constructors (like XXmCreatePushButtonGadget). X XAriRegAll.c contains the single function AriRegisterAthena(). This Xfunction lets the Wc library know about all the Athena widget class Xnamed (like Command), and class pointers (like commandWidgetClass). X XWcWidgetCreation() - see WcCreate.c X------------------ X XThis function takes a Widget as its only argument. A widget tree Xrooted at the widget is created from the Xrm database. This widget Xis called the root widget in this discussion, but it can really be any Xwidget. X XThe Xrm database is usually loaded as a matter of course by calling XXtInitialize(). It is possible to load the resource database directly, Xusing XrmGetFileDatabase() and XrmMergeDatabases(). See the function XWcLoadResourceFileCB in the file WcCallb.c for an example. X XThe algorithm used by WcWidgetCreation is recursive, as follows: X X 1. Fetch the wcChildren resource from Xrm database for the X initial widget. This will be a list of widget names. X X 2. For each child: X X 3. Fetch the set of Wc resources. X X 3a. If wcResFile is specified, load that resource file and X fetch the Wc resources again. X X 3b. Using the wcClass, wcClassName, or wcConstructor resource, X create the new child widget. Widget creation uses other X resources defined in the Xrm database specific to the type X of the widget, such as labelString for XmLabels. X X 3c. If wcCallback resource is defined (specifying a list of X callback functions), invoke each callback in order. X X 3d. If wcTrace is True, then dump the name of the just created X widget to stdout. X X 3e. If wcManaged is True (the default), then this widget will be X managed along with all of its siblings, after they are all X created (a single call to XtManageChildren is invoked by Wc). X X 3f. If the newly created widget has wcChildren specified, then X recursively invoke step (2.) above. Note that this X implements a depth first creation policy, which is generally X optimal for widget trees with manager widget nodes. X XNote that WcWidgetCreation() does a depth first creation, and that Xthe order of creation is controlled by the order of the names in the XwcChildren resource. X XEarlier versions of Wc required bizarre contortions when using Xconstructors in order to avoid toolkit warnings such as: X X Xt Warning: not all widgets have same parent in XtManageChildren() X XYou don't need to worry about this anymore - this behavior was Xconsidered a `bug' not a `feature' and therefore has been fixed. X X XWcCreateNamedChildren() - see WcCreate.c X---------------------- X XThis function creates named children of a reference widget by invoking Xthe same algorithm as WcWidgetCreation, except that only the specifically Xnamed children are created, rather than all the children. X XRegistration Functions - see WcReg.c X---------------------- X XThe Widget Creation Library converts strings in the database, such as X"XmCreateFileSelectionBox", into its needed types, such as constructors, Xusing Xt converters. These converters intrinsicly know nothing: they Xmust be told what each string maps into. The converters learn about Xthe appropriate mappings via the registration functions: X X WcRegisterCallback() X WcRegisterClassPtr() X WcRegisterClassName() X WcRegisterConstructor() X WcRegisterAction() X XBy default, these registration routines ignore attempts to re-register Xa string-to-whatever mapping. This is generally useful, in that it Xhelps to catch duplicate and therefore unneeded invocations of the Xregistration routines. X XIn some clients, there exists the need to override such registrations. XFor example, interface builders built using the Widget Creation Library Xand a C interpreter or a dynamic linking environment may allow a given Xcallback name to refer to different functions as the application Xevolves. The following functions are provided to support these cases: X X WcAllowDuplicateRegistration() X WcAllowDuplicateCallbackReg() X WcAllowDuplicateClassPtrReg() X WcAllowDuplicateClassNameReg() X WcAllowDuplicateConstructorReg() X XAn interface builder will probably call WcAllowDuplicateRegistration() Xbefore any callbacks, classes, et al are registered. It may also be Xappropriate to first register all standard callbacks and widgets, and Xthen call WcAllowDuplicateRegistration(). X XWcRegisterCallback() - see WcReg.c X-------------------- X XProbably all of your useful applications will require your own Xcallbacks. These callbacks are registered with the Widget Creation XLibrary's string-to-callback converter using WcRegisterCallback(). X XIn fact, this function is used by Wc itself to register the standard Wc Xsupplied callbacks, such as WcSetValueCB and WcExitCB. See the Xfunction WcRegisterWcCallbacks() at the end of WcCallb.c to see how XWc uses this function internally. X XWcRegisterClassPtr() - see WcReg.c X-------------------- X XThis function is used to tell the Widget Creation Library about a Xwidget class pointer which can be used within XtCreateWidget(). The Xname of the widget class pointer is passed in as a string (for example, X"xmPushButtonWidgetClass"). This string value can be provided as the XwcClass resource value within a resource file. X XWcRegisterClassName() - see WcReg.c X--------------------- X XThis function is used to tell the Widget Creation Library about a Xwidget class name. The name is mapped to a widget class pointer which Xcan be used within XtCreateWidget(). The name of the widget class is Xpassed in as a string (for example, "XmPushButton"). This string value Xcan be provided as the wcClassName resource value within a resource Xfile. X XWcRegisterConstructor() - see WcReg.c X----------------------- X XThis function is used to tell the Widget Creation Library about a Xwidget constructor. The name of the constructor is passed in as a Xstring (for example, "XmCreatePushButton"). This string value can be Xprovided as the wcConstructor resource value within a resource file. X XWcRegisterAction() - see WcReg.c X----------------- X XThis is a simple wrapper around XtAppAddActions(). If you are Xregistering many actions, you probably should copy the function XWcRegisterWcActions() in WcActions.c and make the obvious Xmodifications rather than using this function. This will help Xperformance. X +FUNKY+STUFF+ echo '-rw-r--r-- 1 david 7462 Aug 18 10:49 6thREADME (as sent)' chmod u=rw,g=r,o=r 6thREADME ls -l 6thREADME exit 0 dan ---------------------------------------------------- O'Reilly && Associates argv@sun.com / argv@ora.com Opinions expressed reflect those of the author only. -- dan ---------------------------------------------------- O'Reilly && Associates argv@sun.com / argv@ora.com Opinions expressed reflect those of the author only.