XtAddCallback()XtAddCallback()Name
XtAddCallback - add a callback procedure to a named callback list.
Synopsis
void XtAddCallback(object, callback_name, callback, client_data)
Widget object;
String callback_name;
XtCallbackProc callback;
XtPointer client_data;
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
procedure is to be added.
callback Specifies the procedure to be added.
client_data
Specifies data to be passed to callback when it is invoked,
or NULL.
DescriptionXtAddCallback() adds the procedure callback and the data client_data to
the callback list named by callback_name in the widget or object
object. If the procedure already appears on the list, with the same or
with different data, it will be added to the list again, and when the
callback list is invoked, the procedure will be called as many times as
it has been added.
The callback procedure must be of type XtCallbackProc. This procedure
type expects three arguments and does not return anything. The argu‐
ments are the widget or object that caused the callback to be invoked,
the untyped data (client_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 several callback procedures at the same time,
you can use XtAddCallbacks(). 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 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.
See AlsoXtAddCallbacks(1), XtCallCallbacks(1), XtRemoveAllCallbacks(1),
XtRemoveCallback(1), XtRemoveCallbacks(1),
XtCallbackProc(2).
Xt - Callbacks XtAddCallback()
