10
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 JCArrowButtons. 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:

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.

Behavior

• 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, enabling 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 JCSpinBoxes 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 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 use 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 JCArrowButtons) 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 of the arrow buttons and of 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 Appendix A: Colors and Fonts.

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.

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