Reply

SwingX: Introduction to the JXDatePicker

At 11:56 PM on Sep 14, 2005, R.J. Lorimer wrote:

The JXDatePicker from the SwingLab's SwingX project is a quickly maturing, and generally useful 'calendar' component for Swing. To give you a quick idea of what I mean by calendar component, here is what the JXDatePicker looks like using the Ocean look and feel and my System look and feel for Windows XP:

To quickly show you the hoops of working with the JXDatePicker I have written a quick example program that responds to changes in the JXDatePicker. Note that I simply print the user's selected date in a JLabel, which, for all intents and purposes is pointless because the date picker already comes with a pre-formatted text field for that same purpose, but, I needed to do *something* with the date, and I'm not finding the creativity to come up with a better example.

final JLabel label = new JLabel();
label.setText("Choose Date by selecting below.");
 
final JXDatePicker datePicker = new JXDatePicker(System.currentTimeMillis());
datePicker.addActionListener(new ActionListener() {
	public void actionPerformed(ActionEvent e) {
		label.setText(datePicker.getDate().toString());
	}
});
 
 
frame.getContentPane().add(label, BorderLayout.NORTH);
frame.getContentPane().add(datePicker, BorderLayout.CENTER);

Once you've integrated the date picker in to your application, you need to learn what customization options you have available to you.

User-Provided Format Processing

One of the keys to the JXDatePicker is the embedded text field. This allows keyboard-savvy users to bypass the calendar component altogether, and simply enter the date manually. The expectation is that once they are done, the date picker will still fire events that your application can respond to; where yoru application code isn't concerned as to whether they used the calendar drop down, or simply used the text field. The trick is that every user has a potentially different idea of how to input a date. Sure, you can provide them with some documentation as to what format you expect, but wouldn't it be nice if you could understand multiple commonly provided formats. By using either the JXDatePicker.setFormats(String[]) or JXDatePicker.setFormats(DateFormat[]) methods, you can. Each entry in the provided array is a possible acceptable format. The String[] in the former method is simply composed of String patterns that apply for the java.text.SimpleDateFormat class - so read the documentation there to learn what options are available to you.

In reality, however, the JXDatePicker already has multiple common formats available. The only remaining piece of the puzzle is what format will be used in the text field if the user selects a value in the calendar, rather than entering it manually. The answer is: the format in the first index of the array provided (or the long format of the built-in JXDatePicker formats), or the format the user provided if they have ever manually entered a value - once they have entered a value manually, it remembers what format they used, and outputs any further selections in that format.

The Link Panel

At the bottom of the calendar view, there is a little panel with a link with today's date:

This panel can be customized freely by you. First, you can specify the date that should be used, and the message format that should be used with that date:

datePicker.setLinkDate(System.currentTimeMillis(), new MessageFormat("The time is now {0}"));

Alternatively, you can completely replace the link panel with your own implementation (with whatever you want in reality) by using JXDatePicker.setLinkPanel(JPanel) .

The Month View

If the date picker is too coarsely defined for you, and you don't want to have all of the popup, button, and text field thrown together, you can consider the JXMonthView. This view operates identically to the JXDatePicker calendar window, but it doesn't have the associated text field or button, and can simply be embedded into a panel. Here is some example code using that:

final JLabel label = new JLabel();
label.setText("Choose Date by selecting below.");
 
final JXMonthView monthView = new JXMonthView(System.currentTimeMillis());
monthView.setSelectionMode(JXMonthView.MULTIPLE_SELECTION);
monthView.addActionListener(new ActionListener() {
	public void actionPerformed(ActionEvent e) {
		label.setText(monthView.getSelectedDateSpan().getEndAsDate().toString());
	}
});
 
 
frame.getContentPane().add(label, BorderLayout.NORTH);
frame.getContentPane().add(monthView, BorderLayout.CENTER);

Here is what it looks like:

You'll notice that in this case, my code is working a little differently to get the selected value. That is because the month view supports multiple selection types - you can technically set these on the full date picker as well by calling JXDatePicker.getMonthView() and setting them on the month view, but it really doesn't apply in that case. The month view allows for single selection, multi-selection (via mouse dragging), week-level selection (simply via clicking), and no selection, which for the most part makes the month view a read-only component.

Happy coding, and stay tuned for more journeys into the SwingX world in the near future.

Until next time,

R.J. Lorimer
Contributing Editor - rj -at- javalobby.org
Author              - http://www.coffee-bytes.com
Software Consultant - http://www.crosslogic.com