















        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 consists of 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, for example, 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 that 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 using the
                  window manager.






        August 26, 1994                                         10-1







        OSF/Motif Programmer's Guide


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

             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:





        10-2                                         August 26, 1994







                                                   Managing Geometry


                +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
                  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




        August 26, 1994                                         10-3







        OSF/Motif Programmer's Guide


                  child's rreessiizzee procedure to inform the child of
                  the size change.  This procedure makes any
                  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




        10-4                                         August 26, 1994







                                                   Managing Geometry


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




        August 26, 1994                                         10-5







        OSF/Motif Programmer's Guide


                  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
                  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                                         August 26, 1994







                                                   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 is given the
                  geometry it requested and the child's rreessiizzee
                  procedure is 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




        August 26, 1994                                         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
             it 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                                         August 26, 1994







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




        August 26, 1994                                         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                                        August 26, 1994







                                                   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.










        August 26, 1994                                        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                                        August 26, 1994







                                                   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




        August 26, 1994                                        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 Section 10.6.  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                                        August 26, 1994







                                                   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:

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

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

             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:






        August 26, 1994                                        10-15







        OSF/Motif Programmer's Guide


             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 this
                       resource is 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.  When this resource is 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 bottom edge of the RowColumn.

             XXmmNNeennttrryyBBoorrddeerr
                       When this resource is nonzero, it specifies
                       the border width for all children of the
                       RowColumn.  When this resource is 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
                       This resource 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
                       This resource 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 this resource is True, RowColumn adjusts
                       its own height when possible to accommodate
                       its children.  When this resource is 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 this resource is True, RowColumn adjusts
                       its own width when possible to accommodate
                       its children.  When this resource is 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.  It specifies




        10-16                                        August 26, 1994







                                                   Managing Geometry


                       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.
                       When this resource is 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 this
                       resource is 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 this resource is 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:

                       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.

                       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.

                       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.




        August 26, 1994                                        10-17







        OSF/Motif Programmer's Guide


             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:

                       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 value is
                                 applicable only when all children
                                 in a row contain textual data.

                       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 value is
                                 applicable only when all children
                                 in a row contain textual data.

                       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.

                       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.

                       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-18                                        August 26, 1994







                                                   Managing Geometry


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

                       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.

                       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




        August 26, 1994                                        10-19







        OSF/Motif Programmer's Guide


                                 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.

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

             MenuBar   The first MenuBar child is placed at the top
                       of the window.

             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 OK button in the order of their
                       creation.

             Others    The layout of additional children that are
                       not in the above categories is undefined.







        10-20                                        August 26, 1994







                                                   Managing Geometry


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

                       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.





        August 26, 1994                                        10-21







        OSF/Motif Programmer's Guide


                       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.

                       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.

                       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.

                       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.

                       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.

                       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




        10-22                                        August 26, 1994







                                                   Managing Geometry


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




        August 26, 1994                                        10-23







        OSF/Motif Programmer's Guide


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




        10-24                                        August 26, 1994







                                                   Managing Geometry


                       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 (for example, after
                  creating and managing it, but before realizing it)
                  give it a right attachment using 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.

                +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




        August 26, 1994                                        10-25







        OSF/Motif Programmer's Guide


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

                +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                                        August 26, 1994





 m
