XtAddCallbacks() XtAddCallbacks()
Name
XtAddCallbacks - add an array of callback procedures to a named callback list.
Synopsis
void XtAddCallbacks(object, callback_name, callbacks)
Widget object;
String callback_name;
XtCallbackList callbacks;
Inputs
object Specifies the object which owns the callback list; may be of class Object or any subclass thereof.
callback_name
Specifies the resource name of the callback list to which the procedures are to be added.
callbacks Specifies a NULL-terminated array of callback procedures and corresponding client data.
Description
XtAddCallbacks() adds the procedure/data pairs specified in callbacks to the callback list named callback_name in the widget or object
object. Each element of callbacks is a structure of type XtCallbackRec and contains a pointer to a callback procedure and the data to be
registered with and passed to that procedure. Because XtAddCallbacks() does not have an argument that specifies the length of this array,
the last element of the array must contain NULL in both of its fields.
A procedure may appear multiple times in the callbacks array, and may be added to a callback list more than once, with different or even
with the same data. When the callback list is invoked, each procedure will be called as many times as it appears on the list.
Each procedure to be added to the callback list must be of type XtCallbackProc. This procedure type expects three arguments and does not
return anything. The arguments are the widget or object that caused the callback to be invoked, the untyped data that was registered with
the procedure, and another untyped argument, call_data which generally points to a structure which contains data particular to the callback
list and object class. See XtCallbackProc(2).
Usage
The order that callback procedures are invoked in is, unfortunately, not specified by the Xt Intrinsics. If you have several operations
that must be executed in a particular order, you should not register them as separate callbacks. Instead you should register a single
callback that invokes each of the operations sequentially.
If you want to register only a single callback procedure, XtAddCallback() is easier to use. You may find this function easier even if you
are registering several functions, because it does not require you to declare and initialize an array of XtCallbackRec.
Callbacks can also be set on a callback list by specifying a XtCallbackList as a resource when the widget is created. A callback list
should not be set with XtSetValues() once a widget is created, however, because this replaces the entire list of procedures rather than
simply adding new procedures to the list. The Intrinsics do not define a String-to-XtCallbackList converter, but if you write one and use
it in your application, then you can also specify callbacks from a resource file. Finally, note that callback lists in a widget are com-
piled into an internal form by the Intrinsics, so attempting to examine a callback list with XtGetValues() will not work.
Background
Generally speaking, a widget expecting to interact with an application will declare one or more callback lists as resources; the applica-
tion adds functions to these callback lists, which will be invoked whenever the predefined callback conditions are met. Callback lists
have resource names, so that the application can add and remove functions to a callback list by name.
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.)
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.
Example
When calling XtAddCallbacks(), you will generally use a statically initialized array like the following:
XtCallbackRec button_callback_list[] = {
{dispatch_function, (XtPointer) 1},
{dispatch_function, (XtPointer) 2},
{do_something_else, NULL},
{(XtCallbackProc) NULL, (XtPointer) NULL},
};
Structures
typedef struct _XtCallbackRec {
XtCallbackProc callback;
XtPointer closure;
} XtCallbackRec, *XtCallbackList;
See Also
XtAddCallback(1), XtCallCallbacks(1), XtRemoveAllCallbacks(1), XtRemoveCallback(1), XtRemoveCallbacks(1),
XtCallbackProc(2).
Xt - Callbacks XtAddCallbacks()