Support for Scrolling: JViewport, and JScrollPane

Contents
Swinging Duke

The JViewport and JScrollPane Classes

The Swing API for scrolling is functionally a superset of the java.awt.ScrollPane class that was provided in JDK 1.1. In Swing, support for scrolling is implemented using two basic classes: JViewport and JScrollPane. (Scroll bars for Swing components are created using the JScrollBar class, which is described in the specification titled "The Scrollbar API.")

The JViewport class encapsulates the standard scrolling idiom: The viewport displays a view, typically the viewport's child, that is potentially larger than the viewport. The JScrollPane class is a composite that contains a viewport and scrollbars; it takes care of connecting the scrollbars to the viewport, laying the parts out, and so on.

JScrollPane also supports two additional viewports -- rowHeading and columnHeading -- that scroll in only one dimension. For example, the rowHeading viewport is scrolled horizontally along with the main viewport; however, it is not scrolled vertically. JScrollPane also allows the developer to provide components for the spaces in the corners between the headings and the scrollbars.

In addition to headings and corners, JScrollPane offers a few other features not found in java.awt.ScrollPane:

A new scrollbar display policy. In Swing, scrollbars can be displayed in three different ways: "as needed," always, or never. Any of these three characteristics can be specified for any individual scrollbar.
JScrollPane subclasses can easily specify their own scroll-bar classes.
The block and line increments used by scrollbars are computed values, not constants. This arrangement makes scrolling variable height items straightforward.

All Swing components inherit a method called scrollRectToVisible() that interacts with JViewport. A component can call this method to ensure that it will be visible in its viewport ancestor (if it has any).

Swing components also support autoscrolling. If autoscrolling is enabled, a mouse drag that extends outside the component causes the component's viewport ancestor to scroll in the same direction.

The following illustration -- a screen shot of the SwingSet example application that you can find in the Examples folder -- shows how the JViewport and JScrollPane classes support scrolling in Swing:

The JViewport Class

The JViewport class defines the basic scrolling model. Although JViewport is designed to support both logical scrolling and pixel-based scrolling, by default it supports the latter. The viewport's child, called the view, is scrolled by calling JViewport.setViewPosition(). For example, the following code fragment shows how you can create a 100-pixel by 100-pixel viewport with a 500-by-500 view, with view coordinates 10, 20 at the origin of the viewport:

JComponent view = new JComponent();
view.setSize(500, 500);

JViewport viewport = new JViewport();
viewport.setSize(100, 100);
viewport.setView(view);
viewport.setViewPosition(10, 20);

The JViewport class supports logical scrolling -- that is, a kind of scrolling in which view coordinates aren't pixels (they might be row, column indices, for example.) To support logical scrolling, JViewport defines a small set of methods that can be used to define the geometry of a viewport and a view. By default, these methods just report the pixel dimensions of the viewport and view; however, pixel coordinates are not suitable when a client needs to ensure compatibility with a JViewport subclass that implements a logical scrolling scheme. A JScrollPane object (see next section) is one example of an object that might require the use of logical scrolling.

The following diagram shows the geometry of a JViewport and the methods used to manage it:

By default, JViewport is constructed with a LayoutManager named JViewportLayout. The JViewportLayout manager defines a policy for layout that should be useful for most applications. The viewport makes its view the same size as the viewport; however, it does not make the view smaller than its minimum size. As the viewport grows, the view is kept bottom-justified until the entire view is visible. Subsequently, the view is kept top-justified.

The JScrollPane Class

The JScrollPane class defines a composite that contains a main viewport, horizontal and vertical scrollbars, row and column heading viewports, and components to fill in the gaps in the corners of windows that implement scrolling. The current ScrollPaneUI implementations all use the JScrollPaneLayout LayoutManager to arrange all these parts.

To create a JScrollPane with both scrollbars displayed as needed (the default), you could execute a series of statements like this:

        JComponent view = new JComponent();
        view.setSize(500, 500);

        JScrollPane scrollpane = new JScrollPane();
        scrollpane.setViewportView(view);

You can control when scrollbars appear by using Swing's scrollbar display policy properties: verticalScrollbarPolicy and horizontalScrollbarPolicy. Both these properties can have values of AS_NEEDED, ALWAYS, or NEVER. An AS_NEEDED scrollbar is displayed when the main viewport's viewSize is larger than its extentSize.

You can define a JScrollPane class that computes block and unit scrollbar increments. Scroll bars bear the responsibility for computing these values. For example, when the user clicks on a Basic scrollbars-down arrow, the scrollbar uses the value returned by its getUnitIncrement() method to compute scrolling distance. By default, getUnitIncrement() just returns a constant; however, it is often useful to compute a value that takes into account partially visible items or variable-height items. To force the JScrollPane to use a scrollbar with a special getUnitIncrement() method, override JScrollPane.createXScrollbar(), as shown here:

class MyScrollPane extends JScrollPane
{
    public JScrollBar createVerticalScrollBar() {
	return new MyVerticalScrollBar();
    }
}

class MyVerticalScrollBar extends JScrollBar
{
    public int getBlockIncrement(int direction) {
	return ...; 
    }

    public int getUnitIncrement(int direction) {
	return ...; 
    }

    public ListBoxVerticalScrollBar() {
	super(JScrollBar.VERTICAL);
    }
}

Scrolling Methods

The following methods in JComponent work with the components viewport ancestor, if it has one:

public void scrollRectToVisible(Rectangle rect)
public void setAutoscrolls(boolean autoscrolls)
public boolean getAutoscrolls()

The scrollRectToVisible() method sets the viewPosition property of the components first JViewport ancestor to ensure that the specified rectangle is visible. If the rectangle is already visible, scrollRectToVisible() does nothing.

If the autoscrolls property is true, the component is automatically scrolled to a point at which its contents are visible when the user drags the mouse outside the component's bounds rectangle.