Name

XtAddCallbacks — add a list of callback procedures to a given widget’s callback list. 

Synopsis

void XtAddCallbacks(object, callback_name, callbacks)

    Widget object;
    String callback_name;
    XtCallbackList callbacks;

Arguments

objectSpecifies the object; may be of class Object or any subclass thereof. 

callback_name
Specifies the resource name of the callback list to which the procedure is to be appended.

callbacksSpecifies the NULL-terminated list of callback procedures and corresponding client data. 

Description

Generally speaking, a widget expecting to interact with an application will declare one or more callback lists as resources; the application adds functions to these callback lists, which will be invoked whenever the predefined callback conditions are met.  Callback lists are resources, so that the application can set or change the function that will be invoked. 

Callbacks are not necessarily invoked in response to any event; a widget can call the specified routines at any arbitrary point in its code, whenever it wants to provide a "hook" for application interaction.  For example, all widgets provide an XtNdestroyCallback resource to allow applications to interpose a routine to be executed when the widget is destroyed. 

Widgets can define additional callback lists as they see fit.  For example, the Athena Command widget defines the XtNcallback callback list to notify clients when the widget has been activated (by the user clicking on it with the pointer).  (This is actually a poor choice of names.  It should have been given a more specific name, such as XtNnotifyCallback.) 

Callback functions are registered with a widget using a call to XtAddCallbacks or XtAddCallback.  Even though callback lists are resources, callback functions cannot be added from resource files, since callback lists are maintained in a private internal form by the Intrinsics.  They cannot be modified directly except through one of the calls (such as XtAddCallback) provided to access them. 

XtAddCallbacks adds new callbacks to the end of the callback list.  A callback will be invoked as many times as it occurs in the callback list.  See XtCallbackProc(2) for a description of the format of a callback function. 

Use XtAddCallback to add a single callback to a widget’s callback list. 

Callbacks differ from actions in the way that the registered function is invoked.  For callbacks, the trigger is an abstract occurrence defined by the widget, which may or may not be event-related.  The routines on a widget’s callback lists are invoked by the widget code, using a call to XtCallCallbacks.  Actions, on the other hand, are invoked directly by Xt, as the result of an event combination specified by the translations mechanism. 

Another major difference between an action function and a callback function is that action functions are called with an event as an argument, while actions do not have the client_data or call_data arguments present for callback functions.  This means the only way to pass application data into an action function is through global variables.  On the other hand, the presence of the event argument means that you can use the contents of the event structure in the action function. 

There are many cases where you might want to add more than one callback function to the same callback list.  The use of XtCallbackExclusive et al.  provides a good case in point.  There are Intrinsics-defined callback functions that can be used to pop up a widget.  However, they do not place the pop up. 

To pop up a dialog box upon the press of a command button, you would typically add two callback functions to the Command widget’s XtNcallback list:  one of the Intrinsics-supplied XtCallback∗ functions, and one of your own to place the pop up. 

One way to add more then one callback function is to call XtAddCallback more than once.  Another way is to call XtAddCallbacks, which takes an XtCallbackRect array as an argument.  This array is usually initialized at compile time, as shown in the example below.  The final NULL, NULL entry terminates the list.  (This particular list registers the functions place_popup and XtCallbackExclusive and passes them both 0 as client_data.) 

XtCallbackRec quit_callback_list[] = {
{place_popup, 0}
{XtCallbackExclusive, 0},
{(XtCallbackProc) NULL, (caddr_t) NULL},
};

This form of XtCallbackRec list can also be used to replace a callback list with XtSetValues (but not to get a callback list, because Xt compiles the list into an internal form). 

Structures

typedef struct _XtCallbackRec∗    XtCallbackList;
 typedef struct _XtCallbackRec {
XtCallbackProc callback;
caddr_t client_data;
} XtCallbackRec, ∗XtCallbackList;

See Also

XtAddCallback(1), XtCallCallbacks(1), XtRemoveAllCallbacks(1), XtRemoveCallback(1), XtRemoveCallbacks(1),
XtCallbackProc(2).