Tutorial

JCalendar

JCalendar is the generic name for two Java components: one is called JCalendar and the other is called JCalendarCombo. They both share common features, particularly the ability to select a date and/or time. The former accomplishes this with a panel and the latter with a combo-box.

Creating the Components

The simplest constructors for JCalendar and JCalendarCombo have no arguments. They create calendar components that allow a date to be selected from the default calendar in the default locale.

The next step is to select the specific Calendar and Locale classes to use (but the JCalendar components have only been tested with the Gregorian calendar). There are three more parameters that can be specified:

  • Whether to select a date, a time or both.
  • Whether to display today's date at the bottom of the component.
  • The SimpleDateFormat pattern to use in displaying the time selection field.

Normally, the calendar components allow you to select a null date/time (press Delete or Backspace to set a null selection). This is useful for cases where the user has an option of not specifying a date/time. You can turn this off by calling setNullAllowed(false).

For the JCalendarCombo, you also have the option of making the combo-box editable (as with any combo-box). You can control the date format that appears in the combo-box field with setDateFormat().

Date Selections

You can set the selected date with setDate(). The default date/time selection will be today's date/time unless you explicitly set a date. You can read the currently selected date at any time using getDate() or getCalendar(). Finally, you can add a DateListener to listen for date changes. Each time the date/time changes, the listener is called.

Fonts

You may specify the font to use for each elements that makes up a calendar component. The elements are:

  • The month-year title.
  • The day-of-week labels (Mon, Tue, etc.).
  • The day buttons.
  • The time spinner.
  • The today's date message.

In addition, the combo box text can be changed in the usual way—by calling setFont() on the combo box component.

Keyboard Control

The calendar appears with buttons that allow the user to move a month or year backwards or forward. You can use the arrow keys to do the same:

  • Left Arrow - Move back a month.
  • Right Arrow - Move forward a month.
  • Shift Left Arrow - Move back a year.
  • Shift Right Arrow - Move forward a year.

In addition, you can use Delete or Backspace to select a null date (if null dates are allowed).

As normal, you can tab through the various buttons (including the day buttons) and press Enter to activate the button.

If there is a time field, it can be a little problematic. Once it has focus, the up/down arrow keys increment/decrement portions of the time field. The left/right keys select the portion of the time to increment/decrement. You will need to tab out of the time field or use the mouse to select a button elsewhere in the calendar in order to restore the normal keyboard controls.

The JCalendarCombo has some additional keyboard controls. The down arrow pops up a calendar if one is not visible. The up arrow hides the calendar pop-up (as does the Enter key). The Escape key also hides the calendar, but restores the date to the value it had before the calendar was popped up.

Internationalization

The JCalendar components take advantage of the internationalization and localization work done by the Calendar class. In order to fully localize JCalendar to other than US English, you will need to obtain the source code for JCalendar and create a org.freixas.jcalendar.Bundle_<locale>.properties file which translates the text in org.freixas.jcalendar.Bundle.properties, where <locale> is a two-letter country code.

The main thing in this file are the tooltips for the various buttons and the text for displaying today's date as well as some error messages.

Look-and-Feel

It was important for my own use that the JCalendar combo-box adopt the current Java Look-and-Feel (L&F). As it turns out, it is impossible to design a class that can automatically do this for all possible L&F's. If you need to use a L&F other than Metal, Windows or Motif, you will need to obtain the JCalendar source code and make some changes.

In the updateUI() method of JCalendarCombo.java, you will need to add some code that looks like this:

else if (cui instanceof SomeComboBoxUI) {
    cui = new SomeDateComboBoxUI();
}

Then in the inner class section of the code, add a new inner class:

class SomeDateComboBoxUI
    extends SomeComboBoxUI
{
    protected ComboPopup createPopup() {
        return new CalendarComboPopup();
    }
}

Of course, the word "Some" would be replaced by the name of your L&F (Metal, Motif, etc.). When your L&F is installed, the JCalendarCombo combo-box will now look the same as a normal JComboBox.

Summary

The JCalendar components are designed to be easy to use—create the component you want, set up a few options and register a DateListener and you're in business.

After reading this tutorial, you should examine the example programs provided which exercise many of the features of JCalendar components.