Introducing JXMonthView!

A JDNC Calendar Component

by Joshua Outwater

February 22, 2005

What is it?

JXMonthView is a component that displays a monthly calendar, very similar to what you would see in applications such as Evolution and Outlook. Although many applications require the use of a calendar, most developers currently write their own solutions. It is our hope that this open source version will fill this void and allow developers to concentrate on their applications.

What can it do?

JXMonthView can display any number of months. Depending on the component orientation, months are drawn from left to right or right to left and then top to bottom. For example, the following JXMonthView component is configured to display one column and two rows.

As more drawing area is provided to the component, it adds more rows or columns. For instance, if the user horizontally stretches the above demo application, another column (two months) is added once enough space becomes available.

Four selection modes are available to determine how the user can interact with the component. Single selection allows the user to select just one day at a time, while multiple selection lets the user select any consecutive number of days. Week selection ensures that selections of over 7 days snap to a full week. A no-selection mode is useful for displaying a calendar that doesn't take input.

Applications such as calendar clients may need to flag particular days on the calendar. A list of these days can be given to the JXMonthView, which displays these days in boldface.

How do I use it?

I'm glad you asked! And I'm glad you made it this far through the article! In this section I'll describe the API available in the JXMonthView component.

Creating a JXMonthView by calling the default constructor creates an instance that displays the current month.

// Create a JXMonthView with the default constructor
JXMonthView monthView = new JXMonthView();

Another constructor takes a long specifying the time in milliseconds of the month you wish to display. To display the month of January in the year 2004, for example, you need a time in milliseconds that falls within that particular month and year. Here's some code to do just that:

// Create a calendar that has the date of January 1, 2004.
Calendar cal = Calendar.getInstance(2004, 1, 1);
// Create a new JXMonthView using the date set in the calendar.
JXMonthView monthView = new JXMonthView(cal.getTimeInMillis());

You can configure JXMonthView to display more than one month at a time by calling setPreferredCalCols or setPreferredCalRows. These methods set the preferred number of months to display in each column or row. When the preferred number of columns or rows changes, the dimensions returned from getMinimumSize and getPreferredSize are updated so the component knows the amount of space it needs to draw. The following code configures the month view to display two columns and two rows:

monthView.setPreferredCols(2);
monthView.setPreferredRows(2);

By default the first day of the week is retrieved from the Calendar class for the current locale. Using the setFirstDayOfWeek method you can make any day of the week the first day. You can also change the character representation of the days painted in the header by providing an array of strings.

// Set the first day of the week to Monday.
monthView.setFirstDayOfWeek(Calendar.MONDAY);
// Supply our own character representation of the days of the week.
// Sunday is always considered the first entry.
monthView.setDaysOfTheWeek(new String[]{"S", "M", "T", "W", "R", "F", "S"});

To flag days, you need to provide an array of longs (time in milliseconds) ordered from smallest to largest. This is useful to inform users of days that have scheduled appointments.

// Create some dates that we want to flag as being important.
Calendar cal1 = Calendar.getInstance();
cal1.set(2004, 3, 12);
Calendar cal2 = Calendar.getInstance();
cal2.set(1976, 4, 9);


long[] flaggedDates = new long[] {
    System.currentTimeMillis()
    cal1.getTimeInMillis(),
    cal2.getTimeInMillis(),
};

// Sort them in ascending order.
java.util.Arrays.sort(flaggedDates);
// Flag these dates as important.
monthView.setFlaggedDates(flaggedDates);

As we mentioned before, JXMonthView supports four modes of selection: single, multiple, week, and no selection. Once the user makes a selection, an action is fired to inform listeners that selection has changed. The following example prints out the selected date range every time the action listener is called.

// Change the selection mode to select full weeks.
monthView.setSelectionMode(JXMonthView.WEEK_SELECTION);

// Add an action listener to be notified when the user
// changes selection via the mouse.
monthView.addActionListener(new ActionListener() {
    public void actionPerformed(ActionEvent e) {
        System.out.println(((JXMonthView)e.getSource()).
            getSelectedDateSpan());
    }
});

How do I get it?

JXMonthView is part of JDNC. You can find JDNC downloads and source at: jdnc.dev.java.net.

Post a Comment