1.4 Callback data and events

The following table lists the functions and methods that install callback functions together with the calling sequence of the callback function.

Xt.AddInput:                   callback(client_data, fileno, id)
Xt.AddTimeOut:                 callback(client_data, id)
Xt.AddWorkProc:                callback(client_data)
Xt.AddEventHandler:            continue_to_dispatch = callback(w,
                                       client_data, call_data)
Xt.AddRawEventHandler:         continue_to_dispatch = callback(w,
                                       client_data, call_data)
Xt.AddActions:                 callback(w, call_data, plist)
Xt.AddActionHook:              callback(w, client_data, action,
                                        call_data, plist)
w.AddCallback:                 callback(w, client_data, call_data)
insertPosition resource:       position = callback(w)
createPopupChildProc resource: callback(w)
dropProc resource:             callback(w, None, call_data)
dragProc resource:             callback(w, None, call_data)
transferProc resource:         callback(w, client_data, selection,
                                        type, value, length, format)
convertProc resource:          type, value, format = callback(w,
                                        selection, target, max_length,
                                        client_data, request_id)

Here, client_data is the user-supplied data, fileno is the file descriptor that was being checked, id is the identifier that Xt.AddInput() or Xt.AddTimeOut() returned, w is the widget object on behalf of which the callback is called or installed, and call_data is the data giving the reason for the callback which the library supplies. If the callback function for an event handler returns 0, the continue_to_dispatch return parameter of the library function is cleared. See the manual pages for XtAddEventHandler() and XtAddRawEventHandler().

The call_data parameter is an object representing the structure that is passed by the library, possibly ultimately by the user through the widget method CallCallbacks(). The object has attributes with the same names as the fields of the structure it represents. Many attributes can be changed, and the change is reflected in the underlying structure. This is especially useful for the XmTextField and XmText widgets.

The call_data parameter of the event and action handlers is always an object representing a XEvent structure. The structure that is passed to a callback installed with the AddCallback() method depends on the class of the widget and the type of the callback. For Athena widgets, the structure is a XEvent. For Motif widgets, the structure contains at least the fields reason and event. The event is a XEvent structure. Which attributes exist can be seen by using the __members__ attribute which returns a list of attribute names. The name of the structure is given by the __name__ attribute.

The attributes of the call_data parameter are only valid as long as the callback function is active. It is useless to keep a reference to the object for use after the callback function returns. Also, the object returned by a reference to the event attribute of a Motif callback is invalid when the callback is not active anymore. Access to attributes of these objects result in an exception.

Here is an example of a Motif TextField widget that uses a verification callback to make sure only digits are entered. Accepted digits are changed to '*', so this code can be used as the basis for a function that reads personal identification numbers.

    import Xt, Xm

    def cbmodify(w, client_data, call_data):
        if call_data.text:
            # only accept digits...
            for c in call_data.text:
                if c not in '0123456789':
                    call_data.doit = 0
            # ... and change them into *'s
            call_data.text = '*' * len(call_data.text)

    top = Xt.Initialize()
    text = top.CreateManagedWidget('text', Xm.TextField, {})
    text.AddCallback('modifyVerifyCallback', cbmodify, None)
    top.RealizeWidget()
    Xt.MainLoop()

Some functions and methods return or accepts as parameters objects representing XEvent structures. These objects are compatible with the call_data objects described above. Event objects that are returned by functions and methods remain valid as long as there is a reference to them.