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
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.
JCSpinBox behaves in the following way:
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.
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.
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
).
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.
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.
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
.
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
.
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) }
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.
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