















        Chapter 9.  SSccrroolllliinngg,, PPaanneess,, aanndd FFrraammeess








             Chapters 6 and 7 discuss the OSF/Motif Manager widgets
             used to construct menus and dialogs.  Motif also
             provides more general-purpose managers intended for use
             in main application windows and some dialogs.  This
             chapter discusses widgets that perform the following
             functions:

                +o Establishing a viewport for a larger underlying
                  scroll

                +o Providing a main application window with a
                  combination of standard and custom components

                +o Placing a shadowed frame around a widget and an
                  optional title at the top

                +o Creating multiple subwindows for a composite with
                  adjustable boundaries between the subwindows



        9.1  SSccrroolllleeddWWiinnddooww



             Frequently a collection occupies an area that is too
             large to display within an application or that may grow
             or shrink as the user adds or deletes data.  Examples
             include text in a Text widget, items in a List, and
             graphical objects in a DrawingArea or other canvas.
             Three approaches exist for handling this problem:



        May 9, 1992                                              9-1








        OSF/Motif Programmer's Guide


                +o Set a fixed size for the widget.  The disadvantage
                  of this approach is that when the collection grows
                  beyond the bounds of the widget, part of the
                  collection is not visible.

                +o Allow the widget to make geometry requests to
                  expand or contract, perhaps up to some maximum or
                  down to some minimum size.  The disadvantages of
                  this approach are that it may disrupt the
                  application's visual layout and that the widget is
                  able to grow only within limits, perhaps not at
                  all.

                +o Treat the collection as a virtual scroll, with the
                  widget acting as a (more or less) fixed-size
                  viewport onto the scroll.  The user can move the
                  viewport to expose obscured portions of the
                  scroll.

             The ScrolledWindow widget implements the last approach.
             It is a Manager with one or two ScrollBar children, a
             child widget that acts as the virtual scroll, and in
             some cases another child that acts as a viewport onto
             the scroll.  By using the ScrollBars or keyboard
             scrolling commands, the user moves the viewport to
             expose part of the scroll.



        9.1.1  AAuuttoommaattiicc aanndd AApppplliiccaattiioonn--DDeeffiinneedd SSccrroolllliinngg



             ScrolledWindow implements two scrolling models:
             automatic and application-defined.

             In automatic scrolling, the application creates a
             widget to serve as the virtual scroll, and the
             ScrolledWindow creates the ScrollBars and a widget to
             serve as a fixed-size viewport onto the scroll.  The
             application adjusts the size of the scroll widget as
             necessary to contain the entire collection.  The
             ScrolledWindow adjusts the appropriate ScrollBar
             resources so that the size and position of the slider
             reflect the position of the viewport in relation to the
             scroll and the proportion of the scroll's entire size
             that the viewport represents.  The ScrolledWindow also
             handles the user's interaction with the ScrollBars,
             moving the viewport in relation to the scroll as the
             user manipulates the ScrollBars.  Usually the
             application need have no interaction with the



        9-2                                              May 9, 1992








                                        Scrolling, Panes, and Frames


             ScrollBars or the widget that serves as the viewport.

             In application-defined scrolling, the application must
             create the ScrollBars as well as the widget that acts
             as the virtual scroll and, if necessary, a separate
             viewport widget.  The application must determine how
             large to make the viewport widget and what portion of
             the data to display in the viewport.  The application
             handles all interaction with the ScrollBars.  It must
             adjust the appropriate ScrollBar resources if it wants
             the size and position of the slider to reflect the
             relation of the viewport to the underlying scroll.  It
             must also move the viewport in relation to the scroll
             as the user interacts with the ScrollBars.

             The ScrolledWindow resource XXmmNNssccrroolllliinnggPPoolliiccyy
             determines the scrolling model.  Possible values are
             XXmmAAUUTTOOMMAATTIICC and XXmmAAPPPPLLIICCAATTIIOONN__DDEEFFIINNEEDD.  The default is
             XXmmAAPPPPLLIICCAATTIIOONN__DDEEFFIINNEEDD.



        9.1.2  OOtthheerr RReessoouurrcceess



             In addition to XXmmNNssccrroolllliinnggPPoolliiccyy, ScrolledWindow has
             two sets of resources.

             One set of resources holds the components of the
             ScrolledWindow.  An application usually does not have
             to set any of these resources; the ScrolledWindow
             examines the class and other characteristics of each
             child as it is created and sets the appropriate
             resource.  If the application needs to supply a new
             ScrollBar or scroll widget after creating the initial
             component, it can use either XXttSSeettVVaalluueess or
             XXmmSSccrroolllleeddWWiinnddoowwSSeettAArreeaass.

             XXmmNNcclliippWWiinnddooww
                       The value is the ID of the viewport widget
                       created by the ScrolledWindow in automatic
                       scrolling.  This resource applies only when
                       the XXmmNNssccrroolllliinnggPPoolliiccyy is XXmmAAUUTTOOMMAATTIICC.  It is
                       a read-only resource; the application cannot
                       set a new value.

             XXmmNNhhoorriizzoonnttaallSSccrroollllBBaarr
                       The value is the ID of the horizontal
                       ScrollBar.  The ScrolledWindow creates this
                       ScrollBar and sets the value of this resource



        May 9, 1992                                              9-3








        OSF/Motif Programmer's Guide


                       when the XXmmNNssccrroolllliinnggPPoolliiccyy is XXmmAAUUTTOOMMAATTIICC.
                       In application-defined scrolling, the
                       application must create and manage the
                       ScrollBar, but the ScrolledWindow
                       automatically sets the value of this resource
                       to its widget ID.

             XXmmNNvveerrttiiccaallSSccrroollllBBaarr
                       The value is the ID of the vertical
                       ScrollBar.  The ScrolledWindow creates this
                       ScrollBar and sets the value of this resource
                       when the XXmmNNssccrroolllliinnggPPoolliiccyy is XXmmAAUUTTOOMMAATTIICC.
                       In application-defined scrolling, the
                       application must create and manage the
                       ScrollBar, but the ScrolledWindow
                       automatically sets the value of this resource
                       to its widget ID.

             XXmmNNwwoorrkkWWiinnddooww
                       The value is the ID of the widget that serves
                       as the scroll.  The application has to create
                       and manage this widget, but it usually does
                       not have to set this resource.  When the
                       application creates a child of the
                       ScrolledWindow that is not a ScrollBar, the
                       ScrolledWindow automatically sets the value
                       of this resource to its widget ID.

             The second set of resources specifies the layout of the
             ScrolledWindow:

             XXmmNNssccrroollllBBaarrDDiissppllaayyPPoolliiccyy
                       This resource determines whether the
                       ScrolledWindow always displays managed
                       ScrollBars or displays them only when the
                       corresponding dimensions of the scroll exceed
                       those of the viewport.  Possible values are
                       XXmmAASS__NNEEEEDDEEDD and XXmmSSTTAATTIICC.  The value is
                       forced to XXmmSSTTAATTIICC when the scrolling policy
                       is XXmmAAPPPPLLIICCAATTIIOONN__DDEEFFIINNEEDD and defaults to
                       XXmmAASS__NNEEEEDDEEDD when the scrolling policy is
                       XXmmAAUUTTOOMMAATTIICC.

             XXmmNNssccrroollllBBaarrPPllaacceemmeenntt
                       This resource determines where the
                       ScrolledWindow places the horizontal and
                       vertical ScrollBars.  The possible values are
                       constants that specify on which sides of the
                       viewport the ScrolledWindow places the two
                       ScrollBars: XXmmTTOOPP__LLEEFFTT, XXmmTTOOPP__RRIIGGHHTT,
                       XXmmBBOOTTTTOOMM__LLEEFFTT, and XXmmBBOOTTTTOOMM__RRIIGGHHTT.



        9-4                                              May 9, 1992








                                        Scrolling, Panes, and Frames


             XXmmNNssccrroolllleeddWWiinnddoowwMMaarrggiinnHHeeiigghhtt
                       This resource specifies the margins between
                       the top and bottom sides of the
                       ScrolledWindow and the first child on each
                       side.

             XXmmNNssccrroolllleeddWWiinnddoowwMMaarrggiinnWWiiddtthh
                       This resource specifies the margins between
                       the left and right sides of the
                       ScrolledWindow and the first child on each
                       side.

             XXmmNNssppaacciinngg
                       This resource specifies the distance between
                       each ScrollBar and the viewport.



        9.2  AAuuttoommaattiicc SSccrroolllliinngg



             In the automatic scrolling model, the ScrolledWindow
             creates a fixed-size viewport and handles all
             interaction with the ScrollBars.  The application
             usually needs to take only the following steps:

                +o Create and manage a ScrolledWindow, supplying a
                  value of XXmmAAUUTTOOMMAATTIICC for XXmmNNssccrroolllliinnggPPoolliiccyy in the
                  argument list passed to the creation function

                +o Create and manage a widget child of the
                  ScrolledWindow to serve as the scroll

                +o Adjust the size of the scroll widget, typically
                  using XXttSSeettVVaalluueess of XXmmNNhheeiigghhtt and XXmmNNwwiiddtthh, as
                  necessary to contain all the data in the scroll

             The ScrolledWindow automatically creates a widget to
             serve as the viewport and sets XXmmNNcclliippWWiinnddooww to the ID
             of this widget.  It also creates horizontal and
             vertical ScrollBars and sets XXmmNNhhoorriizzoonnttaallSSccrroollllBBaarr and
             XXmmNNvveerrttiiccaallSSccrroollllBBaarr to the appropriate IDs of the
             ScrollBars.  The ScrolledWindow attaches callback
             procedures to the ScrollBars to handle user interaction
             with the ScrollBars.

             The ScrolledWindow sets the ScrollBar resource
             XXmmNNiinnccrreemmeenntt to a small fraction of the height or width
             of the viewport.  It sets the ScrollBar resource
             XXmmNNppaaggeeIInnccrreemmeenntt to a large fraction of the height or



        May 9, 1992                                              9-5








        OSF/Motif Programmer's Guide


             width of the viewport.  If the ScrolledWindow resizes
             the viewport, it recomputes the values of these
             resources.

             The ScrolledWindow sets the ScrollBar resources
             XXmmNNmmaaxxiimmuumm, XXmmNNmmiinniimmuumm, and XXmmNNsslliiddeerrSSiizzee so that the
             size of the slider reflects the proportion of the
             entire scroll that the viewport represents.  If the
             application resizes the scroll or if the ScrolledWindow
             resizes the viewport, the ScrolledWindow recomputes the
             values of some or all of these resources.

             If the value of XXmmNNssccrroollllBBaarrDDiissppllaayyPPoolliiccyy is
             XXmmAASS__NNEEEEDDEEDD, as it is by default in automatic
             scrolling, the ScrolledWindow displays a ScrollBar only
             if the size of the scroll exceeds the size of the
             viewport in the relevant dimension.  If the value of
             XXmmNNssccrroollllBBaarrDDiissppllaayyPPoolliiccyy is XXmmSSTTAATTIICC, the
             ScrolledWindow always displays both ScrollBars.

             As the user manipulates a ScrollBar and changes its
             XXmmNNvvaalluuee, the ScrolledWindow moves the scroll with
             respect to the viewport.  For example, if the user
             moves the slider down in a vertical ScrollBar, the
             ScrolledWindow moves the scroll up with respect to the
             viewport.

             The ScrolledWindow may need to move the scroll (and set
             a ScrollBar's XXmmNNvvaalluuee) in circumstances other than the
             user's interaction with the ScrollBar.  For example, if
             the viewport is at the bottom of the scroll and the
             application reduces the height of the scroll, the
             ScrolledWindow must move the scroll down with respect
             to the viewport.  In this case it reduces the
             ScrollBar's XXmmNNmmaaxxiimmuumm and XXmmNNvvaalluuee.

             In automatic scrolling the application should not try
             to set any of the following resources:

                +o The XXmmNNxx or XXmmNNyy of any child of the
                  ScrolledWindow

                +o Any geometry resources of the viewport (the
                  XXmmNNcclliippWWiinnddooww)

                +o The XXmmNNmmaaxxiimmuumm, XXmmNNmmiinniimmuumm, XXmmNNvvaalluuee,
                  XXmmNNiinnccrreemmeenntt, or XXmmNNppaaggeeIInnccrreemmeenntt of a ScrollBar

             The application can add callbacks of its own to a
             ScrollBar, but because the ScrolledWindow adds its own
             callbacks, the application must not call



        9-6                                              May 9, 1992








                                        Scrolling, Panes, and Frames


             XXttRReemmoovveeAAllllCCaallllbbaacckkss for a ScrollBar.

             The application or user can specify other resources,
             such as those that determine appearance, for the
             ScrolledWindow or its children.  The names of the
             automatically created ScrollBars are "HorScrollBar" and
             "VertScrollBar".



        9.2.1  TTrraavveerrssiinngg ttoo OObbssccuurreedd WWiiddggeettss



             By default it is not possible to use keyboard traversal
             to move to a widget that is inside the scroll but
             outside the viewport.  For example, if the user presses
             KKNNeexxttFFiieelldd and the next field is not within the
             viewport, focus does not move to that field.  The user
             must first use the ScrollBars or a scrolling command to
             position the viewport so that the target widget is no
             longer obscured.

             ScrolledWindow has a callback list,
             XXmmNNttrraavveerrsseeOObbssccuurreeddCCaallllbbaacckk, that allows an application
             to make it possible to traverse to widgets that are in
             the scroll but not in the viewport.  The callback list
             is invoked when the user tries to traverse to such a
             widget in a ScrolledWindow with automatic scrolling.
             The callback procedure is passed a pointer to an
             XXmmTTrraavveerrsseeOObbssccuurreeddCCaallllbbaacckkSSttrruucctt structure, which
             contains the reason (XXmmCCRR__OOBBSSCCUURREEDD__TTRRAAVVEERRSSAALL), the
             event, the widget that is the target of the traversal,
             and the traversal direction passed to
             XXmmPPrroocceessssTTrraavveerrssaall.

             Usually the callback procedure can allow traversal to
             the target widget simply by calling XXmmSSccrroollllVViissiibbllee.
             This function takes as arguments the ScrolledWindow,
             the target widget, and requested margins between the
             target widget and the edges of the viewport.  The
             function moves the work area with respect to the
             viewport to make the obscured widget visible.  This
             function applies only to ScrolledWidgets with automatic
             scrolling.

             When ScrolledWindows are nested and focus is in an
             inner ScrolledWindow, the XXmmNNttrraavveerrsseeOObbssccuurreeddCCaallllbbaacckk
             callbacks of the inner ScrolledWindow are invoked first
             if necessary.  If the destination widget remains
             outside the viewport of the first ancestor



        May 9, 1992                                              9-7








        OSF/Motif Programmer's Guide


             ScrolledWindow, that ScrolledWindow's
             XXmmNNttrraavveerrsseeOObbssccuurreeddCCaallllbbaacckk callbacks are invoked, and
             so on up the widget hierarchy.



        9.2.2  EExxaammppllee ooff AAuuttoommaattiicc SSccrroolllliinngg



             This section contains the scrolling-related portions of
             an example program that uses a ScrolledWindow with an
             automatic scrolling policy.  The ScrolledWindow is
             actually a MainWindow, a subclass of ScrolledWindow
             that is often the containing manager for the primary
             window of an application.  (MainWindow is discussed in
             a later section of this chapter.)  The scroll widget is
             a DrawingArea.

             The application allows the user to create a simple map
             in the DrawingArea.  The user can use the mouse to
             establish points representing cities and to draw lines
             between the cities.  The application contains a
             TextField that allows the user to enter the name of a
             city and then to create a button child of the
             DrawingArea located at the city and containing the
             city's name as its label.  The user can adjust the size
             of the DrawingArea by manipulating two Scales, one for
             the height of the DrawingArea and the other for the
             width.  Other parts of the application save and
             retrieve the map data.

             This section contains only the portions of the
             application that relate directly to creating and
             maintaining the ScrolledWindow.  These include:

                +o Creating the MainWindow with an automatic
                  scrolling policy

                +o Creating the DrawingArea child of the
                  ScrolledWindow

                +o Resizing the DrawingArea in response to the user's
                  interaction with the Scales

                +o Establishing an XXmmNNttrraavveerrsseeOObbssccuurreeddCCaallllbbaacckk
                  procedure

             /*-------------------------------------------------------------
             **      Create a Main Window with a menubar, a command panel containing
             **      2 scales and a textfied, and a workarea.



        9-8                                              May 9, 1992








                                        Scrolling, Panes, and Frames


             **      Also put in the graphic structure the workarea info and the
             **      textfield ids.
             */
             void CreateApplication (
             Widget          parent,
             Graphic *       graph )
             {
                 Widget main_window, menu_bar, menu_pane, cascade,
                        button, comw, scale ;
                 Arg args[5];
                 int n ;

                 /*  Create automatic MainWindow.
                  */
                 n = 0;
                 XtSetArg (args[n], XmNscrollingPolicy, XmAUTOMATIC);  n++;
                 main_window = XmCreateMainWindow (parent, "main_window", args, n);

                 XtAddCallback (main_window, XmNtraverseObscuredCallback, TravCB, NULL);

                 XtManageChild (main_window);

             ...

                 /*  Create work_area in MainWindow
                  */
                 n = 0;
                 XtSetArg (args[n], XmNresizePolicy, XmRESIZE_NONE); n++ ;
                 XtSetArg (args[n], XmNmarginWidth, 0); n++ ;
                 XtSetArg (args[n], XmNmarginHeight, 0); n++ ;
                 graph->work_area = XmCreateDrawingArea(main_window, "work_area", args, n);
                 XtAddCallback (graph->work_area, XmNexposeCallback, DrawCB,
                                (XtPointer)graph);
                 XtAddCallback (graph->work_area, XmNresizeCallback, DrawCB,
                                (XtPointer)graph);
                 XtAddCallback (graph->work_area, XmNinputCallback, DrawCB,
                                (XtPointer)graph);
                 XtManageChild (graph->work_area);

                 /*  Create a commandWindow in MainWindow with text and scales
                  */
                 n = 0;
                 comw = XmCreateRowColumn(main_window, "comw", args, n);
                 XtManageChild (comw);
                 n = 0;
                 XtSetArg (args[n], XmNcommandWindow, comw);  n++;
                 XtSetValues (main_window, args, n);

                 /* find the initial size of the work_area and report to the scales */
                 n = 0;
                 XtSetArg (args[n], XmNwidth, &graph->old_width);  n++;



        May 9, 1992                                              9-9








        OSF/Motif Programmer's Guide


                 XtSetArg (args[n], XmNheight, &graph->old_height);  n++;
                 XtGetValues (graph->work_area, args, n);

                 n = 0;
                 XtSetArg (args[n], XmNorientation, XmHORIZONTAL);  n++;
                 XtSetArg (args[n], XmNvalue, graph->old_width);  n++;
                 scale = XmCreateScale(comw, "scale_w", args, n); /* scale_w is the name */
                 XtAddCallback (scale, XmNvalueChangedCallback, ValueCB,
                                (XtPointer)graph->work_area);
                 XtManageChild (scale);

                 n = 0;
                 XtSetArg (args[n], XmNorientation, XmHORIZONTAL);  n++;
                 XtSetArg (args[n], XmNvalue, graph->old_height);  n++;
                 scale = XmCreateScale(comw, "scale_h", args, n);
                 XtAddCallback (scale, XmNvalueChangedCallback, ValueCB,
                                (XtPointer)graph->work_area);
                 XtManageChild (scale);

                 n = 0;
                 graph->textf = XmCreateTextField(comw, "textf", args, n);
                 XtManageChild (graph->textf);

                 /*  Set MainWindow areas
                  */
                 XmMainWindowSetAreas (main_window, menu_bar, comw, NULL, NULL,
                                       graph->work_area);
             }

             /*-------------------------------------------------------------
             **      TravCB          - callback for traverseObscure
             */
             void TravCB (
             Widget          w,              /*  widget id           */
             XtPointer       client_data,    /*  data from application   */
             XtPointer       call_data )     /*  data from widget class  */
             {
                 XmTraverseObscuredCallbackStruct * tocs =
                     (XmTraverseObscuredCallbackStruct *) call_data ;

                 XmScrollVisible(w, tocs->traversal_destination, 20, 20) ;
             }

             /*-------------------------------------------------------------
             **      ValueCB         - callback for scales
             */
             void ValueCB (
             Widget          w,              /*  widget id           */
             XtPointer       client_data,    /*  data from application   */
             XtPointer       call_data )     /*  data from widget class  */
             {



        9-10                                             May 9, 1992








                                        Scrolling, Panes, and Frames



                 Arg args[5];
                 int n ;
                 int value ;
                 Widget workarea = (Widget) client_data ;

                 /* get the value outof the Scale */
                 n = 0;
                 XtSetArg (args[n], XmNvalue, &value);  n++;
                 XtGetValues (w, args, n);

                 n = 0;
                 if (strcmp(XtName(w), "scale_w") == 0 ) { /* width scale */
                     XtSetArg (args[n], XmNwidth, value);  n++;
                 } else {
                     XtSetArg (args[n], XmNheight, value);  n++;
                 }
                 XtSetValues (workarea, args, n);
             }



        9.3  AApppplliiccaattiioonn--DDeeffiinneedd SSccrroolllliinngg



             In application-defined scrolling, the application is
             responsible for all aspects of the interactions among
             the scroll, the viewport, and the ScrollBars.  The
             ScrolledWindow remains responsible for geometry and
             layout, but the application must adjust both the
             ScrollBars and the scroll position in response to the
             user's scrolling actions.

             Because this model requires more work on the part of
             the application, it is most suitable for programs in
             which automatic scrolling is not adequate.  For
             example, an application may contain a text editor or
             browser that reads only enough of a file to fill the
             viewport.  This application must be informed of the
             user's scrolling actions so that it can read more of
             the file when necessary.

             The application implements a scheme of its choosing for
             the relationship between the scroll and the viewport.
             Following are two common models:

                +o A fixed-size viewport widget as the parent of a
                  variable-sized scroll widget that contains the
                  data.  The application resizes the scroll widget
                  as necessary to contain all the data.  As the user



        May 9, 1992                                             9-11








        OSF/Motif Programmer's Guide


                  interacts with the ScrollBar, the application
                  moves the scroll widget with respect to the
                  viewport, which clips the scroll.  This is the
                  model that ScrolledWindow uses for automatic
                  scrolling.

                +o A single widget that serves as the viewport, with
                  the scroll contained in internal data structures
                  or a combination of data structures and files.
                  The application expands the internal structures as
                  necessary to contain all the data.  As the user
                  interacts with the ScrollBar, the application
                  retrieves the appropriate portion of the data from
                  the internal structures or files and displays that
                  portion of the data in the viewport.  This is the
                  model that the Motif ScrolledList and ScrolledText
                  widgets use.

             In both models, the application must be notified when
             the viewport is resized.  It may need to adjust the
             scroll with respect to the viewport, and it must
             recompute ScrollBar resources to reflect the new
             relation between the viewport and the scroll.  If the
             viewport is a DrawingArea the application can use the
             XXmmNNrreessiizzeeCCaallllbbaacckk callbacks for this purpose.
             Otherwise, the application can establish an event
             handler for CCoonnffiigguurreeNNoottiiffyy events.

             The application needs to take the following steps to
             use application-defined scrolling:

                +o Create and manage a ScrolledWindow, horizontal and
                  vertical ScrollBar children, and a child to serve
                  as the viewport.

                +o If the application is using a separate widget as
                  the scroll, create and manage that widget as a
                  child of the viewport widget.

                +o Add callbacks to the ScrollBars to notify the
                  application when the user interacts with the
                  ScrollBars.  The application should at least
                  provide a procedure for the
                  XXmmNNvvaalluueeCChhaannggeeddCCaallllbbaacckk list.

                +o Add a callback (such as the DrawingArea
                  XXmmNNrreessiizzeeCCaallllbbaacckk) or an event handler to the
                  viewport widget to notify the application when the
                  widget is resized.





        9-12                                             May 9, 1992








                                        Scrolling, Panes, and Frames


                +o Based on the initial relationship between the
                  viewport and the scroll, supply initial values for
                  the ScrollBars' XXmmNNiinnccrreemmeenntt, XXmmNNppaaggeeIInnccrreemmeenntt,
                  XXmmNNmmaaxxiimmuumm, XXmmNNmmiinniimmuumm, XXmmNNvvaalluuee, and
                  XXmmNNsslliiddeerrSSiizzee resources.

                +o Adjust the size of the scroll widget or internal
                  data structures as necessary to contain the data
                  in the scroll.

                +o As the data in the scroll changes, recompute the
                  ScrollBars' XXmmNNmmaaxxiimmuumm and XXmmNNsslliiddeerrSSiizzee and
                  perhaps XXmmNNmmiinniimmuumm and XXmmNNvvaalluuee to reflect the new
                  relation between the viewport and the scroll.

                +o When the viewport is resized, if necessary
                  reposition and resize the scroll with respect to
                  the viewport.  Recompute the ScrollBars'
                  XXmmNNsslliiddeerrSSiizzee and XXmmNNppaaggeeIInnccrreemmeenntt and possibly
                  other resources to reflect the new relation
                  between the viewport and the scroll.

                +o As the user interacts with the ScrollBars, if a
                  separate scroll widget exists, reposition the
                  scroll with respect to the viewport.  If no
                  separate scroll widget exists, bring in additional
                  data from files if necessary, recompute which
                  portion of the data to make visible, and redisplay
                  the viewport.  If the size of the scroll has
                  changed, recompute the ScrollBar resources to
                  reflect the new relation between the viewport and
                  the scroll.



        9.3.1  EExxaammppllee ooff AApppplliiccaattiioonn--DDeeffiinneedd SSccrroolllliinngg



             This section contains the scrolling-related portions of
             an example program that uses a ScrolledWindow with an
             application-defined scrolling policy.  As in the
             example of automatic scrolling, the ScrolledWindow is a
             MainWindow, and the scroll widget is a DrawingArea.  In
             this example the scroll widget also serves as the
             viewport widget, and the scroll data is maintained in
             internal data structures.

             The application is a simple file browser for C source
             code.  The user selects a file name.  The program reads
             the file and parses it (in the C locale) into an



        May 9, 1992                                             9-13








        OSF/Motif Programmer's Guide


             internal table of lines.  The application displays in
             the DrawingArea as many lines as will fit into the
             current dimensions of the DrawingArea.

             The application uses only a vertical ScrollBar, which
             allows the user to browse through the file.  After
             reading the file, the program sets the ScrollBar's
             XXmmNNmmiinniimmuumm and XXmmNNvvaalluuee to 0, its XXmmNNmmaaxxiimmuumm to the
             number of lines in the file, and its XXmmNNsslliiddeerrSSiizzee to
             lesser of the number of lines in the file and the
             number of lines that can be displayed in the viewport.

             The program establishes a ScrollBar
             XXmmNNvvaalluueeCChhaannggeeddCCaallllbbaacckk and a DrawingArea
             XXmmNNeexxppoosseeCCaallllbbaacckk that redisplay the lines in the
             viewport.  The redisplay procedure fetches and displays
             lines from the internal data structure, starting with
             the line indicated by the ScrollBar's XXmmNNvvaalluuee and
             proceeding to the last line that fits in the viewport.
             The program also establishes a DrawingArea
             XXmmNNrreessiizzeeCCaallllbbaacckk that recomputes the ScrollBar's
             XXmmNNsslliiddeerrSSiizzee and XXmmNNvvaalluuee based on the number of lines
             that can be displayed in the viewport.  The application
             does not resize the DrawingArea itself.

             This section contains only the portions of the
             application that relate directly to creating and
             maintaining the ScrolledWindow.  These include:

                +o Creating the MainWindow with an application-
                  defined scrolling policy

                +o Creating the DrawingArea and vertical ScrollBar
                  children of the ScrolledWindow

                +o Establishing an XXmmNNaaccttiivvaatteeCCaallllbbaacckk callback for
                  the OK button of the FileSelectionBox invoked from
                  the file menu Open button

                +o Establishing a ScrollBar XXmmNNvvaalluueeCChhaannggeeddCCaallllbbaacckk

                +o Establishing a DrawingArea XXmmNNeexxppoosseeCCaallllbbaacckk and
                  XXmmNNrreessiizzeeCCaallllbbaacckk

             /*-------------------------------------------------------------
             **      Internal data structure to hold file info.
             */
             typedef struct {
                 Widget work_area  ;
                 Widget v_scrb ;
                 String file_name ;



        9-14                                             May 9, 1992








                                        Scrolling, Panes, and Frames


                 XFontStruct * font_struct ;
                 GC draw_gc ;
                 char ** lines ;
                 int num_lines ;
             } FileData ;

             /*-------------------------------------------------------------
             **      Create an app_defined Main Window with a Menubar to load a file
             **      Add the vertical scrollbar and the workarea to filedata.
             */
             void CreateApplication (
             Widget          parent,
             FileData *      filedata )
             {
                 Widget main_window, menu_bar, menu_pane, cascade,
                        button ;
                 Arg args[5];
                 int n ;

                 /*  Create app_defined MainWindow.
                  *  XmAPPLICATION_DEFINED is the default; not necessary to
                  *  specify it here.
                  */
                 n = 0;
                 XtSetArg (args[n], XmNscrollingPolicy, XmAPPLICATION_DEFINED);  n++;
                 main_window = XmCreateMainWindow (parent, "main_window", args, n);
                 XtManageChild (main_window);

                 /*  Create MenuBar in MainWindow.
                  */

             ...

                 /*  Create "File" PulldownMenu with Open and Quit buttons
                  */

                 n = 0;
                 menu_pane = XmCreatePulldownMenu (menu_bar, "menu_pane", args, n);

                 n = 0;
                 button = XmCreatePushButton (menu_pane, "Open...", args, n);
                 XtManageChild (button);

                 /* pass the file data to the Open callback */
                 XtAddCallback (button, XmNactivateCallback, OpenCB, (XtPointer)filedata);
                 n = 0;
                 button = XmCreatePushButton (menu_pane, "Quit", args, n);
                 XtManageChild (button);
                 XtAddCallback (button, XmNactivateCallback, QuitCB, NULL);

                 n = 0;



        May 9, 1992                                             9-15








        OSF/Motif Programmer's Guide


                 XtSetArg (args[n], XmNsubMenuId, menu_pane);  n++;
                 cascade = XmCreateCascadeButton (menu_bar, "File", args, n);
                 XtManageChild (cascade);

                 /*  Create "Help" PulldownMenu with Help button.
                  */

             ...

                 /*  Create vertical scrollbar only
                  */
                  n = 0;
                 XtSetArg (args[n], XmNorientation, XmVERTICAL);  n++;
                 filedata->v_scrb = XmCreateScrollBar (main_window, "v_scrb", args, n);
                 XtAddCallback (filedata->v_scrb, XmNvalueChangedCallback, ValueCB,
                                (XtPointer)filedata);
                 XtManageChild (filedata->v_scrb);

                 /*  Create work_area in MainWindow
                  */
                 n = 0;
                 filedata->work_area = XmCreateDrawingArea(main_window, "work_area", args, n);
                 XtAddCallback (filedata->work_area, XmNexposeCallback, DrawCB,
                                (XtPointer)filedata);
                 XtAddCallback (filedata->work_area, XmNresizeCallback, DrawCB,
                                (XtPointer)filedata);
                 XtManageChild (filedata->work_area);

                 /*  Set MainWindow areas
                  */
                 XmMainWindowSetAreas (main_window, menu_bar, NULL, NULL,
                                       filedata->v_scrb,
                                       filedata->work_area);

             }

             /*-------------------------------------------------------------
             **      OpenCB                  - callback for Open button
             */
             void OpenCB (
             Widget          w,              /*  widget id           */
             XtPointer       client_data,    /*  data from application   */
             XtPointer       call_data )     /*  data from widget class  */
             {
                     static Widget fsb_box = NULL ;

                     if (!fsb_box) {
                         fsb_box = XmCreateFileSelectionDialog (w, "Load file",
                                                                NULL, 0);
                         /* just propagate the file information */
                         XtAddCallback (fsb_box, XmNokCallback, ReadCB, client_data);



        9-16                                             May 9, 1992








                                        Scrolling, Panes, and Frames


                     }

                     XtManageChild (fsb_box);
             }

             /*-------------------------------------------------------------
             **      ReadCB  - callback for fsb activate
             */
             void ReadCB (
             Widget          w,              /*  widget id           */
             XtPointer       client_data,    /*  data from application   */
             XtPointer       call_data )     /*  data from widget class  */
             {
                 FileData * filedata = (FileData *) client_data ;
                 String file_name ;
                 Arg args[5];
                 int n, slider_size ;
                 Dimension height ;

                 file_name = XmTextGetString(
                              XmFileSelectionBoxGetChild(w, XmDIALOG_TEXT)) ;

                 if (!BuildLineTable(filedata, file_name)) {
                     WarnUser (w, "Cannot open %s0, file_name);
                 } else {
                     filedata->file_name = file_name ;

                     /* ok, we have a new file, so reset some values */
                     n = 0;
                     XtSetArg (args[n], XmNheight, &height);  n++;
                     XtGetValues (filedata->work_area, args, n);

                     slider_size = (height - 4) / (filedata->font_struct->ascent
                                                   + filedata->font_struct->descent) ;
                     if (slider_size <= 0) slider_size = 1 ;
                     if (slider_size > filedata->num_lines)
                         slider_size = filedata->num_lines ;

                     n = 0 ;
                     XtSetArg (args[n], XmNsliderSize, slider_size);  n++;
                     XtSetArg (args[n], XmNmaximum, filedata->num_lines);  n++;
                     XtSetArg (args[n], XmNvalue, 0);  n++;
                     XtSetValues (filedata->v_scrb, args, n);

                     /* clear and redraw */
                     XClearWindow(XtDisplay(filedata->work_area),
                                  XtWindow(filedata->work_area));
                     ReDraw (filedata);
                 }
             }




        May 9, 1992                                             9-17








        OSF/Motif Programmer's Guide


             /*-------------------------------------------------------------
             **      ValueCB         - callback for scrollbar
             */
             void ValueCB (
             Widget          w,              /*  widget id           */
             XtPointer       client_data,    /*  data from application   */
             XtPointer       call_data )     /*  data from widget class  */
             {
                 FileData * filedata = (FileData *) client_data ;

                 /* clear and redraw, dumb dumb.. */
                 XClearWindow(XtDisplay(filedata->work_area),
                              XtWindow(filedata->work_area));
                 ReDraw(filedata);
             }

             /*-------------------------------------------------------------
             **      DrawCB                  - callback for drawing area
             */
             void DrawCB (
             Widget          w,              /*  widget id           */
             XtPointer       client_data,    /*  data from application   */
             XtPointer       call_data )     /*  data from widget class  */
             {

                 XmDrawingAreaCallbackStruct * dacs =
                     (XmDrawingAreaCallbackStruct *) call_data ;
                 FileData * filedata = (FileData *) client_data ;
                 XSetWindowAttributes xswa;

                 static Boolean first_time = True ;

                 switch (dacs->reason) {
                 case XmCR_EXPOSE:
                     if (first_time) {
                         /* Change once the bit gravity of the Drawing Area; default
                            is north west and we want forget, so that resize
                            always generates exposure events */
                         first_time = False ;
                         xswa.bit_gravity = ForgetGravity ;
                         XChangeWindowAttributes(XtDisplay(w), XtWindow(w),
                                                 CWBitGravity, &xswa);
                     }

                     ReDraw(filedata) ;

                     break ;
                 case XmCR_RESIZE:
                     ReSize(filedata) ;

                     break ;



        9-18                                             May 9, 1992








                                        Scrolling, Panes, and Frames


                 }
             }

             void ReDraw(
             FileData * filedata )
             {
                 /* Display as many line as slider_size actually shows, since
                    slider_size is computed relative to the work_area height */

                 Cardinal i ;
                 int value, slider_size ;
                 Arg args[5];
                 int n ;
                 Position y ;

                 if (filedata->num_lines == 0) return ;

                 n = 0;
                 XtSetArg (args[n], XmNvalue, &value);  n++;
                 XtSetArg (args[n], XmNsliderSize, &slider_size);  n++;
                 XtGetValues (filedata->v_scrb, args, n);

                 for (i = value, y = 2 + filedata->font_struct->ascent;
                      i < value + slider_size ;
                      i++, y += (filedata->font_struct->ascent
                                 + filedata->font_struct->descent)) {
                     XDrawString(XtDisplay(filedata->work_area),
                                 XtWindow(filedata->work_area),
                                 filedata->draw_gc,
                                 4, y,
                                 filedata->lines[i], strlen(filedata->lines[i]));
                 }
             }

             void ReSize(
             FileData * filedata )
             {
                 /* Just update the scrollbar internals here, don't bother to redisplay
                    since the gravity is none */

                 Arg args[5];
                 int n ;
                 int value, slider_size ;
                 Dimension height ;

                 if (filedata->num_lines == 0) return ;

                 n = 0;
                 XtSetArg (args[n], XmNheight, &height);  n++;
                 XtGetValues (filedata->work_area, args, n);




        May 9, 1992                                             9-19








        OSF/Motif Programmer's Guide


                 /* sliderSize is the number of visible lines */
                 slider_size = (height - 4) / (filedata->font_struct->ascent
                                               + filedata->font_struct->descent) ;
                 if (slider_size <= 0) slider_size = 1 ;
                 if (slider_size > filedata->num_lines)
                     slider_size = filedata->num_lines ;

                 n = 0;
                 XtSetArg (args[n], XmNvalue, &value);  n++;
                 XtGetValues (filedata->v_scrb, args, n);

                 /* value shouldn't change that often but there are cases
                    where it matters */
                 if (value > filedata->num_lines - slider_size)
                     value = filedata->num_lines - slider_size;

                 n = 0;
                 XtSetArg (args[n], XmNsliderSize, slider_size);  n++;
                 XtSetArg (args[n], XmNvalue, value);  n++;
                 XtSetArg (args[n], XmNmaximum, filedata->num_lines);  n++;
                 XtSetValues (filedata->v_scrb, args, n);
             }



        9.4  MMaaiinnWWiinnddooww



             Motif provides a widget, MainWindow, that serves as a
             template for the primary window of most applications.
             MainWindow is a subclass of ScrolledWindow.  In
             addition to the viewport and ScrollBar components of
             the ScrolledWindow, MainWindow has an optional MenuBar,
             Command window, and Message window.

             MainWindow lays out these components in a manner
             compliant with the _O_S_F/_M_o_t_i_f _S_t_y_l_e _G_u_i_d_e specifications
             for the primary window of an application.  The MenuBar,
             if present, spans the top of the MainWindow
             horizontally.  By default the Command window, if
             present, spans the MainWindow horizontally just below
             the MenuBar.  The ScrolledWindow viewport and
             ScrollBars are below the Command window, and the
             Message window is below the ScrolledWindow viewport or
             horizontal ScrollBar.  If the MainWindow resource
             XXmmNNccoommmmaannddWWiinnddoowwLLooccaattiioonn is set to
             XXmmCCOOMMMMAANNDD__BBEELLOOWW__WWOORRKKSSPPAACCEE at the time the MainWindow is
             created, the Command window is located below the
             ScrolledWindow viewport or horizontal ScrollBar.




        9-20                                             May 9, 1992








                                        Scrolling, Panes, and Frames


             If the MainWindow resource XXmmNNsshhoowwSSeeppaarraattoorr is True,
             the MainWindow automatically creates up to three
             SeparatorGadgets to separate the components.  The names
             of these automatically created SeparatorGadgets are
             "Separator1", "Separator2", and "Separator3".  The
             application can retrieve their widget IDs by using the
             functions XXmmMMaaiinnWWiinnddoowwSSeepp11, XXmmMMaaiinnWWiinnddoowwSSeepp22, and
             XXmmMMaaiinnWWiinnddoowwSSeepp33.

             In addition to the ScrolledWindow resources that hold
             the widget IDs of the ScrollBars, scroll widget, and
             viewport widget, MainWindow has resources that hold the
             widget IDs of the other MainWindow components:

             XXmmNNccoommmmaannddWWiinnddooww
                       The value is the widget ID of the Command
                       window.  If a child is a Command widget and
                       no Command window exists, MainWindow
                       automatically sets the value of this resource
                       to the child's widget ID.

             XXmmNNmmeennuuBBaarr
                       The value is the widget ID of the MenuBar.
                       If a child is a MenuBar and no MainWindow
                       MenuBar exists, MainWindow automatically sets
                       the value of this resource to the child's
                       widget ID.

             XXmmNNmmeessssaaggeeWWiinnddooww
                       The value is the widget ID of the Message
                       window.  After creating the Message window,
                       the application must use XXttSSeettVVaalluueess to set
                       the value of this resource to the child's
                       widget ID.

             MainWindow has a convenience routine,
             XXmmMMaaiinnWWiinnddoowwSSeettAArreeaass, to establish both the MainWindow
             and the ScrolledWindow components.
             XXmmMMaaiinnWWiinnddoowwSSeettAArreeaass does not set the Message window;
             an application must use XXttSSeettVVaalluueess of XXmmNNmmeessssaaggeeWWiinnddooww
             to set the Message window.  An application that has no
             Message window and uses only standard components for
             the other MainWindow children may not need to call
             XXmmMMaaiinnWWiinnddoowwSSeettAArreeaass or XXttSSeettVVaalluueess for the component
             resources, but it is good practice to make these calls.
             If an application uses a Message window or has
             additional MainWindow children beyond the standard
             components, it must call XXmmMMaaiinnWWiinnddoowwSSeettAArreeaass and
             XXttSSeettVVaalluueess for XXmmNNmmeessssaaggeeWWiinnddooww.





        May 9, 1992                                             9-21








        OSF/Motif Programmer's Guide


             An application takes the following steps to use
             MainWindow:

                +o Create and manage the MainWindow, usually as a
                  child of the ApplicationShell.  If the scrolling
                  mode is to be automatic, supply an initial value
                  of XXmmAAUUTTOOMMAATTIICC for XXmmNNssccrroolllliinnggPPoolliiccyy.

                +o Create and manage the components of the
                  MainWindow.

                +o If necessary call XXmmMMaaiinnWWiinnddoowwSSeettAArreeaass or
                  XXttSSeettVVaalluueess for the MainWindow components.

                +o Take any other actions needed to regulate the
                  ScrolledWindow components.  These actions are
                  discussed in the descriptions of automatic and
                  application-defined scrolling above.

             For examples of using MainWindow with both automatic
             and application-defined scrolling policies, see the
             ScrolledWindow examples elsewhere in this chapter.



        9.5  FFrraammee



             Frame is a simple manager that encloses a child and
             displays a shadow around it.  An application usually
             uses a Frame to provide a shadow for a widget, such as
             a RowColumn WorkArea, that does not display a shadow
             itself.  The Frame resource XXmmNNsshhaaddoowwTTyyppee determines
             the type of shadow to draw.  The resources
             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 specify the margin
             between the shadow and the border of the child.

             Frame can also have one other child that serves as a
             title.  Frame places the title above the principal
             child of the Frame.  The following constraint resources
             determine the Frame's treatment of the child:

             XXmmNNcchhiillddTTyyppee
                       The value is a constant that tells the Frame
                       whether the child is the principal (work
                       area) child, the title, or another kind of
                       child.  Possible values are
                       XXmmFFRRAAMMEE__WWOORRKKAARREEAA__CCHHIILLDD (the default),
                       XXmmFFRRAAMMEE__TTIITTLLEE__CCHHIILLDD, and
                       XXmmFFRRAAMMEE__GGEENNEERRIICC__CCHHIILLDD.  When the value is



        9-22                                             May 9, 1992








                                        Scrolling, Panes, and Frames


                       XXmmFFRRAAMMEE__GGEENNEERRIICC__CCHHIILLDD Frame does not include
                       the child in its layout.

             XXmmNNcchhiillddHHoorriizzoonnttaallAAlliiggnnmmeenntt
                       The value specifies the alignment of the
                       title with respect to the left and right
                       inner edges of the Frame (determined by the
                       child's XXmmNNcchhiillddHHoorriizzoonnttaallSSppaacciinngg).
                       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 title is
                            placed at the left inner edge when the
                            Frame's XXmmNNssttrriinnggDDiirreeccttiioonn is
                            XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__LL__TTOO__RR, otherwise at
                            the right inner edge.  This is the
                            default.

                          +o XXmmAALLIIGGNNMMEENNTT__EENNDD-The title is placed at
                            the right inner edge when the Frame's
                            XXmmNNssttrriinnggDDiirreeccttiioonn is
                            XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__LL__TTOO__RR, otherwise at
                            the left inner edge.

                          +o XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR-The title is centered
                            betweent the edges.

             XXmmNNcchhiillddHHoorriizzoonnttaallSSppaacciinngg
                       The value is the minimum distance between the
                       title and the shadow along the left and right
                       edges of the Frame.  The default is the
                       Frame's XXmmNNmmaarrggiinnWWiiddtthh.

             XXmmNNcchhiillddVVeerrttiiccaallAAlliiggnnmmeenntt The value specifies the
                       alignment of the title with respect to the
                       shadow along the top edge of the Frame.
                       Following are the possible values:

                          +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-The baseline
                            of the last line of text in the title is
                            even with the shadow along the top edge
                            of the Frame.

                          +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-The baseline of
                            the first line of text in the title is
                            even with the shadow along the top edge
                            of the Frame.

                          +o XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR-The center of the
                            title is even with the shadow along the
                            top edge of the Frame.  This is the
                            default.



        May 9, 1992                                             9-23








        OSF/Motif Programmer's Guide


                          +o XXmmAALLIIGGNNMMEENNTT__WWIIDDGGEETT__BBOOTTTTOOMM-The bottom
                            edge of the title is even with the
                            shadow along the top edge of the Frame.

                          +o XXmmAALLIIGGNNMMEENNTT__WWIIDDGGEETT__TTOOPP-The top edge of
                            the title is even with the shadow along
                            the top edge of the Frame.

             Following is a UIL specification for an example Frame
             with a Label title and a Form child (not defined here):

             object exampleFrame : XmFrame {
               controls {
                   XmLabel  { arguments {
                       XmNchildType = XmFRAME_TITLE_CHILD;
                       XmNchildHorizontalSpacing = 4;
                       XmNchildVerticalAlignment = XmALIGNMENT_WIDGET_BOTTOM;
                     }; };
                     XmForm exampleForm;
                 };
             };



        9.6  PPaanneeddWWiinnddooww



             PanedWindow is a manager that lays out its children
             vertically from top to bottom and, by default, places a
             separator between each pair of children.  Each child
             spans the width of the PanedWindow, which resizes
             children to be as wide as the widest child.  When
             possible the PanedWindow grows to accommodate the width
             of the widest child and the heights of all the
             children.

             Usually PanedWindow allows the user to adjust the
             height of each pane.  When a pane is adjustable,
             PanedWindow creates a control called a sash and places
             it below the pane that it controls.  By manipulating
             the sash with the mouse or keyboard commands, the user
             changes the height of the pane above.  This may also
             change the height of a pane below the sash.

             PanedWindow has the following resources to control
             general appearance:

             XXmmNNmmaarrggiinnHHeeiigghhtt
                       The value specifies the margin between the
                       PanedWindow's top and bottom shadows and the



        9-24                                             May 9, 1992








                                        Scrolling, Panes, and Frames


                       children nearest those shadows.

             XXmmNNmmaarrggiinnWWiiddtthh
                       The value specifies the margin between the
                       PanedWindow's left and right shadows and the
                       children nearest those shadows.

             XXmmNNsseeppaarraattoorrOOnn
                       The value determines whether or not
                       PanedWindow displays a separator between each
                       pair of panes.

             XXmmNNssppaacciinngg
                       The value is the distance between each pane.

             The following PanedWindow resources control the
             appearance of the sashes:

             XXmmNNssaasshhHHeeiigghhtt
                       The value specifies the height of each sash.

             XXmmNNssaasshhIInnddeenntt
                       The value specifies the distance between each
                       sash and the inner margin of the left or
                       right side of the PanedWindow.  If the value
                       is positive, the sash is offset from the near
                       (left) side of the PanedWindow.  If the value
                       is negative, the sash is offset from the far
                       (right) side of the PanedWindow.  If the
                       value is greater than the width of the
                       PanedWindow minus the width of the sash, the
                       sash is placed flush against the near side of
                       the PanedWindow.

             XXmmNNssaasshhSShhaaddoowwTThhiicckknneessss
                       The value specifies the shadow thickness for
                       each sash.

             XXmmNNssaasshhWWiiddtthh
                       The value specifies the width of each sash.

             PanedWindow has one other resource, XXmmNNrreeffiigguurreeMMooddee.
             When this resource is set to False, the PanedWindow
             does not recompute its layout when either the user or
             the application resizes a pane or when the PanedWindow
             is resized.

             PanedWindow children have a number of constraint
             resources that PanedWindow uses to determine the
             positions and size limitations of the panes:




        May 9, 1992                                             9-25








        OSF/Motif Programmer's Guide


             XXmmNNaalllloowwRReessiizzee
                       The value specifies whether the PanedWindow
                       grants resize requests from the pane.  When
                       the value is False (the default) and the pane
                       is realized, PanedWindow refuses such
                       requests, but it allows the user to resize
                       the pane if it is adjustable.  For example,
                       if the application attempts to change the
                       height or width of the pane via XXttSSeettVVaalluueess,
                       PanedWindow does not allow the change.  If
                       the value is True or if the pane is not
                       realized, PanedWindow grants requests by the
                       pane to change its size if possible.

             XXmmNNppaanneeMMaaxxiimmuumm
                       The value is the maximum height to which the
                       user or application can resize the pane.  If
                       this value is the same as the value of
                       XXmmNNppaanneeMMiinniimmuumm, the pane cannot be resized at
                       all, and PanedWindow does not display a sash
                       at the bottom of the pane.

             XXmmNNppaanneeMMiinniimmuumm
                       The value is the minimum height to which the
                       user or application can resize the pane.  If
                       this value is the same as the value of
                       XXmmNNppaanneeMMaaxxiimmuumm, the pane cannot be resized at
                       all, and PanedWindow does not display a sash
                       at the bottom of the pane.

             XXmmNNppoossiittiioonnIInnddeexx
                       The value is the ordinal position of the pane
                       in the PanedWindow's list of pane children.
                       The application or user can specify the value
                       as an integer between 0 and the number of
                       children already in the list, or as the value
                       XXmmLLAASSTT__PPOOSSIITTIIOONN (the default), which means
                       the child is inserted at the end of the list.
                       If specifying a new value causes the order of
                       children in the list to change, PanedWindow
                       recomputes its layout according to the new
                       order of children: the first pane is
                       displayed at the top of the PanedWindow, the
                       second child below the first, and so on.

             XXmmNNsskkiippAAddjjuusstt"
                       The value specifies whether or not the
                       PanedWindow resizes the pane when the
                       PanedWindow itself is resized or when the
                       user resizes another pane.  When the value is
                       True, PanedWindow does not resize this pane



        9-26                                             May 9, 1992








                                        Scrolling, Panes, and Frames


                       under these circumstances, but the user can
                       still resize the pane if XXmmNNppaanneeMMaaxxiimmuumm is
                       greater than XXmmNNppaanneeMMiinniimmuumm.  The default is
                       False.


















































        May 9, 1992                                             9-27






 
