Undocumented Matlab

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.