12

Spin Boxes

Features of JCSpinBox and JCSpinNumberBox  Classes and Interfaces  Properties

Constructors and Methods  Examples

---

12.1 Features of JCSpinBox and JCSpinNumberBox

Swing provides checkboxes and radio buttons, but no spin boxes. The JClass spin boxes fill the need for components that let the user select a number or an Object by clicking on up or down arrows. You can use a JCSpinBox to spin through a list of Objects (so long as the required editors and renderers exist, or have provided them), or use a JCSpinNumberBox, which can display any numeric object.

• JCSpinBox looks very much like a JComboBox except that it has no dropdown. It takes a list of objects and presents these values in a spin box. You use the up and down arrows to cycle through the list.
• Use JCSpinNumberBox for incrementing and decrementing objects of type java.lang.Number. You can select numbers of type Byte, Short, Integer, Long, or Float, and you can set maximum and minimum values for the spin operation.
• Both components follow Swing's MVC paradigm. A JCSpinBoxModel interface is used to manage the spin box's data.
• JCSpinBox has four constructors for the various ways in which you can supply data; that is, as Objects, Vectors, or via a JCSpinBoxModel. A fourth parameterless constructor is available. It uses an empty DefaultSpinBoxModel as a placeholder for data that will be provided later.
• Contents of a spin box may be modified via a JCSpinBoxEditor interface.
• A KeySelectionManager interface defines a method for associating a keystroke to an item in the spin box.
• JCSpinBoxModel methods are inherited from javax.swing.ListModel and javax.swing.ComboBoxModel. These are addListDataListener, getElementAt, getSize, removeListDataListener, getSelectedItem, and setSelectedItem.
• The listener is the addValueListener, and the event is JCValueEvent.

---

12.2 Classes and Interfaces

Interfaces

JCSpinBoxEditor	The editor component used for JCSpinBox components.
JCSpinBoxModel	A data model for JCSpinBox modeled after javax.swing.ComboBoxModel. JCSpinBoxModel is a ListDataModel with a selected item. This selected item is in the model since it is not always in the item list. It inherits its methods from javax.swing.ComboBoxModel and javax.swing.ListModel.
JCSpinBox MutableModel	Extends JCSpinBoxModel to define models that are changeable. It declares methods for adding, inserting, and removing elements.

Helper Classes

AbstractSpinBox	The super class for JCSpinBox and JCSpinNumberBox. The class is abstract because it does not define spinUp(), spinDown(), and checkArrowButtons(), but it does provide the common functionality for JCSpinBox and JCSpinNumberBox.
JCValueEvent	The event object has methods getSource, getOldValue, and getNewValue, allowing you to find out which spin box posted the event, and its old and new values.

---

12.3 Properties

JCSpinBox properties

These properties contain all of the functionality of JCSpinBox. In keeping with Swing's MVC design paradigm, the JCSpinBoxModel interface contains a data model for JCSpinBox modeled after javax.swing.ComboBoxModel. JCSpinBoxModel is a ListDataModel with a selected item. This selected item is in the model since it is not always in the item list.

Property Name	Description
actionCommand	Sets or returns the action command that is included in the event sent to action listeners.
continuousScroll	Determines how selection is handled when the mouse button is held down on a spin arrow button. If continuousScroll is true, the component scrolls continuously through the items in the scroll box until the mouse button is released. If continuousScroll is false, a separate mouse click is required to select the next item in the scroll box.
getItemAt	Returns the list item at the specified index.
getItemCount	Returns the number of items in the list.
model	Sets or returns the data model currently used by the JCSpinBox.
renderer	Sets or returns the renderer used to display the selected item in the JCSpinBox field.
selectedIndex	Returns the index of the currently selected item in the list, or selects the item at the position marked by the index.
selectedItem	Returns the currently selected item, or sets the selected item in the JCSpinBox by specifying the object in the list.
isEditable	Returns true if the JCSpinBox is editable.

JCSpinNumberBox properties

These properties let you specify the operation, that is, whether the numbers in the spin box are whole numbers or floating point numbers. Additionally, you can set the spin increment and bounds.

For a complete list of properties, please see Properties of JCSpinBox and Properties of JCSpinNumberBox in Appendix A.

Property Name	Description
continuousScroll	Determines how selection is handled when the mouse button is held down on a spin arrow button. If continuousScroll is true, the component scrolls continuously through the items in the scroll box until the mouse button is released. If continuousScroll is false, a separate mouse click is required to select the next item in the scroll box.
maximumValue	Returns or sets the maximum value. The default is Long.MAX_VALUE
minimumValue	Returns or sets the minimum value. The default is Long.MIN_VALUE.
numberFormat	The NumberFormat object used by the spinner to parse and format numbers
operation	Takes a JCSpinNumberBox.INTEGER and sets the operation.
spinStep	The spin increment. The default is 1.
value	The current value of the spinner.
valueRange	Convenience method to set maximum and minimum values together. Defaults are Long.MIN_VALUE, Long.MAX_VALUE.

---

12.4 Constructors and Methods

Constructors

JCSpinNumberBox()

Use this component when you want to let your users increment or decrement a object of type java.lang.Number. Long.MIN_VALUE, Long.MAX_VALUE, and floating point numbers outside the range Double.MIN_VALUE cause an exception. Use setOperation(JCSpinNumberBox.FLOATING_POINT) when you want to use floating point numbers. The use of setOperation(JCSpinNumberBox.INTEGER) is optional, since this is the default case.

JCSpinBox()

Use this component when you want a spin box containing an Object. For some non-standard objects, you may need to create your own editor and renderer.

JCSpinBox methods

These methods manage a list of items by providing methods for adding and removing items from the list of objects, and for adding listeners for these changes. See the API for the complete list of JCSpinBox methods.

Method Name	Description
addActionListener()	Adds an ActionListener.
removeActionListener()	Removes an ActionListener.
removeAllItems()	Removes all items from the item list.
addItem()	Adds an item to the item list.
removeItem()	Removes an item from the item list.
removeItemAt()	Removes the item at anIndex. To use this method, the JCSpinBox data model must implement JCSpinBoxMutableModel.
addItemListener()	Adds a java.awt.event.ItemListener. Its parameter is the class that will receive the event when the selected item changes.
removeItemListener()	Removes a java.awt.event.ItemListener.

---

12.5 Examples

To use a JCSpinNumberBox, simply instantiate it and set its parameters according to your needs, for example:

  JCSpinNumberBox float_spin = new JCSpinNumberBox();
  float_spin.setName("FloatingPointSpinBox");
  float_spin.setValue(new Integer(0));
  float_spin.setValueRange(new JCSpinNumberBox.Range(new Integer(0), new Integer(12)));
  float_spin.setSpinStep(new Double(1.5));
  float_spin.setOperation(float_spin.FLOATING_POINT);

You don't need to use the setOperation method when you create an INTEGER version of a JCSpinNumberBox since that is the default type.

Similarly, you can create a JCSpinBox:

JCSpinBox string_spin = new JCSpinBox(titles);
string_spin.setName("StringSpinBox");
string_spin.setSelectedIndex(0);
string_spin.addValueListener(listener);

The figure shows that each time a mouse click changes a spin box's value, the generated event can report on both the old and the new value. The output in Figure 42 results from clicking each spin box in succession twice.

Figure 42 :  Capturing spin box events.

Listening for Spin Box Events

JCNumberSpinBox uses the JCValueModel interface to set and get its values, and to define its listeners. To respond to spin events, do something like this:

1. Create a listener as part of the setup for the component, for example:

   JCValueListener listener = new ValueListener();

2. Then add a listener to the spin box:

   float_spin.addValueListener(listener);

3. Implement the listener class and define a valueChanged method:

   class ValueListener implements JCValueListener {
public void valueChanging(JCValueEvent e) {
}

public void valueChanged(JCValueEvent e) {
System.out.println(((Component) e.getSource()).getName() + " changed from " +e. getOldValue() +
" to " +
e.getNewValue());
}
} // end of ValueListener