2.16. 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;

           w Specifies the widget.  Must be of class Object or any subclass thereof.

           callback_name Specifies the callback list to be executed.

           call_data Specifies a callback-list-specific data value to pass to each of the callback

                procedure in the list, or NULL.

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

    void XtCallCallbackList(widget, callbacks, call_data)

          Widget widget;

          XtCallbackList callbacks;

          XtPointer call_data;

           widget Specifies the widget instance that contains the callback list.  Must be of class Object or any subclass thereof.

           callbacks Specifies the callback list to be executed.

           call_data Specifies a callback-list-specific data value to pass

                to each of the callback procedures in the list, or NULL.

2.16.1. Setting Widget State   

To modify the current values of resources associated with a widget instance, use XtSetValues.

    void XtSetValues(object, args, num_args)

          Widget object;

          ArgList args;

          Cardinal num_args;

           object Specifies the object whose resources are to be modified.  Must be of class Object or any subclass thereof.

                                       args Specifies the argument list of name/value pairs that contain the

                resources to be modified and their new values.

           num_args Specifies the number of entries in the argument list.

If the class of the object's parent is a subclass of constraintWidgetClass, XtSetValues also updates the object's constraints. It starts with the constraint resources specified for constraintWidgetClass and proceeds down the subclass chain to the parent's class. At each stage, it replaces the constraint resource fields with any values specified in the argument list. It then calls the constraint set_values procedures from constraintWidgetClass down to the parent's class. The constraint set_values procedures are called with widget arguments, as for all set_values procedures, not just the constraint records, so that they can make adjustments to the desired values based on full information about the widget. Any arguments specified that do not match a resource list entry are silently ignored.

If the object is of a subclass of RectObj, XtSetValues determines if a geometry request is needed by comparing the old object to the new object. If any geometry changes are required, XtSetValues restores the original geometry and makes the request on behalf of the widget.a If the geometry manager returns XtGeometryYes, XtSetValues calls the object's resize procedure. If the geometry manager returns XtGeometryDone, XtSetValues continues, as the object's resize procedure should have been called by the geometry manager. If the geometry manager returns XtGeometryNo, XtSetValues ignores the geometry request and continues. If the geometry manager returns XtGeometryAlmost, XtSetValues calls the set_values_almost procedure, which determines what should be done. XtSetValues then repeats this process, deciding once more whether the geometry manager should be called.

Finally, if any of the set_values procedures returned True, and the widget is realized, XtSetValues causes the widget's expose procedure to be invoked by calling XClearArea on the widget's window.

To modify the current values of resources associated with a widget instance using varargs lists, use XtVaSetValues.

    void XtVaSetValues(object, ...)

          Widget object;

           object Specifies the object whose resources are to be modified.  Must be of class Object or any subclass thereof.

           ...  Specifies the variable argument list of name/value pairs that

                contain the resources to be modified and their new values.

2.16.1.1. Widget State: the set_values Procedure   

The set_values procedure pointer in a widget class is of type XtSetValuesFunc.

    typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList, Cardinal*);

          Widget current;

          Widget request;

          Widget new;

          ArgList args;

          Cardinal *num_args;

           current Specifies a copy of the widget as it was before the XtSetValues call.

           request Specifies a copy of the widget with all values changed as asked for by the

                XtSetValues call before any class set_values procedures have been called.

           new Specifies the widget with the new values that are actually allowed.

           args Specifies the argument list passed to

                XtSetValues or the transformed argument list passed to XtVaSetValues.

           num_args Specifies the number of entries in the argument list.

Like the initialize procedure, set_values mostly deals only with the fields defined in the subclass, but it has to resolve conflicts with its superclass, especially conflicts over width and height.

Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, size calculations of a superclass are often incorrect for a subclass and, in this case, the subclass must modify or recalculate fields declared and computed by its superclass.

As an example, a subclass can visually surround its superclass display. In this case, the width and height calculated by the superclass set_values procedure are too small and need to be incremented by the size of the surround. The subclass needs to know if its superclass's size was calculated by the superclass or was specified explicitly. All widgets must place themselves into whatever size is explicitly given, but they should compute a reasonable size if no size is requested. How does a subclass know the difference between a specified size and a size computed by a superclass?

The request and new parameters provide the necessary information. The request widget is a copy of the widget, updated as originally requested. The new widget starts with the values in the request, but it has additionally been updated by all superclass set_values procedures called so far. A subclass set_values procedure can compare these two to resolve any potential conflicts. The set_values procedure need not refer to the request widget unless it must resolve conflicts between the current and new widgets. Any changes the widget needs to make, including geometry changes, should be made in the new widget.

In the above example, the subclass with the visual surround can see if the width and height in the request widget are zero. If so, it adds its surround size to the width and height fields in the new widget. If not, it must make do with the size originally specified. In this case, zero is a special value defined by the class to permit the application to invoke this behavior.

The new widget is the actual widget instance record. Therefore, the set_values procedure should do all its work on the new widget; the request widget should never be modified. If the set_values procedure needs to call any routines that operate on a widget, it should specify new as the widget instance.

Before calling the set_values procedures, the Intrinsics modify the resources of the request widget according to the contents of the arglist; if the widget names all its resources in the class resource list, it is never necessary to examine the contents of args.

Finally, the set_values procedure must return a Boolean that indicates whether the widget needs to be redisplayed. Note that a change in the geometry fields alone does not require the set_values procedure to return True; the X server will eventually generate an Expose event, if necessary. After calling all the set_values procedures, XtSetValues forces a redisplay by calling XClearArea if any of the set_values procedures returned True. Therefore, a set_values procedure should not try to do its own redisplaying.

Set_values procedures should not do any work in response to changes in geometry because XtSetValues eventually will perform a geometry request, and that request might be denied. If the widget actually changes size in response to a call to XtSetValues, its resize procedure is called. Widgets should do any geometry-related work in their resize procedure.

Note that it is permissible to call XtSetValues before a widget is realized. Therefore, the set_values procedure must not assume that the widget is realized.

2.16.1.2. Widget State: the set_values_almost Procedure   

The set_values_almost procedure pointer in the widget class record is of type XtAlmostProc.

    typedef void (*XtAlmostProc)(Widget, Widget, XtWidgetGeometry*, XtWidgetGeometry*);

          Widget old;

          Widget new;

          XtWidgetGeometry *request;

          XtWidgetGeometry *reply;

           old Specifies a copy of the object as it was before the XtSetValues call.

           new Specifies the object instance record.

           request Specifies the original geometry request that was sent to the geometry

                manager that caused XtGeometryAlmost to be returned.

           reply Specifies the compromise geometry that was returned by the geometry

                manager with XtGeometryAlmost.

The set_values_almost procedure is called when a client tries to set a widget's geometry by means of a call to XtSetValues, and the geometry manager cannot satisfy the request but instead returns XtGeometryNo or XtGeometryAlmost and a compromise geometry. The new object is the actual instance record. The x, y, width, height, and border_width fields contain the original values as they were before the XtSetValues call and all other fields contain the new values. The request parameter contains the new geometry request that was made to the parent. The reply parameter contains reply->request_mode equal to zero if the parent returned XtGeometryNo and contains the parent's compromise geometry otherwise. The set_values_almost procedure takes the original geometry and the compromise geometry and determines if the compromise is acceptable or whether to try a different compromise. It returns its results in the request parameter, which is then sent back to the geometry manager for another try. To accept the compromise, the procedure must copy the contents of the reply geometry into the request geometry; to attempt an alternative geometry, the procedure may modify any part of the request argument; to terminate the geometry negotiation and retain the original geometry, the procedure must set request->request_mode to zero. The geometry fields of the old and new instances must not be modified directly.

2.16.2. Translation Management   

Except under unusual circumstances, widgets do not hardwire the mapping of user events into widget behavior by using the event manager. Instead, they provide a default mapping of events into behavior that you can override.

The translation manager provides an interface to specify and manage the mapping of X event sequences into widget-supplied functionality, for example, calling procedure Abc when the y key is pressed.

The translation manager uses two kinds of tables to perform translations:

The action tables, which are in the widget class structure, specify the mapping of externally available procedure name strings to the corresponding procedure implemented by the widget class.

A translation table, which is in the widget class structure, specifies the mapping of event sequences to procedure name strings.

You can override the translation table in the class structure for a specific widget instance by supplying a different translation table for the widget instance. The resources XtNtranslations and XtNbaseTranslations are used to modify the class default translation table.