[ Previous | Next | Contents | Glossary | Home | Search ]
Motif 2.1 Programmer's Guide



ScrolledWindow

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:

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

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

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

  4. Automatic and Application-Defined Scrolling

    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 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 XmNscrollingPolicy determines the scrolling model. Possible values for this resource are XmAUTOMATIC and XmAPPLICATION_DEFINED. The default value is XmAPPLICATION_DEFINED.

    Other Resources

    In addition to XmNscrollingPolicy, 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 XtSetValues or XmScrolledWindowSetAreas.

    Following are the resources that hold components of the ScrolledWindow:

    XmNclipWindow

    The value is the ID of the viewport widget created by the ScrolledWindow in automatic scrolling. This resource applies only when the XmNscrollingPolicy is XmAUTOMATIC. It is a read-only resource; the application cannot set a new value.

    XmNhorizontalScrollBar

    The value is the ID of the horizontal ScrollBar. The ScrolledWindow creates this ScrollBar and sets the value of this resource when the XmNscrollingPolicy is XmAUTOMATIC. 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.

    XmNverticalScrollBar

    The value is the ID of the vertical ScrollBar. The ScrolledWindow creates this ScrollBar and sets the value of this resource when the XmNscrollingPolicy is XmAUTOMATIC. 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.

    XmNworkWindow

    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:

    XmNscrollBarDisplayPolicy

    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 XmAS_NEEDED and XmSTATIC. The value is forced to XmSTATIC when the scrolling policy is XmAPPLICATION_DEFINED and defaults to XmAS_NEEDED when the scrolling policy is XmAUTOMATIC.

    XmNscrollBarPlacement

    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: XmTOP_LEFT, XmTOP_RIGHT, XmBOTTOM_LEFT, and XmBOTTOM_RIGHT.

    XmNscrolledWindowMarginHeight

    This resource specifies the margins between the top and bottom sides of the ScrolledWindow and the first child on each side.

    XmNscrolledWindowMarginWidth

    This resource specifies the margins between the left and right sides of the ScrolledWindow and the first child on each side.

    XmNspacing

    This resource specifies the distance between each ScrollBar and the viewport.


    [ Previous | Next | Contents | Glossary | Home | Search ]