Migration

The following changes require that you update your code because otherwise it won't compile. We make such changes from time to time to improve code readability and to make it more maintainable.

• Refactored most JDatePicker methods in a new Popup object. This means:

  • Calendar properties can no longer be specified using the setCalendar* methods. Instead you should access the calendar itself with getPopup().getMonthView(). For instance:

    //the old way of specifying the calendar title foreground color
    datePicker.setCalendarTitleForeground(color);
    
    //the new way to do it
    datePicker.getPopup().getMonthView().setTitleForeground(color);

  • The calendarVisible property that controlled whether the calendar is showing or not, has been removed. The visibility can now be controlled using a Popup object. For instance:

    //the old way of programmatically showing the popup
    datePicker.setCalendarVisible(true);
    
    //the new way to do it
    datePicker.getPopup().setVisible(true);

  • If you've created new UI delegates for JDatePicker just to access its JMonthView, you no longer need them as the popup calendar can be accessed directly.

    //the old way of configuring the popup calendar of JDatePicker was to go in its UI delegate
    public class DatePickerCustomCalendarUI extends BasicDatePickerUI {
      public static ComponentUI createUI(JComponent c) {
        return new DatePickerCustomCalendarUI();
      }
    
      protected JMonthView createMonthView() {
        JMonthView mv = super.createMonthView();
        mv.callSomeMethodHere();
    
        return mv;
      }
    }
    
    //the new way to do it
    JMonthView mv = datePicker.getPopup().getMonthView();
    mv.callSomeMethodHere();

New Features

• JDatePicker and JDateField can now be used with JBuilder's dbSwing data binding framework. We now provide support for three major data binding frameworks: JGoodies, Oracle's JClient and JBuilder's dbSwing.

• Months can now be edited by their names or by using numbers in both JDateField and JDatePicker. For instance, you can enter D, Dec, December or 12 to specify the month of December. The names of the months depend on the used locale. The previous example is for English-based locales.

• The JDatePicker calendar can now be configured using a Popup object.

  The drop-down calendar of a JDatePicker is no longer configurable by using the calendar methods but by using the new Popup object. The Popup offers direct access to the calendar thus making these methods unnecessary. As a result of this change:

  • The JDatePicker class has fewer methods (reduced from 29 to 7)

  • Configuring the popup JMonthView is now straight-forward (just access it from the popup object); the previous version didn't expose all the calendar properties in JDatePicker

  • The popup can notify when it is about to open or close

• Added the scrollDateToVisible(java.util.Date) method to JMonthView.

Improvements

• JDatePicker is created faster. Its popup calendar is created only when it is made visible for the first time. The time needed to create a non-editable JDatePicker is comparable to that of a non-editable JComboBox. This improvement is noticeable especially in forms that use many JDatePicker objects.

  The only drawback is that it will take longer when the popup calendar is created for the first time. But if a calendar (JMonthView) has been created at least once before, this is not a problem anymore.

Bug Fixes

• Clicking the today button in JDatePicker calendar doesn't reset the time fields.

• In a JDateEditComponent, the time zone information for the date format was not updated until a setDateFormat method was called.

• The setEnabled method from JMonth didn't disable the component completely.

• The date selection model didn't fire an event when the last selected date was deselected.

• A deadlock occurred when setting a date format for a RTL locale like Arabic, Qatar.

• The JDatePicker popup didn't always keep its selected date in view when it was opened.

Migration

The following changes require that you update your code because otherwise it won't compile. We make such changes from time to time to improve code readability and to make it more maintainable.

• The names of the jars files were changed from javadatepicker[-suffix] to jdatepicker[-suffix].jar to match the new product name.

• We have refactored the JDateEditComponent methods that dealt with the date format to improve their readability. Previous version had two properties for specifying the date format:

  • setDateFormat(int), getDateFormat():int

  • setCustomDateFormat(String), getCustomDateFormat():String

  The changes in this version are as follows:

  • Renamed setCustomDateFormat(String) to setDateFormat(String)

  • Added setDateFormat(int, int) to specify both date and time format using the DateFormat constants. The method setDateFormat(int) specified only a date format using the DateFormat constants.

  • Replaced the getDateFormat():int and getCustomDateFormat():String with getDateFormat():DateFormat.

  With these changes it should be easier to see all the date format methods in one place (for instance when using auto-completion) and also specify a date-time format using DateFormat constants that can be used with various locales.

• In JMonthView, the displayToday property was renamed to todayButtonVisible to keep it consistent with the noneButtonVisible property. This means that

  • setDisplayToday(boolean) -> setTodayButtonVisible(boolean)

  • isDisplayToday():boolean -> isTodayButtonVisible():boolean

New Features

• JDatePicker and JDateField can now be used with the Oracle ADF JClient data binding framework.

• The dates from the calendar can be flipped (displayed horizontally or vertically) using the setDatesOrientation(int) method in JMonth.

• Added the getSelectedDateAsText method in JDateEditComponent to return the currently selected date in text format.

  This method is particularly useful if you need to return the text representation of the date as a custom string. For instance, you could override it to represent the Christmas date as Christmas '01 instead of Dec 25, 2001.

Improvements

• Faster loading time. This version improves the loading time for JDatePicker, JMonthView and JMonth with over 40%.

• Improved time zone parametrization for all date components

  • Moved the setTimeZone method from JDateEditComponent to JDateComponent.

  • Added a setTimeZone method to DateSelectionModel and MonthModel.

  • Changed getWeekNumber(Date) to getWeekNumber(Date,TimeZone) in WeekModel.

• Improved the WeekModel to return the month for a selected day of week. Until now it was impossible to know the month when a day of week was selected.

  Added the getSelectedMonth() method and changed setSelectedDow(int) to setSelectedDow(int, int).

• Improved the date format methods API for JDateEditComponent. See the Migration section above for more details.

• Added the setMonth(int, int) method in JMonth to make it easier to change the month programmatically.

• Added Danish, Dutch, Finnish and Polish localizations for JMonthView. This localization refers to the texts for the Today and None buttons that cannot be retrieved from somewhere else. The component is now localized for the following languages: Danish, Dutch, English, Finish, French, German, Hungarian, Italian, Norwegian, Polish, Portuguese, Romanian, Spanish and Swedish.

Bug Fixes

• Fixed DefaultWeekModel bug that added a WeekModel listener instead of removing it.

• The date from the date picker editor is committed before opening the popup. In this way the actual edited date is saved and the popup calendar is synchronized.

• Failed to set emptyselectionallowed on JDatePicker after the component was created.

• The JDatePicker popup didn't close when the mouse was clicked in the editor.

• The text displayed by an editing component in free text mode when a null date was selected was not updated correctly.

• Fixed JDatePicker to select date intervals.

Migration

• We have renamed two AbstractMonthViewUI methods to better reflect their meaning:

  • createTodayLabel():JLabel -> createTodayComponent():JComponent

  • createNoneLabel():JLabel -> createNoneComponent():JComponent

  This change is not supposed to make you update your code unless you are using a custom month view UI delegate that extends AbstractMonthViewUI, BasicMonthViewUI or DefaultMonthViewUI.

New Features

• Added three more properties to JDatePicker to control its calendar:

  • setCalendarTrailingPreviousEnabled

  • setCalendarTrailingNextEnabled

  • setCalendarDowFirst

• Added the setNoneButtonVisible method to JMonthView to control the visibility of the none button.

• Added the disabledDateSelectionAttempted method to DateSelectionListener. This will allow to receive notifications every time when an attempt to select a disabled date is made.

• Added support for ISO week numbers. Read the ISO week numbers section for more information on how to configure a JMonth component to display week numbers according to the ISO 8601 format.

  • getWeekNumber was added in WeekModel

  • setWeekNumberISOFormatEnabled and isWeekNumberISOFormatEnabled were added in DefaultWeekModel

• One letter week day names in DefaultWeekModel. Added the DOW_NAMES_LETTER type value for the dowFormat parameter in DefaultWeekModel. This is important when the names of the week days are displayed in the calendar.

• Added time zone parametrization for JDateEditComponent components.

Improvements

• Added the autoUpdateToday property to JMonth and JMonthView. When this property is enabled, an internal timer that updates the today date at midnight is started. By default it is not enabled.

  The previous implementation started and stopped this timer automatically. So, if you relied on the component to update the today date automatically, you would have to add a line of code that enables it.

• The default date renderers are registered in the UI delegates and not in the constructors of the components.

• The AbstractXXXUI classes that define the UI delegates contain two new methods: createDefaults and initializeDefaults. The createDefaults method can be overridden to specify a UI delegate's specific set of default values.

• Added two new buttons to the JMonthView UI delegate that scroll the years.

  The new buttons are created using the #createNextYearButton() and #createPreviousYearButton() methods from AbstractMonthViewUI. By default, these methods return null which means that no button is created. But the UI delegate class can be extended to return actual buttons. This sample UI delegate shows how to do this.

Bug Fixes

• The date edit components didn't update their internal state correctly when using the free text mode. This meant that the registered parser received wrong text information and the date that it produced was also wrong. The bug was discovered when using an editable date picker with the "MM/dd/yy" date format and Japanese locale.

• If a value bigger than the maximum allowed value is typed in the day field, we interpret it as being the maximum.

  For instance, if the current date is 01/01/2005 (dd/MM/yyyy) and then we type 31/04/2005, the date resulted after pressing enter is 30/04/2005 (the month of April has at most 30 days). This inconsistence appears when changing the date as explained above; the day changes to 31 (a valid value for the month of January) and then the month is changed to April (a month that has less than 31 days).

• The JDatePicker popup was aligned to the left.

  If the JDatePicker was too wide, the popup appeared to the left which made the component a little unusable as the user had to move the mouse to the left to select a date. Now, the popup is aligned to the right which means that it is displayed right under the drop-down button.

• Fixed popup display on multi-monitor systems. It was displayed only in the primary monitor.

• The AbstractDateSelectionModel#setSelectedDates() method selected all the dates and it didn't reject the disabled dates.

• Fixed behavior for the date cell editor.

  The date cell editor stops the editing when a date is selected from the popup or the user hits enter in the text field (when JDatePicker is editable).

• JMonth receives focus when one of its dates is clicked.

• UI delegates where instantiated twice when they were associated to a JDateComponent.

• Fixed an internal memory leak.

Migration

• We have restructured the MonthModel interface and moved some of its methods and fields.

  • MonthModel#getDowFirst -> WeekModel#getDowFirst

  • MonthModel#setDowFirst -> WeekModel#setDowFirst

  • MonthModel#getDows -> WeekModel#getDows

  • MonthModel#DOW_NAMES_LONG -> DefaultWeekModel#DOW_NAMES_LONG

  • MonthModel#DOW_NAMES_SHORT -> DefaultWeekModel#DOW_NAMES_SHORT

  • MonthModel#getDowNamesFormat -> DefaultWeekModel#getDowNamesFormat

  • MonthModel#MONTH_NAMES_LONG -> DefaultMonthModel#MONTH_NAMES_LONG

  • MonthModel#MONTH_NAMES_SHORT -> DefaultMonthModel#MONTH_NAMES_SHORT

  • MonthModel#getMonthNamesFormat -> DefaultMonthModel#getMonthNamesFormat

• The DefaultMonthModel has also changed as follows.

  • DefaultMonthModel#setDowFormat -> DefaultWeekModel#setDowNamesFormat

  • DefaultMonthModel#setMonthFormat -> DefaultMonthModel#setMonthNamesFormat

• The MonthModelListener has also changed as follows.

  • MonthModelListener#dowFirstChanged -> WeekModelListener#dowFirstChanged

  • MonthModelListener#dowNamesFormatChanged -> WeekModelListener#dowNamesChanged

  • MonthModelListener#monthNamesFormatChanged -> MonthModelListener#monthNamesChanged

New Features

• Refactored the MonthModel interface and its related classes DefaultMonthModel and MonthModelListener. This was done because a new WeekModel interface was added and MonthModel contained week related methods. The month model contains information strictly about months and the week model information about weeks.

  The tutorial sections that described the month model have been updated. You may want to know more about what a month model is, how to listen for changes on it, how to implement a custom month model or which are the most used methods.

• Added a new WeekModel interface, mainly to control week and day of week selection. You may want to know more about what a week model is, how to listen for changes on it, how to implement a custom week model or which are the most used methods.

  The week model is the supporting mechanism that is used to select weeks or days of week. Users will click on the week number to select a week. But this mechanism is not enabled by default in a JMonth component. Read this section for more information.

• Added the toggleDateSelectionEnabled property to JMonth components. This feature is especially useful when you want to select multiple dates but you do not want to use the CTRL + mouse click to do that. Enabling this property has the same effect as holding down the CTRL key. The tutorial contains a new section that explains this feature.

Improvements

• The demo uses the JGoodies Plastic LF instead of Kunststoff and Metouia LFs. We decided to make this replacement because many developers prefer it. When using the Plastic LF with JDatePicker, the PlasticComboBoxUI must be recompiled without the final modifier. Read this section for more information.

• Added a new section in the javadoc that explains why we use client properties to configure the components.

Bug Fixes

• NPE when typing non-digits after the last cursor position in a JDateEditComponent component.

• It was possible to reselect a null date for a JDateComponent component. This generated unnecessary events.

• Selecting a date in the calendar also changed the date of the date picker which triggered unnecessary date selection events.

  Form now on, selecting a date in the drop-down calendar of JDatePicker does not change the date picker selected date. This happens only when the user presses ENTER, clicks on a date or toggles the popup. If ESC is pressed, the calendar selection is lost.

• The today date represented by Java Date Picker components (JMonth, JMonthView, JDatePicker) was not synchronized with the system date if the application ran over night. If the application was left over night running and then used the second day, the today date would be in fact the yesterday date.

  This meant that both the calendar today date was not rendered correctly and also the today label from JMonthView didn't display the right date. To fix this bug we did some API changes:

  • Added the MonthModel#setToday() and MonthModel#getToday() methods.

  • Added the MonthModelListener#todayChanged() method.

  The fix actually consisted of introducing a timer to trigger an event when the day changes.

  A JMonth/JMonthView component has an internal timer that updates the today date from MonthModel each time the day changes. This leads to an accurate representation of the today date in all Java Date Picker components (JMonth, JMonthView, JDatePicker).

New Features

• Added support for multiple months in JMonthView. Months can be arranged on rows and columns. The tutorial contains a new section that explains this feature.

• Added the scrollingDelta property for JMonthView to control scrolling behavior.

• Added the trailingNextEnabled and trainlingPreviousEnabled properties for JMonth to control trailing dates visibility.

• Added support for the JGoodies data binding framework.

• Added horizontalAlignment property for JDateEditComponents.

Improvements

• Added a new section with issues that may prevent the good use of the Java Date Picker components.

• Added the JDateEditComponent.clearDateOnEdit client property for JDateEditComponent components (JDateField and JDatePicker). See the updated tutorial section on date editing behavior.

• The demo application can also be started as an applet using the startDemo.html file.

• Removed jar signing for the standard distribution.

• JDatePicker uses the same JComboBox keyboard shortcuts to open the popup.

• Improved editing for the am/pm field. One can just type "am" or "pm" to change this field.

Bug Fixes

• Fixed caret blink problem for JDateField and JDatePicker.

• DateModel registration was not handled properly by JDateEditComponents.

• Fixed stylesheet problem for JDK 1.5. The demo could not be started with 1.5.

• Fixed focus problem for Mac OS X.

• Surrenders focus to the underlying text field when the date field gains it.

• Fixed layout arrangement for the JTextField used by JDateField.

• Fixed calendar year spinner problem for JDatePicker.

• Fixed lead date selection behavior for AbstractDateSelectionModel.

Improvements

• Improved the UI delegate API. This is a major improvement because it allows to create UI delegates for the Java Date Picker components easily. UI delegates can help you refine the way components look and behave. The tutorial contains a new section that explains how to use the UI delegates.

• The year spinner from JMonth (used by JMonthView and JDatePicker) repeatedly increments or decrements the year as long as its buttons are pressed.

• Added "JDatePicker.backgroundOnEditable" client property to JDatePicker. More details can be found here.

• Added action event support for JDateComponents. JMonthView components will fire an action event when a selectable date is double-clicked.

• Added new methods to JDateEditComponent (commitEdit, isEditValid, invalidEdit). See the updated tutorial section on date validation behavior.

• Added new methods to JDateEditComponent (setAutoCenturyYear and getAutoCenturyYear). These methods are useful when a year is specified as a short one (between 0 and 99).

• Added new methods to DateModel (isUsed, setUsed, setAutoCenturyYear and getAutoCenturyYear).

• Added Norwegian and Swedish localizations for JMonthView. This localization refers to the texts for the Today and None buttons that cannot be retrieved from somewhere else. The component is now localized for the following languages: German, Spanish, French, Hungarian, Italian, Norwegian, Portuguese, Romanian and Swedish.

• Demo source code files accessible from this tutorial where converted to html using java2html. This makes the code easier to read. Here is a link to such a file.

Bug Fixes

• Fixed the components to work with the Netbeans 3.6 Form editor. This is a bug in Netbeans rather than in the Java Date Picker components. The fix is actually a workaround to allow the components to be used with Netbeans.

• JMonth generated NPE when using Java 1.4 under certain instantiation conditions.

• Improved date editing behavior. The caret position is now kept consistent while editing a date. When editing a date you can also type a separator char to advance the caret to the next field.

• The months popup menu from JMonth was sometimes displayed improperly if the mouse was clicked, dragged and then released.

• JMonth and JMonthView report correctly focusGained and focusLost events.

New Features

• JMonthView inherits from JMonth. The methods inherited from JMonth will act on the months aggregated by JMonthView.

• Date selection API is simpler. Although date selection can be made using the underlying date selection model, the components must provide a set of methods that are frequently used.

  As a consequence, we have added the methods setSelectionMode and setSelectedDates to JMonth and moved the method setSelectedDate from JDateEditComponent to JDateComponent.

  Also, the methods selectDate (use setSelectedDates instead) and selectToday from JMonth were removed.

• More customization options for a JMonth component. Added grid control operations and week days names visibility operations.

• More customization options for the JMonthView component. Can control visibility for the JMonthView status bar which contains the Today and None buttons.

• Added SelectTodayAction in JDateComponent

• Removed getDowNamesFormat and getMonthNamesFormat from JMonth.

Improvements

• Documentation is easy to use. The tutorial has become the main source of information about the Java Date Picker suite. All documents (changes, license, instructions to install, etc) have been moved here.

• Tool tip support for JDatePicker and JDateField.

• All the components resize correctly, especially JMonthView.

• Foreground and background colors for JDatePicker and JDateField.

• Demo application restructured. The demo application is entirely explained in the tutorial. Each tutorial section that explains the functionality of a component uses a certain demo part for that.

• Duplicate messages that were generated when the same date was selected where removed.

Bug Fixes

• Obscured calendar popup. The calendar popup used by JDatePicker was not always kept entirely visible.

• Fixed fast scrolling for JMonthView when using Single selection Mode. If JMonthView was in Single selection mode and the mouse was dragged over the trailing dates, the selected date would change very fast, too fast for a user to follow it.

• Fixed JBuilder palette problem. JBuilder failed to add JMonthView and JDatePicker when working in Design mode.

• Fixed memory leak in JDatePicker.

Migration

• For JDatePicker, the methods setPopupVisible and isPopupVisible have been renamed to setCalendarVisible and isCalendarVisible to be consistent with the other calendar methods.

• For JDatePicker, change listeners are not accepted anymore. One can register a date model listener instead to be notified about date field changes. This is explained below in Listening for Changes on Date Model.

New Features

• New JDateComponent. All date selection components are based on JDateComponent. It is also the container for standard date selection actions.

  This is explained below in Using a JDateComponent.

• New JDateEditComponent. JDateEditComponent is the base class for all date editing components. By default, dates are edited using an internal editor that forces users to type correct dates according to a standard or custom date format.

  The component can also accept free text entries that are converted to dates using a date parser. This makes it possible to plug special parsers that can convert shortcut strings like 'today' to an appropriate date.

  This is explained below in Using a JDateEditComponent.

Improvements

• Home & End actions. Home and end action will select the first, respectively the last selectable days in a month.

• PopupVisible Property. In JDatePicker, the popupVisible property has been renamed to calendarVisible to be consistent with other calendar methods. So, the calendar's visibility can be controlled using the setCalendarVisible method.

Bug Fixes

• Obscured calendar popup. The calendar popup used by JDatePicker was obscured when the component appeared near the bottom of the screen. Now, the calendar is visible no matter where the JDatePicker component is placed.

New Features

• Null Dates Support. Added support for null dates (empty selection).

• Date Renderer. The calendar's appearance can be customized with a custom renderer.

• Today/None Texts Localization. The texts for the today and none buttons can be customized using a properties file.

• Editor Change Listener. Change listener that will receive notifications when the date is changed by the editor.

Improvements

• New Date Editor. The date editor has been redesigned to allow easier date input. One could simply type "01012004" to say "January 1st, 2004".

• Easier Keyboard Navigation. Selecting a disabled date with the keyboard will select the next possible date.

• New JMonthView keyboard shortcuts. Added DELETE and BACKSPACE to select no date.

• JMonthView API enhancement. Added methods for the components to support easier model control (setSelectionMode, getSelectionMode).

• Table Editor Enhancement. Create a table cell editor with a specified date picker. (JDatePicker#createTableCellEditor(datePicker)).

• Register Custom Actions. Custom actions can be registered on the components to make them even more customizable.

Bug Fixes

• All the components get the focus when it is requested either by mouse or keyboard allowing for smoother navigation.

• Look and feel is changed correctly for the table cell editor.

Improvements

• Fixed month scrolling to mean only that. When using the JMonthView arrow buttons, the month popup menu or the year spinner, only the month is changed without any date selection.

Migration

• The package com.standbysoft.datepicker has been renamed to com.standbysoft.component.date which now contains generic classes and interfaces that can be used for date selection. The Swing components are contained in the sub package com.standbysoft.component.date.swing.

New Features

• Dates can be represented and edited by JDatePicker using a custom date format (see JDatePicker#setCustomFormat()).

Improvements

• JDatePicker can be used with any look and feel (Metal, Motif, Windows, Aqua and custom ones).

• Improved date editor to edit time fields. Now it can be considered a date time editor also.

Migration

• Restrictions on the minimum allowed date and maximum allowed date have been moved from MonthModel to DateSelectionModel. This design expresses more the nature of these restrictions. See the tutorial on how to work with the new DateSelectionModel.

  The following operations have been removed from MonthModel:

  1. rollYear -> use the date selection API to select a certain date

  2. rollMonth -> use the date selection API to select a certain date

  3. getMinimumAllowed -> use DateSelectionModel#getMinimumAllowed

  4. getMaximumAllowed -> use DateSelectionModel#getMaximumAllowed

  5. isMonthInRange -> use DateSelectionModel#isDateSelectable

  The following operations have been removed from MonthModelListener and MonthModelAdapter:

  1. dateIntervalChanged -> use DateSelectionListener#disabledDatesChanged

  The following operations have been removed from JMonth:

  1. rollYear -> use the date selection API to select a certain date

  2. rollMonth -> use the date selection API to select a certain date

• Added more methods for JDatePicker to support calendar customization. We urge you to use these methods in order to customize the date picker calendar as they allow for a cleaner code and maintenance.

  The following attributes have been added to JDatePicker:

  1. calendarDisplayToday (setCalendarDisplayToday, getCalendarDisplayToday)

  2. calendarWeekNumbersVisible (setCalendarWeekNumbersVisible, getCalendarWeekNumbersVisible)

New Features

• Added more methods for JDatePicker to support calendar customization.

Improvements

• Improved the date selection mechanism. Setting the minimum and maximum allowed dates is now part of the date selection model. The AbstractDateSelectionModel class has been added, it contains a basic implementation for the DateSelectionModel interface.

• Improved the JDatePicker built-in editor. The editor acts like a masked edit control where each field of the date can be edited.

• Improved tutorial documentation.

New Features

• Added an editor and two more fields (dateFormat, editable) to JDatePicker.

Improvements

• Improved Javadoc comments.

Bug Fixes

• JDatePicker can now be used with any Look and Feel.

New Features

• Added two more methods (setPopupVisible, isPopupVisible) to DatePickerUI and JDatePicker.

Bug Fixes

• The popup for TableCellEditor is hidden only when a day is explicitly selected.