5
JCScrolledWindow

Introduction · Sample Program Code · Scrollbar Properties

Setting FilterTime for Scroll Events · Property Listing · Example Program

Introduction

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

JCScrolledWindow contains and controls the data to be viewed. When the user interacts with the scrollbar in a JCScrolledWindow, the data within the other component (the " viewport") scrolls. Instead of having to resize the display, the user can scroll through the information within the component. The JCScrolledWindow class combines one or two Scrollbars and a viewing area to implement a viewport onto another (usually larger) data display. The visible part of the window can be scrolled through the larger display using the scrollbars.

Scrolled Windows were not incorporated in the Java Development Kit (JDK) 1.0.2, though they have been incorporated in the JDK 1.1 as ScrollPane.

Behavior

JCScrolledWindow behaves in the following manner:

• The contents within the viewport are scrolled by clicking on arrow buttons or moving the slider;
• clicking in the slider area 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 towards the end of the scrollable display;
• clicking on the arrow button increments the scrolling display by one unit;
• the size of the slider component is inversely related 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 the scrollbar of a JCScrolledWindow 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. Also, focus switches `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.

Sample Program Code

JCScrolledWindow can accept one child which is made into a child of the scrolled window's viewport container. To put a component in a JCScrolledWindow, simply add it to the window. By default, the scrollbars will only be displayed if the child is larger than the viewport. By calling setScrollbarDisplay (DISPLAY_ALWAYS) the scrollbars are always displayed within the program, regardless of the circumstance.

The following code fragment shows how a JCScrolledWindow (containing an AWT and a JCButton) can be used to create a simple scrollable window display:

package jclass.bwt.examples;
import jclass.bwt.BWTEnum;
import jclass.bwt.JCAlignerLayout;
import jclass.bwt.JCButton;
import jclass.bwt.JCContainer;
import jclass.bwt.JCLabel;
import jclass.bwt.JCScrolledWindow;
import jclass.bwt.JCTextField;
import jclass.contrib.ContribFrame;
import jclass.util.JCString;
import java.awt.*;
/**
 * This example demonstrates the use of a JCScrolledWindow.
 */
public class scrolledWindow extends java.applet.Applet {
public void init() {
	setBackground(Color.lightGray);
	setLayout(new GridLayout(1,1));
	JCContainer main_panel = new JCContainer();
	main_panel.setLayout(new BorderLayout());
	main_panel.setInsets(new Insets(0, 10, 0,10));
	JCLabel label = new JCLabel(null, "../images/klg_logo.gif", this, 0);
	label.setPreferredSize(BWTEnum.NOVALUE, 100);
	main_panel.add("North", label);
	Panel panel = new Panel();
	panel.setLayout(new JCAlignerLayout(2, 10, 10));
	panel.add(new JCLabel("Name:"));
	panel.add(new JCTextField("Harry"));
	panel.add(new JCLabel("Address:"));
	panel.add(new JCTextField("260 King Street"));
	panel.add(new JCLabel("Phone:"));
	panel.add(new JCTextField("905-555-1212"));
	main_panel.add("Center", panel);
	panel = new Panel();
	panel.add(new Button("An AWT button"));
	panel.add(new JCButton(
		   JCString.parse(this, "A [color=red]BWT[color=default] button")));
	main_panel.add("South", panel);
	JCScrolledWindow window = new JCScrolledWindow();
	window.setScrollbarDisplay(BWTEnum.DISPLAY_ALWAYS);
	window.add(main_panel);
	add(window);
}
public Dimension preferredSize() { 
	return new Dimension(super.preferredSize().width, 200);
}
public static void main(String args[]) {
	ContribFrame frame = new ContribFrame("ScrolledWindow");
	scrolledWindow s = new scrolledWindow();
	s.init();
	frame.add(s);
	frame.pack();
	frame.show();
}
}
}

This code produces the following results:

The scrollbars for the JCScrolledWindow appear as needed. If the height of the content in the viewport is larger than the height of the scrolled window, a vertical scrollbar appears. Similarly, if the width of the content in the viewport is larger than the width of the scrolled window, a horizontal scrollbar appears.

This example uses JCStrings to insert red text within the BWT button. For more information on JCStrings, see .

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

Scrollbar Properties

The ScrollbarOffset property sets the amount of space between the scrollbar and the component for the JCScrolledWindow (default: 5 pixels).

The following code fragment offsets the scrollbar from the component it controls by 10 pixels:

JCScrolledWindow window = new JCScrolledWindow();
window.add(main_panel);
window.setPreferredSize(500, 250);
window.setScrollbarOffset(10);
add(window);

The ScrollbarDisplay property is used to set under what circumstances the scrollbars are to be displayed. ScrollbarDisplay can take one of five different values: DISPLAY_ALWAYS (scrollbars are always displayed), DISPLAY_AS_NEEDED (scrollbars are displayed as necessary), DISPLAY_VERTICAL_ONLY (the vertical scrollbar is always displayed), DISPLAY_HORIZONTAL_ONLY (the horizontal scrollbar is always displayed), or DISPLAY_NONE (never display scrollbars). By default, ScrollbarDisplay is set to DISPLAY_AS_NEEDED.

Setting FilterTime for Scroll Events

In most situations, it is desirable to have the content contained in the viewport updated continuously as the user actively scrolls. There are some circumstances where this action is not desirable, such as where a screen-redraw of the viewport contents will take an excessive amount of processing to do interactively.

To specify that no processing is done as the user drags the slider until it is released, set FilterTime to MAXINT.

Property Listing

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

jclass.bwt.JCScrolledWindow

Example Program

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

	java jclass.bwt.examples.scrolledWindow