Query: xtquerygeometry
OS: hpux
Section: 3
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
XtQueryGeometry() XtQueryGeometry()
Name
XtQueryGeometry - query a child widget's preferred geometry.
Synopsis
XtGeometryResult XtQueryGeometry(w, intended, preferred_return)
Widget w; XtWidgetGeometry *intended; XtWidgetGeometry *preferred_return;
Inputs
w Specifies the widget whose geometry preferences are being queried.
intended Specifies any changes the parent plans to make to the child's geometry, or NULL.
preferred_return
Returns the child widget's preferred geometry.
Returns
A response to the request: XtGeometryYes, XtGeometryNo, or XtGeometryAlmost.
Description
XtQueryGeometry() invokes a widget's query_geometry() method to determine its preferred (or at least its current) geometry. Some parents
may want to ask their children what their ideal geometry would be if they were not constrained at all. Others, when about to set some
aspect of the geometry (such as width), may query the child to determine what its preferred geometry would be given this new constraint.
For example, a label widget that supported word-wrapping might want a larger height if its width was being made smaller.
The intended structure specifies the geometry values that the parent plans to set. The geometry_return structure returns the child's pre-
ferred geometry. Each argument has a flags field in which bits are set to indicate which of the geometry fields the respective widgets
have set. The return value of the function may be one of the following values:
XtGeometryYes
The proposed change is acceptable to the child without modifications. This means that the proposed changes are exactly what the child
would prefer.
XtGeometryAlmost
The child does not agree entirely with the proposed change. At least one field in preferred_return with a bit set in pre-
ferred_return->request_mode is different from the corresponding field in request, or a bit was set in preferred_return->request_mode that
was not set in the request. The parent can use or ignore the returned values in preferred_return.
XtGeometryNo
The child would prefer that no changes were made to its current geometry. The parent can respect or ignore this response.
If the child widget does not have a query_geometry() method, XtQueryGeometry() fills preferred_return with the widget's current geometry,
sets preferred_return->request_mode to zero, and returns XtGeometryYes.
If the intended argument is NULL, XtQueryGeometry() replaces it with a pointer to an XtWidgetGeometry structure with a request_mode field
of zero before calling the query_geometry() method.
After calling a child's query_geometry() method, XtQueryGeometry() sets all fields in preferred_return that do not have bits set in pre-
ferred_return->request_mode to the widget's current geometry values. XtQueryGeometry() clears all bits in preferred_return->request_mode
before calling the query_geometry() method, and does not modify the bits set by the child.
See the "Background" section below for more information. See query_geometry()(4) for more information on how a widget's query_geometry()
method should behave.
Usage
Only widgets should ever need to use XtQueryGeometry(), and then should only call it for their children. It is usually used when a compos-
ite widget is trying to layout its children, for example, when the changed_managed() method is called.
Many widgets can simply examine their children's core.width and core.height fields and use those while calculating layout. Widgets are
supposed to set these fields to their desired geometry within their initialize() and set_values() methods. Since these are the only geome-
try fields that many parents care about, this technique is often sufficient. If a widget is re-laying out its children from its resize()
method, however, it may make more sense to use XtQueryGeometry(). If a widget has been given a size that is too small, then its children
may also be smaller than they prefer. In this case, the children's current sizes are not their preferred sizes, and they must be asked how
large they would like to be.
Note that on return from XtQueryGeometry(), preferred_return always contains the preferred or current geometry (which the widget sets to
its preferred geometry when it initializes itself) of the widget. This means that a parent that is willing to respect its child's layout
wishes can call XtQueryGeometry() and use the contents of preferred_return whatever the return value of the function is. If a parent wants
to query a preferred size without proposing any particular changes, it can pass NULL for intended.
If a parent is not willing to respond to return values of either XtGeometryAlmost or XtGeometryNo need not bother to call XtQueryGeome-
try(); it can just make the geometry changes that it plans to make.
The cases described in the above two paragraphs are widgets that always respect or never respect their children's preferences. Neither
case takes advantage of the full power of this geometry querying scheme. The most common interesting use of XtQueryGeometry(), is when a
parent wants to constrain the width or height of a child, and would like to know the child's preferred size in the other dimension. A
menubar laid out in a Form widget, for example, will probably be laid out across the top and have its width constrained to be equal to the
width of the form. If the form becomes too small to display all the items in the menu bar, the menubar might want to wrap onto a second
line. In this case, the parent would set the width in intended, and use the height returned in preferred_return, regardless of the return
value of the function. Note that in this case the parent is ignoring any return values of XtGeometryNo-it must constrain the width of the
menubar even if the child would prefer that the width not be constrained. Many widgets are not as sophisticated as this hypothetical menu
bar widget, and cannot to adjust their layout when they find that only one dimension is constrained. Even these children will return a
preferred size however, and the form can use the preferred height and ignore the preferred width. The Athena Box widget is an example of a
widget that modifies its layout when it finds that it is constrained in one dimension.
Note that if XtQueryGeometry() returns XtGeometryYes, the parent can simply proceed with the geometry changes it indicated in intended
without examining the contents of preferred_return. In practice, however, this return value is uncommon, and it may not be worth writing
special case code to handle it. In the examples given above, the parent never even needs to check the return value of the function.
Example
Only three widgets in the Athena widget set call XtQueryGeometry(), and none of the Intrinsics widgets call it. The following code is from
the Athena Viewport widget.
if (!w->viewport.allowvert) {
intended->height = *clip_height;
intended->request_mode = CWHeight;
}
if (!w->viewport.allowhoriz) {
intended->width = *clip_width;
intended->request_mode = CWWidth;
}
if ( query ) {
if ( (w->viewport.allowvert w->viewport.allowhoriz) ) {
XtQueryGeometry( child, intended, &preferred );
if ( !(intended->request_mode & CWWidth) )
if ( preferred.request_mode & CWWidth )
intended->width = preferred.width;
else
intended->width = child->core.width;
if ( !(intended->request_mode & CWHeight) )
if ( preferred.request_mode & CWHeight )
intended->height = preferred.height;
else
intended->height = child->core.height;
}
}
Background
If XtQueryGeometry() is called from within a geometry_manager() procedure for the widget that issued XtMakeGeometryRequest() or XtMakeRe-
sizeRequest(), the results are not guaranteed to be consistent with the requested changes. The change request passed to the geometry man-
ager takes precedence over the preferred geometry.
The query_geometry() procedure may assume that no XtMakeResizeRequest() or XtMakeGeometryRequest() is in progress for the specified widget;
that is, it is not required to construct a reply consistent with the requested geometry if such a request were actually outstanding.
Structures
The possible return values of XtQueryGeometry() are defined as follows:
typedef enum {
XtGeometryYes, /* Request accepted */
XtGeometryNo, /* Request denied */
XtGeometryAlmost,/* Request denied but willing to take reply */
XtGeometryDone /* never returned by XtQueryGeometry() */
} 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;
XtQueryGeometry(), like the Xlib XConfigureWindow() function, uses request_mode to determine which fields in the XtWidgetGeometry structure
you that the parent and the child have set. 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 XConfigureWindow() in Volume Two, Xlib
Reference Manual. XtSMDontChange indicates that the widget wants its current stacking order preserved.
See Also
XtMakeGeometryRequest(1),
query_geometry(4).
Xt - Geometry Management XtQueryGeometry()