Spinner User's Guide

Table Of Contents

Copyright © 1998 IBM Corp. All rights reserved.

Java, JavaBeans and 100% Pure Java are trademarks of Sun Microsystems, Inc. All other trademarks are the property of their respective owners.


TOC

Overview

The spinner is a component with two small direction buttons that lets the user scroll a list of
predetermined values and select one, or possibly enter a new legal value.

Properties

Following are the significant properties of Spinner Bean Suite:
 

Property Description Data Type Flags* Default Value Valid Value
background The background color of this component.
Note:This property do not apply to ObjectListSpinner when it is not  editable.
java.awt.Color R, W, B java.awt.Color.white any instance of Color
foreground The foreground color of this component.
Note:This property do not apply to ObjectListSpinner when it is not  editable.
java.awt.Color R, W, B java.awt.Color.black any instance of Color
font The font of this component.
Note:This property do not apply to ObjectListSpinner when it is not  editable.
java.awt.Font R, W, B new java.awt.Font("dialog", java.awt.Font.PLAIN, 12) any instance of Font
opaque Marking whether this component is opaque.
Note:This property do not apply to ObjectListSpinner when it is not  editable.
boolean R, W, B True True - this component is opaque
False - this component is not opaque
columns The columns of the input field, it is used to invalidate the layout.
Note: columns is a property derived from Swing JTextField, the function of columns in Spinner is similar to columns of Swing JTextField. This property do not apply to ObjectListSpinner.
int R, W, B 20 columns>0
enabled Marking whether this component is enabled. boolean R, W, B True True - this component  is enabled                                      False - this component  is disabled
editable Marking whether this component is editable. boolean R, W, B True True - this component is editable
False - this component is not editable
incrButtonArrowColor The color of the increment arrow button. java.awt.Color R, W, B java.awt.Color.black any instance of Color
decrButtonArrowColor The color of the decrement arrow button. java.awt.Color R, W, B java.awt.Color.black any instance of Color
orientation The orientation of the arrow button. int R, W, B 0 0 - SPIN_VERTICAL
 (display name: VERTICAL)
1 - SPIN_HORIZONTAL
(display name: HORIZONTAL)
wrap Marking whether the wrap action is allowed.
If wrap is true, the wrap action is allowed: Assume Spinner's value is the maximum, if Spinner is scrolled up, it will change to it's minimum; Assume Spinner's value is the minimum, if Spinner is scrolled down, it will change to it's maximum.
If wrap is false, the wrap action is forbidden:
Assume Spinner's value is the maximum, it can not be scrolled up; Assume Spinner's Value is the minimum, it can not be scrolled down.
boolean R, W, B True True - the wrap action is allowed
False - the wrap action is forbidden

* R = read, W = write, B = bound, E = expert


Events

The Spinner Bean Suite fires the following events:

          Listener Method: stateChanged
                                       increased(javax.swing.event.ChangeEvent)
                                       decreased(javax.swing.event.ChangeEvent)

          Listener Method: internalError(com.ibm.spinner.SpinnerErrorEvent)

Methods

    The Spinner Bean Suite  implements the following significant methods:

    public void scrollUp()
     Increments the spinner's value.

    public void scrollDown()
     Decrements the spinner's value.

User Interface

    This section describes the user interface of the Spinner Bean Suite. It shows what  the Spinner Bean Suite looks like.

    Vertical Button Screen
    The vertical button orientation Spinner Bean is as shown in Figure A when you first put it in a program assembler.

    Horizontal Button Screen
    The bean is shown as Figure B  when you set the "orientation" property to "HORIZONTAL".

          Figure B  - The Horizontal Button Spinner Bean

     The currently selected value is displayed in an input field. You can change the value by clicking on the arrow buttons, or just by typing a string into the input field to set the current value.

CalendarSpinner Bean

The CanlendarSpinner Bean is a component which displays and spins date and time.

Properties

Following are the significant properties of the CalendarSpinner bean:
 

Property Description Data Type Flags* Default Value Valid Value
wrapAssociated Marking whether the changes of different field values of the calendar should be associated. For example "1998,12", if it is true, when the month is incremented from 12 to 1, the year would change from 1998 to 1999. boolean R, W, B True False - the changes of different field values are not associated 
True - the changes of different field values are  associated
timeZone Representing a time zone offset, and also figuring out daylight  savings. String R, W, B The system local time zone. valid time zone string
year The year of the calendar. int R, W, B, E The current system year. valid year
month The month of the calendar. 
( Note: the property value of month is from 0 to 11, but it's displaying value in UI is from 1 to 12, because this keep consistent with WebRunner and JDK )
int R, W, B, E The current system month. integer from 0 to 11
day The day of the calendar. int R, W, B, E The current system day. valid day
hour The hour of the calendar. int R, W, B, E The current system hour. valid hour
minute The minute of the calendar. int R, W, B, E The current system minute. valid minute
second The second of the calendar. int R, W, B, E The current system second. valid second
formatString The user-defined pattern string  for formatting and parsing date or time in a locale sensitive manner. String R, W, B "dd-MMM-yy h:mm:ss a" SHORT - "M/d/yy h:mm a"
MEDIUM - "dd-MMM-yy h:mm:ss a"
LONG - "MMMM d,yyyy h:mm:ss  a z"
FULL - "EEEE,MMMM d,yyyy h:mm:ss 'o'clock' a z" 
formattingStyle The ID of format string.
(Note:This property is 
redundant with the 
formattingString porperty.
But to keep  compatible
with Webrunner API, it
cannot be eliminated. So it 
is left as a  hidden property. It can only be manipulated
by the set/get methods.)
int R, W, B, H 2 0 - FULL
1 - LONG
2 - MEDIUM
3 - SHORT
caretPos The caret position which represents the current field to be changed. It can be one of  YEAR, MONTH,  DATE, HOUR, MINUTE, and SECOND.
Note:The "caretPos" property of CalendarSpinner is defined for invoking API, it is not similar to the caret position defined in the TextField. So when you mapulate CalendarSpinner, the caret position displayed in the input field may not be consistent with the value of "caretPos" property displayed in the property sheet.
int R, W, B 0 0 - YEAR
1 - MONTH
2 - DATE
3 - HOUR
4 - MINUTE
5 - SECOND
datePartValue The date value in long. long R, W, B, E The current system date. minimum<datePartValue <maximum
timePartValue The time value in long. long R, W, B, E The current system time. minimum<timePartValue <maximum
calendar The calendar value in calendar java.util.Calendar R, W, B The current system calendar. any instance of Calendar
value The calendar value in long. long R, W, B, E The current system calendar in long. minimum<value<maximum
maximum The maximum value. java.util.Calendar R, W, B 12/31/2050 11:59:59 PM maximum>minimum
minimum The minimum value. java.util.Calendar R, W, B 01/01/1950 12:00:00 AM any instance of Calendar
dateString The date and time shown in the entry field. String R, W, B, E The current system date. the instance of valid date string
date The current date and time. java.util.Date R, W, B, H The current system date and time. any instance of Date

* R = read, W = write, B = bound,E = expert, H = hidden


Events

The CalendarSpinner fires the following events:

          Listener Method: dateChanged(com.ibm.spinner.DateChangedEvent)

Methods

Please refer to the Methods section of Overview.


User Interface

This section describes the user interface of the CalendarSpinner Bean. It shows what the CalendarSpinner bean looks like and how to use the CalendarSpinner at runtime.

          Figure 1-1  - The Vertical Button CalendarSpinner Bean

The currently selected value is displayed in an input field. You can change the date or time value by clicking on different subfields within the input field and using the arrow buttons to spin them either independentlyor associatedly, or just by typing a date or time string into the input field to set the current value. If the input is invalid, the CalendarSpinner will automatically restore the previous value when you press the "Enter" or "Tab" key, or change the focus to another component.
 

The bean is shown as Figure 1-3  when you set the "formatString" property to "SHORT".
The short style includes six subfields. They are "month", "day", "year", "hour", "minute", and "PM_AM". The first five subfields show digital value and can be changed by either inputting a digital value directly or by scrolling. The "PM_AM" subfield is different. It can only be changed by scrolling. Otherwise, when you input a digital value directly, the last valid key input will be added to the end of the string, whereas the old value will be "pushed" leftward and the first digit of the old value will be lost. For example, if the old value is "14" in the minute subfield, you enter "3" the old value moves leftward and loses the first digit, "3" then, is added to the end of the string and the value thus become "43".
 

          Figure 1-3  - The SHORT Style CalendarSpinner Bean
 

The bean is shown as Figure 1-4  when you set the "formatString" property to "MEDIUM".
The medium style includes seven subfields. They are "day", "month", "year", "hour", "minute", "second", and "PM_AM". The "day", "year", "hour", "minute", and "second" show digital value and can be changed by either inputting a digital value directly or by scrolling. The "month" and "PM_AM" are different. It can only be changed by scrolling. Like as the short style,  the new input will "pushed" the old value leftward.
 

          Figure 1-4  - The MEDIUM Style CalendarSpinner Bean
 

The bean is shown as Figure 1-5  when you set the "formatString" property to "LONG".
The long style includes eight subfields. They are "month", "day", "year", "hour", "minute", "second", "PM_AM", and "time zone". The "day", "year", "hour", "minute", and "second" show digital value and can be changed by either inputting a digital value directly or by scrolling. The "month", "PM_AM" and "time zone" are different. It can only be changed by scrolling. Like as the short style,  the new input will "push" the old value leftward.

          Figure 1-5  - The LONG Style CalendarSpinner Bean
 

The bean is shown as Figure 1-6  when you set the "formatString" property to "FULL".
The full style includes nine subfields. They are "day of week", "month", "day", "year", "hour", "minute", "second", "PM_AM", and "time zone". The "day", "year", "hour", "minute", and "second" show digital value and can be changed by either inputting a digital value directly or by scrolling. The "day of week", "month", "PM_AM" and "time zone" are different. It can only be changed by scrolling. Like as the short style,  the new input will "push" the old value leftward.

          Figure 1-6  - The FULL Style CalendarSpinner Bean



 

DateSpinner Bean

A DateSpinner is a component  which displays and spins date.

Properties

Following are the significant properties of the DateSpinner bean:
 

Property Description Data Type Flags* Default Value Valid Value
wrapAssociated Marking whether the changes of different field values of the date should be associated. For example "1998,12", if it is true, when the month is incremented from 12 to 1, the year would change from 1998 to 1999. boolean R, W, B True False - the changes of different field values are not associated
True - the changes of different field values are associated
year The year of the date. int R, W, B, E The current system year. valid year
month The month of the date.
( Note: the property value of month is from 0 to 11, but it's displaying value in UI is from 1 to 12, because this keep consistent with WebRunner and JDK )
int R, W, B, E The current system month. integer from 0 to 11
day The day of the date. int R, W, B, E The current system day. valid days
formatString The user-defined pattern string  for formatting and parsing date  in a locale sensitive manner. String R, W, B "dd - MMM - yy" SHORT - "M/d/yy"
MEDIUM - "dd-MMM-yy"
LONG - "MMMM d,yyyy"
FULL - "EEEE,MMMM d,yyyy" 
formattingStyle The ID of format string.
(Note:This property is 
redundant with the 
formattingString porperty.
But to keep  compatible
with Webrunner API, it
cannot be eliminated. So it 
is left as a  hidden property. It can only be manipulated
by the set/get methods.)
int R, W, B, H 2 0 - FULL
1 - LONG
2 - MEDIUM
3 - SHORT
caretPos The caret position which represents the current field to be changed. It can be one of  YEAR, MONTH, or DATE.
Note:The "caretPos" property of DateSpinner is defined for invoking API, it is not similar to the caret position defined in the TextField. So when you mapulate DateSpinner, the caret position displayed in the input field may not be consistent with the value of "caretPos" property displayed in the property sheet.
int R, W, B 0 0 - YEAR
1 - MONTH
2 - DATE
value The calendar value in long. long R, W, B, E The current system calendar in long. minimum<value <maximum
calendar
(display name:Date)
The calendar value in calendar. java.util.Calendar R, W, B The current system calendar. any instance of Calendar
maximum The maximum value.  java.util.Calendar R, W, B 12/31/2050 maximum>minimum
minimum The minimum value. java.util.Calendar R, W, B 01/01/1950 any instance of Calendar
dateString The date shown in the entry field. String R, W, B, E The current system date. any instance of valid date string

* R = read, W = write, B=bound, E = expert, H = hidden


Events

The DateSpinner fires the following events:

          Listener Method: dateChanged(com.ibm.spinner.DateChangedEvent)

Methods

Please refer to the Methods section of Overview.

 


User Interface

This section describes the user interface of the DateSpinner Bean. It shows what  the DateSpinner Bean looks like and how to use the DateSpinner.

          Figure 2-1  - The Vertical Button DateSpinner Bean

The currently selected value is displayed in an input field. You can change the date value by clicking on different subfields within the input field and using the arrow button to spin them either independentlyor associatedly, or just by typing a date string into the input field to set the current value. If the input is invalid, the DateSpinner will automatically restore the previous value when you press the "Enter" or "Tab" key, or change the focus to another component.

About how to input in the textfield, please refer to the User Interface of CalendarSpinner, the description to the fields related to the time has no use to the DateSpinner.


TimeSpinner Bean

A TimeSpinner is a component  which displays and spins time.

Properties

Following are the significant properties of the TimeSpinner Bean:
 

Property Description Data Type Flags* Default Value Valid Value
wrapAssociated Marking whether the changes of different field values of the time  should be associated.  boolean R, W, B True False - the changes of different field values are not associated
True - the changes of different field values are  associated
timeZone Representing a time zone offset, and also figuring out daylight  savings. String R, W, B system local time zone valid time zone string
hour The hour of the time. int R, W, B, E The current system hour. valid hour
minute The minute of the time. int R, W, B, E The current system minute. valid minute
second The seconds of the time. int R, W, B, E The current system second. valid second
formatString The user-defined pattern string  for formatting and parsing time in a locale sensitive manner. String R, W, B "h:mm:ss a" SHORT - "h:mm a"
MEDIUM - "h:mm:ss a"
LONG - "h:mm:ss  a z"
FULL - " h:mm:ss 'o'clock' a z"
formattingStyle The ID of format string.
(Note:This property is 
redundant with the 
formattingString porperty.
But to keep  compatible
with Webrunner API, it
cannot be eliminated. So it 
is left as a  hidden property. It can only be manipulated
by the set/get methods.)
int R, W, B, H 2 0 - FULL
1 - LONG
2 - MEDIUM
3 - SHORT
caretPos The caret position which represents the current field to be changed. It can be one of: HOUR, MINUTE, and SECOND. 
Note:The "caretPos" property of TimeSpinner is defined for invoking API, it is not similar to the caret position defined in the TextField. So when you mapulate TimeSpinner, the caret position displayed in the input field may not be consistent with the value of "caretPos" property displayed in the property sheet.
int R, W, B 3 3 - HOUR
4 - MINUTE
5 - SECOND
value The calendar value in long. long R, W, B, E The current system calendar in long. minimum<value< maximum
calendar
(display name:Time)
The calendar value in calendar. java.util.Calendar R, W, B The current system calendar. any instance of Calendar
maximum The maximum value. java.util.Calendar R, W, B 11:59:59 PM maximum>minimum
minimum The minimum value. java.util.Calendar R, W, B 00:00:00 AM any instance of Calendar
dateString The time shown in the entry field. String R, W, B, E The current system time. any instance of valid time string

* R = read, W = write, B = bound, E = expert, H = hidden


Events

The TimeSpinner fires the following events:

          Listener Method: dateChanged(com.ibm.spinner.DateChangedEvent)

Methods

Please refer to the Methods section of Overview.


User Interface

This section describes the user interface of the TimeSpinner Bean. It shows what the TimeSpinner Bean looks like and how to use the TimeSpinner.
 

          Figure 3-1  - The Vertical Button TimeSpinner Bean

The currently selected value is displayed in an input field. You can change the time value by clicking on different subfields within the input field and using the arrow buttons to spin them either independentlyor associatedly, or just by typing a time string into the input field to set the current value.If the input is invalid, the TimeSpinner will automatically restore the previous value when you press the "Enter" or "Tab" key, or change the focus to another component.

About how to input in the textfield, please refer to the User Interface of CalendarSpinner, the description to the fields related to the date has no use to the TimeSpinner.


NumericSpinner Bean

The NumericSpinner Bean is a component which displays and spins a list of integers with bounded range.

Properties

Following are the significant properties of the NumericSpinner Bean:
 

Property Description Data Type Flags* Default Value Valid Value
model The data model used in the Numeric Spinner. com.sun.java.swing.BoundedRangeModel R, W, B, E a new instance of com.sun.java.swing.
DefaultBoundedRangeModel
(0,0,0,100)
any instance of BoundedRangeModel
increment The step value  by which the value is changed every time. int R, W, B 1 increment>0
value The current value. int R, W, B 0 maximum>=value>=minimum
minimum The minimum value. int R, W, B 0 minimum<=maximum
maximum The maximum value. int R, W, B 100 maximum>=minimum

* R = read, W = write, B = bound, E = expert


Events

Please Refer to the Events section of Overview.

Methods

Please refer to the Methods section of Overview.

 


User Interface

This section describes the user interface of the NumericSpinner Bean. It shows what the NumericSpinner Bean looks like.

          Figure 4-1  - The Vertical Button NumericSpinner Bean
 

The currently selected value is displayed in an input field. You can change the integer value by clicking on the arrow buttons, or just by typing an integer number into the input field to set the current value. If the input is invalid, the NumericSpinner will automatically restore the previous value when you press the "Enter" or "Tab" key, or change the focus to another component.