4

Date Chooser

Features of JCDateChooser  Classes and Interfaces  Properties  Methods  Examples

---

4.1 Features of JCDateChooser

JCDateChooser is a component that displays a calendar in one of four variant forms. Each one displays the days of the month in the familiar form of a calendar, but varies the ways that the month and year are displayed.

The different styles are:

• Spin Popdown
  The year is shown in a spin box; the month is shown in a popdown.

  
  
  

• Dual Spin
  Spin boxes are used to display both the year and the month.

  
  
  

• Quick Select
  The year is shown in a spin box; a table is used to display all twelve months. One of the months may be highlighted to indicate that it has been selected.

  
  
  

• Read Only
  The year and month are shown in non-editable fields. The table showing the days of the month is read-only as well. Selected "special" dates still appear highlighted.

  
  
  

• Like the standard Swing components, JCDateChooser provides for the optional use of a Tool Tip.

The accompanying figure shows the full component in its Quick Select form, so the year is shown in a spin box, while tables are used to show months and days of the month. Note that special days, in this case Saturdays and Sundays, are distinguishable from the others. You can observe the other calendar styles by running the example called examples.elements.DateChooser.java.

Figure 27 :  A JCDateChooser.

---

4.2 Classes and Interfaces

Classes in the com.klg.jclass.util.calendar Package

AbstractLabel	An abstract class for setting dates in a locale-dependent fashion. It is used for MonthLabels and YearLabels.
DayTable	The days of the month.
JCCalendarContainer	A container that manages CalendarComponent children. That is, any calls to the calendar component interface methods are automatically passed to any calendar component children.
JCCalendar	A calendaring utility class that can define special dates and custom date classes, such as "Tuesdays" or "April Fool's Day" (April 1).   JCCalendar augments java.util.Calendar by providing extra date-specific capabilities.
JCDateChooser	A GUI component with four styles of calendar. Special dates display differently from other dates.
MonthLabel	Displays a locale-specific table of month labels.
MonthPopdown	Encapsulates the months of the year in a popdown.
MonthSpin	Encapsulates the months of the year in a spin box.
MonthTable	Encapsulates the months of the year in a table.
YearLabel	Presents the designated year in a label.
YearSpin	Presents the designated year in a spin box.

4.2.1 The CalendarComponent Interface

The calendar component uses a single model for the day, month, and year.

The methods declared in public interface CalendarComponent are:

• public void setCalendarModel(JCValueModel model)
Sets the model which provides the current date being used by the calendar component.
• public void setSpecialDates(JCCalendar special_dates
Sets the special dates being used by the calendar component.
• public void setLocale(Locale locale);
  Sets the locale being used by the calendar component.
• public void addActionListener(ActionListener l)
Adds an action listener to detect specific actions on this component.
• public void removeActionListener(ActionListener l)
Removes action listener to detect specific actions on this component.

4.2.2 The SpecialDate Interface

This interface has only one method:

boolean isSpecialDate(int year, int month, int date, int week)

You'll note that the numeric value for the week (1 - 52) is a redundant parameter in isSpecialDate. This is done for efficiency's sake. If you implement the SpecialDate interface, you will have to supply a numeric value for the week even though it is possible to compute it from the first three parameters in isSpecialDate. Note that you use JCCalendar's dayofweek() method to calculate this value.

---

4.3 Properties

Properties of JCDateChooser

chooserType	For specifying the date chooser type, use one of JCDateChooser.DUAL_SPIN, JCDateChooser.QUICK_SELECT, JCDateChooser.READ_ONLY, or JCDateChooser.SPIN_POPDOWN.
days	The days array* used by the date chooser
minimumDate, maximumDate	Bounds between which dates are valid. Any date outside these bounds will be rejected by the validator.
months	The months array* used by the date chooser
shortMonths	The months' short form array* used by the date chooser
toolTipText	The text that appears in the tool tip box when the mouse pointer rests over the component.
value	The currently selected date.
*This array must be at least as long as what the JCDateChooser's locale expects. By default, the array is initialized to the locale's default list.

Properties of JCCalendar

addSpecialDate, removeSpecialDate	Mark a special date on the calendar, or remove one that has already been designated as special.
isSpecialDate	A Boolean indicating whether the given date is special.

For a full listing of the properties, see Appendix A.

---

4.4 Methods

JCDateChooser

There are four visual aspects to the date chooser: Quick Select, Dual Spin, Spin Popdown, and Read Only. Use setChooserType(int type) to select the type you want to display. type is one of JCDateChooser.DUAL_SPIN, JCDateChooser.QUICK_SELECT, JCDateChooser.READ_ONLY, or JCDateChooser.SPIN_POPDOWN.

The CalendarComponent interface provides the mechanism for extracting parts of a JCDateChooser date. The methods are getDayComponent(), getMonthComponent(), and getYearComponent().

As noted in the section on properties, you set minimum and maximum dates by providing setMinimumDate() and setMaximumDate() with a java.util.Calendar object.

Set the currently selected date programmatically with setValue(), or determine what its value is with getValue(). The parameter is once again a java.util.Calendar object.

JCCalendar

While not subclassed from java.util.Calendar, JCCalendar is used in conjunction with it to provide for a classification of some dates as "special." Special days are managed through these methods: addSpecialDate() and removeSpecialDate(), which take a SpecialDate object as a parameter. and isSpecialDate(). There is no restriction on how many dates may be deemed special.

The class contains a number of utility methods. One, called isLeapYear(), can be used to determine if any given year is a leap year. With dayOfWeek(), you can determine the day of the week given a year, month, and day. You can clone a Calendar object using copyCalendar().

Certain applications involving calendars require that certain days are treated specially. For example, some businesses that are open on the weekend close on Mondays. In such a case, it is useful to be able to lump all Mondays together and classify them as days when the store is closed. Perhaps the store's founder always holds a sale on his birthday, the 29th of February. In this and similar cases, it's useful to be able to denote anniversary days that occur on the same date every year. There are other days, such as Labor day, which is defined as the first Monday in September. JCCalendar contains inner classes DayOfWeek, MonthDayOfMonth, MonthWeekDayOfWeek to help you deal with these situations. These classes allow you to store various calendar objects of the types just mentioned. The first of these allows you to store a day, like Sunday, by declaring an instance variable

DayOfWeek sunday = new DayOfWeek(0);

From the example, you see that the seven days of the week are mapped using a zero-based index.

To store a date like July 4, use:

MonthDayOfMonth july4 = new MonthDayOfMonth(7, 4)

To store a date like Labor Day, use:

MonthWeekDayOfWeek laborDay = new MonthWeekDayOfWeek(9, 1, 1)

---

4.5 Examples

The illustrative code snippets shown here demonstrate how you can create special days and how you can set bounds on the permissible dates. Refer to the Date Chooser example, automatically installed into com/klg/jclass/examples/elements/ when you install JClass Elements, for the complete example.

//The location of JCDateChooser
import com.klg.jclass.util.calendar.*;

//Create an instance of JCDateChooser within your class.
dateChooser = new JCDateChooser();
...
//Create a "special day"
JCCalendar special_dates = new JCCalendar();
// Make Sundays special days
special_dates.addSpecialDate(new JCCalendar.DayOfWeek(0));
...
dateChooser.setSpecialDates(special_dates);
...
//Set bounds for the calendar
Calendar max = Calendar.getInstance();
  max.set(max.YEAR, 2050);
dateChooser.setMaximumDate(max);