aboutsummaryrefslogtreecommitdiff
path: root/libXt/specs/CH06
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2011-03-25 10:41:05 +0000
committermarha <marha@users.sourceforge.net>2011-03-25 10:41:05 +0000
commit272e57235cd60a2e65ac8258d96a02eb3939b687 (patch)
tree789d74bd6ec1cc468f1f81aab97d4e4dfdb2d5c5 /libXt/specs/CH06
parentb39f063f74bf0163eaf34db03134f226d18142ec (diff)
downloadvcxsrv-272e57235cd60a2e65ac8258d96a02eb3939b687.tar.gz
vcxsrv-272e57235cd60a2e65ac8258d96a02eb3939b687.tar.bz2
vcxsrv-272e57235cd60a2e65ac8258d96a02eb3939b687.zip
git update until 25 Mar 2011
xserver fontconfig glproto libXau libXft libXmu libfontenc libxcb mesa mkfontscale pixman randrproto xkeyboard-config xtrans xwininfo updated following packages: xproto-7.0.21 xineramaproto-1.2.1 libXt-1.1.1 libxkbfile-1.0.7 libXpm-3.5.9 libXfont-1.4.3 libXaw-1.0.9 bdftopcf-1.0.3 encodings-1.0.4 fixesproto-5.0 font-adobe-100dpi-1.0.3 font-adobe-75dpi-1.0.3 font-adobe-utopia-100dpi-1.0.4 font-adobe-utopia-75dpi-1.0.4 font-adobe-utopia-type1-1.0.4 font-alias-1.0.3 font-arabic-misc-1.0.3 font-bh-100dpi-1.0.3 font-bh-75dpi-1.0.3 font-bh-lucidatypewriter-100dpi-1.0.3 font-bh-lucidatypewriter-75dpi-1.0.3 font-bh-ttf-1.0.3 font-bh-type1-1.0.3 font-bitstream-100dpi-1.0.3 font-bitstream-75dpi-1.0.3 font-bitstream-speedo-1.0.2 font-bitstream-type1-1.0.3 font-cronyx-cyrillic-1.0.3 font-cursor-misc-1.0.3 font-daewoo-misc-1.0.3 font-dec-misc-1.0.3 font-ibm-type1-1.0.3 font-isas-misc-1.0.3 font-jis-misc-1.0.3 font-micro-misc-1.0.3 font-misc-cyrillic-1.0.3 font-misc-ethiopic-1.0.3 font-misc-meltho-1.0.3 font-misc-misc-1.1.2 font-mutt-misc-1.0.3 font-schumacher-misc-1.1.2 font-screen-cyrillic-1.0.4 font-sony-misc-1.0.3 font-sun-misc-1.0.3 font-util-1.2.0 font-winitzki-cyrillic-1.0.3 font-xfree86-type1-1.0.4
Diffstat (limited to 'libXt/specs/CH06')
-rw-r--r--libXt/specs/CH061110
1 files changed, 1110 insertions, 0 deletions
diff --git a/libXt/specs/CH06 b/libXt/specs/CH06
new file mode 100644
index 000000000..34c2861b0
--- /dev/null
+++ b/libXt/specs/CH06
@@ -0,0 +1,1110 @@
+.\" $Xorg: CH06,v 1.3 2000/08/17 19:42:45 cpqbld Exp $
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" X Consortium
+.\"
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of the X Consortium shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from the X Consortium.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" Digital Equipment Corporation, Maynard, Massachusetts.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for any
+.\" purpose and without fee is hereby granted, provided that the above copyright
+.\" notice appears in all copies and that both that copyright notice and this
+.\" permission notice appear in supporting documentation, and that the name of
+.\" Digital not be used in in advertising or publicity pertaining
+.\" to distribution of the software without specific, written prior permission.
+.\" Digital makes no representations about the suitability of the
+.\" software described herein for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\"
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 6\fP\s-1
+
+\s+1\fBGeometry Management\fP\s-1
+.sp 2
+.nr H1 6
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 6 \(em Geometry Management
+.XE
+.LP
+.IN "geometry_manager procedure"
+.IN "Geometry Management"
+.IN "Configure Window"
+A widget does not directly control its size and location;
+rather, its parent is responsible for controlling them.
+Although the position of children is usually left up to their parent,
+the widgets themselves often have the best idea of their optimal sizes
+and, possibly, preferred locations.
+.LP
+To resolve physical layout conflicts between sibling widgets and between
+a widget and its parent, the \*(xI provide the geometry management mechanism.
+Almost all
+composite
+widgets have a geometry manager specified in the \fIgeometry_manager\fP field
+in the widget class record that is responsible for the size, position, and
+stacking order of the widget's children.
+The only exception is fixed boxes,
+which create their children themselves and can ensure that
+their children will never make a geometry request.
+
+.NH 2
+Initiating Geometry Changes
+.LP
+.XS
+\*(SN Initiating Geometry Changes
+.XE
+Parents, children, and clients each initiate geometry changes differently.
+Because a parent has absolute control of its children's geometry,
+it changes the geometry directly by calling
+.PN XtMove\%Widget ,
+.PN XtResizeWidget ,
+or
+.PN XtConfigureWidget .
+A child must ask its parent for a geometry change by calling
+.PN XtMakeGeometryRequest
+or
+.PN XtMakeResizeRequest .
+An application or other client code initiates a geometry change by calling
+.PN XtSetValues
+on the appropriate geometry fields,
+thereby giving the widget the opportunity to modify or reject the client
+request before it gets propagated to the parent and the opportunity
+to respond appropriately to the parent's reply.
+.LP
+When a widget that needs to change its size, position, border width,
+or stacking depth asks its parent's geometry manager to make the desired
+changes,
+the geometry manager can allow the request, disallow the request, or
+suggest a compromise.
+.LP
+When the geometry manager is asked to change the geometry of a child,
+the geometry manager may also rearrange and resize any or all
+of the other children that it controls.
+The geometry manager can move children around freely using
+.PN XtMoveWidget .
+When it resizes a child (that is, changes the width, height, or
+border width) other than the one making the request,
+it should do so by calling
+.PN XtResizeWidget .
+The requesting child may be given special treatment; see Section 6.5.
+It can simultaneously move and resize a child with a single call to
+.PN XtConfigureWidget .
+.LP
+Often, geometry managers find that they can satisfy a request only if
+they can reconfigure a widget that they are not in control of; in particular,
+the
+composite
+widget may want to change its own size.
+In this case,
+the geometry manager makes a request to its parent's geometry manager.
+Geometry requests can cascade this way to arbitrary depth.
+.LP
+Because such cascaded arbitration of widget geometry can involve extended
+negotiation,
+windows are not actually allocated to widgets at application
+startup until all widgets are satisfied with their geometry;
+see Sections 2.5 and 2.6.
+.NT Notes
+.IP 1. 5
+The \*(xI treatment of stacking requests is deficient in several areas.
+Stacking requests for unrealized widgets are granted but will have no effect.
+In addition, there is no way to do an
+.PN XtSetValues
+that will generate a stacking geometry request.
+.IP 2. 5
+After a successful geometry request (one that returned
+.PN XtGeometryYes ),
+a widget does not know whether its resize procedure has been called.
+Widgets should have resize procedures that can be called more than once
+without ill effects.
+.NE
+
+.NH 2
+General Geometry Manager Requests
+.XS
+\*(SN General Geometry Manager Requests
+.XE
+.LP
+When making a geometry request, the child specifies an
+.PN XtWidgetGeometry
+structure.
+.LP
+.IN "XtGeometryMask"
+.KS
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef unsigned long XtGeometryMask;
+
+typedef struct {
+ XtGeometryMask request_mode;
+ Position x, y;
+ Dimension width, height;
+ Dimension border_width;
+ Widget sibling;
+ int stack_mode;
+} XtWidgetGeometry;
+.De
+.eM
+.KE
+.LP
+To make a general geometry manager request from a widget, use
+.PN XtMakeGeometryRequest .
+.LP
+.IN "XtMakeGeometryRequest" "" "@DEF@"
+.sM
+.FD 0
+XtGeometryResult XtMakeGeometryRequest(\fIw\fP, \fIrequest\fP, \
+\fIreply_return\fP)
+.br
+ Widget \fIw\fP;
+.br
+ XtWidgetGeometry *\fIrequest\fP;
+.br
+ XtWidgetGeometry *\fIreply_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request. \*(rI
+.IP \fIrequest\fP 1i
+Specifies the desired widget geometry (size, position, border width,
+and stacking order).
+.IP \fIreply_return\fP 1i
+Returns the allowed widget size, or may be NULL
+if the requesting widget is not interested in handling
+.PN XtGeometryAlmost .
+.LP
+.eM
+Depending on the condition,
+.PN XtMakeGeometryRequest
+performs the following:
+.IP \(bu 5
+If the widget is unmanaged or the widget's parent is not realized,
+it makes the changes and returns
+.PN XtGeometryYes .
+.IP \(bu 5
+If the parent's class is not a subclass of
+.PN compositeWidgetClass
+or the parent's \fIgeometry_manager\fP field is NULL,
+it issues an error.
+.IP \(bu 5
+If the widget's \fIbeing_destroyed\fP field is
+.PN True ,
+it returns
+.PN XtGeometryNo .
+.IP \(bu 5
+If the widget \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, and
+\fIborder_width\fP fields are
+all equal to the requested values,
+it returns
+.PN XtGeometryYes ;
+otherwise, it calls the parent's geometry_manager procedure
+with the given parameters.
+.IP \(bu 5
+If the parent's geometry manager returns
+.PN XtGeometryYes
+and if
+.PN XtCWQueryOnly
+is not set in \fIrequest->request_mode\fP
+and if the widget is realized,
+.PN XtMakeGeometryRequest
+calls the
+.PN XConfigureWindow
+Xlib function to reconfigure the widget's window (set its size, location,
+and stacking order as appropriate).
+.IP \(bu 5
+If the geometry manager returns
+.PN XtGeometryDone ,
+the change has been approved and actually has been done.
+In this case,
+.PN XtMakeGeometryRequest
+does no configuring and returns
+.PN XtGeometryYes .
+.PN XtMakeGeometryRequest
+never returns
+.PN XtGeometryDone .
+.IP \(bu 5
+Otherwise,
+.PN XtMakeGeometryRequest
+just returns the resulting value from the parent's geometry manager.
+.LP
+Children of primitive widgets are always unmanaged; therefore,
+.PN XtMakeGeometryRequest
+always returns
+.PN XtGeometryYes
+when called by a child of a primitive widget.
+.LP
+The return codes from geometry managers are
+.IN "XtGeometryResult"
+.LP
+.KS
+.sM
+.Ds 0
+.TA .5i 1.75i
+.ta .5i 1.75i
+typedef enum {
+ XtGeometryYes,
+ XtGeometryNo,
+ XtGeometryAlmost,
+ XtGeometryDone
+} XtGeometryResult;
+.De
+.eM
+.KE
+.LP
+The \fIrequest_mode\fP definitions are from
+.Pn < X11/X.h >.
+.LP
+.sM
+.TS
+lw(.5i) lw(2.5i) lw(.75i).
+T{
+#define
+T} T{
+.PN CWX
+T} T{
+(1<<0)
+T}
+T{
+#define
+T} T{
+.PN CWY
+T} T{
+(1<<1)
+T}
+T{
+#define
+T} T{
+.PN CWWidth
+T} T{
+(1<<2)
+T}
+T{
+#define
+T} T{
+.PN CWHeight
+T} T{
+(1<<3)
+T}
+T{
+#define
+T} T{
+.PN CWBorderWidth
+T} T{
+(1<<4)
+T}
+T{
+#define
+T} T{
+.PN CWSibling
+T} T{
+(1<<5)
+T}
+T{
+#define
+T} T{
+.PN CWStackMode
+T} T{
+(1<<6)
+T}
+.TE
+.LP
+.eM
+The \*(xI also support the following value.
+.LP
+.sM
+.TS
+lw(.5i) lw(2.5i) lw(.75i).
+T{
+#define
+T} T{
+.PN XtCWQueryOnly
+T} T{
+(1<<7)
+T}
+.TE
+.LP
+.eM
+.PN 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.
+.LP
+.PN XtMakeGeometryRequest ,
+like the
+.PN XConfigureWindow
+Xlib function, uses \fIrequest_mode\fP to determine which fields in the
+.PN XtWidgetGeometry
+structure the caller wants to specify.
+.LP
+The \fIstack_mode\fP definitions are from
+.Pn < X11/X.h >:
+.LP
+.sM
+.TS
+lw(.5i) lw(2.5i) lw(.75i).
+T{
+#define
+T} T{
+.PN Above
+T} T{
+0
+T}
+T{
+#define
+T} T{
+.PN Below
+T} T{
+1
+T}
+T{
+#define
+T} T{
+.PN TopIf
+T} T{
+2
+T}
+T{
+#define
+T} T{
+.PN BottomIf
+T} T{
+3
+T}
+T{
+#define
+T} T{
+.PN Opposite
+T} T{
+4
+T}
+.TE
+.LP
+.eM
+The \*(xI also support the following value.
+.LP
+.sM
+.TS
+lw(.5i) lw(2.5i) lw(.75i).
+T{
+#define
+T} T{
+.PN XtSMDontChange
+T} T{
+5
+T}
+.TE
+.LP
+.eM
+For definition and behavior of
+.PN Above ,
+.PN Below ,
+.PN TopIf ,
+.PN BottomIf ,
+and
+.PN Opposite ,
+see Section 3.7 in \fI\*(xL\fP.
+.PN XtSMDontChange
+indicates that the widget wants its current stacking order preserved.
+
+.NH 2
+Resize Requests
+.XS
+\*(SN Resize Requests
+.XE
+.LP
+To make a simple resize request from a widget, you can use
+.PN XtMakeResizeRequest
+as an alternative to
+.PN XtMakeGeometryRequest .
+.LP
+.IN "XtMakeResizeRequest" "" "@DEF@"
+.sM
+.FD 0
+XtGeometryResult XtMakeResizeRequest(\fIw\fP, \fIwidth\fP, \fIheight\fP, \
+\fIwidth_return\fP, \fIheight_return\fP)
+.br
+ Widget \fIw\fP;
+.br
+ Dimension \fIwidth\fP, \fIheight\fP;
+.br
+ Dimension *\fIwidth_return\fP, *\fIheight_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request. \*(rI
+.IP \fIwidth\fP 1i
+Specify the desired widget width and height.
+.br
+.ns
+.IP \fIheight\fP 1i
+.IP \fIwidth_return\fP 1i
+Return the allowed widget width and height.
+.br
+.ns
+.IP \fIheight_return\fP 1i
+.LP
+.eM
+The
+.PN XtMakeResizeRequest
+function, a simple interface to
+.PN XtMakeGeometryRequest ,
+creates an
+.PN XtWidgetGeometry
+structure and specifies that width and height should change
+by setting \fIrequest_mode\fP to
+.PN CWWidth
+\fB|\fP
+.PN CWHeight .
+The geometry manager is free to modify any of the other window attributes
+(position or stacking order) to satisfy the resize request.
+If the return value is
+.PN XtGeometryAlmost ,
+\fIwidth_return\fP and \fIheight_return\fP contain a compromise width and height.
+If these are acceptable,
+the widget should immediately call
+.PN XtMakeResizeRequest
+again and request that the compromise width and height be applied.
+If the widget is not interested in
+.PN XtGeometryAlmost
+replies,
+it can pass NULL for \fIwidth_return\fP and \fIheight_return\fP.
+
+.NH 2
+Potential Geometry Changes
+.XS
+\*(SN Potential Geometry Changes
+.XE
+.LP
+Sometimes a geometry manager cannot respond to
+a geometry request from a child without first making a geometry request
+to the widget's own parent (the original requestor's grandparent).
+If the request to the grandparent would allow the parent to satisfy the
+original request,
+the geometry manager can make the intermediate geometry request
+as if it were the originator.
+On the other hand,
+if the geometry manager already has determined that the original request
+cannot be completely satisfied (for example, if it always denies
+position changes),
+it needs to tell the grandparent to respond to the intermediate request
+without actually changing the geometry
+because it does not know if the child will accept the compromise.
+To accomplish this, the geometry manager uses
+.PN XtCWQueryOnly
+in the intermediate request.
+.LP
+When
+.PN XtCWQueryOnly
+is used, the geometry manager needs to cache
+enough information to exactly reconstruct the intermediate request.
+If the grandparent's response to the intermediate query was
+.PN XtGeometryAlmost ,
+the geometry manager needs to cache the entire
+reply geometry in the event the child accepts the parent's compromise.
+.LP
+If the grandparent's response was
+.PN XtGeometryAlmost ,
+it may also be necessary to cache the entire reply geometry from
+the grandparent when
+.PN XtCWQueryOnly
+is not used.
+If the geometry manager is still able to satisfy the original request,
+it may immediately accept the grandparent's compromise
+and then act on the child's request.
+If the grandparent's compromise geometry is insufficient to allow
+the child's request and if the geometry manager is willing to offer
+a different compromise to the child,
+the grandparent's compromise should not be accepted until the child
+has accepted the new compromise.
+.LP
+Note that a compromise geometry returned with
+.PN XtGeometryAlmost
+is guaranteed only for the next call to the same widget;
+therefore, a cache of size 1 is sufficient.
+
+.NH 2
+Child Geometry Management: The geometry_manager Procedure
+.XS
+\*(SN Child Geometry Management: The geometry_manager Procedure
+.XE
+.LP
+The geometry_manager procedure pointer in a composite widget class is of type
+.PN XtGeometryHandler .
+.LP
+.IN "XtGeometryHandler" "" "@DEF@"
+.sM
+.FD 0
+typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry*, \
+XtWidgetGeometry*);
+.br
+ Widget \fIw\fP;
+.br
+ XtWidgetGeometry *\fIrequest\fP;
+.br
+ XtWidgetGeometry *\fIgeometry_return\fP;
+.FN
+.IP \fIw\fP 1.2i
+Passes the widget making the request.
+.IP \fIrequest\fP 1.2i
+Passes the new geometry the child desires.
+.IP \fIgeometry_return\fP 1.2i
+Passes a geometry structure in which the geometry manager may store a
+compromise.
+.LP
+.eM
+A class can inherit its superclass's geometry manager during class
+initialization.
+.LP
+A bit set to zero in the request's \fIrequest_mode\fP
+field means that the child widget
+does not care about the value of the corresponding field,
+so the geometry manager can change this field as it wishes.
+A bit set to 1 means that the child wants that geometry element set
+to the value in the corresponding field.
+.LP
+If the geometry manager can satisfy all changes requested
+and if
+.PN XtCWQueryOnly
+is not specified,
+it updates the widget's \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP,
+and \fIborder_width\fP fields
+appropriately.
+Then, it returns
+.PN XtGeometryYes ,
+and the values pointed to by the \fIgeometry_return\fP argument are undefined.
+The widget's window is moved and resized automatically by
+.PN XtMakeGeometryRequest .
+.LP
+Homogeneous composite widgets often find it convenient to treat the widget
+making the request the same as any other widget, including reconfiguring
+it using
+.PN XtConfigureWidget
+or
+.PN XtResizeWidget
+as part of its layout process, unless
+.PN XtCWQueryOnly
+is specified.
+If it does this,
+it should return
+.PN XtGeometryDone
+to inform
+.PN XtMakeGeometryRequest
+that it does not need to do the configuration itself.
+.NT
+To remain
+compatible with layout techniques used in older widgets (before
+.PN XtGeometryDone
+was added to the \*(xI), a geometry manager should avoid using
+.PN XtResizeWidget
+or
+.PN XtConfigureWidget
+on the child making
+the request because the layout process of the child may be in an
+intermediate state in which it is not prepared to handle a call to its
+resize procedure. A self-contained widget set may choose this
+alternative geometry management scheme, however, provided that it
+clearly warns widget developers of the compatibility consequences.
+.NE
+.LP
+Although
+.PN XtMakeGeometryRequest
+resizes the widget's window
+(if the geometry
+manager returns
+.PN XtGeometryYes ),
+it does not call the widget class's resize procedure.
+The requesting widget must perform whatever
+resizing calculations are needed explicitly.
+.LP
+If the geometry manager disallows the request,
+the widget cannot change its geometry.
+The values pointed to by \fIgeometry_return\fP are undefined,
+and the geometry manager returns
+.PN XtGeometryNo .
+.LP
+Sometimes the geometry manager cannot satisfy the request exactly
+but 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 the structure pointed to by
+\fIgeometry_return\fP with the actual changes
+it is willing to make, including an appropriate \fIrequest_mode\fP mask, and returns
+.PN XtGeometryAlmost .
+If a bit in \fIgeometry_return->request_mode\fP is zero,
+the geometry manager agrees not to change the corresponding value
+if \fIgeometry_return\fP is used immediately
+in a new request.
+If a bit is 1,
+the geometry manager does change that element to the corresponding
+value in \fIgeometry_return\fP.
+More bits may be set in \fIgeometry_return->request_mode\fP
+than in the original request if
+the geometry manager intends to change other fields should the
+child accept the compromise.
+.LP
+When
+.PN XtGeometryAlmost
+is returned,
+the widget must decide if the compromise suggested in \fIgeometry_return\fP
+is acceptable.
+If it is, the widget must not change its geometry directly;
+rather, it must make another call to
+.PN XtMakeGeometryRequest .
+.LP
+If the next geometry request from this child uses the
+\fIgeometry_return\fP values filled in by the geometry manager with an
+.PN 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
+.PN XtGeometryYes .
+However,
+dynamic behavior in
+the user's window manager may affect the final outcome.
+.LP
+To return
+.PN XtGeometryYes ,
+the geometry manager frequently rearranges the position of other managed
+children by calling
+.PN XtMoveWidget .
+However, a few geometry managers may sometimes change the
+size of other managed children by calling
+.PN XtResizeWidget
+or
+.PN XtConfigureWidget .
+If
+.PN XtCWQueryOnly
+is specified,
+the geometry manager must return data describing
+how it would react to this geometry
+request without actually moving or resizing any widgets.
+.LP
+Geometry managers must not assume that the \fIrequest\fP
+and \fIgeometry_return\fP 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.
+
+.NH 2
+Widget Placement and Sizing
+.XS
+\*(SN Widget Placement and Sizing
+.XE
+.LP
+To move a sibling widget of the child making the geometry request,
+the parent uses
+.PN XtMoveWidget .
+.LP
+.IN "XtMoveWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtMoveWidget(\fIw\fP, \fIx\fP, \fIy\fP)
+.br
+ Widget \fIw\fP;
+.br
+ Position \fIx\fP;
+.br
+ Position \fIy\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget. \*(rI
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the new widget x and y coordinates.
+.LP
+.eM
+The
+.PN XtMoveWidget
+function returns immediately if the specified geometry fields
+are the same as the old values.
+Otherwise,
+.PN XtMoveWidget
+writes the new \fIx\fP and \fIy\fP values into the object
+and, if the object is a widget and is realized, issues an Xlib
+.PN XMoveWindow
+call on the widget's window.
+.sp
+.LP
+To resize a sibling widget of the child making the geometry request,
+the parent uses
+.PN XtResizeWidget .
+.LP
+.IN "XtResizeWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtResizeWidget(\fIw\fP, \fIwidth\fP, \fIheight\fP, \fIborder_width\fP)
+.br
+ Widget \fIw\fP;
+.br
+ Dimension \fIwidth\fP;
+.br
+ Dimension \fIheight\fP;
+.br
+ Dimension \fIborder_width\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget. \*(rI
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+.br
+.ns
+.IP \fIborder_width\fP 1i
+Specify the new widget size.
+.LP
+.eM
+The
+.PN XtResizeWidget
+function returns immediately if the specified geometry fields
+are the same as the old values.
+Otherwise,
+.PN XtResizeWidget
+writes the new \fIwidth\fP, \fIheight\fP, and \fIborder_width\fP values into
+the object and, if the object is a widget and is realized, issues an
+.PN XConfigureWindow
+call on the widget's window.
+.LP
+If the new width or height is different from the old values,
+.PN XtResizeWidget
+calls the object's resize procedure to notify it of the size change.
+.sp
+.LP
+To move and resize the sibling widget of the child making the geometry request,
+the parent uses
+.PN XtConfigureWidget .
+.LP
+.IN "XtConfigureWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtConfigureWidget(\fIw\fP, \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, \
+\fIborder_width\fP)
+.br
+ Widget \fIw\fP;
+.br
+ Position \fIx\fP;
+.br
+ Position \fIy\fP;
+.br
+ Dimension \fIwidth\fP;
+.br
+ Dimension \fIheight\fP;
+.br
+ Dimension \fIborder_width\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget. \*(rI
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the new widget x and y coordinates.
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+.br
+.ns
+.IP \fIborder_width\fP 1i
+Specify the new widget size.
+.LP
+.eM
+The
+.PN XtConfigureWidget
+function returns immediately if the specified new geometry fields
+are all equal to the current values.
+Otherwise,
+.PN XtConfigureWidget
+writes the new \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP,
+and \fIborder_width\fP values
+into the object and, if the object is a widget and is realized, makes an Xlib
+.PN XConfigureWindow
+call on the widget's window.
+.LP
+If the new width or height is different from its old value,
+.PN XtConfigureWidget
+calls the object's resize procedure to notify it of the size change;
+otherwise, it simply returns.
+.sp
+.LP
+To resize a child widget that already has the new values of its width,
+height, and border width, the parent uses
+.PN XtResizeWindow .
+.LP
+.IN "XtResizeWindow" "" "@DEF@"
+.sM
+.FD 0
+void XtResizeWindow(\fIw\fP)
+.br
+ Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget. \*(cI
+.LP
+.eM
+The
+.PN XtResizeWindow
+function calls the
+.PN XConfigureWindow
+Xlib function to make the window of the specified widget match its width,
+height, and border width.
+This request is done unconditionally because there is no
+inexpensive way to tell if these
+values match the current values.
+Note that the widget's resize procedure is not called.
+.LP
+There are very few times to use
+.PN XtResizeWindow ;
+instead, the parent should use
+.PN XtResizeWidget .
+
+.NH 2
+Preferred Geometry
+.XS
+\*(SN Preferred Geometry
+.XE
+.LP
+Some parents may be willing to adjust their layouts to accommodate the
+preferred geometries of their children.
+They can use
+.PN XtQueryGeometry
+to obtain the preferred geometry
+and, as they see fit, can use or ignore any portion of the response.
+.sp
+.LP
+To query a child widget's preferred geometry, use
+.PN XtQueryGeometry .
+.LP
+.IN "XtQueryGeometry" "" "@DEF@"
+.sM
+.FD 0
+XtGeometryResult XtQueryGeometry(\fIw\fP, \fIintended\fP, \
+\fIpreferred_return\fP)
+.br
+ Widget \fIw\fP;
+.br
+ XtWidgetGeometry *\fIintended\fP;
+.br
+ XtWidgetGeometry *\fIpreferred_return\fP;
+.FN
+.IP \fIw\fP 1.1i
+Specifies the widget. \*(rI
+.IP \fIintended\fP 1.1i
+Specifies the new geometry the parent plans to give to the child, or
+NULL.
+.IP \fIpreferred_return\fP 1.1i
+Returns the child widget's preferred geometry.
+.LP
+.eM
+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 \fIintended.request_mode\fP,
+and calls
+.PN 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.
+.LP
+.PN XtQueryGeometry
+clears all bits in the \fIpreferred_return->request_mode\fP
+field and checks the
+\fIquery_geometry\fP field of the specified widget's class record.
+If \fIquery_geometry\fP is not NULL,
+.PN XtQueryGeometry
+calls the query_geometry procedure and passes as arguments the
+specified widget, \fIintended\fP, and \fIpreferred_return\fP structures.
+If the \fIintended\fP argument is NULL,
+.PN XtQueryGeometry
+replaces it with a pointer to an
+.PN XtWidgetGeometry
+structure with \fIrequest_mode\fP equal to zero before calling the
+query_geometry procedure.
+.NT
+If
+.PN XtQueryGeometry
+is called from within a geometry_manager
+procedure for the widget that issued
+.PN XtMakeGeometryRequest
+or
+.PN XtMakeResizeRequest ,
+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.
+.NE
+.sp
+.LP
+The query_geometry procedure pointer is of type
+.PN XtGeometryHandler .
+.LP
+.IN "query_geometry procedure" "" "@DEF@"
+.sM
+.FD 0
+typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry*, \
+XtWidgetGeometry*);
+.br
+ Widget \fIw\fP;
+.br
+ XtWidgetGeometry *\fIrequest\fP;
+.br
+ XtWidgetGeometry *\fIpreferred_return\fP;
+.FN
+.IP \fIw\fP 1.2i
+Passes the child widget whose preferred geometry is required.
+.IP \fIrequest\fP 1.2i
+Passes the geometry changes that the parent plans to make.
+.IP \fIpreferred_return\fP 1.2i
+Passes a structure in which the child returns its preferred geometry.
+.LP
+.eM
+.IN "query_geometry procedure"
+The query_geometry procedure is expected to examine the bits set in
+\fIrequest->request_mode\fP, evaluate the preferred geometry of the widget,
+and store the result in \fIpreferred_return\fP
+(setting the bits in \fIpreferred_return->request_mode\fP corresponding
+to those geometry fields that it cares about).
+If the proposed geometry change is acceptable without modification,
+the query_geometry procedure should return
+.PN XtGeometryYes .
+If at least one field in \fIpreferred_return\fP
+with a bit set in \fIpreferred_return->request_mode\fP
+is different
+from the corresponding field in \fIrequest\fP
+or if a bit was set in \fIpreferred_return->request_mode\fP
+that was not set in the request,
+the query_geometry procedure should return
+.PN XtGeometryAlmost .
+If the preferred geometry is identical to the current geometry,
+the query_geometry procedure should return
+.PN XtGeometryNo .
+.NT
+The query_geometry procedure may assume
+that no
+.PN XtMakeResizeRequest
+or
+.PN 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.
+.NE
+.LP
+After calling the query_geometry procedure
+or if the \fIquery_geometry\fP field is NULL,
+.PN XtQueryGeometry
+examines all the unset bits in \fIpreferred_return->request_mode\fP
+and sets the corresponding fields in \fIpreferred_return\fP
+to the current values from the widget instance.
+If
+.PN CWStackMode
+is not set,
+the \fIstack_mode\fP field is set to
+.PN XtSMDontChange .
+.PN XtQueryGeometry
+returns the value returned by the query_geometry procedure or
+.PN XtGeometryYes
+if the \fIquery_geometry\fP field is NULL.
+.LP
+Therefore, the caller can interpret a return of
+.PN XtGeometryYes
+as not needing to evaluate the contents of the reply and, more important,
+not needing to modify its layout plans.
+A return of
+.PN 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
+.PN 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 \fIpreferred_return\fP structure contains complete
+geometry information for the child.
+.LP
+Parents are expected to call
+.PN 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.
+
+.NH 2
+Size Change Management: The resize Procedure
+.XS
+\*(SN Size Change Management: The resize Procedure
+.XE
+.LP
+A child can be resized by its parent at any time.
+Widgets usually need to know when they have changed size
+so that they can lay out their displayed data again to match the new size.
+When a parent resizes a child, it calls
+.PN XtResizeWidget ,
+which updates the geometry fields in the widget,
+configures the window if the widget is realized,
+and calls the child's resize procedure to notify the child.
+The resize procedure pointer is of type
+.PN XtWidgetProc .
+.IN "resize procedure" "" "@DEF@"
+.LP
+If a class need not recalculate anything when a widget is resized,
+it can specify NULL for the \fIresize\fP field in its class record.
+This is an unusual case and should occur only for widgets
+with very trivial display semantics.
+The resize procedure takes a widget as its only argument.
+The \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP,
+and \fIborder_width\fP fields of the widget contain the new values.
+The resize procedure should recalculate the layout of internal data
+as needed.
+(For example, a centered Label in a window that changes size
+should recalculate the starting position of the text.)
+The widget must obey resize as a command and must not treat it as a request.
+A widget must not issue an
+.PN XtMakeGeometryRequest
+or
+.PN XtMakeResizeRequest
+call from its resize procedure.
+.bp