Callback data and events -- X Python Reference Manual

Next: Unsupported features Prev: Non-default visuals Up: Introduction Top: Top

# 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,
                                            None, 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.

Next: Unsupported features Prev: Non-default visuals Up: Introduction Top: Top