Using Components, the GUI Building Blocks

How to Use Scroll Panes

The 1.1 AWT introduced the ScrollPane class, which makes it easy for you to provide a scrolling area. A ScrollPane manages a single child component, displaying as much of the component as space permits.

By default, a scroll pane's scrollbars are visible only when they're needed. For example, if a scroll pane is wide enough to show its child's full width, then the horizontal scrollbar isn't needed, and by default the horizontal scrollbar will completely disappear. The following picture shows an applet in which both the vertical and horizontal scrollbars are currently needed.

Here is the code that creates a scroll pane and puts a child component in it:

ScrollPane sp1 = new ScrollPane();
sp1.add(aComponent);

When you create a scroll pane (but not later), you can specify when the scroll pane shows scrollbars, using one of these three ScrollPane constants:

SCROLLBARS_AS_NEEDED

The default value. Show each scrollbar only when it's needed.

SCROLLBARS_ALWAYS

Always show scrollbars.

SCROLLBARS_NEVER

Never show scrollbars. You might use this option if you don't want the user to directly control what part of the child component is shown.

Here's an example of specifying the scrollbar display policy:

ScrollPane sp2 = new ScrollPane(ScrollPane.SCROLLBARS_ALWAYS);

When you implement a component to be put in a scroll pane, you must take special care:

• You need to implement the child component's getPreferredSize method so that it returns the dimensions needed to fully display the component.
• You should implement the child component so that it works well when its drawing area is larger than its preferred size. For example, the component might draw itself in the center of its drawing area, filling the extra space with a solid color.
• When the component is being scrolled, you might notice flashing, or flickering, in the display area. If you don't want this to occur, you'll need to implement the update method in the child component, and possibly double buffering as well. These techniques are discussed in Eliminating Flashing.

Here's the scrolling-related code from the previous applet:

//The component that will be scrolled.
class ScrollableCanvas extends Canvas {
    ...
    Dimension preferredSize = new Dimension(600, 320);
    Dimension minimumSize = new Dimension(10, 10);

    public Dimension getMinimumSize() {
        return minimumSize;
    }

    public Dimension getPreferredSize() {
        return preferredSize;
    }

    public void paint(Graphics g) {
        g.drawImage(image, 0, 0, getBackground(), this);
    }
}

public class ImageScroller ... {
    ...//where initialization occurs:
        ScrollableCanvas canvas = new ScrollableCanvas();
        ...
        ScrollPane pane = new ScrollPane();
        setLayout(new BorderLayout());
        pane.add(canvas);
        add("Center", pane);
    }
}

Scroll panes don't generate events. If you want to be notified of scrolling activity, then you can get the scroll pane's scrollbars and listen to adjustment events from them. The horizontal scrollbar is returned by the ScrollPane getHAdjustable method, and the vertical scrollbar by the getVAdjustable method.

Another reason you might need to get the scrollbars is to control the scrollbars' appearance or behavior. For example, in a text processor you might need to set the amount scrolled when the user clicks in the scrollbar. For information on setting scrollbar attributes, see How to Use Scrollbars.

Using Components, the GUI Building Blocks