XtQueryGeometry()XtQueryGeometry()NameXtQueryGeometry - query a child widget's preferred geometry.
Synopsis
XtGeometryResult XtQueryGeometry(w, intended, preferred_return)
Widget w; XtWidgetGeometry *intended; XtWidgetGeome‐
try *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 XtGeome‐
tryAlmost.
DescriptionXtQueryGeometry() invokes a widget's query_geometry() method to deter‐
mine 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 deter‐
mine 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 val‐
ues:
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 geom‐
etry. The parent can respect or ignore this response.
If the child widget does not have a query_geometry() method, XtQueryGe‐
ometry() 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_geome‐
try() 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 composite
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 suffi‐
cient. 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 pre‐
ferred_return whatever the return value of the function is. If a par‐
ent 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 XtGe‐
ometryAlmost or XtGeometryNo need not bother to call XtQueryGeometry();
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 wid‐
gets 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 with‐
out 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() proce‐
dure for the widget that issued XtMakeGeometryRequest() or XtMakeResiz‐
eRequest(), the results are not guaranteed to be consistent with the
requested changes. The change request passed to the geometry manager
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 struc‐
ture you that the parent and the child have set. The request_mode def‐
initions 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 Ref‐
erence Manual. XtSMDontChange indicates that the widget wants its cur‐
rent stacking order preserved.
See AlsoXtMakeGeometryRequest(1),
query_geometry(4).
Xt - Geometry Management XtQueryGeometry()
