# 16

# JCScrollbar

Introduction · Sample Program Code · Specifying Orientation

Controlling Scroll Increments · Setting Scrollbar Size

Handling Scroll Events · Events · Property Listing

Example Program

## 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 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 with the total size of the scrollable content it controls. The `JCScrollbar` can also be set to different Windows 95 scrolling behaviors.

#### Behavior

`JCScrollbar`s 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 narrow region 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` property determines 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 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