The Callback Mechanisms


The callback mechanism in Xarm allows any member function of a class to receive a callback just as a C function would. The only requirement of a callback function in Xarm is that the member function must have the proper number and types of parameters for the type of callback being added.

When the callback function to be registered is a static member function of an object or a regular non-member C++ function, then either the normal XtAddCallback and associated functions may be used or the Xarm supplied wrapper functions may be used. The Xarm supplied functions allow for a consistent callback interface to be used in a program. All callbacks can be registered using addCallback. The static/non-member callback routines provided are:

These functions serve as wrappers for XtAddCallback, XtRemoveCallback and XtRemoveAllCallbacks respectively. Note that there is no Widget parameter specified. These functions are defined in the Xarm WObject class and so are available to any Xarm derived Widget object. As such, they implicitly know to what widget they belong.

The remainder of this document addresses the more common case in C++/Motif programming. Using non-static member functions as callback routines.

Callbacks in Xarm are maintained in a global list (actually, a Standard C++ STL vector). When an object registers a callback, it is added to the list and a destory callback is automatically added to the widget for which the callback is registered so that the memory allocated for the callback information is properly freed. Therefore, the programmer is free to add callbacks without worrying about memory leaks. A mechanism is provided to remove callbacks at any time if necessary.

There are two forms of each type of addCallback function in Xarm. One is used for CObject derived objects and is simply a shorthand form of the General addCallback functions.

CObject Derived Callbacks

Any object derived from one of the standard Xarm classes automatically inherits the CObject callback functions. Typically, these would be the Application object (as used in the examples) and possibly objects derived from one of the manager classes. An object derived from Form, for example, might create controls to be placed on the form. The Form-derived object would define member functions to handle events generated from the controls, onOK and onCancel for example. The Form-derived object could then use addCallback to register these functions to be called when one of these buttons is pressed. See the PasswordField class for a good example of the CObject-based callback features.

The argument list for CObject-based callbacks is different from the General addCallback functions only in that the pointer to object is not required because, since the functions are members of CObject, "this" is available and is cast to CObject. The CObject-based functions are listed below, but the descriptions are given in the General addCallback section along with the function signature requirements.

General addCallback Interface

The general version of the addCallback routines allow any C++ object to receive a callback. There is no requirement for an object to be derived from any standard base class. An object may have no inheritence hierarchy, or an arbitrarily complex one. The member function may be public, private or protected. It may also be virtual. The only requirements are that a member function callback must have the proper signature for the type of callback requested and that the function must not be static.

Because of the necessarily complex syntax of the actual addCallback function declarations, the member-function callback types will be shown using the same style as the CObject-based callbacks above. The signatures of the various callback functions are described below.

p_msg void p_msg(Widget w, XtPointer udata, XtPointer cdata);

This is the same signature as a standard XtCallbackProc.

See the man page for XtAddCallback for a complete description.

p_work_msg Boolean p_work_msg(XtPointer udata);

This is equivalent to XtWorkProc.

See the man page for XtAppAddWorkProc for a complete description.

p_timer_msg void p_timer_msg(XtPointer udata, XtIntervalId *tid);

This is equivalent to XtTimerCallbackProc.

See the man page for XtAppAddTimeout for a complete description.

p_input_msg void p_input_msg(XtPointer udata, int *ip, XtInputId *iid);

This is equivalent to XtInputCallbackProc.

See the man page for XtAppAddInput for a complete description.

p_event_msg void p_event_msg(Widget w, XtPointer udata, XEvent *xev, Boolean *pb);

This is equivalent to XtEventHandler.

See the man page for XtAddEventHandler for a complete description.

Callback Functions

addCallback(T *obj, p_msg mfunc, Widget w, _XtString type, XtPointer closure=NULL);

obj Pointer to the object to receive the callback.
mfunc member function of obj that is to be called.
w widget on which to register the callback.
type The name of the callback (XmNactivateCallback, etc.)
closure A pointer to any user-defined data to pass to the function.
C equivalent XtAddCallback

removeCallback(T *obj, p_msg mfunc, Widget w, _XtString type, XtPointer closure=NULL);

removeAllCallbacks(Widget w, _XtString type);

addProtocolCallback(T *obj, p_msg mfunc, Widget w, Atom property, Atom protocol, XtPointer closure=NULL);
obj Pointer to the object to receive the callback.
mfunc member function of obj that is to be called.
w widget on which to register the callback.
property property Atom
protocol protocol Atom to cause the callback
closure A pointer to any user-defined data to pass to the function.
C equivalent XmAddProtocolCallback()