Scroll Pane Configuration

Scroll Pane Styles

MacOS uses two kinds of scroll bars: legacy scroll bars, which occupy fixed tracks outside the scroll pane viewport, and overlay scroll bars, which are painted over the scroll pane viewport and are hidden when not in use. VAqua supports both of these scroll bar styles in scroll panes and, by default, selects the style to use by tracking the system preferred scroll bar style.

A scroll bar style can also be specified for a scroll pane by setting the client property JScrollPane.style on a JScrollPane to legacy or overlay.

MacOS defines two variants of overlay scroll bars, a dark style (the default) and a light style that works better over dark backgrounds. These variants can be selected by setting the client property JScrollPane.thumbStyle on a JScrollPane to dark or light.

When overlay scroll bars are in use, the Always scroll bar policy is interpreted as As Needed. The Never scroll bar policy inhibits an overlay scroll bar from appearing, but does not inhibit mouse wheel scrolling.

Smooth Scrolling

Using a Custom Scroll Pane Layout Manager

The implementation of overlay scroll bars requires VAqua to replace the standard scroll pane layout manager in the scroll pane with a layout manager that understands overlay scroll bars. If an application installs its own custom layout manager, the legacy style of scroll bar will be used regardless of the style property or the system preferred scroll bar style.

To create a scroll pane that uses a custom layout manager for legacy scroll bars and also supports overlay scroll bars, the custom layout manager class should implement the UIResource interface. Implementing this interface signals to VAqua that it is permissable to replace the layout manager with the overlay scroll bar layout manager when the overlay style is requested. The custom layout manager will be reinstalled when the overlay style is no longer being used.

Additional style dependent configuration can be performed by tracking the client property AquaOverlayScrollBars on the scroll pane. VAqua sets this property to Boolean.TRUE when overlay scroll bars are in use and to Boolean.FALSE when legacy scroll bars are in use. VAqua sets this property to null when its scroll pane UI is uninstalled.