Introduction · Sample Program Code · Specifying Orientation
Controlling Scroll Increments · Setting Scrollbar Size
Handling Scroll Events · Events · Property Listing
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.
JCScrollbar
s behave in the following manner:
JCScrollbar
dispatches the same events as the AWT scrollbar, and also enables callbacks to be registered;
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.
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:
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.
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).
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);
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);
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.
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() }
The following summarizes the properties of JCScrollbar
. Complete reference documentation is available online in standard
javadoc format in
jclass.bwt.JCScrollbar.html.
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