set_valuesA(3x) — HP-UX 9.05

NAME

set_values_almost − RectObj class method to negotiate compromise geometries.

Synopsis

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

    Widget current;
    Widget set;
    XtWidgetGeometry *request_in_out;
    XtWidgetGeometry *reply;

Inputs

currentSpecifies a copy of the object made by XtSetValues() before any resources were set or set_values() methods were called.

setSpecifies the object. It has had its resources set and fields modified by set_values(), set_value_hook(), and Constraint set_values() methods.

request_in_out
Specifies the geometry request that was sent to the geometry manager.

replySpecifies the compromise geometry that was returned by the geometry manager.

Outputs

request_in_out
Returns the desired geometry; can be empty, the compromise geometry, or some new geometry to try.

Description

The set_values_almost() method is registered on the set_values_almost() field of the RectObj or Core class part structure. It is invoked by XtSetValues() when a widget’s geometry fields have changed, but the widget’s parent’s geometry_manager() will not allow the requested geometry and returns XtGeometryNo or XtGeometryAlmost. When a widget’s geometry fields have been changed from the argument list, or by one of the set_values() methods, Constraint set_values(), or set_values_hook() methods that were called to handle the resource changes, XtSetValues() restores the original values, and calls XtMakeGeometryRequest() to actually request the new values from the widget’s parent. If the return value of the request is XtGeometryNo or XtGeometryAlmost, XtSetValues() calls the widget’s set_values_almost() method to determine whether the geometry should be left as is, the proposed compromise geometry accepted, or some other geometry tried. The current and set arguments are the same as the arguments by the same name that are passed to the set_values() method, except that the geometry fields of set (x, y, width, height, and border_width) contain the original values of the widget geometry, not the requested values. The request_in_out argument is the geometry request made by XtSetValues(); it contains the new values of the geometry fields that changed, and request_in_out->request_mode contains flags that indicate which of those fields are set. If the geometry request returned XtGeometryAlmost, then reply contains the proposed compromise geometry. If the request returned XtGeometryNo, then reply->request_mode will be zero. The set_values_almost() method should do one of the following:

•Set request_in_out->request_mode to zero to terminate geometry negotiation and retain the original geometry.

•Copy the contents of reply into request_in_out to accept the compromise geometry. The parent is guaranteed to accept the compromise.

•Set some other geometry proposal into request_in_out. If the parent does not accept this geometry, the set_values_almost() method will be called again. Note that the set_values_almost() method is not chained as are the set_values(), set_values_hook(), and Constraint set_values() methods. A widget class can inherit the set_values_almost() method of its superclass by specifying XtInheritSetValuesAlmost on the set_values_almost() field of the RectObj or Core class part structure. It is not specified what will happen if the set_values_almost() field is NULL (though some of the Xaw widgets have this method NULL). The Intrinsics specification says in one place that set_value_almost() will be called on a result of XtGeometryNo, and says in another that it will not. Until the specification is clarified, set_values_almost() methods should be prepared to handle this case, but widget must not rely on these methods to detect it. See set_values(4) for more information on the current and set arguments. See XtSetValues(1) for a full description of the resource setting algorithm. See XtMakeGeometryRequest(1) and geometry_manager(4) for details on geometry management.

Usage

Most classes will inherit this method from their superclass. The RectObj set_values_almost() method always accepts the compromise geometry; it is shown in the example below.

Example

The following procedure is the RectObj set_values_almost() method. It simply copies the contents of reply into request_in_out in order to accept the compromise geometry.

/*ARGSUSED*/
static void RectSetValuesAlmost(old, new, request, reply)
    Widget              old;
    Widget              new;
    XtWidgetGeometry    *request;
    XtWidgetGeometry    *reply;
{
    *request = *reply;
}

Structures

The XtWidgetGeometry structure is similar, but not identical, to the corresponding Xlib structure:

typedef unsigned long XtGeometryMask;
typedef struct {
XtGeometryMask request_mode;
Position x, y;
Dimension width, height;
Dimension border_width;
Widget sibling;
int stack_mode;
} XtWidgetGeometry;

The request_mode definitions are from <X11/X.h>:

#defineCWX(1<<0)
#defineCWY(1<<1)
#defineCWWidth(1<<2)
#defineCWHeight(1<<3)
#defineCWBorderWidth(1<<4)
#defineCWSibling(1<<5)
#defineCWStackMode(1<<6)

The stack_mode definitions are from <X11/X.h>:

#defineAbove0
#defineBelow1
#defineTopIf2
#defineBottomIf3
#defineOpposite4

The Intrinsics also support the following value:

#defineXtSMDontChange5

For precise definitions of Above, Below, TopIf, BottomIf, and Opposite, see the reference page for ConfigureWindow() in Volume Two, Xlib Reference Manual. XtSMDontChange indicates that the widget wants its current stacking order preserved.

Museum

Related Articles