Widget Creation Library Standard Callbacks
------------------------------------------

The standard Wc callbacks are intended to map closely to existing Xt
functions.  They simply provide XtCallbackProc wrappers to many
commonly used Xt functions.  These wrapper procs perform argument
parsing: e.g., converting strings to widgets using WcFullNameToWidget.

Below is a complete list of callbacks which are registered by Wc
whenever you call WcWidgetCreation.  The "arguments" below are
prototypes of what one puts in a resouce file.  The terms mean:

   parent       name of widget, full path or wildcarded.
   child        name of child starting from the parent widget.
   widget       see parent
   resLHS       <widget path name>
   resRHS       <any legal resource value>

    WcCreateChildrenCB   ( parent, child [, child] ... )
    WcManageChildrenCB   ( parent, child [, child] ... )
    WcUnmanageChildrenCB ( parent, child [, child] ... )

    WcManageCB         ( widget [, widget] ... )
    WcUnmanageCB       ( widget [, widget] ... )
    WcDestroyCB        ( widget [, widget] ... )
    WcSetSensitiveCB   ( widget [, widget] ... )
    WcSetInsensitiveCB ( widget [, widget] ... )

    WcPopupCB     ( widget )
    WcPopupGrabCB ( widget )
    WcPopdownCB   ( widget )
    WcMapCB       ( widget )
    WcUnmapCB     ( widget )

    WcSetValueCB ( resLHS: resRHS )
    
    WcLoadResourceFileCB ( filename )
    
    WcSystemCB ( shell command line )
    WcTraceCB  ( annotation )

    WcExitCB ( exitValue )

See the file WcCallb.c for the implementations of all of these standard
callbacks.  These callbacks are registered together in the function
WcRegisterWcCallbacks() which is at the bottom of the same source
file.  Clients of Wc do not have to invoke WcRegisterWcCallbacks()
directly, as it is called from WcWidgetCreation() in the WcCreate.c
source file.


Widget Naming in Callback Arguments
-----------------------------------

In all of these callbacks, the function WcFullNameToWidget is invoked
to convert a string to a widget.  WcFullNameToWidget allows relative
widget naming, relative to the widget which invoked the callback.  The
special characters are presented in examples below:

    this	means: `the widget which invoked this callback'
    ^foobar	means: `a sibling widget named foobar'
    ~foobar	means: `a child of the shell ancestor named foobar'
    ~^foobar	means: `a sibling of the shell ancestor named foobar'

The relative naming characters `^' and `~' are parsed left to right.

In addition, normal wildcarding works as expected - as long as the
final name component is a widget instance, and not a widget class
name.  For example:

    *foobar
    *Table*XmRowColumn*foobar


WcCreateChildrenCB( parent, child [, child] ... )
-------------------------------------------------

This callback causes new widgets to be created.  The name of the parent
can include wildcards, or can be a relative pathname from the widget
invoking the callback.  The names of the children widgets must be
single widget names, not pathnames.  For example:

    *danger.callback:  WcCreateChildrenCB( *Panel, EmergencyControls)

In this case, pressing a danger button creates a new tree of widgets
providing emergency controls.  The new tree is rooted at the existing
Panel widget.


WcManageChildrenCB( parent, child [, child] ... )
-------------------------------------------------

This callback manages multiple children of a single parent.  It is a
wrapper around XtManageChildren.  As with WcCreateChildrenCB, the
parent name can include wildcards, or can be a relative pathname from
the widget invoking the callback.  The names of the children widgets
must be single widget names, not pathnames.  For example:

    *new.activateCallback:  WcManageChildrenCB( *foo, one, two, three )


WcUnmanageChildrenCB( parent, child [, child] ... )
---------------------------------------------------

Identical to WcManageChildrenCB, except that the child widgets are 
unmanaged rather than managed via a call to XtUnmanageChildren.


WcManageCB( widget [, widget] ... )
-----------------------------------

This callback takes a list of widget names, each of which
can be wildcarded and/or relative widget pathname.  After
the widget ID is resolved via the WcFullNameToWidget function,
the widgets are managed using XtManageChild().


WcUnmanageCB( widget [, widget] ... )
-------------------------------------

This callback is identical to WcManageCB, except that the
widgets are unmanaged using XtUnmanageChild().


WcDestroyCB( widget [, widget] ... )
------------------------------------

This callback allows widgets to be destroyed using XtDestroyWidget().


WcSetSensitiveCB( widget [, widget] ... )
-----------------------------------------

This callback invokes XtSetSensitive( TRUE ) on each of the
widgets named by the argument.


WcSetInsensitiveCB( widget [, widget] ... )
-------------------------------------------

This callback is identical to WcSetSensitiveCB, but the widgets
are made insensitive.


WcPopupCB( widget )
-------------------

This callback invokes XtPopup() with the XtGrabKind set to
XtGrabNonexclusive.  The widget must be a pop-up shell widget.


WcPopupGrabCB( widget )
-----------------------

This callback invokes XtPopup() with the XtGrabKind set to
XtGrabExclusive.  The widget must be a pop-up shell widget.


WcPopdownCB( widget )
---------------------

This callback invokes XtPopdown().  The widget must be a pop-up shell
widget.

WcMapCB( widget )
---------------------

This callback invokes XtMapWidget().  The widget must be a shell
widget.

WcUnmapCB( widget )
---------------------

This callback invokes XtUnmapWidget().  The widget must be a shell
widget.


WcSetValueCB( resLHS: resRHS )
------------------------------

WcSetValueCB maps very closely to XtSetValues().  An augmented resource
file syntax is accepted so you can cut and paste the arguments and
names.  The widget path name can include wildcards, and it can also be
a relative path from the invoking widget.  Real examples:

  *push.activateCallback: WcSetValueCB( *push.activateCallback: WcExitCB(1) ), \
                          WcSetValueCB( *push.labelString:      Goodbye! )

  *fileMenu.wcCallback:   WcSetValueCB(*file.subMenuId: this)

  *Pink.armCallback:	  WcSetValueCB( ^^drawing.background: Pink )


WcLoadResourceFileCB( filename )
--------------------------------

This callback loads specified resource file into application resource
database. It allows to load resources on as-needed basis, reducing the
intitial resource file load overhead.  The file to load is specified as
client data. The directory search for the file (should be) the same as
for application class resource file.

To prevent repeated loads of the same file, the callback keeps track of
each filename.  Note that I do not allow a file to be re-loaded even if
it is changed, or if a new file of the same name appears on the search
path.  This was done for two reasons:  first, it makes the code more
portable, as I don't have to depend upon various system calls.  Second,
resources can't be un-written, so a user might get the wrong impression
that a resource specification can be deleted, and the resource file
re-loaded, and something will happen.  It just isn't so.

NOTE:
The file search list rule used by WcLoadResourceFileCB 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


WcSystemCB( shell command line )
--------------------------------

This callback passes the entire string argument to you standard shell
using the system() C library function.


WcTraceCB( annotation )
-----------------------

This callback can be used to assist in interface debugging. The
callback prints the invoking wiget pathname and a specified message on
stdout.


WcExitCB( exitValue )
---------------------

This callback converts the argument string into a base 10 integer, and
passes the result to exit(), which of course terminates the
application.
