Query: set_valuesa
OS: hpux
Section: 3
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
set_values_almost() set_values_almost()
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
current Specifies a copy of the object made by XtSetValues() before any resources were set or set_values() methods were called.
set Specifies 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.
reply Specifies 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 geom-
etry 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 val-
ues.
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 XtGeome-
tryAlmost, 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:
o Set request_in_out->request_mode to zero to terminate geometry negotiation and retain the original geometry.
o Copy the contents of reply into request_in_out to accept the compromise geometry. The parent is guaranteed to accept the compromise.
o 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 geome-
try; 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>:
#define CWX(1<<0)
#define CWY(1<<1)
#define CWWidth(1<<2)
#define CWHeight(1<<3)
#define CWBorderWidth(1<<4)
#define CWSibling(1<<5)
#define CWStackMode(1<<6)
The stack_mode definitions are from <X11/X.h>:
#define Above0
#define Below1
#define TopIf2
#define BottomIf3
#define Opposite4
The Intrinsics also support the following value:
#define XtSMDontChange5
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.
See Also
XtMakeGeometryRequest(1), XtSetValues(1),
Core(3),
geometry_manager(4), set_values(4).
Xt - Intrinsics Methods set_values_almost()