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.
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.
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.
addCallback(T *obj, p_msg mfunc, Widget w, _XtString type, XtPointer closure=NULL);
Description: Add a callback on the specified widget.
| 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);
Description: Remove all callbacks of the specified type
from the Widget w.
C equivalent : XtRemoveAllCallbacks().
| 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() |