v10i051: wcl -- Widget Creation Library, Part03/11
David E. Smyth
david at jpl-devvax.jpl.nasa.gov
Tue Dec 18 13:02:51 AEST 1990
Submitted-by: david at jpl-devvax.jpl.nasa.gov (David E. Smyth)
Posting-number: Volume 10, Issue 51
Archive-name: wcl/part03
Submitted-by: david at 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 at 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 at 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 at 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 at 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 at 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 at 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 at 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 at 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 at sun.com / argv at ora.com
Opinions expressed reflect those of the author only.
--
dan
----------------------------------------------------
O'Reilly && Associates argv at sun.com / argv at ora.com
Opinions expressed reflect those of the author only.
More information about the Comp.sources.x
mailing list