XtAddCallbacks()XtAddCallbacks()Name
XtAddCallbacks - add an array of callback procedures to a named call‐
back 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.
DescriptionXtAddCallbacks() 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 reg‐
istered 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 XtCall‐
backProc. 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 call‐
back that invokes each of the operations sequentially.
If you want to register only a single callback procedure, XtAddCall‐
back() 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 XtCall‐
backList 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 compiled 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 application
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 wid‐
get 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 XtNno‐
tifyCallback.)
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 rou‐
tines 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 ini‐
tialized 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 AlsoXtAddCallback(1), XtCallCallbacks(1), XtRemoveAllCallbacks(1),
XtRemoveCallback(1), XtRemoveCallbacks(1),
XtCallbackProc(2).
Xt - Callbacks XtAddCallbacks()
