2.14. Preferred Geometry 2.14. Preferred Geometry Some parents may be willing to adjust their layouts to accommodate the preferred geometries of their children. They can use XtQueryGeometry to obtain the preferred geometry and, as they see fit, can use or ignore any portion of the response.
To query a child widget's preferred geometry, use
XtQueryGeometry.
To discover a child's preferred geometry, the child's parent stores the new geometry in the corresponding fields of the intended structure, sets the corresponding bits in intended.request_mode, and calls XtQueryGeometry. The parent should set only those fields that are important to it so that the child can determine whether it may be able to attempt changes to other fields.
XtGeometryResult XtQueryGeometry(w, intended, preferred_return)
Widget w;
XtWidgetGeometry *intended, *preferred_return;
w Specifies the widget. Must be of class RectObj or any subclass thereof.
intended Specifies the new geometry the parent plans to give to the child, or NULL.
preferred_return Returns the child widget's preferred geometry.
XtQueryGeometry clears all bits in the preferred_return->request_mode field and checks the query_geometry field of the specified widget's class record. If query_geometry is not NULL, XtQueryGeometry calls the query_geometry procedure and passes as arguments the specified widget, intended, and preferred_return structures. If the intended argument is NULL, XtQueryGeometry replaces it with a pointer to an XtWidgetGeometry structure with request_mode equal to zero before calling the query_geometry procedure.
The query_geometry procedure pointer is of type
XtGeometryHandler.
The query_geometry procedure is expected to examine the bits set in request->request_mode, evaluate the preferred geometry of the widget, and store the result in preferred_return (setting the bits in preferred_return->request_mode corresponding to those geometry fields that it cares about). If the proposed geometry change is acceptable without modification, the query_geometry procedure should return XtGeometryYes. If at least one field in preferred_return with a bit set in preferred_return->request_mode is different from the corresponding field in request or if a bit was set in preferred_return->request_mode that was not set in the request, the query_geometry procedure should return XtGeometryAlmost. If the preferred geometry is identical to the current geometry, the query_geometry procedure should return XtGeometryNo.
typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry*, XtWidgetGeometry*);
Widget w;
XtWidgetGeometry *request;
XtWidgetGeometry *preferred_return;
w Passes the child widget whose preferred geometry is required.
request Passes the geometry changes which the parent plans to make.
preferred_return Passes a structure in which the child returns its preferred geometry.
After calling the query_geometry procedure or if the query_geometry field is NULL, XtQueryGeometry examines all the unset bits in preferred_return->request_mode and sets the corresponding fields in preferred_return to the current values from the widget instance. If CWStackMode is not set, the stack_mode field is set to XtSMDontChange. XtQueryGeometry returns the value returned by the query_geometry procedure or XtGeometryYes if the query_geometry field is NULL.
Therefore, the caller can interpret a return of XtGeometryYes as not needing to evaluate the contents of the reply and, more important, not needing to modify its layout plans. A return of XtGeometryAlmost means either that both the parent and the child expressed interest in at least one common field and the child's preference does not match the parent's intentions or that the child expressed interest in a field that the parent might need to consider. A return value of XtGeometryNo means that both the parent and the child expressed interest in a field and that the child suggests that the field's current value in the widget instance is its preferred value. In addition, whether or not the caller ignores the return value or the reply mask, it is guaranteed that the preferred_return structure contains complete geometry information for the child.
Parents are expected to call XtQueryGeometry in their layout routine and wherever else the information is significant after change_managed has been called. The first time it is invoked, the changed_managed procedure may assume that the child's current geometry is its preferred geometry. Thus, the child is still responsible for storing values into its own geometry during its initialize procedure.
