12
JCSlider

Introduction · Sample Program Code · Slider Orientation

Setting Slider Size · Setting Slider Values · Setting Label Values

Tick Marks and Page Increments · Property Listing · Example Program

Introduction

Sliders are a common component to most Windowing systems, and they are most commonly used in applications where the user needs to set or adjust values along a continuous range, such as a volume or brightness control. A slider consists of a two main elements: a slide bar that the user moves, and a track along which the bar slides. The track bar contains a number of tick marks, which indicate discrete values along the continuous range of values.

JCSlider supports a number of options, including the ability to be set to either a horizontal or vertical orientation, defining the size of the of the slide bar or how fine a user can manipulate the values generated by the slider. JCSlider has an elongated rectangular region similar to a JCScrollBar. The user can modify the JCSlider's value by moving the slide bar within this rectangular region, or by clicking within a sensitive region bounded by the area between the track and the ticks. A JCSlider can also include labels, which are located at either end of the track display. The following illustration shows the separate parts comprising a JCSlider.

There is no equivalent to JCSlider in the Java Development Kit (JDK). JCSlider conforms to standard Windows 95 "look and feel" and behavior.

Note that much of the functionality and methods used by JCSlider are common to those used by JCScrollbar.

Behavior

JCSlider behaves in the following manner:

• when a user clicks on the slide bar, the slide bar can be moved around the track bar at will
• the area the immediately surrounds the track bar (encompassing the tick marks) is sensitive to mouse clicks, and when this area is clicked the track bar will gradually slide over to the point on the track corresponding to the cursor position
• if a user clicks on the slide bar, focus is retained until the user releases the mouse button. This behavior continues even if the user strays outside of the slider area.

Keyboard Traversal

The slider can be accessed through the TAB key, and the arrow keys can be used to move the slide bar in the direction represented by the key.

Sample Program Code

The following code fragment shows how a JCSlider can be created:

package jclass.bwt.examples;
import jclass.bwt.BWTEnum;
import jclass.bwt.JCAdjustmentEvent;
import jclass.bwt.JCAdjustmentListener;
import jclass.bwt.JCGridLayout;
import jclass.bwt.JCLabel;
import jclass.bwt.JCSlider;
import jclass.contrib.ContribFrame;
import java.awt.*;

/**
 * This example demonstrates the a JCSlider.
 */
public class slider 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 JCGridLayout(BWTEnum.VARIABLE, 1));

	label = new JCLabel();
	label.setAlignment(JCLabel.BOTTOMCENTER);
	add(label);

	JCSlider sb = new JCSlider(JCSlider.HORIZONTAL, 0, 0, 100);
	sb.addAdjustmentListener(this);
	sb.setValue(50, true);
	sb.setMinimumLabel(new JCLabel("0"));
	sb.setMaximumLabel(new JCLabel("100"));
	add(sb);
}

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

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

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

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

Slider Orientation

The orientation of a JCSlider is set within the initial constructor. JCSliders can take two orientation values: JCSlider.HORIZONTAL (default) and JCSlider.VERTICAL. A JCSlider can be also be constructed so that it reads its values from an applet, or to have an initial orientation, value, and minimum and maximum values, as in the following code fragment:

     JCSlider sb = new JCSlider(JCSlider.VERTICAL, 0, 5, 100);

Setting Slider Size

Typically, sliders 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 JCSlider can be specifically set to a numerical value, as shown by the following code fragment:

     sb.setPreferredSize(300, 500);

Setting Slider Values

The absolute minimum and maximum values for a slider are set by using the Values property. Values is set with three integer values: the value of the slider's placement along the track, followed by the minimum and maximum values of the slider.

The following code fragment sets the Values property of a typical JCSlider:

     sb.setValues(50, 0, 100);

Setting Label Values

Minimum and maximum label values can be set by using the MinimumLabel and MaximumLabel properties respectively. Both MinimumLabel and MaximumLabel take a string and/or a JCString value (for more information on JCStrings, see Appendix B: JCString Properties).

Label values on sliders often represent the numerical range covered by the JCSlider, but more non-numerical, more descriptive string values can also be used. Instead of using "0" and "100" as the minimum and maximum respective values for a JCSlider, "Small" and "Big" can be used instead, as in the following code snippet:

     sb.setMinimumLabel(new JCLabel("Small"));
     sb.setMaximumLabel(new JCLabel("Big"));

Tick Marks and Page Increments

Tick marks are not only a visual aid to users, but also indicates the level of discrete points (the "granularity") of the values that can be manipulated by the user. The number of tick marks displayed does not have to represent the granularity of a particular JCSlider, as the amount of page increments that exist on the slider can also be set.

There are two properties that control the display of tick marks along a track. The AutoTick property (default) draws a tick mark is drawn at each page increment. This value can be overridden by the NumTicks property if its value is greater than zero. The discrete movement of the slide bar along the track is set by the PageIncrement property (default: 10).

The following code fragment when added to a program forces the JCSlider to display 50 tick marks along the track, and that each tick corresponds to a discrete page increment:

     sb.setNumTicks(50);
     sb.setPageIncrement(50);

Property Listing

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

Example Program

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

		java jclass.bwt.examples.slider