Introduction

Scrollbars are standard Graphical User Interface (GUI) components common to virtually all windowing systems. The JCScrollbar component enables the user to view data that is too large to be displayed within a given space.

Scrollbars are usually located beside a component or adjacent to a JCScrolledWindow containing the data to be viewed. When the user interacts with the scrollbar in a scrolled window, the data within the other component (the "viewport") scrolls. Instead of having to resize the display, the user can scroll the information within the component instead.

The scrollbar consists of two JCArrowButtons at either end, and a rectangular area called a slider within it. The data is scrolled by clicking a button, clicking to either side of the slider, dragging the slider, or clicking within a rectangular area (called the "thumb") within it.

Scrollbars are available in the Java Development Kit (JDK), but their functionality is limited. The Win32 release of JDK 1.0.2 and JDK 1.1 contains scrollbars that behave erratically and inconsistently across different operating systems (Windows 95 and Windows NT), and browsers (various versions of Netscape Navigator and Microsoft Internet Explorer). The current release of the JDK contains scrollbars whose sliders are always at a fixed width, and the slider control sometimes "bounces" between the two arrow buttons. The chief advantages of JCScrollbar (and JCScrolledWindow) is that they behave correctly and consistently across all platforms. The scrollbar display has the standard Windows 95 "look and feel", including a slider which is resized proportionally the total size of the scrollable content it controls. The JCScrollbar can also be set to different Windows 95 scrolling behaviors.

Behavior

JCScrollbars behave in the following manner:

by clicking on arrow buttons, moving the slider or clicking within the thumb, the contents of the scrollbar is scrolled
clicking in the trough area of the slider causes the scrollable region to scroll one viewport "page" at a time
scrolling can be updated while the user is actively scrolling, or updated when the user releases the mouse
clicking to either side of the slider with the CONTROL key pressed causes the slider to move to the end of the scrollable display
JCScrollbar dispatches the same events as the AWT scrollbar, and also enables callbacks to be registered
clicking on the arrow button increments the scrolling display by one unit
the size of the slider component is inversely proportional to the size of the area it scrolls; the smaller the size of the scrolled display, the larger the slider, and the larger the size of the scrolled display, the smaller the slider.

Keyboard Traversal

When a JCScrollbar has focus, hitting the UP or DOWN cursor keys (for a vertical scrollbar) or the RIGHT or LEFT cursor keys (for a horizontal scrollbar) scrolls the scrollbar in the direction of the cursor key. It also switches focus to the arrow button in the direction of the cursor. Pressing either the ENTER key or the SPACE BAR activates the arrow button (i.e. it is depressed), and it moves the scrollbar in the direction of the arrow button. Clicking PAGE-UP or PAGE-DOWN will scroll up or down by a page respectively. Clicking HOME or END will scroll to the beginning or end of the scrollable area respectively.

Sample Program Code

The following code fragment shows how a JCScrollbar can be used to create a simple scale:

package jclass.bwt.examples;
import jclass.bwt.BWTEnum;
import jclass.bwt.JCAdjustmentEvent;
import jclass.bwt.JCAdjustmentListener;
import jclass.bwt.JCLabel;
import jclass.bwt.JCScrollbar;
import jclass.contrib.ContribFrame;
import jclass.util.JCUtilConverter;
import java.awt.*;

/**
 * This example demonstrates the use of a JCScrollbar as a scale.
 */
public class scrollbar extends java.applet.Applet implements JCAdjustmentListener {

JCLabel label;

public void adjustmentValueChanged(JCAdjustmentEvent ev) {
	label.setLabel(""+ev.getValue());
}

public void init() {
	setBackground(Color.lightGray);
	setLayout(new BorderLayout());
	label = new JCLabel();
	label.setAlignment(JCLabel.BOTTOMCENTER);
	add("Center", label);

	JCScrollbar sb = new JCScrollbar(JCScrollbar.HORIZONTAL, 0, 10, 0, 110);
	sb.setPreferredSize(200, BWTEnum.NOVALUE);
	sb.addAdjustmentListener(this);
	sb.setValue(50, true);
	add("South", sb);
}

public Insets insets() {
	return new Insets(5,5,5,5);
}

public static void main(String args[]) {
	ContribFrame frame = new ContribFrame("Scrollbar");
	scrollbar s = new scrollbar();

	s.init();
	frame.add(s);
	frame.pack();
	frame.show();
}
}

This code produces the following results:

A sample JCScrollbar

This sample code is incorporated into the example file scrollbar.class provided with JClass BWT. For information on how to run this program, see the "Example Program " section at the end of this chapter.

Specifying Orientation

A scrollbar can have one of two possible orientations: horizontal and vertical. A vertical JCScrollbar is set using the value JCScrollbar.VERTICAL, while a horizontal JCScrollbar is set using the value JCScrollbar.HORIZONTAL. It can also be set by the Orientation resource, using the same VERTICAL and HORIZONTAL values. Orientation must be called before the scrollbar is visible (i.e. before it is added to its parent).

Controlling Scroll Increments

There are two sets of properties for controlling the rate at which scroll displays are incriminated for JCScrollbar . The PageIncrement resource sets the page scroll increment. This is the amount that will be scrolled up or down when the user clicks above or below the slider (default: slider size). The LineIncrement resource sets the line increment (default: 10). This is the amount that is scrolled up or down when the user clicks the arrow buttons.

The following code fragment shows how to set to the scroll increment to a scroll value of 20 pixels:

     colorScrollbar.setPageIncrement(20);
     colorScrollbar.setLineIncrement(20);

Setting Scrollbar Size

Typically, scrollbars are sized to match the height or width of the component it controls. By default, the preferredHeight and the preferredWidth methods return SB_SIZE . For circumstances where this is not desirable, the size of a JCScrollbar can be specifically set to a numerical value.

The following code fragment depicts a scrollbar set to a numerical value:

     colorScrollbar.setPreferredSize(100, 20);
     colorScrollbar.setValues(128, 20, 0, 255+20);

Handling Scroll Events

When the user clicks on a scrollbar, the event's "arg" field is set to the scrollbar's current value. When a scroll event occurs, a SCROLL_ABSOLUTE event is sent and the callback is called.

If the user clicks the up-arrow of a vertical scrollbar (or the right arrow of a horizontal scrollbar) SCROLL_LINE_UP is dispatched by mouseDown . If the user clicks the down-arrow of a vertical scrollbar (or the left arrow of a horizontal scrollbar) SCROLL_LINE_DOWN is dispatched by mouseDown .

If the user clicks in the area above the slider (or the area to the right of the slider on a horizontal scrollbar), SCROLL_PAGE_UP is dispatched by mouseDown . If the user clicks in the area above the slider (or the area to the right of the slider on a horizontal scrollbar), SCROLL_PAGE_DOWN is dispatched by mouseDown .

The InitialRepeatDelay method is used to set the time in milliseconds that the JCScrollbar should wait before scrolling continuously when an arrow button is pressed and held down for extended period of time (default: 250 ms). If InitialRepeatDelay is set to MAXINT , scrolling only occurs once.

Events

A class can be notified when the a JCScrollbar 's value changes by implementing the JCAdjustmentEvent interface and registering itself with the scrollbar via addAdjustmentListener , as the following code demonstrates:

public interface JCAdjustmentEvent {
        public void adjustmentValueChanged(JCAdjustmentEvent e);
}
public class JCAdjustmentEvent {
        // Returns the component where the event originated.
        public Object getSource()
        // Returns the event type: ADJUSTMENT_VALUE_CHANGED.
        public int getId()
        // Returns the current value in the adjustment event.
        public int getValue()
        // Returns the type of adjustment which caused the value changed event:  UNIT_INCREMENT, UNIT_DECREMENT, BLOCK_INCREMENT, BLOCK_DECREMENT, TRACK
        public int getAdjustmentType()
}

Property Listing

The following summarizes the properties of JCScrollbar. Complete reference documentation is available online in standard javadoc format in jclass.bwt.JCScrollbar.html.

jclass.bwt.JCScrollbar

Name	Method	Inherited from
`Background`	`setBackground`	`jclass.bwt.JCComponent`
`FilterTime`	`setFilterTime`	`jclass.bwt.JCScrollbar`
`Foreground`	`setForeground`	`jclass.bwt.JCComponent`
`InitialRepeatDelay`	`setInitialRepeatDelay`	`jclass.bwt.JCScrollbar`
`Orientation`	`setOrientation`	`jclass.bwt.JCScrollbar`
`PreferredSize`	`setPreferredSize`	`jclass.bwt.JCComponent`
`Value`	`setValue`	`jclass.bwt.JCScrollbar`
`UserData`	`setUserData`	`jclass.bwt.JCComponent`

Example Program

Demonstration programs and example code containing JCScrollbars come with JClass BWT. The examples can be viewed in applet form by launching index.html within the /jclass/bwt/examples directory. scrollbar.class can also be run as stand-alone Java applications from the command prompt by typing:

     java jclass.bwt.examples.scrollbar

15 JCScrollbar