# 13

# 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 volume or brightness. 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`:

The parts that comprise 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 that 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 code produces the following results:

A sample JCSlider

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. `JCSlider`s 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);

Note that the height and weight of a slider is not necessarily directly related to the scale of values covered by the slider. In other words, the size of a slider is not necessarily proportional to the range of the values covered by the slider. The absolute values for a scale are set explicitly by the `Values` property, covered in the following section.

## 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);

In this case, the slider will report values along an integer range between `0` and`100`, and the slide bar is displayed in the middle of the maximum and minimum values.

## 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 ).

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"));

By using explicit descriptive values as labels, the user can get a much better understanding of the values being altered as the `JCSlider` value is changed.

## 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.

### jclass.bwt.JCSlider

Name | Method | Inherited from
--- | --- | ---
`AutoTick` | `setAutoTick` | `jclass.bwt.JCSlider`
`Background` | `setBackground` | `jclass.bwt.JCContainer`
`BlockIncrement` | `setBlockIncrement` | `jclass.bwt.JCContainer`
`Foreground` | `setForeground` | `jclass.bwt.JCContainer`
Maximum | `set`Maximum | `jclass.bwt.JCComboBox`
`MaximumLabel` | `setMaximumLabel` | `jclass.bwt.JCSlider`
`Minimum` | `setMinimum` | `jclass.bwt.JCContainer`
`MinimumLabel` | `setMinimumLabel` | `jclass.bwt.JCSlider`
`NumTicks` | `setNumTicks` | `jclass.bwt.JCSlider`
`Orientation` | `setOrientation` | `jclass.bwt.JCContainer`
PreferredSize | `set`PreferredSize | `jclass.bwt.JCContainer`
ThumbSize | `set`ThumbSize | `jclass.bwt.JCSlider`
UnitIncrement | `set`UnitIncrement | `jclass.bwt.JCContainer`
UserData | `set`UserData | `jclass.bwt.JCContainer`
Value | `set`Value | `jclass.bwt.JCContainer`

## 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