# 11

# JCSpinBox and JCSpinBoxString

Introduction · Sample Program Code · Defining a Numerical Range

Defining a Text Range · Arrow Button Actions · SpinBox and SpinBoxString Appearance

SpinBox and SpinBoxString Sizing · Events · Property Listing

Example Program

## Introduction

Spinboxes are common Windows components that enable a user to cycle through a numeric range or a specific list of items, or to enter their own value in a text field. `JCSpinBox` provides the capabilities of an `JCTextField` and 2 `JCArrowButton`s. The user can either type a value in the text field, or click on the arrow buttons to increase or decrease the value the value displayed in the text field. If the user attempts to enter an invalid value in the text field, it is disallowed. Spinboxes are typically used in situations where a program can accept a wide range of user input values, but where precision and the ability to accept direct user input is required. Spinboxes are most often accompanied by an explanatory label.

The following illustration shows a typical `JCSpinBox`:

A typical JCSpinBox with descriptive label.

`JCSpinBoxString` provides the capabilities of `JCSpinBox` but allows the user to select a value from a number of related choices which are displayed in sequence. By default, the text field is editable. If the user attempts to enter an invalid value, it is disallowed.

The Java Development Kit (JDK) does not implement spinboxes. `JCSpinBox` has the "look and feel" plus the behavior of its MS Windows 95 equivalent.

#### JBehavior

JCSpinBox behaves in the following way:

- clicking on the up arrow button increases the value contained in the text field; clicking on the down arrow button decreases the value contained in the text field;
- clicking within the text field brings it into focus, allowing the user to change the value contained in the text field;
- if an invalid value is entered into the text field, a system beep is activated, warning the user to correct the value entered.

#### Keyboard Traversal

Clicking the TAB key cycles through the text field, the top arrow, the bottom arrow, and then to the next `JCSpinBox` or `JCSpinBoxString`. Clicking ENTER or SPACE BAR when either arrow button has focus changes the value contained in the text field. The UP and DOWN cursor keys increase and decrease the value displayed in the `JCSpinBox` or `JCSpinBoxString` that has focus.

## Sample Program Code

The following code shows how two `JCSpinBox`es and a `JCSpinBoxString` can be incorporated into a program:

    package jclass.bwt.examples;
    import jclass.bwt.BWTEnum;
    import jclass.bwt.JCAlignerLayout;
    import jclass.bwt.JCLabel;
    import jclass.bwt.JCSpinBox;
    import jclass.bwt.JCSpinBoxEvent;
    import jclass.bwt.JCSpinBoxListener;
    import jclass.bwt.JCSpinBoxString;
    import jclass.contrib.ContribFrame;
    import jclass.util.JCString;
    import jclass.util.JCUtilConverter;
    import java.awt.*;
    /**
     * This example demonstrates various types of JCSpinBoxes and events
     */
    public class spinBox extends java.applet.Applet implements JCSpinBoxListener {
    public void spinBoxChangeBegin(JCSpinBoxEvent ev) {}
    public void spinBoxChangeEnd(JCSpinBoxEvent ev) {}
    public void init() {
    	JCSpinBox box1, box2;
    	JCSpinBoxString box3;
    	setBackground(Color.lightGray);
    	setLayout(new JCAlignerLayout());
    	add(new JCLabel("Integer:"));
    	add(box1 = new JCSpinBox(5));
    	box1.setMaximum(10);
    	add(new JCLabel("Float:"));
    	add(box2 = new JCSpinBox(5));
    	box2.setMinimum(-100);
    	box2.setMaximum(100);
    	box2.setDecimalPlaces(2);
    	add(new JCLabel("String:"));
    	add(box3 = new JCSpinBoxString(10));
    	box3.getTextField().setEditable(false);
    	box3.getTextField().setShowCursorPosition(false);
    	box3.setStringList(getToolkit().getFontList());
    }
    public static void main(String args[]) {
    	ContribFrame frame = new ContribFrame("SpinBox");
    	spinBox s = new spinBox();
    	s.init();
    	frame.add(s);
    	frame.pack();
    	frame.show();
    }
    }

This code produces the results seen in the following illustration:

A sample application incorporating two JCSpinBoxes and one JCSpinBoxString

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

## Defining a Numerical Range

If a numerical value is being used within a `JCSpinBox`, three values must be set: the minimum and maximum allowable values, and the number that is initially displayed within the text field. The highest possible value is set by the `Maximum` property, (default: `MAXINT`), and the lowest possible value is set by the `Minimum` property (default: `0`). The number that is initially displayed in the text field is set by the `Position` property, (default: `0`).

## Defining a Text Range

The `StringList` property works within a `JCSpinBoxString` component to set an array of string values to be displayed. The `Position` property works in conjunction with `StringList` to set the initial string to be displayed within the `JCSpinBoxString` component. Position takes an integer value that corresponds to the numeric placement of the strings held in the array. By default, `Position` is set to `0`, so if the first string that appears in the array is "Times Roman", it is displayed as the initial value. If you want to set the value of the third string in the array to be displayed, `Position` would be set to a value of `2` instead.

## Arrow Button Actions

The arrow buttons used in a `JCSpinBox` or `JCSpinBoxString` (comprised of two `JCArrowButton`s) can be clicked to increment or decrement the value displayed in the text field. The `Increment` property is used to set the amount to increment or decrement the value (default: `1`).

The `DecimalPlaces` property sets the number of decimal points used when displaying the value in the text field (default: `0`).

If `Increment` is left at its default value when a decimal value is specified by the `DecimalPlaces` property, the value is incremented or decremented accordingly by 1 in the lowest decimal place. If `DecimalPlaces` is set to `2` and `Increment` left at its default, clicking the up arrow button increments an initial value of `0.00` to `0.01`.

If the value in the text field reaches its maximum or minimum value, by default `AutoArrowDisable` is invoked, disabling the respective arrow button.

## SpinBox and SpinBoxString Appearance

There are several properties which can be used to customize the display of a `JCSpinBox` or `JCSpinBoxString`. The `Background` and `Foreground` properties can be used to set the color of the background and text/foreground elements of a `JCSpinBox` or `JCSpinBoxString`. `Foreground` not only sets the color of any alphanumeric characters contained in the text field, but also that of the arrow buttons and the cursor within the text field.

The display of fonts within a `JCSpinBox` or `JCSpinBoxString` is controlled by the `Font` property. For a listing of available fonts, see .

## SpinBox and SpinBoxString Sizing

The size of a `JCSpinBox` or `JCSpinBoxString` can be set using the `PreferredSize` property, which sets the container's preferred size. If either dimension is set to `NOVALUE`, it is calculated by the subclass.

The individual `PreferredWidth()` and `PreferredHeight()` methods each deal with the subclass' preferred width (default: `100`). The subclass should not include the inset sizes in its calculation, as these are added by `JCContainer`.

## Events

A class can be notified before and after the user has changed the value of a `JCSpinBox` or `JCSpinBoxString` by implementing the `JCSpinBoxListener` interface and registering itself with the spinbox via `addSpinBoxListener`, as the following code demonstrates:

    public interface JCSpinBoxListener {
            // Invoked before the field's value is changed. The event's values can be modified via its setValue method.
            public void spinBoxChangeBegin(JCSpinBoxEvent e);
            // Invoked after the field's value is changed. Any changes made to the event are ignored.
            public void spinBoxChangeEnd(JCSpinBoxEvent e);
    }
    public class JCSpinBoxEvent {
            // Returns the component where the event originated.
            public Object getSource()
            // Returns the event type: ACTION_PERFORMED.
            public int getId()
            // Determines whether the text field's value should change.
            public boolean getAllowChange()
            // If this value is set to false, the text field's value is not changed (default: true).
            public void setAllowChange(boolean v)
            // Gets the position of the new item in the list.
            public int getPosition()
            // Gets the value that will be copied to the text field.
            public Object getValue()
            // Sets the value that will be copied to the text field.
            public void setValue(Object v)
    }

## Property Listing

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

### jclass.bwt.JCSpinBox

Name | Method | Inherited from
--- | --- | ---
AutoArrowDisable | setAutoArrowDisable | jclass.bwt.JCSpinBox
Alignment | setAlignment | jclass.bwt.JCTextComponent
Background | setBackground | java.awt.Component
Columns | setColumns | jclass.bwt.JCTextComponent
CursorPosition | setCursorPosition | jclass.bwt.JCTextComponent
DecimalPlaces | setDecimalPlaces | jclass.bwt.JCSpinBox
DoubleBuffer | setDoubleBuffer | jclass.bwt.JCContainer
Font | setFont | jclass.bwt.JCContainer
Foreground | setForeground | java.awt.Component
Editable | setEditable | jclass.bwt.JCTextComponent
HighlightColor | setHighlightColor | jclass.bwt.JCComponent
HighlightThickness | setHighlightThickness | jclass.bwt.JCComponent
Increment | setIncrement | jclass.bwt.JCSpinBox
Insets | setInsets | jclass.bwt.JCContainer
Maximum | setMaximum | jclass.bwt.JCSpinBox
MaximumLength | setMaximumLength | jclass.bwt.JCTextComponent
Minimum | setMinimum | jclass.bwt.JCSpinBox
Overstrike | setOverstrike | jclass.bwt.JCTextComponent
Position | setPosition | jclass.bwt.JCSpinBox
PreferredSize | setPreferredSize | jclass.bwt.JCContainer
SelectedBackground | setSelectedBackground | jclass.bwt.JCTextComponent
SelectedForeground | setSelectedForeground | jclass.bwt.JCTextComponent
SelectionEnd | setSelectionEnd | jclass.bwt.JCTextComponent
SelectionList | setSelectionList | jclass.bwt.JCTextComponent
SelectionStart | setSelectionStart | jclass.bwt.JCTextComponent
ShadowThickness | setShadowThickness | jclass.bwt.JCComponent
ShowCursorPosition | setShowCursorPosition | jclass.bwt.JCTextComponent
StringCase | setStringCase | jclass.bwt.JCTextComponent
Text | setText | jclass.bwt.JCSpinBox
UserData | setUserData | jclass.bwt.JCContainer

### jclass.bwt.JCSpinBoxString

Name | Method | Inherited from
--- | --- | ---
AutoArrowDisable | setAutoArrowDisable | jclass.bwt.JCSpinBox
Background | setBackground | jclass.bwt.JCContainer
DoubleBuffer | setDoubleBuffer | jclass.bwt.JCContainer
Font | setFont | jclass.bwt.JCContainer
Foreground | setForeground | jclass.bwt.JCContainer
Insets | setInsets | jclass.bwt.JCContainer
Position | setPosition | jclass.bwt.JCSpinBoxString
PreferredSize | setPreferredSize | jclass.bwt.JCContainer
StringList | setStringList | jclass.bwt.JCSpinBoxString
UserData | setUserData | jclass.bwt.JCContainer

## Example Program

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

    	java jclass.bwt.examples.spinBox