Page:123456

Chapter 8


Callbacks

Applications and other widgets often need to register a procedure with a widget that gets called under certain prespecified conditions. For example, when a widget is destroyed, every procedure on the widget's destroy_callbacks list is called to notify clients of the widget's impending doom.

Every widget has an XtNdestroyCallbacks callback list resource. Widgets can define additional callback lists as they see fit. For example, the Pushbutton widget has a callback list to notify clients when the button has been activated.

Except where otherwise noted, it is the intent that all Intrinsics functions may be called at any time, including from within callback procedures, action routines, and event handlers.

Home


8.1. Using Callback Procedure and Callback List Definitions

Callback procedure pointers for use in callback lists are of type XtCallbackProc.

typedef void (*XtCallbackProc)(Widget, XtPointer, XtPointer);
Widget w;
XtPointer client_data;
XtPointer call_data;
wSpecifies the widget owning the list in which the callback is registered.
client_dataSpecifies additional data supplied by the client when the procedure was registered.
call_dataSpecifies any callback-specific data the widget wants to pass to the client. For example, when Scrollbar executes its XtNthumbChanged callback list, it passes the new position of the thumb.

The client_data argument provides a way for the client registering the callback procedure 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. The client_data value may be NULL if all necessary information is in the widget. The call_data argument is a convenience to avoid having simple cases where the client could otherwise always call XtGetValuesor 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.

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.

typedef struct {
XtCallbackProc callback;
XtPointer 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, (XtPointer) clientDataA},
{B, (XtPointer) clientDataB},
{(XtCallbackProc) NULL,(XtPointer) NULL}
};

Although callback lists are passed by address in arglists and varargs lists, the Intrinsics recognize callback lists through the widget resource list and will copy the contents when necessary. Widget initialize and set_values procedures should not allocate memory for the callback list contents. The Intrinsics automatically do this, potentially using a different structure for their internal representation.

Home


8.2. Identifying Callback Lists

Whenever a widget contains a callback list for use by clients, it also exports in its public .h file the resource name of the callback list. Applications and client widgets never access callback list fields directly. Instead, they always identify the desired callback list by using the exported resource name. All the callback manipulation functions described in this chapter except XtCallCallbackList check to see that the requested callback list is indeed implemented by the widget.

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 implementationdependent; 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 XtCallbackStatus XtCallbackHasNone), access to callback list resources must be made through other Intrinsics procedures.

Home


8.3. Adding Callback Procedures

To add a callback procedure to a widget's callback list, use XtAddCallback.

void XtAddCallback(w,callback_name, callback, client_data)
Widget w;
String callback_name;
XtCallbackProc callback;
XtPointer client_data;
wSpecifies the widget. Must be of class Object or any subclass thereof.
callback_nameSpecifies the callback list to which the procedure is to be appended.
callbackSpecifies the callback procedure.
client_dataSpecifies additional data to be passed to the specified procedure when it is invoked, or NULL.

A callback will be invoked as many times as it occurs in the callback list.

To add a list of callback procedures to a given widget's callback list, use XtAddCallbacks.

void XtAddCallback(w,callback name, callbacks)
Widget w;
String callback_name;
XtCallbackList callbacks;
wSpecifies the widget. Must be of class Object or any subclass thereof.
callback_nameSpecifies the callback list to which the procedures are to be appended.
callbacksSpecifies the null-terminated list of callback procedures and corresponding client data.


Home


8.4. Removing Callback Procedures

To delete a callback procedure from a widget's callback list, use XtRemoveCallback.

void XtRemoveCallback(w,callback name, callback, client_data)
Widget w;
String callback_name;
XtCallbackProc callback;
XtPointer client_data;
wSpecifies the widget. Must be of class Object or any subclass thereof.
callback_nameSpecifies the callback list from which the procedure is to be deleted.
callbackSpecifies the callback procedure.
client_dataSpecifies the client data to match with the registered callback entry.

The XtRemoveCallback function removes a callback only if both the procedure and the client data match.

To delete a list of callback procedures from a given widget's callback list, use XtRemoveCallbacks .

void XtRemoveCallbacks(w,callback_name, callbacks)
Widget w;
String callback_name;
XtCallbackList callbacks;
wSpecifies the widget. Must be of class Object or any subclass thereof.
callback_nameSpecifies the callback list from which the procedures are to be deleted.
callbacksSpecifies the null-terminated list of callback procedures and corresponding client data.

To delete all callback procedures from a given widget's callback list and free all storage associated with the callback list, use XtRemoveAllCallbacks.

void XtRemoveAIICallbacks(w,callback_name)
Widget w;
String callback_name;
wSpecifies the widget. Must be of class Object or any subclass thereof.
callback_nameSpecifies the callback list to be cleared.


Home


8.5. Executing Callback Procedures

To execute the procedures in a given widget's callback list, specifying the callback list by resource name, use XtCallCallbacks.

void XtCallCallbacks(w,callback_name, call_data)
Widget w;
String callback_name;
XtPointer call_data;

wSpecifies the widget. Must be of class Object or any subclass thereof.
callback_nameSpecifies the callback list to be executed.
call_dataSpecifies a callback-list-specific data value to pass to each of the callback procedure in the list, or NULL.

XtCallCallbacks calls each of the callback procedures in the list named by callback_name in the specified widget, passing the client data registered with the procedure and call-data.

To execute the procedures in a callback list, specifying the callback list by address, useXtCallCallbackList .

void XtCallCallbackList(widget,callbacks, call_data)
Widget widget;
XtCallbackList callbacks;
XtPointer call data;
widgetSpecifies the widget instance that contains the callback list. Must be of class Object or any subclass thereof.
callbacksSpecifies the callback list to be executed.
call_dataSpecifies a callback-list-specific data value to pass to each of the callback procedures in the list, or NULL.

The callbacks parameter must specify the contents of a widget or object resource declared with representation type XtRCallback. If callbacks is NULL, XtCallCallbackList returns immediately; otherwise it calls each of the callback procedures in the list, passing the client data and call_data.

Home


8.6. Checking the Status of a Callback List

To find out the status of a given widget's callback list, use XtHasCallbacks;

typedef enum {XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome} XtCallbackStatus;

XtCallbackStatus XtHasCallbacks(w,callback_name)
Widget w;
String callback_name;
wSpecifies the widget. Must be of class Object or any subclass thereof.
callback_nameSpecifies the callback list to be checked.

The XtHasCallbacks function first checks to see if the widget has a callback list identified by callback_name. If the callback list does not exist, XtHasCallbacks returns XtCallbackNoList. If the callback list exists but is empty, it returnsXtCallbackHasNone. If the callback list exists and has at least one callback registered, it returns XtCallbackHasSome.

Home

Contents Previous Chapter Next Chapter