Date selection components

Have you ever wondered why Matlab does not have standard GUI date-handling components?

Matlab has many built-in date-handling functions (calendar, date, datestr, datenum, datetick, datevec etc.). Unfortunately, this built-in support does not extend to Matlab GUI. If we need a date-selection drop-down or calendar panel we have to design it ourselves, or use a third-party Java component or ActiveX control.

JIDE Components

Luckily, we have a much better alternative, right within Matlab. This relies on the undocumented fact that Matlab uses JIDE components for many of its GUI components. As already explained earlier, JIDE controls are pre-bundled in Matlab (/java/jarext/jide/jide-grids.jar under the Matlab root). You can find further details on JIDE Grids in the Developer Guide (pages 28-35) and the Javadoc documentation.

In particular, JIDE Grids includes the following date-selection controls:

• DateChooserPanel – an extension of Swing’s JPanel that displays a single month and enables selecting one or more days
• CalendarViewer – a similar panel, that displays several months in a table-format (e.g., 4×3 months)
• DateComboBox – a combo-box (drop-down/popup menu) that presents a DateChooserPanel for selecting a date
• DateSpinnerComboBox – presents a date-selection combo-box that includes both the DateComboBox and a spinner control (this control is only available in the latest Matlab releases)
• MonthChooserPanel – a panel that enables selection of entire months (not specific dates)
• MonthComboBox – a month selection combo-box, similar to DateComboBox but without the ability to select individual days

Usage of these controls is very similar, so I’ll just show the basics here. First, to present any control, we need to use the built-in javacomponent function or the uicomponent utility:

% Initialize JIDE's usage within Matlab
com.mathworks.mwswing.MJUtilities.initJIDE;
 
% Display a DateChooserPanel
jPanel = com.jidesoft.combobox.DateChooserPanel;
[hPanel,hContainer] = javacomponent(jPanel,[10,10,200,200],gcf)

 

DateChooserPanel and MonthChooserPanel components

2x2 CalendarViewer component

Just as with any Java object, properties may either be accessed with the Java accessor methods (e.g. getName() or setName(name)), or the Matlab get/set semantics (e.g. get(prop,’Name’) or set(prop,’Name’,value)). When using the Matlab syntax, remember to wrap the Java object in a handle() call, to prevent a memory leak (or use hPanel rather than jPanel):

jPanel.setShowWeekNumbers(false);    % Java syntax
set(hPanel,'ShowTodayButton',true);  % Matlab syntax

Retrieving the selected date is easy:

>> selectedDate = jPanel.getSelectedDate()
selectedDate =
Sun Jun 27 00:00:00 IDT 2010
% or: selectedDate = get(jPanel,'SelectedDate');
 
% Note: selectedDate is a java.util.Date object:
>> selectedDate.get
	Class = [ (1 by 1) java.lang.Class array]
	Date = [27]
	Day = [0]
	Hours = [0]
	Minutes = [0]
	Month = [5]
	Seconds = [0]
	Time = [1.27759e+012]
	TimezoneOffset = [-180]
	Year = [110]

We can enable selection of multiple dates (SINGLE_SELECTION=0, SINGLE_INTERVAL_SELECTION=1,MULTIPLE_INTERVAL_SELECTION=2):

jModel = hPanel.getSelectionModel;  % a com.jidesoft.combobox.DefaultDateSelectionModel object
jModel.setSelectionMode(jModel.MULTIPLE_INTERVAL_SELECTION);
 
>> hPanel.getSelectionModel.getSelectedDates
ans =
java.util.Date[]:
    [java.util.Date]
    [java.util.Date]
    [java.util.Date]

And of course we can set a callback for whenever the user modifies the selected date(s):

hModel = handle(hPanel.getSelectionModel, 'CallbackProperties');
set(hPanel, 'ValueChangedCallback', @myCallbackFunction);

For the combo-box (drop-down/popup menus) controls, we obviously need to modify the displayed size (in the javacomponent call) to something much more compact, such as [10,10,100,20]. These components display one of the above panels as their pop-up selection panels. Users can access and customize these panels using the combo-box control’s getPopupPanel() function (or PopupPanel property).

 

DateComboBox and DateSpinnerComboBox components

Numerous other customizations are possible with these JIDE components – have fun exploring (my uiinspect utility can be quite handy in this)! Just remember that JIDE evolves with Matlab, and so JIDE’s online documentation, which refers to the latest JIDE version, may be partially inapplicable if you use an old Matlab version. The older your Matlab, the more such inconsistencies that you may find.

Alternative components

There are several alternatives to the JIDE components:

If we have Matlab’s Financial toolbox, we can use the uicalendar function. Unfortunately, this control is not available if you don’t own the expensive Financial toolbox.

If we only target Windows-based platforms, we could use third-party ActiveXes such as the Microsoft Date-and-Time-Picker (MSComCtl2.DTPicker.2), Microsoft MonthView (MSComCtl2.MonthView.2) or the Microsoft Office Calendar (MSCAL.Calendar.7) ActiveX controls. Depending on your installed applications, you may have other similar controls. For example, if you have Symantec’s EndPoint Protection (SEP), you have access to the SEP Date Control (LDDATETIME.LDDateCtrl.1). Of course, these controls will not work on non-Windows platforms, or platforms that do not have these ActiveX controls installed.

We can also use other (non-JIDE) third-party Java controls from places like javashareware.com, swinglabs.org, downloadthat.com, sharewareconnection.com, easyfreeware.com, l2fprod.com, fileheap.com/software/components.html, swing-components.safe-install.com and many others. One specific example is NachoCalendar, from SourceForge.com.

Finally, we could use some of the utilities posted on the Matlab File Exchange: uical, uisetdate, calender (sic) and several others.

In my own biased opinion, none of these alternatives comes close to the ease-of-use and functionality of the JIDE components presented above. What do you think? Please add your comments here.

Related posts:

1. Color selection components Matlab has several internal color-selection components that can easily be integrated in Matlab GUI...
2. Plot-type selection components Several built-in components enable programmatic plot-type selection in Matlab GUI - this article explains how...
3. Setting status-bar components Matlab status-bars are Java containers in which we can add GUI controls such as progress-bars, not just simple text labels...
4. Figure toolbar components Matlab's toolbars can be customized using a combination of undocumented Matlab and Java hacks. This article describes how to access existing toolbar icons and how to add non-button toolbar components....
5. Uitable customization report In last week’s report about uitable sorting, I offered a report that I have written which covers uitable customization in detail. Several people have asked for more details about the contents of this report. This is a reasonable request, and...
6. Tri-state checkbox Matlab checkboxes can easily be made to support tri-state functionality....