Name
XtCallbackProc — prototype callback procedure.
Synopsis
typedef void (∗XtCallbackProc)(Widget, XtPointer, XtPointer);
Widget w;
XtPointer client_data;
XtPointer call_data;
Arguments
wSpecifies the widget for which the callback is registered.
client_data
Specifies the data that the widget will pass to the client’s procedure when the widget performs the callback.
call_dataSpecifies the data registered with the callback by the client.
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, and then these functions will be invoked whenever the predefined callback conditions are met. Because callback lists are resources, the application can set or change at any time the function or functions 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.
Whenever a client wants to pass a callback list as an argument in an XtCreateWidget, XtSetValues, or XtGetValues call, it should specify the address of a NULL-terminated array of type XtCallbackList (see the Structures section below). Callback procedure fields for use in callback lists are of type XtCallbackProc.
When a callback procedure, or list of callback procedures, is passed as a resource argument, Xt constructs an internal data structure for the callback list. Subsequently, callback lists cannot be queried. Because Xt doesn’t support a string-to-callback resource converter, callbacks cannot be specified in resource files. The internal form can only be accessed by the Intrinsics functions XtAddCallback, XtAddCallbacks, XtRemoveCallback, XtRemoveCallbacks, XtCallCallbacks, etc. Furthermore, since callback lists are handled specifically by the Intrinsics, widget procedures should not allocate memory for callback lists passed as resources. Unlike other resources, a widget’s initialize method should not attempt to make copies of resources of type XtRCallback.
An XtCallbackProc takes three arguments:
•The first argument is the widget that triggered the callback, as specified as the first argument in XtAddCallback. You would use the value of this argument in your callback function if you registered the same function as a callback for two different widgets, and if you wanted to distinguish in the callback which widget called it.
•The second argument, client_data, is the value passed as the last argument of XtAddCallback. client_data provides a way for the client registering the callback also to register client-specific data (for example, a pointer to additional information about the widget, a reason for invoking the callback, and so on). client_data should be NULL if all necessary information is in the widget.
•The third argument, call_data, is a piece of data passed from the widget. Some classes of widget set this argument, but others do not. The documentation for the widget will specify the contents of this data if it is used. The Athena Command widget doesn’t provide any call_data, but the Athena Scroll widget, for example, passes back the current position of the thumb.
The call_data argument is a convenience to avoid having simple cases where the client would otherwise have to call XtGetValues or a widget-specific function to retrieve data from the widget. Widgets should generally avoid putting complex state information in call_data. The client can use the more general data retrieval methods, if necessary.
For the Intrinsics to find and correctly handle callback lists, they must be declared with a resource type of XtRCallback. The internal representation of a callback list is implementation-dependent; widgets may make no assumptions about the value stored in this resource if it is non-NULL. Except to compare the value to NULL (which is equivalent to XtCallbackHasNone returned by XtHasCallbacks), access to callback list resources must be made through other Intrinsics procedures.
Structures
typedef struct {
XtCallbackProc callback;
caddr_t closure;
} XtCallbackRec, ∗XtCallbackList;
For example, the callback list for procedures A and B with client data clientDataA and clientDataB, respectively, is:
static XtCallbackRec callbacks[] = {
{A, (caddr_t) clientDataA},
{B, (caddr_t) clientDataB},
{(XtCallbackProc) NULL, (caddr_t) NULL}
};
See Also
XtAddCallback(1), XtAddCallbacks(1), XtCallCallbacks(1), XtCreateWidget(1), XtGetValues(1), XtHasCallbacks(1), XtRemoveCallback(1), XtRemoveCallbacks(1), XtSetValues(1), XtVaGetValues(1), XtVaSetValues(1).