Query: xtmakegeometryrequest
OS: hpux
Section: 3
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
XtMakeGeometryRequest() XtMakeGeometryRequest()
Name
XtMakeGeometryRequest - request parent to change child's geometry.
Synopsis
XtGeometryResult XtMakeGeometryRequest(w, request, compromise_return)
Widget w;
XtWidgetGeometry *request;
XtWidgetGeometry *compromise_return;
Inputs
w Specifies the child widget that is making the request. Must be of class RectObj or any subclass thereof.
request Specifies the desired widget geometry (size, position, border width, and stacking order).
Outputs
compromise_return
Returns a compromise geometry when the function returns XtGeometryAlmost. May be NULL if the requesting widget is not interested
in handling XtGeometryAlmost.
Returns
A response to the request: XtGeometryYes, XtGeometryNo or XtGeometryAlmost.
Description
XtMakeGeometryRequest() requests the parent of w to change w's geometry to that specified in request. The request_mode field of request
specifies which elements of its geometry the object is asking to have changed, and the remaining fields of this structure specify the val-
ues for each of those elements. If a bit is not set in request_mode, then XtMakeGeometryRequest() may change that element of the geometry
in its effort to satisfy the requested changes.
There are three possible return values from this function, with the following meanings:
XtGeometryYes
The request was granted and has been performed (unless request_mode contained the XtCWQueryOnly bit). The object's internal core geome-
try fields have been updated and, if it is realized, the window has been correctly configured for the new geometry. The contents of com-
promise_return are undefined. w's resize() method may or may not have been called. XtMakeGeometryRequest() does not call that method,
but some parent widgets will call it in the process of satisfying the geometry request. The object should assume that it has not been
called and perform any necessary resize calculations.
XtGeometryNo
The request was denied. The contents of compromise_return are undefined.
XtGeometryAlmost
The request could not be satisfied exactly, but the object's parent has proposed a compromise geometry in compromise_return. If these
compromise values are immediately used in another call to XtMakeGeometryRequest() the request is guaranteed to succeed.
See the "Background" section below for a detailed listing of the steps followed by XtMakeGeometryRequest().
Usage
XtMakeGeometryRequest() should only be used in widget code by widgets which would like to change their own size. This is the only way that
a widget is allowed to change its own size.
Applications that want to set a widget size should use XtSetValues() on the various geometry resources of a widget.
A widget that wants to change the geometry of one of its children should use XtConfigureWidget(), XtMoveWidget() or XtResizeWidget().
Background
XtMakeGeometryRequest() performs the following tasks:
o If the widget is unmanaged or the widget's parent is not realized, it makes the changes to the widget's preferred geometry and returns
XtGeometryYes.
o If the parent is not a subclass of compositeWidgetClass or the parent's geometry_manager() method (the function pointed to by the
geometry_manager() field in the widget class record) is NULL, it issues an error.
o If the widget's being_destroyed field is True, it returns XtGeometryNo.
o If the widget x, y, width, height, and border_width fields are already equal to the requested values, it returns XtGeometryYes; other-
wise, it calls the parent's geometry_manager() method with the given parameters.
o If the parent's geometry manager returns XtGeometryYes, if XtCWQueryOnly is not set in request_mode (see Structures below for details),
and if the widget is realized, then XtMakeGeometryRequest() calls the Xlib XConfigureWindow() function to adjust the widget's window
(setting its size, location, and stacking order as appropriate).
o If the geometry manager returns XtGeometryDone, the change has been approved and actually has been done. In this case, XtMakeGeome-
tryRequest() does no configuring and returns XtGeometryYes. XtMakeGeometryRequest() never returns XtGeometryDone.
o Otherwise, XtMakeGeometryRequest() returns the resulting value from the parent's geometry manager.
Children of non-Composite widgets are always unmanaged; thus, XtMakeGeometryRequest() always returns XtGeometryYes when called by a child
of a non-Composite widget.
Structures
The return codes from geometry managers are:
typedef enum _XtGeometryResult {
XtGeometryYes, /* Request accepted */
XtGeometryNo, /* Request denied */
XtGeometryAlmost,/* Request denied but willing to take reply */
XtGeometryDone /* never returned by XtMakeGeometryRequest() */
} XtGeometryResult;
The XtWidgetGeometry structure is similar to 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;
XtMakeGeometryRequest(), like the Xlib XConfigureWindow() function, uses request_mode to determine which fields in the XtWidgetGeometry
structure you want to specify. 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 Xt Intrinsics also support the following value:
#define XtCWQueryOnly (1<<7)
XtCWQueryOnly indicates that the corresponding geometry request is only a query as to what would happen if this geometry request were made
and that no widgets should actually be changed.
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
XtSMDontChange indicates that the widget wants its current stacking order preserved. For precise definitions of Above, Below, TopIf, Bot-
tomIf, and Opposite, see the reference page for XConfigureWindow() in Volume Two, Xlib Reference Manual.
See Also
XtConfigureWidget(1), XtMakeResizeRequest(1), XtMoveWidget(1), XtResizeWidget(1),
geometry_manager(4).
Xt - Geometry Management XtMakeGeometryRequest()