















        Chapter 10.  MMaannaaggiinngg GGeeoommeettrryy







             The geometry of a widget comprises its size, location,
             and stacking order.  Widgets often have preferred sizes
             and perhaps locations.  For example, a Label widget may
             prefer to be just large enough to display the text of
             the label.  But composite widgets usually have
             preferences or constraints in laying out their
             children, and these may conflict with the preferences
             of the child widgets.  Furthermore, the user or the
             application can change a widget's geometry at any time,
             as by resizing the top-level window.  Geometry
             management is the process by which the user, parent
             widgets, and child widgets negotiate the actual sizes
             and locations of the widgets in the application.

             Following are some common occasions for geometry
             changes:

                +o The application manages or unmanages a child
                  widget.

                +o The application sets a geometry resource.

                +o The application sets a resource, and this setting
                  causes one of the geometry resources to change.
                  For example, setting a new label for a Label
                  widget may cause a geometry change.

                +o The user resizes a top-level window via the window
                  manager.

                +o The user resizes a pane of a PanedWindow.




        May 9, 1992                                             10-1








        OSF/Motif Programmer's Guide


             Following are the basic Core and RectObj resources that
             determine widget geometry:

             XXmmNNxx      Specifies the x-coordinate of the upper left
                       outside corner (outside the border) of the
                       widget's window.  The value is relative to
                       the upper left inside corner (inside the
                       border) of the parent window.

             XXmmNNyy      Specifies the y-coordinate of the upper left
                       outside corner (outside the border) of the
                       widget's window.  The value is relative to
                       the upper left inside corner (inside the
                       border) of the parent window.

             XXmmNNwwiiddtthh  Specifies the inside width (excluding the
                       border) of the widget's window.

             XXmmNNhheeiigghhtt Specifies the inside height (excluding the
                       border) of the widget's window.

             XXmmNNbboorrddeerrWWiiddtthh
                       Specifies the width of the border that
                       surrounds the widget's window on all four
                       sides.



        10.1  XXtt aanndd GGeeoommeettrryy MMaannaaggeemmeenntt


             The Intrinsics provide the basic mechanisms and
             policies that underlie geometry management in Motif.
             The fundamental principle of geometry management is
             that parent widgets control the geometry of their
             children.  Child widgets _r_e_q_u_e_s_t changes to their
             geometry; parent widgets _r_e_s_p_o_n_d to requests from their
             children and _c_h_a_n_g_e the geometry of their children
             directly.



        10.1.1  WWiiddggeett CCllaassss PPrroocceedduurreess


             Six widget class procedures, two in the parent and four
             in the child, handle most of the work of geometry
             management:

                +o The parent's cchhaannggee__mmaannaaggeedd procedure.  When a
                  child is managed or unmanaged, the parent often



        10-2                                             May 9, 1992








                                                   Managing Geometry


                  must move or resize some of its children.  In the
                  cchhaannggee__mmaannaaggeedd procedure, the parent can move a
                  child by calling XXttMMoovveeWWiiddggeett, resize a child by
                  calling XXttRReessiizzeeWWiiddggeett, or both move and resize a
                  child by calling XXttCCoonnffiigguurreeWWiiddggeett.  These
                  functions update the appropriate geometry
                  resources of the child and, if the child is
                  realized, reconfigure the child's window.

                +o The parent's ggeeoommeettrryy__mmaannaaggeerr procedure.  This
                  function receives and acts on requests from child
                  widgets to change their geometry.  The
                  ggeeoommeettrryy__mmaannaaggeerr procedure can grant a request,
                  deny a request, or suggest a compromise to the
                  child.  If the procedure grants the request, it
                  updates the appropriate geometry resources of the
                  child.  If the child is realized, the parent can
                  either reconfigure the child's window itself or
                  let the Intrinsics reconfigure the window.  To
                  make all geometry changes itself, the procedure
                  can call XXttMMoovveeWWiiddggeett, XXttRReessiizzeeWWiiddggeett, or
                  XXttCCoonnffiigguurreeWWiiddggeett.

                +o The child's sseett__vvaalluueess procedure.  Whenever the
                  application or user sets one of the basic geometry
                  resources-XXmmNNxx, XXmmNNyy, XXmmNNwwiiddtthh, XXmmNNhheeiigghhtt, or
                  XXmmNNbboorrddeerrWWiiddtthh-Xt automatically makes a request to
                  the widget's parent for the geometry change.  In
                  the sseett__vvaalluueess procedure the widget can determine
                  whether a change to another resource requires a
                  geometry change.  If so, it can simply change one
                  or more of the geometry resources, and Xt makes
                  the appropriate geometry request of the parent.
                  If the parent denies the request, Xt restores the
                  geometry resources to the values they had before
                  the call to XXttSSeettVVaalluueess.

                +o The child's sseett__vvaalluueess__aallmmoosstt procedure.  When the
                  user or the application sets one of the widget's
                  geometry resources, the parent may suggest a
                  compromise geometry change.  The child's
                  sseett__vvaalluueess__aallmmoosstt procedure determines whether to
                  accept the compromise, reject the compromise, or
                  request an alternate geometry change.

                +o The child's rreessiizzee procedure.  When a parent calls
                  XXttRReessiizzeeWWiiddggeett or XXttCCoonnffiigguurreeWWiiddggeett with a size
                  change, Xt makes the changes to the child's
                  geometry resources and window and then invokes the
                  child's rreessiizzee procedure to inform the child of
                  the size change.  This procedure makes any



        May 9, 1992                                             10-3








        OSF/Motif Programmer's Guide


                  internal changes necessary to conform to the new
                  dimensions.  If the child is itself a composite
                  widget, its rreessiizzee procedure may move or resize
                  its own children.

                +o The child's qquueerryy__ggeeoommeettrryy procedure.  A parent
                  widget may take account of a child's preferred
                  geometry in determining its layout.  The parent
                  calls XXttQQuueerryyGGeeoommeettrryy, which invokes the child's
                  qquueerryy__ggeeoommeettrryy procedure.  The child can accept
                  the parent's intended geometry change, inform the
                  parent of the child's preferred geometry, or
                  indicate that the child's current geometry is its
                  preferred geometry.  The parent can use the
                  results however it wants.



        10.1.2  GGeeoommeettrryy CChhaannggee RReeqquueessttss


             A widget uses XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt to make a request
             to its parent for a change in its geometry.  The widget
             can also use XXttMMaakkeeRReessiizzeeRReeqquueesstt, a simple interface to
             XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt for requests to change width or
             height.  Primitive widgets seldom invoke
             XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt directly.  They usually generate
             geometry requests indirectly when the application sets
             a resource that requires a geometry change.  Composite
             widgets often make geometry requests when they try to
             accommodate requests from their children.  For example,
             when a child asks to grow, the parent may ask its own
             parent to grow as well.  In such cases the parent's
             ggeeoommeettrryy__mmaannaaggeerr procedure invokes
             XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt directly.

             If the requesting widget is unmanaged, its parent is
             not realized, or the requested geometry resource values
             are the same as the current values,
             XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt makes the requested changes and
             returns XXttGGeeoommeettrryyYYeess.  If the widget is being
             destroyed, it returns XXttGGeeoommeettrryyNNoo.  Otherwise, it
             invokes the parent's ggeeoommeettrryy__mmaannaaggeerr procedure.  If
             the ggeeoommeettrryy__mmaannaaggeerr procedure approves the request,
             XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt returns XXttGGeeoommeettrryyYYeess.  If the
             ggeeoommeettrryy__mmaannaaggeerr procedure denies the request,
             XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt returns XXttGGeeoommeettrryyNNoo.  If the
             ggeeoommeettrryy__mmaannaaggeerr procedure suggests a compromise
             geometry, XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt returns
             XXttGGeeoommeettrryyAAllmmoosstt.  In this case the widget can accept
             the compromise by immediately making another geometry



        10-4                                             May 9, 1992








                                                   Managing Geometry


             request with the compromise parameters.

             The second argument to XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt is a
             pointer to an XXttWWiiddggeettGGeeoommeettrryy structure.  This
             structure contains the parameters of the widget's
             geometry request:  the intended x, y, width, height,
             border width, and stacking mode.  The structure also
             contains a bitmask with a bit for each parameter.  If a
             bit is set, the widget intends to set the corresponding
             parameter to the intended value.  If a bit is not set,
             the widget does not care about the corresponding
             parameter, and the parent is free to change it.

             The third argument to XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt is a
             pointer to another XXttWWiiddggeettGGeeoommeettrryy structure.  This
             argument is valid only when the return value is
             XXttGGeeoommeettrryyAAllmmoosstt.  In that case the argument, if not
             NULL, returns the parameters of the parent's compromise
             geometry.



        10.1.3  TThhee ggeeoommeettrryy__mmaannaaggeerr PPrroocceedduurree


             When a managed child widget makes a geometry request of
             a realized parent, XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt invokes the
             parent's ggeeoommeettrryy__mmaannaaggeerr procedure.  The arguments are
             the same as those to XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt.  This
             routine examines the bitmask (the rreeqquueesstt__mmooddee member)
             and the requested geometry parameters in the
             XXttWWiiddggeettGGeeoommeettrryy structure provided by the child.  If
             the ggeeoommeettrryy__mmaannaaggeerr routine can satisfy the request,
             it has two choices:

                +o Change the appropriate geometry resources of the
                  child, and return XXttGGeeoommeettrryyYYeess to
                  XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt.  If the child is a widget,
                  XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt then calls XXCCoonnffiigguurreeWWiinnddooww
                  to change the geometry of the child's window.  If
                  the child is not a widget, XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt
                  clears both the old and the new areas occupied by
                  the child.  XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt does not call
                  the child's rreessiizzee procedure.  It returns
                  XXttGGeeoommeettrryyYYeess to the child.

                +o Call XXttCCoonnffiigguurreeWWiiddggeett, XXttMMoovveeWWiiddggeett, or
                  XXttRReessiizzeeWWiiddggeett on the child, and return
                  XXttGGeeoommeettrryyDDoonnee to XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt.
                  XXttCCoonnffiigguurreeWWiiddggeett, XXttMMoovveeWWiiddggeett, and
                  XXttRReessiizzeeWWiiddggeett configure the child's window or



        May 9, 1992                                             10-5








        OSF/Motif Programmer's Guide


                  clear the old and new areas occupied by the child,
                  and when the child's size changes they call its
                  rreessiizzee procedure.  XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt returns
                  XXttGGeeoommeettrryyYYeess to the child.

             To satisfy a child's geometry request, the
             ggeeoommeettrryy__mmaannaaggeerr routine may need to move or resize
             other children.  It uses XXttCCoonnffiigguurreeWWiiddggeett,
             XXttMMoovveeWWiiddggeett, or XXttRReessiizzeeWWiiddggeett to do this.  A
             ggeeoommeettrryy__mmaannaaggeerr procedure that returns XXttGGeeoommeettrryyDDoonnee
             calls these routines on the child making the request as
             well.  The difference between answers of XXttGGeeoommeettrryyDDoonnee
             and XXttGGeeoommeettrryyYYeess is as follows:

                +o XXttGGeeoommeettrryyDDoonnee means that the ggeeoommeettrryy__mmaannaaggeerr
                  routine has called the child's rreessiizzee procedure if
                  the child's size changes.  XXttGGeeoommeettrryyYYeess means
                  that neither the ggeeoommeettrryy__mmaannaaggeerr routine nor
                  XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt calls the child's rreessiizzee
                  procedure.  The caller of XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt
                  must call the child's rreessiizzee procedure if
                  necessary.

                +o XXttGGeeoommeettrryyDDoonnee means that the ggeeoommeettrryy__mmaannaaggeerr
                  routine has configured the child's window or
                  cleared the old and new areas occupied by the
                  child.  XXttGGeeoommeettrryyYYeess means that
                  XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt should do this.

             NNoottee::  The ggeeoommeettrryy__mmaannaaggeerr procedures for Motif
                    widgets return XXttGGeeoommeettrryyYYeess, not
                    XXttGGeeoommeettrryyDDoonnee, and they do not call the
                    rreessiizzee procedure of the child making the
                    geometry request.

             The ggeeoommeettrryy__mmaannaaggeerr procedure may be able to satisfy
             some but not all of a child's request.  For example, it
             may be able to grant the requested width but not the
             requested height.  In this case the ggeeoommeettrryy__mmaannaaggeerr
             procedure may offer the child a compromise geometry.
             It fills in the reply XXttWWiiddggeettGGeeoommeettrryy structure with
             the parameters it intends to allow, and it sets the
             corresponding bit in the reply bitmask for any
             parameter it intends to change from the value
             requested.  It then caches these parameters and returns
             XXttGGeeoommeettrryyAAllmmoosstt to the child.  If the child
             immediately makes another geometry request using the
             compromise parameters, the ggeeoommeettrryy__mmaannaaggeerr procedure
             must grant the request if it can.





        10-6                                             May 9, 1992








                                                   Managing Geometry


        10.1.4  IInntteerrmmeeddiiaattee GGeeoommeettrryy RReeqquueessttss


             Often a parent widget must change its own geometry in
             order to satisfy a child's request.  The parent's
             ggeeoommeettrryy__mmaannaaggeerr procedure uses XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt
             to ask its own parent for a geometry change.  If
             XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt to the grandparent returns
             XXttGGeeoommeettrryyYYeess, the parent's actions depend on whether
             the widget set's policy is for a ggeeoommeettrryy__mmaannaaggeerr
             procedure to return XXttGGeeoommeettrryyDDoonnee or XXttGGeeoommeettrryyYYeess
             when it grants a request:

                +o With an XXttGGeeoommeettrryyDDoonnee policy, the
                  ggeeoommeettrryy__mmaannaaggeerr procedure calls the requesting
                  widget's rreessiizzee procedure.  During a successful
                  intermediate request, the grandparent's
                  ggeeoommeettrryy__mmaannaaggeerr procedure calls the parent's
                  rreessiizzee procedure.  The parent widget's
                  ggeeoommeettrryy__mmaannaaggeerr and rreessiizzee procedures must
                  cooperate to ensure that before the child's
                  request is granted the child ends up with the
                  geometry it requested and the child's rreessiizzee
                  procedure has been called.  The parent's
                  ggeeoommeettrryy__mmaannaaggeerr procedure then returns
                  XXttGGeeoommeettrryyDDoonnee.

                +o With an XXttGGeeoommeettrryyYYeess policy, the ggeeoommeettrryy__mmaannaaggeerr
                  procedure does not call the requesting widget's
                  rreessiizzee procedure.  During a successful
                  intermediate request, the grandparent's
                  ggeeoommeettrryy__mmaannaaggeerr procedure does not call the
                  parent's rreessiizzee procedure.  The parent widget's
                  ggeeoommeettrryy__mmaannaaggeerr procedure updates the requesting
                  child's geometry fields and may resize other
                  children, but it should not call the requesting
                  child's rreessiizzee procedure.  The parent may call its
                  own rreessiizzee procedure so long as that routine does
                  not call the requesting child's rreessiizzee procedure.
                  The parent's ggeeoommeettrryy__mmaannaaggeerr procedure then
                  returns XXttGGeeoommeettrryyYYeess.

             Sometimes the parent needs to make a geometry request
             to its own parent just to find out whether the
             grandparent will accept a proposed change.  For
             example, the parent may intend to offer a compromise
             geometry to the child but must first determine whether
             the grandparent will allow the parent to change its own
             geometry in order to offer the compromise.  In this
             case the parent does not want the grandparent actually
             to make the proposed change; it just wants the



        May 9, 1992                                             10-7








        OSF/Motif Programmer's Guide


             grandparent to tell the parent whether the change is
             acceptable.

             In making its own geometry request to the grandparent,
             the parent sets the XXttCCWWQQuueerryyOOnnllyy bit in the request
             bitmask.  The grandparent can return XXttGGeeoommeettrryyYYeess but
             must not actually change any of its children.  The
             parent then returns XXttGGeeoommeettrryyAAllmmoosstt to the child,
             along with its compromise parameters.  If the child
             accepts the compromise, the parent repeats its request
             to the grandparent without setting XXttCCWWQQuueerryyOOnnllyy.  The
             grandparent should grant the parent's request, and the
             parent can then grant the child's request.

             If the grandparent's response is XXttGGeeoommeettrryyAAllmmoosstt and
             the parent still wishes to offer a compromise to the
             child, it caches the grandparent's reply and returns
             XXttGGeeoommeettrryyAAllmmoosstt to the child.  If the child accepts
             this compromise, the parent then makes another request
             of the grandparent, using the cached compromise
             parameters from the grandparent and without setting
             XXttCCWWQQuueerryyOOnnllyy.  The grandparent should grant the
             parent's request, and the parent can then grant the
             child's request.



        10.1.5  XXttSSeettVVaalluueess


             When a user or application invokes XXttSSeettVVaalluueess on a
             geometry resource, XXttSSeettVVaalluueess makes a geometry
             request.  After invoking all the widget's sseett__vvaalluueess
             procedures, XXttSSeettVVaalluueess checks for changes to any
             geometry resources.  If any of those resources have
             changed, it sets their values to those in effect before
             XXttSSeettVVaalluueess was called and then makes a geometry
             request with the new values as the requested geometry
             parameters.  If the geometry request returns
             XXttGGeeoommeettrryyYYeess, XXttSSeettVVaalluueess calls the widget's rreessiizzee
             procedure.  If the parent's ggeeoommeettrryy__mmaannaaggeerr procedure
             returns XXttGGeeoommeettrryyDDoonnee, XXttSSeettVVaalluueess does not call the
             widget's rreessiizzee procedure.

             If the geometry request returns XXttGGeeoommeettrryyNNoo or
             XXttGGeeoommeettrryyAAllmmoosstt, XXttSSeettVVaalluueess calls the widget's
             sseett__vvaalluueess__aallmmoosstt procedure, passing it the request and
             reply XXttWWiiddggeettGGeeoommeettrryy structures.  If the request
             returns XXttGGeeoommeettrryyNNoo, the bitmask in the reply
             structure is 0.  The sseett__vvaalluueess__aallmmoosstt procedure can
             accept a compromise geometry by copying the reply



        10-8                                             May 9, 1992








                                                   Managing Geometry


             parameters into the request structure.  It can also
             construct another request by altering the request
             structure, or it can end the negotiation by setting the
             request bitmask to 0.  If the request bitmask is
             nonzero when the sseett__vvaalluueess__aallmmoosstt procedure returns,
             XXttSSeettVVaalluueess makes another geometry request and treats
             the result in the same way as for the original request.

             A widget's sseett__vvaalluueess procedure can initiate a geometry
             request by changing any of the geometry resources.  For
             example, if XXttSSeettVVaalluueess is invoked on a Label's text,
             the sseett__vvaalluueess procedure can calculate how large the
             widget should be to contain the new text and then set
             the relevant geometry fields accordingly.  The
             sseett__vvaalluueess procedure should not do any resizing itself;
             in particular, it should not resize any child widgets,
             because the geometry request might be denied.  Resizing
             is usually done in the widget's rreessiizzee procedure.  The
             widget's sseett__vvaalluueess__aallmmoosstt procedure may need to
             restore some widget state in the event the geometry
             request is denied.



        10.1.6  TThhee rreessiizzee PPrroocceedduurree


             A widget's rreessiizzee procedure is invoked in the following
             circumstances:

                +o By XXttCCoonnffiigguurreeWWiiddggeett or XXttRReessiizzeeWWiiddggeett when the
                  parent resizes the widget

                +o By XXttSSeettVVaalluueess when the widget's geometry
                  resources are changed and the resulting geometry
                  request returns XXttGGeeoommeettrryyYYeess

                +o By the parent's ggeeoommeettrryy__mmaannaaggeerr procedure when it
                  grants the widget's geometry request and is about
                  to return XXttGGeeoommeettrryyDDoonnee

             In addition, a shell's rreessiizzee procedure is invoked when
             the size of the shell is changed, often by a user via
             the window manager.

             When the rreessiizzee procedure is called the widget's
             geometry resources contain the new values.  The rreessiizzee
             procedure uses these values to recalculate the widget's
             layout.  In the process it may move or resize child
             widgets.  The rreessiizzee procedure must take its geometry
             resource values as given; it may not issue a geometry



        May 9, 1992                                             10-9








        OSF/Motif Programmer's Guide


             request.

             A composite widget's rreessiizzee procedure may need
             coordination with its ggeeoommeettrryy__mmaannaaggeerr procedure in
             handling a geometry request from a child when the
             parent must make its own geometry request to
             accommodate the child.  If the widget set's
             ggeeoommeettrryy__mmaannaaggeerr procedures return XXttGGeeoommeettrryyYYeess, a
             parent's ggeeoommeettrryy__mmaannaaggeerr procedure may call the
             parent's rreessiizzee procedure after a successful request to
             the grandparent.  In this case the rreessiizzee procedure
             should not resize the child widget making the original
             geometry request.  This problem can be avoided if the
             ggeeoommeettrryy__mmaannaaggeerr and rreessiizzee procedures call a common
             subroutine that performs layout, taking as an argument
             the child that is making the request (if any) so that
             the layout routine can avoid resizing that child.

             If the widget set's ggeeoommeettrryy__mmaannaaggeerr procedures return
             XXttGGeeoommeettrryyDDoonnee, the grandparent's ggeeoommeettrryy__mmaannaaggeerr
             procedure calls the parent's rreessiizzee procedure during a
             successful request to the grandparent.  In this case
             the child's geometry resources may be different from
             the geometry parameters it is requesting at the time
             the parent's rreessiizzee procedure is called.  This problem
             can be avoided if the parent's ggeeoommeettrryy__mmaannaaggeerr
             procedure sets the child's geometry resources to the
             requested values before making its own geometry
             request, setting them back to the original values if
             the parent's request is refused.



        10.1.7  PPrreeffeerrrreedd SSiizzee aanndd LLooccaattiioonn


             When calculating its layout, a parent widget may take
             account of a child's preferred size and location.  The
             parent uses XXttQQuueerryyGGeeoommeettrryy to inquire about a child's
             preferred geometry.  The parent passes to
             XXttQQuueerryyGGeeoommeettrryy pointers to two XXttWWiiddggeettGGeeoommeettrryy
             structures, one containing the parameters that the
             parent intends to impose and the other containing the
             preferred parameters returned by the child.
             XXttQQuueerryyGGeeoommeettrryy then calls the child's qquueerryy__ggeeoommeettrryy
             procedure with pointers to these two XXttWWiiddggeettGGeeoommeettrryy
             structures.

             The child's qquueerryy__ggeeoommeettrryy procedure determines the
             widget's preferred geometry and stores the parameters
             into the return XXttWWiiddggeettGGeeoommeettrryy structure, setting



        10-10                                            May 9, 1992








                                                   Managing Geometry


             corresponding bits in the bitmask for fields that it
             cares about.  It then returns one of these values:

                +o If the parent's intended geometry is acceptable,
                  it returns XXttGGeeoommeettrryyYYeess

                +o If the parent's and child's parameters differ for
                  some field that both widget care about, or if the
                  child has expressed interest in a field that the
                  parent does not care about, it returns
                  XXttGGeeoommeettrryyAAllmmoosstt

                +o If the child's preferred geometry is the same as
                  its current geometry, it returns XXttGGeeoommeettrryyNNoo

             After the qquueerryy__ggeeoommeettrryy procedure returns,
             XXttQQuueerryyGGeeoommeettrryy fills in any fields in the return
             XXttWWiiddggeettGGeeoommeettrryy structure that the child does not care
             about with the current values of the resources in the
             child widget.  XXttQQuueerryyGGeeoommeettrryy returns the value
             returned by the qquueerryy__ggeeoommeettrryy procedure.

             Most composite widgets should call XXttQQuueerryyGGeeoommeettrryy
             whenever they intend to change the geometry of a child
             that is not in the process of making a geometry
             request.  A ggeeoommeettrryy__mmaannaaggeerr procedure should not call
             XXttQQuueerryyGGeeoommeettrryy for the child making the request.  For
             a widget making a geometry request, the requested
             geometry is the preferred geometry.

             This can be problem for widget sets whose
             ggeeoommeettrryy__mmaannaaggeerr procedures call the rreessiizzee procedure
             for the child making the request and then return
             XXttGGeeoommeettrryyDDoonnee.  During a successful intermediate
             geometry request, the grandparent calls the parent's
             rreessiizzee procedure.  This procedure in turn may resize
             the child making the original request, but it cannot
             reliably use XXttQQuueerryyGGeeoommeettrryy to determine the child's
             preferred geometry.  Indeed, the parent's rreessiizzee
             procedure may not know which child is making the
             request or even that it is being invoked as a result of
             a child's geometry request.  The parent widget's
             ggeeoommeettrryy__mmaannaaggeerr procedure may need to arrange to
             communicate this information to the parent's rreessiizzee
             procedure.









        May 9, 1992                                            10-11








        OSF/Motif Programmer's Guide


        10.1.8  EExxppoossuurree aanndd RReeddiissppllaayy


             A widget may recompute its layout in its rreessiizzee,
             sseett__vvaalluueess, or ggeeoommeettrryy__mmaannaaggeerr procedure, but usually
             it does not actually generate the window contents in
             those procedures.  A widget usually regenerates its
             window contents in response to an EExxppoossee event, which
             causes the widget's eexxppoossee procedure to be invoked.
             This procedure takes as arguments the widget, the
             event, and the set of rectangles to be redisplayed.
             Using the current state of the widget (including its
             geometry resources), the eexxppoossee procedure generates the
             contents of either the affected rectangles or the
             window as a whole.

             XXttCCoonnffiigguurreeWWiiddggeett, XXttRReessiizzeeWWiiddggeett, and XXttMMoovveeWWiiddggeett
             call XXCCoonnffiigguurreeWWiinnddooww, XXMMoovveeWWiinnddooww, or XXCClleeaarrAArreeaa as
             appropriate.  These functions cause the server to
             generate EExxppoossee events when necessary.
             XXttMMaakkeeGGeeoommeettrryyRReeqquueesstt also calls XXCCoonnffiigguurreeWWiinnddooww or
             XXCClleeaarrAArreeaa when the parent's ggeeoommeettrryy__mmaannaaggeerr procedure
             returns XXttGGeeoommeettrryyYYeess.  When the ggeeoommeettrryy__mmaannaaggeerr
             procedure returns XXttGGeeoommeettrryyDDoonnee it must call
             XXCCoonnffiigguurreeWWiinnddooww or XXCClleeaarrAArreeaa itself (perhaps
             indirectly).



        10.2  SShheellllss aanndd TThheeiirr CChhiillddrreenn


             Shell widgets encapsulate application widgets,
             principally to communicate with the window manager.
             Motif has three shell classes based on Intrinsics shell
             classes:

             VVeennddoorrSShheellll    Subclass of WWMMSShheellll and superclass for
                            other shell classes that contain both
                            persistent top-level widgets and dialogs

             XXmmDDiiaallooggSShheellll  Subclass of TTrraannssiieennttSShheellll (which is a
                            subclass of VVeennddoorrSShheellll) used to contain
                            dialog widgets, commonly subclasses of
                            XXmmBBuulllleettiinnBBooaarrdd

             XXmmMMeennuuSShheellll    Subclass of OOvveerrrriiddeeSShheellll used to
                            contain RowColumn PulldownMenu and
                            PopupMenu widgets





        10-12                                            May 9, 1992








                                                   Managing Geometry


             A shell has only one managed child.  Except when a
             shell contains an off-the-spot input method, the
             shell's window is coincident with the child's window.
             The ggeeoommeettrryy__mmaannaaggeerr procedures of the shell classes
             treat geometry requests from the child as geometry
             requests for the shell, and the rreessiizzee procedures of
             the shell classes make the child the same size as the
             shell.  Applications should usually change the geometry
             of the child, not of the shell.

             In particular, setting XXmmNNhheeiigghhtt, XXmmNNwwiiddtthh, or
             XXmmNNbboorrddeerrWWiiddtthh for either a shell or its child sets
             that resource to the same value in both the parent and
             the child.  For a child of a shell, setting XXmmNNxx or
             XXmmNNyy sets the corresponding resource of the parent but
             does not change the child's position relative to the
             parent.  XXttGGeettVVaalluueess for the child's XXmmNNxx or XXmmNNyy
             yields the value of the corresponding resource in the
             parent.  The _x and _y coordinates of the child's upper
             left outside corner relative to the parent's upper left
             inside corner are both zero minus the value of
             XXmmNNbboorrddeerrWWiiddtthh.

             The exception is a VendorShell or DialogShell that
             contains an off-the-spot input method.  In this case
             the input method appears inside the shell and below the
             application widget.  The conventions for geometry
             parameters are the same as for other shells, except
             that the values of XXmmNNhheeiigghhtt for the child and the
             shell are not identical.  The height of the shell is
             the sum of the height and border width of the
             application window and the height of the area occupied
             by the input method.

             When the Shell resource XXmmNNaalllloowwSShheellllRReessiizzee is False, a
             shell's ggeeoommeettrryy__mmaannaaggeerr procedure returns XXttGGeeoommeettrryyNNoo
             for all geometry requests from a realized child.



        10.3  MMaannaaggeerr WWiiddggeettss aanndd TThheeiirr CChhiillddrreenn


             Each Primitive widget has resources that determine its
             layout or contents.  For example, the size of a Text
             widget depends on the values of the XXmmNNrroowwss,
             XXmmNNccoolluummnnss, XXmmNNmmaarrggiinnHHeeiigghhtt, and XXmmNNmmaarrggiinnWWiiddtthh Text
             resources; the XXmmNNhhiigghhlliigghhttTThhiicckknneessss and
             XXmmNNsshhaaddoowwTThhiicckknneessss Primitive resources; and the basic
             Core geometry resources.  In addition, when the Text
             XXmmNNrreessiizzeeHHeeiigghhtt or XXmmNNrreessiizzeeWWiiddtthh resource is True, the



        May 9, 1992                                            10-13








        OSF/Motif Programmer's Guide


             size of the widget can depend on the size of the text
             (the XXmmNNvvaalluuee resource).  Setting any of these
             resources can cause Text to generate a geometry
             request.

             Manager widgets have their own layout policies, which
             they use in responding to geometry requests from their
             children or to resizing by their parents.  These
             policies are determined by the Manager's own resources
             and, for some Managers, by its constraint resources.

             Constraints are resources defined by the Manager but
             associated with each child.  An application or user
             initializes, sets, or gets constraint resources for the
             child as if they were resources defined by the child's
             class.  Initialization, XXttSSeettVVaalluueess, and XXttGGeettVVaalluueess
             for the child operate on the parent's constraint
             resources associated with that child.  The Manager has
             constraint iinniittiiaalliizzee and sseett__vvaalluueess procedures that
             allow it to set other constraints and recompute its
             layout.

             Motif uses constraints in determining the layout of
             Form, PanedWindow, and Frame widgets.  Motif also uses
             constraints to adjust the positions of child widgets in
             PanedWindow and RowColumn.  The Form widget is
             discussed in a later section of this chapter.
             PanedWindow and Frame are discussed in chapter 9.



        10.4  MMaannaaggiinngg GGeeoommeettrryy UUssiinngg RRoowwCCoolluummnn


             In addition to its role as the menu widget, RowColumn
             provides general-purpose layout and geometry management
             for child widgets arranged in rows, columns, or grids.
             The default RowColumn type, XXmmWWOORRKK__AARREEAA, provides the
             layout features but not the menu semantics.

             RowColumn's layout is controlled by two sets of
             resources.  One set determines the position of children
             within the parent.  The other set specifies whether
             RowColumn adjusts the internal layout characteristics
             of the children, such as margins and text alignment.

             The two primary resources that control child
             positioning are XXmmNNoorriieennttaattiioonn and XXmmNNppaacckkiinngg.
             XXmmNNoorriieennttaattiioonn determines whether RowColumn lays out
             its children in rows or columns.  When XXmmNNoorriieennttaattiioonn
             is XXmmVVEERRTTIICCAALL-the default for a WorkArea-the layout is



        10-14                                            May 9, 1992








                                                   Managing Geometry


             column-major.  When XXmmNNoorriieennttaattiioonn is XXmmHHOORRIIZZOONNTTAALL the
             layout is row-major.

             XXmmNNppaacckkiinngg controls the general style of the layout.
             The resource has three possible values:

                +o XXmmPPAACCKK__TTIIGGHHTT-RowColumn places children one after
                  the other along the major dimension (for example,
                  in a column when XXmmNNoorriieennttaattiioonn is XXmmVVEERRTTIICCAALL).
                  It proceeds until no more children fit along that
                  dimension and then begins a new row or column.
                  When XXmmNNoorriieennttaattiioonn is XXmmVVEERRTTIICCAALL and the vertical
                  distance remaining in the current column is too
                  small to accommodate the child being placed,
                  RowColumn begins a new column if XXmmNNrreessiizzeeHHeeiigghhtt
                  is FFaallssee or the RowColumn cannot become larger.
                  When placing children in a column, RowColumn does
                  not alter their heights, but it makes the width of
                  each child in the column equal to the width of the
                  widest child in that column.  Analogous rules
                  apply to row-major layouts.  XXmmPPAACCKK__TTIIGGHHTT is the
                  default value for XXmmNNppaacckkiinngg in a WorkArea.

                +o XXmmPPAACCKK__CCOOLLUUMMNN-RowColumn makes the width and height
                  of each child identical.  The width is the maximum
                  width of all children, and the height is the
                  maximum height.  RowColumn uses the value of
                  XXmmNNnnuummCCoolluummnnss to determine the maximum number of
                  columns (in XXmmVVEERRTTIICCAALL orientation) or rows (in
                  XXmmHHOORRIIZZOONNTTAALL orientation) to produce.  RowColumn
                  tries to create XXmmNNnnuummCCoolluummnnss columns (or rows)
                  with an equal number of children in each column
                  (or row).

                +o XXmmPPAACCKK__NNOONNEE-RowColumn does not change the position
                  of any child.  Unless XXmmNNrreessiizzeeWWiiddtthh is False, it
                  tries to grow large enough to enclose the greatest
                  x extent of any child.  Unless XXmmNNrreessiizzeeHHeeiigghhtt is
                  False, it tries to grow large enough to enclose
                  the greatest y extent of any child.

             Several other resources influence the position and size
             of children:

             XXmmNNaaddjjuussttLLaasstt
                       This resource applies only when XXmmNNppaacckkiinngg is
                       XXmmPPAACCKK__TTIIGGHHTT or XXmmPPAACCKK__CCOOLLUUMMNN.  When True and
                       the orientation is vertical, RowColumn
                       increases the widths of children in the last
                       column when necessary so that all children
                       extend to the right edge of the RowColumn.



        May 9, 1992                                            10-15








        OSF/Motif Programmer's Guide


                       When True and the orientation is horizontal,
                       RowColumn increases the heights of children
                       in the last row when necessary so that all
                       children extend to the bottomn edge of the
                       RowColumn.

             XXmmNNeennttrryyBBoorrddeerr
                       When nonzero, specifies the border width for
                       all children of the RowColumn.  When zero,
                       RowColumn does not alter the border width of
                       its children.

             XXmmNNmmaarrggiinnHHeeiigghhtt
                       Specifies the amount of space between the top
                       edge of the RowColumn and the first item in
                       each column and between the bottom edge of
                       the RowColumn and the last item in each
                       column.

             XXmmNNmmaarrggiinnWWiiddtthh
                       Specifies the amount of space between the
                       left edge of the RowColumn and the first item
                       in each row and between the right edge of the
                       RowColumn and the last item in each row.

             XXmmNNrreessiizzeeHHeeiigghhtt
                       When True, RowColumn adjusts its own height
                       when possible to accommodate its children.
                       When False, RowColumn does not request a new
                       height during layout.

             XXmmNNrreessiizzeeWWiiddtthh
                       When True, RowColumn adjusts its own width
                       when possible to accommodate its children.
                       When False, RowColumn does not request a new
                       width during layout.

             XXmmNNssppaacciinngg This resource applies only when XXmmNNppaacckkiinngg
                       is XXmmPPAACCKK__TTIIGGHHTT or XXmmPPAACCKK__CCOOLLUUMMNN.  Specifies
                       the amount of vertical space between each
                       child in a vertical orientation and the
                       amount of horizontal space between each child
                       in a horizontal orientation.

             RowColumn also has several resources that can cause the
             RowColumn to change the internal layout of some classes
             of children:

             XXmmNNaaddjjuussttMMaarrggiinn
                       This resource applies only to children that
                       are subclasses of XXmmLLaabbeell and XXmmLLaabbeellGGaaddggeett.



        10-16                                            May 9, 1992








                                                   Managing Geometry


                       When True and the orientation is vertical,
                       RowColumn sets the XXmmNNmmaarrggiinnLLeefftt and
                       XXmmNNmmaarrggiinnRRiigghhtt for all children to the
                       maximum values for those resources among all
                       children.  When True and the orientation is
                       horizontal, RowColumn sets the XXmmNNmmaarrggiinnTToopp
                       and XXmmNNmmaarrggiinnBBoottttoomm for all children to the
                       maximum values for those resources among all
                       children.  In PopupMenus and PulldownMenus
                       RowColumn adjusts the margins only for button
                       children, not for labels.

             XXmmNNeennttrryyAAlliiggnnmmeenntt
                       This resource applies only to children that
                       are subclasses of XXmmLLaabbeell and XXmmLLaabbeellGGaaddggeett.
                       When XXmmNNiissAAlliiggnneedd is True, RowColumn sets the
                       XXmmNNaalliiggnnmmeenntt of all children to the value
                       specified by XXmmNNeennttrryyAAlliiggnnmmeenntt.  Following
                       are the possible values:

                          +o XXmmAALLIIGGNNMMEENNTT__BBEEGGIINNNNIINNGG-The child's text
                            or pixmap is aligned with the left edge
                            of the child's window

                          +o XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR-The child's text or
                            pixmap is aligned with the center of the
                            child's window

                          +o XXmmAALLIIGGNNMMEENNTT__EENNDD-The child's text or
                            pixmap is aligned with the right edge of
                            the child's window
                       In menus RowColumn sets the alignment only
                       for button children, not for labels.

             XXmmNNeennttrryyVVeerrttiiccaallAAlliiggnnmmeenntt
                       This resource applies only to children that
                       are subclasses of XXmmLLaabbeell, XXmmLLaabbeellGGaaddggeett,
                       XXmmTTeexxtt, and XXmmTTeexxttFFiieelldd.  It also applies
                       only when XXmmNNppaacckkiinngg is XXmmPPAACCKK__CCOOLLUUMMNN (in
                       either orientation) or when XXmmNNppaacckkiinngg is
                       XXmmPPAACCKK__TTIIGGHHTT and the orientation is
                       horizontal.  The value specifies a reference
                       point for aligning the children in any row:

                          +o XXmmAALLIIGGNNMMEENNTT__BBAASSEELLIINNEE__BBOOTTTTOOMM-Causes the
                            last baseline of each child in a row to
                            align with the last baseline of the
                            tallest child in the row.  This resource
                            is applicable only when all children in
                            a row contain textual data.




        May 9, 1992                                            10-17








        OSF/Motif Programmer's Guide


                          +o XXmmAALLIIGGNNMMEENNTT__BBAASSEELLIINNEE__TTOOPP-Causes the
                            first baseline of each child in a row to
                            align with the first baseline of the
                            tallest child in the row.  This resource
                            is applicable only when all children in
                            a row contain textual data.

                          +o XXmmAALLIIGGNNMMEENNTT__BBOOTTTTOOMM-Causes the bottom
                            edge of the last line of text contained
                            in each child to align with the bottom
                            edge of the last line of text of the
                            tallest child in the row.

                          +o XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR-Causes the center of
                            each child to align vertically with the
                            center point established by the tallest
                            child in the row.

                          +o XXmmAALLIIGGNNMMEENNTT__TTOOPP-Causes the top edge of
                            the first line of text contained in each
                            child to align with the top edge of the
                            first line of text of the tallest child
                            in the row.

             XXmmNNiissAAlliiggnneedd
                       When True, RowColumn sets the XXmmNNaalliiggnnmmeenntt
                       resources of children that are subclasses of
                       XXmmLLaabbeell or XXmmLLaabbeellGGaaddggeett to the value
                       specified by XXmmNNeennttrryyAAlliiggnnmmeenntt.



        10.5  MMaannaaggiinngg GGeeoommeettrryy UUssiinngg BBuulllleettiinnBBooaarrdd aanndd DDrraawwiinnggAArreeaa


             BulletinBoard and DrawingArea are two container widgets
             with similar geometry policies.  These widgets have
             three geometry-related resources in common:

             XXmmNNmmaarrggiinnHHeeiigghhtt
                       Specifies the amount of space between the top
                       shadow of the widget and the top edge of any
                       child and between the bottom shadow of the
                       widget and the bottom edge of any child.
                       When the value of this resource is greater
                       than 0, the widget ensures that the top edges
                       of all children are below the widget's top
                       margin.

             XXmmNNmmaarrggiinnWWiiddtthh
                       Specifies the amount of space between the



        10-18                                            May 9, 1992








                                                   Managing Geometry


                       left shadow of the widget and the left edge
                       of any child and between the right shadow of
                       the widget and the right edge of any child.
                       When the value of this resource is greater
                       than 0, the widget ensures that the left
                       edges of all children are to the right of the
                       widget's left margin.

             XXmmNNrreessiizzeePPoolliiccyy
                       Determines the widget's policy with regard to
                       resize requests from its children.  Following
                       are the possible values:

                          +o XXmmRREESSIIZZEE__NNOONNEE-The widget has a fixed
                            size determined by its XXmmNNwwiiddtthh and
                            XXmmNNhheeiigghhtt.  The widget does not accept
                            any geometry requests that would cause
                            it to grow, but it may accept requests
                            (without changing its own size) that
                            would not cause it to grow.  The widget
                            also reports its current size as its own
                            preferred size.

                          +o XXmmRREESSIIZZEE__GGRROOWW-The widget can grow but
                            not shrink.  If its own parent approves,
                            the widget accepts geometry requests
                            that cause it to grow in order to
                            enclose its children.  It may accept
                            requests (without changing its own size)
                            that would not cause it to grow.  When
                            queried about its own preferred size,
                            the widget calculates its layout and
                            reports as its preference the greater of
                            the calculated width and height and the
                            current width and height.

                          +o XXmmRREESSIIZZEE__AANNYY-The widget tries to
                            accommodate geometry requests that would
                            cause it to grow or shrink in order to
                            enclose its children, requesting changes
                            to its own size when necessary.  When
                            queried about its own preferred size,
                            the widget calculates its layout and
                            reports the calculated width and height
                            as its preference.

             In addition to these policies, BulletinBoard has
             geometry facilities that allow it to interact with
             subclasses in laying out complex collections of
             children.  For example, SelectionBox has a List
             containing choices, a Text selection area, labels for



        May 9, 1992                                            10-19








        OSF/Motif Programmer's Guide


             the list and selection area, and three or four buttons.
             Usually the list appears above the selection area.  The
             buttons appear equally spaced in a row below the
             selection area.

             Additional children may be added to the SelectionBox
             after creation.  The first child is used as a work
             area.  The value of XXmmNNcchhiillddPPllaacceemmeenntt determines if the
             work area is placed above or below the Text area, or
             above or below the List area.  Additional children are
             laid out in the following manner:

                +o Menubar-The first menu bar child is placed at the
                  top of the window.

                +o Buttons-All XXmmAArrrroowwBBuuttttoonn, XXmmDDrraawwnnBBuuttttoonn,
                  XXmmPPuusshhBBuuttttoonn, and XXmmTToogggglleeBBuuttttoonn widgets or
                  gadgets, and their subclasses are placed after the
                  OOKK button in the order of their creation.

                +o The layout of additional children that are not in
                  the above categories is undefined.



        10.6  MMaannaaggiinngg GGeeoommeettrryy UUssiinngg FFoorrmm


             Form is a container widget that provides the most
             comprehensive facilities for controlling the layout of
             children.  Constraints are placed on children of the
             Form to define attachments for each of the child's four
             sides.  These attachments can be to the Form, to
             another child widget or gadget, to a relative position
             within the Form, or to the initial position of the
             child.  The attachments determine the layout behavior
             of the Form when resizing occurs.  Form is a subclass
             of BulletinBoard, so the resources and general geometry
             policies of BulletinBoard apply to Form as well.

             Each child has 17 Form constraint resources, four for
             each side of the child and one, XXmmNNrreessiizzaabbllee, that
             applies to the child as a whole.  Following is a
             description of XXmmNNrreessiizzaabbllee and the constraint
             resources that apply to the top side of a child:

             XXmmNNrreessiizzaabbllee This Boolean resource specifies whether or
                       not a child's request for a new size is
                       (conditionally) granted by the Form.  If this
                       resource is set to True the request is
                       granted if possible.  If this resource is set



        10-20                                            May 9, 1992








                                                   Managing Geometry


                       to False the request is always refused.

                       If a child has both left and right
                       attachments, its width is completely
                       controlled by the Form, regardless of the
                       value of the child's XXmmNNrreessiizzaabbllee resource.
                       If a child has a left or right attachment but
                       not both, the child's XXmmNNwwiiddtthh is used in
                       setting its width if the value of the child's
                       XXmmNNrreessiizzaabbllee resource is True.  These
                       conditions are also true for top and bottom
                       attachments, with height acting like width.

             XXmmNNttooppAAttttaacchhmmeenntt
                       Specifies attachment of the top side of the
                       child.  It can have following values:

                          +o XXmmAATTTTAACCHH__NNOONNEE-Do not attach the top side
                            of the child.  If XXmmNNbboottttoommAAttttaacchhmmeenntt is
                            also XXmmAATTTTAACCHH__NNOONNEE, this value is
                            ignored and the child is given a default
                            top attachment.

                          +o XXmmAATTTTAACCHH__FFOORRMM-Attach the top side of the
                            child to the top side of the Form.

                          +o XXmmAATTTTAACCHH__OOPPPPOOSSIITTEE__FFOORRMM-Attach the top
                            side of the child to the bottom side of
                            the Form.  XXmmNNttooppOOffffsseett can be used to
                            determine the visibility of the child.

                          +o XXmmAATTTTAACCHH__WWIIDDGGEETT-Attach the top side of
                            the child to the bottom side of the
                            widget or gadget specified in the
                            XXmmNNttooppWWiiddggeett resource.  If XXmmNNttooppWWiiddggeett
                            is NULL, XXmmAATTTTAACCHH__WWIIDDGGEETT is replaced by
                            XXmmAATTTTAACCHH__FFOORRMM, and the child is attached
                            to the top side of the Form.

                          +o XXmmAATTTTAACCHH__OOPPPPOOSSIITTEE__WWIIDDGGEETT-Attach the top
                            side of the child to the top side of the
                            widget or gadget specified in the
                            XXmmNNttooppWWiiddggeett resource.

                          +o XXmmAATTTTAACCHH__PPOOSSIITTIIOONN-Attach the top side of
                            the child to a position that is relative
                            to the top side of the Form and in
                            proportion to the height of the Form.
                            This position is determined by the
                            XXmmNNttooppPPoossiittiioonn and XXmmNNffrraaccttiioonnBBaassee
                            resources.



        May 9, 1992                                            10-21








        OSF/Motif Programmer's Guide


                          +o XXmmAATTTTAACCHH__SSEELLFF-Attach the top side of the
                            child to a position that is proportional
                            to the current _y value of the child
                            divided by the height of the Form.  This
                            position is determined by the
                            XXmmNNttooppPPoossiittiioonn and XXmmNNffrraaccttiioonnBBaassee
                            resources.  XXmmNNttooppPPoossiittiioonn is set to a
                            value proportional to the current _y
                            value of the child divided by the height
                            of the Form.

             XXmmNNttooppOOffffsseett Specifies the constant offset between the
                       top side of the child and the object to which
                       it is attached.  The relationship established
                       remains, regardless of any resizing
                       operations that occur.

             XXmmNNttooppPPoossiittiioonn
                       This resource is used to determine the
                       position of the top side of the child when
                       the child's XXmmNNttooppAAttttaacchhmmeenntt is set to
                       XXmmAATTTTAACCHH__PPOOSSIITTIIOONN.  In this case the position
                       of the top side of the child is relative to
                       the top side of the Form and is a fraction of
                       the height of the Form.  This fraction is the
                       value of the child's XXmmNNttooppPPoossiittiioonn resource
                       divided by the value of the Form's
                       XXmmNNffrraaccttiioonnBBaassee.  For example, if the child's
                       XXmmNNttooppPPoossiittiioonn is 50, the Form's
                       XXmmNNffrraaccttiioonnBBaassee is 100, and the Form's height
                       is 200, the position of the top side of the
                       child is 100.

             XXmmNNttooppWWiiddggeett
                       Specifies the widget or gadget to which the
                       top side of the child is attached.  This
                       resource is used if XXmmNNttooppAAttttaacchhmmeenntt is set
                       to either XXmmAATTTTAACCHH__WWIIDDGGEETT or
                       XXmmAATTTTAACCHH__OOPPPPOOSSIITTEE__WWIIDDGGEETT.

             These constraint resources interact with the following
             resources of the Form itself:

             XXmmNNffrraaccttiioonnBBaassee
                       Specifies the denominator used in calculating
                       the relative position of a child widget using
                       XXmmAATTTTAACCHH__PPOOSSIITTIIOONN constraints.  The value
                       must not be 0.

                       If the value of a child's XXmmNNlleeffttAAttttaacchhmmeenntt
                       (or XXmmNNrriigghhttAAttttaacchhmmeenntt) is XXmmAATTTTAACCHH__PPOOSSIITTIIOONN,



        10-22                                            May 9, 1992








                                                   Managing Geometry


                       the position of the left (or right) side of
                       the child is relative to the left side of the
                       Form and is a fraction of the width of the
                       Form.  This fraction is the value of the
                       child's XXmmNNlleeffttPPoossiittiioonn (or XXmmNNrriigghhttPPoossiittiioonn)
                       resource divided by the value of the Form's
                       XXmmNNffrraaccttiioonnBBaassee.

                       If the value of a child's XXmmNNttooppAAttttaacchhmmeenntt
                       (or XXmmNNbboottttoommAAttttaacchhmmeenntt) is
                       XXmmAATTTTAACCHH__PPOOSSIITTIIOONN, the position of the top
                       (or bottom) side of the child is relative to
                       the top side of the Form and is a fraction of
                       the height of the Form.  This fraction is the
                       value of the child's XXmmNNttooppPPoossiittiioonn (or
                       XXmmNNbboottttoommPPoossiittiioonn) resource divided by the
                       value of the Form's XXmmNNffrraaccttiioonnBBaassee.

             XXmmNNhhoorriizzoonnttaallSSppaacciinngg
                       Specifies the offset for right and left
                       attachments.

             XXmmNNrruubbbbeerrPPoossiittiioonniinngg
                       Indicates the default near (left) and top
                       attachments for a child of the Form.  (NNoottee::
                       Whether this resource actually applies to the
                       left or right side of the child and its
                       attachment may depend on the value of the
                       XXmmNNssttrriinnggDDiirreeccttiioonn resource.)

                       The default left attachment is applied
                       whenever initialization or XXttSSeettVVaalluueess leaves
                       the child without either a left or right
                       attachment.  The default top attachment is
                       applied whenever initialization or
                       XXttSSeettVVaalluueess leaves the child without either a
                       top or bottom attachment.

                       If this Boolean resource is set to False,
                       XXmmNNlleeffttAAttttaacchhmmeenntt and XXmmNNttooppAAttttaacchhmmeenntt
                       default to XXmmAATTTTAACCHH__FFOORRMM, XXmmNNlleeffttOOffffsseett
                       defaults to the current _x value of the left
                       side of the child, and XXmmNNttooppOOffffsseett defaults
                       to the current _y value of the child.  The
                       effect is to position the child according to
                       its absolute distance from the left or top
                       side of the Form.

                       If this resource is set to True,
                       XXmmNNlleeffttAAttttaacchhmmeenntt and XXmmNNttooppAAttttaacchhmmeenntt
                       default to XXmmAATTTTAACCHH__PPOOSSIITTIIOONN, XXmmNNlleeffttPPoossiittiioonn



        May 9, 1992                                            10-23








        OSF/Motif Programmer's Guide


                       defaults to a value proportional to the
                       current _x value of the left side of the child
                       divided by the width of the Form, and
                       XXmmNNttooppPPoossiittiioonn defaults to a value
                       proportional to the current _y value of the
                       child divided by the height of the Form.  The
                       effect is to position the child relative to
                       the left or top side of the Form and in
                       proportion to the width or height of the
                       Form.

             XXmmNNvveerrttiiccaallSSppaacciinngg
                       Specifies the offset for top and bottom
                       attachments.

             Following are some important considerations in using a
             Form:

                +o Every child must have an attachment on either the
                  left or the right.  If initialization or
                  XXttSSeettVVaalluueess leaves a widget without such an
                  attachment, the result depends upon the value of
                  XXmmNNrruubbbbeerrPPoossiittiioonniinngg.

                  If XXmmNNrruubbbbeerrPPoossiittiioonniinngg is False, the child is
                  given an XXmmNNlleeffttAAttttaacchhmmeenntt of XXmmAATTTTAACCHH__FFOORRMM and an
                  XXmmNNlleeffttOOffffsseett equal to its current _x value.

                  If XXmmNNrruubbbbeerrPPoossiittiioonniinngg is True, the child is
                  given an XXmmNNlleeffttAAttttaacchhmmeenntt of XXmmAATTTTAACCHH__PPOOSSIITTIIOONN
                  and an XXmmNNlleeffttPPoossiittiioonn proportional to the current
                  _x value divided by the width of the Form.

                  In either case, if the child has not been
                  previously given an _x value, its _x value is taken
                  to be 0, which places the child at the left side
                  of the Form.

                +o If you want to create a child without any
                  attachments, and then later (e.g., after creating
                  and managing it, but before realizing it) give it
                  a right attachment via XXttSSeettVVaalluueess, you must set
                  its XXmmNNlleeffttAAttttaacchhmmeenntt to XXmmAATTTTAACCHH__NNOONNEE at the same
                  time.

                +o The XXmmNNrreessiizzaabbllee resource controls only whether a
                  geometry request by the child will be granted.  It
                  has no effect on whether the child's size can be
                  changed because of changes in geometry of the Form
                  or of other children.




        10-24                                            May 9, 1992








                                                   Managing Geometry


                +o Every child has a preferred width, based on
                  geometry requests it makes (whether they are
                  granted or not).

                +o If a child has attachments on both the left and
                  the right sides, its size is completely controlled
                  by the Form.  It can be shrunk below its preferred
                  width or enlarged above it, if necessary, due to
                  other constraints.  In addition, the child's
                  geometry requests to change its own width may be
                  refused.

                +o If a child has attachments on only its left or
                  right side, it will always be at its preferred
                  width (if resizable, otherwise at is current
                  width).  This may cause it to be clipped by the
                  Form or by other children.

                +o If a child's left (or right) attachment is set to
                  XXmmAATTTTAACCHH__SSEELLFF, its corresponding left (or right)
                  offset is forced to 0.  The attachment is then
                  changed to XXmmAATTTTAACCHH__PPOOSSIITTIIOONN, with a position that
                  corresponds to _x value of the child's left (or
                  right) edge.  To fix the position of a side at a
                  specific _x value use XXmmAATTTTAACCHH__FFOORRMM or
                  XXmmAATTTTAACCHH__OOPPPPOOSSIITTEE__FFOORRMM with the _x value as the
                  left (or right) offset.

                +o Unmapping a child has no effect on the Form except
                  that the child is not mapped.

                +o Unmanaging a child unmaps it.  If no other child
                  is attached to it, or if all children attached to
                  it and all children recursively attached to them
                  are also all unmanaged, all of those children are
                  treated as if they did not exist in determining
                  the size of the Form.

                +o When using XXttSSeettVVaalluueess to change the XXmmNNxx resource
                  of a child, you must simultaneously set its left
                  attachment to either XXmmAATTTTAACCHH__SSEELLFF or
                  XXmmAATTTTAACCHH__NNOONNEE.  Otherwise, the request is not
                  granted.  If XXmmNNrreessiizzaabbllee is False, the request is
                  granted only if the child's size can remain the
                  same.

                +o A left (or right) attachment of XXmmAATTTTAACCHH__WWIIDDGGEETT,
                  where XXmmNNlleeffttWWiiddggeett (or XXmmNNrriigghhttWWiiddggeett) is NULL,
                  acts like an attachment of XXmmAATTTTAACCHH__FFOORRMM.





        May 9, 1992                                            10-25








        OSF/Motif Programmer's Guide


                +o If an attachment is made to a widget that is not a
                  child of the Form, but an ancestor of the widget
                  is a child of the Form, the attachment is made to
                  the ancestor.

             All these considerations are true of top and bottom
             attachments as well, with top acting like left, bottom
             acting like right, _y acting like _x, and height acting
             like width.













































        10-26                                            May 9, 1992






 
