Widget Creation Resources
-------------------------

The Widget Creation Library allows user interfaces to be completely
defined within a resource file: the widget heirarchy, widget types, and
bindings of widget callback lists and translations to application
functions are specified in the resource file using Wc* resources.

The following is the complete set of resources which are
interpreted by the Widget Creation Library:

     ...widget.wcResFile:      resourceFileName
     ...widget.wcClass:        classPointerName
     ...widget.wcClassName:    className
     ...widget.wcConstructor:  constructorFunctionName
     ...widget.wcTrace:        true/false (default = false)
     ...widget.wcCallback:     callback1(args), callback2(args), ...
     ...widget.wcChildren:     childName1, childName2, ...
     ...widget.wcManaged:      true/false (default = true)
     ...widget.wcDeferred:     true/false (default = false)

In all cases, the Widget Creation resource names can be specified as
Wc<name> or wc<name>, with the capitalized form having looser binding
(representing the resource class).

WcResFile Resource
------------------

This resource allows you to put additional resource specifications
related to a widget or its children in a separate file.  Like all
widget creation resources, the WcResFile resource value is retrieved
from the Xrm database at widget creation time.

Before the widget is created, the specified resource file is loaded
into the Xrm database, and then another query of the Xrm database is
made to obtain the other Wc resources.  Therefore, all wc resources
(except of course the WcResFile resource) and other widget resources
may be specified in the new resource file.  

NOTE:
The file search list rule used by WcResFile is a gross simplification
of the R3 resource file search mechanism, without the $LANG provision.
Soon the R4 search algorithm will be used.  The current version only
looks into two directories, which may be defined as environmental
variables:

         XAPPLRESDIR  - defaults to "/usr/lib/X11/app-defaults/"
         XUSERRESDIR  - defaults to HOME directory

WcClass, WcClassName, and WcConstructor Resources
-------------------------------------------------

These resources allow you to specify the type of the widget.  Only one
of these resources should be specified for each widget.  If multiple
specifications are made, a warning will be given via XtWarning (the
message prints on stderr).  A WcClass specification overrides a
WcClassName specification which overrides a WcConstructor
specification.

WcTrace Resource
----------------

This resource is useful for debugging your user interface.  When `True'
the full name and class name of the widget is printed to stderr right
after the widget is created.

WcCallback Resource
-------------------

This resource allows you to specify a list of callback functions
which are invoked after the widget is created, and before it is
managed.  The callback functions receive the newly created widget as
their widget argument, and whatever is within the parenthesis following
the callback function name as a string argument as client data.  For
example:

	*foo.wcCallback:	FooSpecialCB( Hi there )

This specification will cause the function `FooSpecialCB' to be
called.  The widget argument will be the newly created widget foo, and
the client_data argument will be the null terminated character array "
Hi there ".  The call_data is whatever was specified when the
FooSpecialCB callback function was registered with
WcRegisterCallback().

This is generally how the interface can create related objects within
the application.  For example, if your application has a storage
object, each widget which provides storage related behaviors or
attribute displays might register themselves with your application's
storage object.

WcChildren Resource
-------------------

After a widget is created, but before it is managed, all of its
children are created (and by default, managed).  The names of children
widgets are specified by the WcChildren resource.  The order of the
names in the resource value indicate the left-to-right order of
widget creation.  The names of the widgets in the example below
imply the order of creation:

	*foo.wcChildren:	ONE, TWO, THREE

Since each widget creation is recursive, the widgets are created depth
first.  I.e., the widget `ONE' and all of ONE's children will be
created before widget `TWO' will be created.

WcManaged Resource
------------------

This resource allows you to specify that a widget should not be managed
following its creation.  By default, widgets are managed together with
their siblings after all siblings are created.  Wc uses a single call
to XtManageChildren when possible.

Obsolete Widget Creation Resources
----------------------------------

The wcDeferred resource is maintained only for compatibility.  It
is never needed, and can simply be deleted from your existing resource
files, along with the appearance of the widget's name from any
wcChildren list.  I.e., if you have the following:

    *foobar.wcChildren: one, two, three, four
        ...
    *two.wcDeferred:    true

Simply drop `two' from the list of children of `foobar' and remove
the `*two.wcDeferred: true' line from your resource file.  Widgets
which are created dynamically have their parentage specified at
creation time, generally via WcCreateCB as follows:

    WcCreateChildrenCB( foobar, two )

Support for wcDeferred resources will be removed in the near future,
so try to purge their use.


How the Application Interacts with the Widget Creation Library 
--------------------------------------------------------------

The typical Wc client application (including Ari and Mri) will create
an application shell and load the Xrm database by calling
XtInitialize().  It will then register widgets, callbacks, and actions
with the Wc library, and then pass the application shell to the
WcWidgetCreation() function.  This function returns when the entire
connected widget heirarchy specified in the Xrm database is created.
The widget tree is realized, and then the XtMainLoop is entered.
Briefly:

	appShell = XtInitialize( ... );

	/* Register widgets, callbacks, and actions */

	WcWidgetCreation( appShell );
	XtRealizeWidget( appShell );
	XtMainLoop();

When Resources are Loaded Into the Xrm Database
-----------------------------------------------

XtInitialize loads an initial set of resource files into the resource
database before any widgets are created.  This initial database may
contain references to other resource files by way of WcResFile resource
specifications.  If a widget `Foo' has a resource specification like
this:

    *Foo.wcResFile:	FooResources

then the resource file named FooResources will be merged into the
resource database before the widget Foo is created.  In fact, several
files named FooResources may be loaded, as the standard Xt resource
file search and load is performed.  See section 2.2 and 11.11 of the
X11R4 Xt Intrinsics - C Language Interface manual for more
information.

NOTE:
The file search list rule used by this version of Wc is a gross
simplification of the R3 resource file search mechanism, without the
$LANG provision.  Soon the R4 search algorithm will be used.  The
current version only looks into two directories, which may be defined
as environmental variables:

         XAPPLRESDIR  - defaults to "/usr/lib/X11/app-defaults/"
         XUSERRESDIR  - defaults to HOME directory


When Resources are Retrieved from the Xrm Database
--------------------------------------------------

Resources are retrieved from the Xrm resource database when widgets are
created.  If the resource database changes after widget `Foo' is
created, subsequent changes to the database will have absolutely no
effect upon widget `Foo.'

How Widgets Are Created from the Xrm Database
---------------------------------------------

The Widget Creation Library starts creating widgets when the
WcWidgetCreation() function is called.  Here is the recursive
scenario.  The initial widget is usually the application shell:

    1.	Fetch the wcChildren resource from Xrm database for the
	initial widget.  This will be a list of widget names.

    2.	For each child: 

    3.	Fetch the set of Wc resources.  

    3a.	If wcResFile is specified, load that resource file and 
	fetch the Wc resources again.

    3b.	Using the wcClass, wcClassName, or wcConstructor resource, 
	create the new child widget.  Widget creation uses other 
	resources defined in the Xrm database specific to the type 
	of the widget, such as labelString for XmLabels.

    3c.	If wcCallback resource is defined (specifying a list of
	callback functions), invoke each callback in order.  

    3d. If wcTrace is True, then dump the name of the just created
	widget to stdout.

    3e.	If wcManaged is True (the default), then this widget will be
	managed along with all of its siblings, after they are all
	created (a single call to XtManageChildren is invoked by Wc).

    3f. If the newly created widget has wcChildren specified, then
	recursively invoke step (2.) above.  Note that this
	implements a depth first creation policy, which is generally
	optimal for widget trees with manager widget nodes.


The resource files themselves have no explicit flow of control
mechanisms.  However, the order of events during widget creation causes
the resources to be evaluated in a deterministic and sometimes
repetitive pattern.

The most significant control over resource evaluation is the order that
widgets are created.  Widget creation is ordered by the order of widget
names in wcChildren resource lists.  The names of widgets in the
example below reflects the order these widgets will be created.  The
order of the resource specifications themselves are irrelevent to the
order of creation:

	Mri.wcChildren:			one, four
	Mri.one.wcClassName:		XmRowColumn
	Mri.one.wcChildren:		two, three
	Mri.one.two.wcClassName:	XmLabel
	Mri.one.three.wcClassName:	XmPushButton
	Mri.four.wcConstructor:		XmCreateWorkingDialog

Widgets can also be created after the initial widget tree.  For example,
help dialogs may be dynamically created only when necessary, so an
experienced user does not need to suffer the additional start-up time
of creating a large number of widgets which are not needed, nor is
memory or swap space consumed by the unnecessary widgets.

Here are resources which demonstrate how a help dialog could be created
due to a button press.  In this case, the newly created widget will
become a child of the application shell (Mri if the resource file is
being interpreted by Mri).  The resources for the help dialog are
segregated into another set of resource files which are named
`HelpDialogResources.'  The standard Xt resource file search path is
used, so /usr/lib/X11/app-defaults/HelpDialogResources, ...,
~/apps-defaults/HelpDialogResources, may be loaded into the Xrm
database due to this one WcResFile specification:

	/* in initial resource file: */
	*helpButton.activateCallback:	WcCreateChildrenCB( Mri, helpDialog )
	*helpDialog.wcResFile:		HelpDialogResources

	/* in HelpDialogResources: */
	*helpDialog.wcConstructor:	XmCreateMessageDialog
	*helpDialog.messageLabel:	Some help message...
	*helpDialog.okCallback:		WcDestroyCB( this )

Frequently, you probably want such dialogs to remain once they are
created.  See the M5.Dialogs resource file for one way to do this.

In the above example, notice that the resources specified in the
HelpDialogResources file are unknown to the Xrm database until an
attempt is made to create the helpDialog widget.
