geometry_ma(3) — OSF1 1.0

Name

geometry_manager — Composite method called when a child requests a new geometry.

Synopsis

typedef XtGeometryResult (∗XtGeometryHandler)(Widget, XtWidgetGeometry ∗);

      Widget w;
      XtWidgetGeometry ∗request;
      XtWidgetGeometry ∗geometry_return;

Arguments

wSpecifies the widget.

requestSpecifies the requested geometry.

geometry_return
Specifies the reply geometry.

Description

The geometry_manager method’s job is to respond to a proposal from a child for a new size of that child.

A class can inherit its superclass’s geometry manager during class initialization, by using the XtInheritGeometryManager symbol in the class structure initialization. However, there is no default geometry manager defined by Composite. Therefore, direct subclasses of Composite or Constraint either define a geometry_manager or set it to NULL.

A bit set to zero in the request’s mask field means that the child widget does not care about the value of the corresponding field. Then, the geometry manager can change it as it wishes. A bit set to 1 means that the child wants that geometry element changed to the value in the corresponding field.

If the geometry manager can satisfy all changes requested, and if XtCWQueryOnly is not specified, it updates the widget’s x, y, width, height, and border_width values appropriately. Then, it returns XtGeometryYes, and the value of the geometry_return argument is undefined. The widget’s window is moved and resized automatically by XtMakeGeometryRequest.

Homogeneous Composite widgets often find it convenient to treat the widget making the request the same as any other widget, possibly reconfiguring it as part of its layout process, unless XtCWQueryOnly is specified. If it does this, it should return XtGeometryDone to inform XtMakeGeometryRequest that it does not need to do the configuration itself.

Although XtMakeGeometryRequest resizes the widget’s window (if the geometry manager returns XtGeometryYes), it does not call the widget class’s resize procedure. The requesting widget must perform whatever resizing calculations are needed explicitly.

If the geometry manager chooses to disallow the request, the widget cannot change its geometry. The value of the geometry_return argument is undefined, and the geometry manager returns XtGeometryNo.

Sometimes the geometry manager cannot satisfy the request exactly, but it may be able to satisfy a similar request. That is, it could satisfy only a subset of the requests (for example, size but not position) or a lesser request (for example, it cannot make the child as big as the request but it can make the child bigger than its current size). In such cases, the geometry manager fills in geometry_return with the actual changes it is willing to make, including an appropriate mask, and returns XtGeometryAlmost.

If a bit in geometry_return−>request_mode is 0, the geometry manager does not change the corresponding value if the geometry_return argument is used immediately in a new request. If a bit is 1, the geometry manager does change that element to the corresponding value in eometry_return. More bits may be set in geometry_return than in the original request if the geometry manager intends to change other fields should the child accept the compromise.

When XtGeometryAlmost is returned, the widget must decide if the compromise suggested in geometry_return is acceptable. If it is, the widget must not change its geometry directly; rather, it must make another call to XtMakeGeometryRequest.

If the next geometry request from this child uses the geometry_return box filled in by an XtGeometryAlmost return, and if there have been no intervening geometry requests on either its parent or any of its other children, the geometry manager must grant the request, if possible. That is, if the child asks immediately with the returned geometry, it should get an answer of XtGeometryYes. However, the user’s window manager may affect the final outcome.

To return an XtGeometryYes, the geometry manager frequently rearranges the position of other managed children by calling XtMoveWidget. However, a few geometry managers may sometimes change the size of other managed children by calling XtResizeWidget or XtConfigureWidget. If XtCWQueryOnly is specified, the geometry manager must return how it would react to this geometry request without actually moving or resizing any widgets.

Geometry managers must not assume that the request and geometry_return arguments point to independent storage. The caller is permitted to use the same field for both, and the geometry manager must allocate its own temporary storage, if necessary.

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 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.

XtMakeGeometryRequest, like the Xlib XConfigureWindow function, uses request_mode to determine which fields in the XtWidgetGeometry structure you want to specify.

The stack_mode definitions are from <X11/X.h>:

#defineAbove0
#defineBelow1
#defineTopIf2
#defineBottomIf3
#defineOpposite4

The Intrinsics also support the following value:

#defineXtSMDontChange5

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.

Examples

The following is the geometry_manager method of the Athena Form widget class:

/∗ ARGSUSED ∗/
static XtGeometryResult GeometryManager(w, request, reply)
    Widget w;
    XtWidgetGeometry ∗request;
    XtWidgetGeometry ∗reply;    /∗ RETURN ∗/
{
    FormConstraints form = (FormConstraints)w->core.constraints;
    XtWidgetGeometry allowed;
     if ((request->request_mode & ~(XtCWQueryOnly | CWWidth | CWHeight)) ||
            !form->form.allow_resize)
        return XtGeometryNo;
      if (request->request_mode & CWWidth)
        allowed.width = request->width;
    else
        allowed.width = w->core.width;
     if (request->request_mode & CWHeight)
        allowed.height = request->height;
    else
        allowed.height = w->core.height;
     if (allowed.width == w->core.width &&
            allowed.height == w->core.height)
        return XtGeometryNo;
     if (!(request->request_mode & XtCWQueryOnly)) {
        /∗ reset virtual width and height. ∗/
        form->form.virtual_width = w->core.width = allowed.width;
        form->form.virtual_height = w->core.height = allowed.height;
        RefigureLocations( (FormWidget)w->core.parent );
    }
    return XtGeometryYes;
}

Museum