Name

XtAddCallback — add a callback procedure to a widget’s callback resource. 

Synopsis

void XtAddCallback(object, callback_name, callback, client_data)

    Widget object;
    String callback_name;
    XtCallbackProc callback;
    XtPointer client_data;

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.  See XtCallbackProc(2). 

callbackSpecifies the callback procedure to be added. 

client_data
Specifies the argument to be passed to the specified callback procedure when it is invoked by XtCallCallbacks, or specifies NULL. 

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 XtAddCallback or XtAddCallbacks.  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. 

XtAddCallback adds a new callback 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 XtAddCallbacks to add a list of callbacks 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. 

See Also

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