57 45 4c 4c 20 44 4f 4e 45 21
                   

The SWT Calendar Combo is a combo box widget written in Java for SWT/JFace/RCP applications that opens a calendar when dropped down. The calendar is modeled after Microsoft Outlook’s calendar widget and acts and behaves exactly the same (and it is also theme based). The calendar supports date ranges, limited selection and much more. Another nice feature is that the combo is not based on CCombo (as many other custom implementations), but is instead attached to the native Combo box. By default, the widget comes with Default implementations for everything that allows you to skin the combo according to the following:

  • Outlook 2005 – Windows XP Blue Theme
  • Outlook 2005 – Windows XP Olive Theme
  • Outlook 2005 – Windows XP Silver Theme
  • Outlook 2007 – It’s basically the same as the 2005 themes

External Site

This widget is under the Eclipse Nebula project, which is a group of custom written widgets that are not part of the standard SWT API but perhaps aim to be so in the future. This site contains more information and also example snippets that are very useful to understanding how to use the widget. Please visit the Nebula homepage for more information.

Go to the Eclipse Nebula homepage

License

The Calendar Combo is released under the EPL (Eclipse Public License). It is imperative that you understand what this license allows you to do. If you do not know what this license entails, please read the full license details at the following link;

The EPL license

Compatability

The code is compiled using Java 1.4 and should work fine with all newer Java versions post 1.4.

Limitations

Currently the widget should without any issues under Windows XP and Mac OS X. There are however issues under Linux (GTK / Ubuntu / etc) where vital listeners are not firing in the same way (or at all). As such, if you need cross platform usability of this widget you can try forcing the combo into SWT.FLAT on GTK and see if it works for you in that mode. SWT.FLAT is normally intended for when the widget is used inside a table (as a cell editor), but when the combo is flat, it will use the CCombo class instead of the Combo class which is a custom implementation of a combo. The drawback of this is that the combo will not have a native look and feel. There is currently no known way to fix the listeners not firing on GTK as of SWT version 3.4. Hopefully SWT version 3.5 will address some of the known listener issues or open up new possibilities.

Internationalization / Localization

The CalendarCombo is basically i18n compliant and should support all Locales with some known exceptions. Currently it does not support the following locales (Java 6):

  1. ja_JP_JP (Japanese Imperial Calendar)
  2. th_TH and th_TH_TH (Thai Buddhist Calendar)
  3. zh_HK (Hong Kong)

All of those calendars are special calendars that do not follow the Gregorian Calendar. You can read more about these locales here.

Unit Test

There is a Unit Test available for download which you can find here: Download Unit Test. This file is not part of the packaged jar as it contains generics and the widget is compiled under Java 1.4. The unit test will run through each known locale and run various date parsing tests which print out information to the console. You will need Java 5+ and JUnit version 4 or above to run it.

Download

I highly recommend you take the latest nightly build and use that as the last stable version is slightly on the old site at the moment. This comment will be removed when the current nightly is considered stable.

Download JAR’s, source and API documentation
CVS Repository

Screenshots

Office 2005 Blue & Month Picker

Office 2005 Silver

Office 2005 Blue

Office 2005 Olive

Usage

As the widgets is more or less handled like your typical Combo box (with a few extra features), you should find using the widget very simple. The constructor has optional extras as well, but by default the widget can be created as if it was any other SWT Combo box. As you can tell by the screenshots, there is no custom Combo box implementation wrapped inside the Calendar Combo Widget, but instead, it is a native Combo box, so whatever OS you use it on, it should take the same appearance as the combo box of that operating system.

Normal Creation

CalendarCombo cCombo = new CalendarCombo(parent, SWT.READ_ONLY)
...

Flat Creation

You may want to force the combo into using a CCombo instead of a normal combo for inclusion inside a table as a cell editor, or for other reasons. To do so, simply pass along SWT.FLAT like this:

CalendarCombo cCombo = new CalendarCombo(parent, SWT.READ_ONLY | SWT.FLAT)
...

Depending on another CalendarCombo

Depending on other CalendarCombos allows mimicing a feature that exists in Microsoft Outlook. By passing in a different CalendarCombo box as a constructor parameter the effect is that when the combo box is dropped down, the initially shown start date is the selected date of the first Calendar Combo box (that is passed as a parameter).

To explain this further, here’s a real life example: Say we have two combo boxes. One represents the Start Date of a project, and the other represents the End Date. The End Date combo is created with passing in the Start Date combo as a constructor parameter. The user selects “June 16″ as a date on the Start Date combo. When they then open the End Date combo, “June 16″ is the initially default selected date which simplifies selecting and end date for the user. Here is the code for this;

CalendarCombo startCombo = new CalendarCombo(parent, SWT.READ_ONLY);
CalendarCombo endCombo = new CalendarCombo(parent, SWT.READ_ONLY, startCombo);
...

Listening to Events

You listen to events more or less like you would on a normal Combo, by using a listener interface that notifies you when date selection has changed. The listener also notifies you if a date range selection has changed should you have enabled that feature in the combo. And finally, you also get notified when the popup closes, in case you wish to do manual validation. For any other standard SWT listeners, you may attach them straight to the Combo itself.

cCombo.addCalendarListener(new ICalendarListener() {
	public void dateChanged(Calendar date) {
		if (date != null) {
			System.err.println(date.getTime().toString());
		}
		else {
			System.err.println("null");
		}
	}

	public void dateRangeChanged(Calendar start, Calendar end) {
	}

	public void popupClosed() {
	}
});

There is also an adapter if you don’t want to implement all the methods for each listener you are introducing. The adapter is called CalendarListenerAdapter.