diff options
Diffstat (limited to 'libXt/specs/CH06')
| -rw-r--r-- | libXt/specs/CH06 | 1110 |
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 |