uitable is probably the most complex basic GUI controls available in Matlab. It displays data in a table within a figure, with settable properties as with any other Matlab Handle-Graphics (HG) control. After many years in which the uitable was available but semi-documented and not officially supported in Matlab, it finally became fully documented and supported in R2008a (aka Matlab 7.6). At that time its internal implementation has changed from a MathWorks-developed Java table to a JIDE-based Java table (another JIDE-derived table was described here last year). Since R2008a, both versions of uitable are available – the old version is available by adding the ‘v0′ input arg.
Matlab’s uitable exposes only a very limited subset of functionalities and properties to the user. Numerous other functionalities are available by accessing the underlying Java table and hidden Matlab properties. Today I will describe a very common need in GUI tables, that for some unknown reason is missing in Matlab’s uitable: Sorting table data columns.
Last week I explained how we can modify table headers of an ActiveX table control to display sorting icons. In that case, sorting was built-in the control, and the question was just how to display the sorting arrow icon. Unfortunately, Matlab’s uitable does not have sorting built-in, although it’s quite easy to add it, as I shall now show.
Old uitable sorting
The old uitable is the default control used until R2007b, or that can be selected with the ‘v0′ input arg since R2008a. It was based on an internal MathWorks extension of the standard Java Swing JTable – a class called com.mathworks.widgets.spreadsheet.SpreadsheetTable.
Users will normally try to sort columns by clicking the header. This has been a deficiency of JTable for ages. To solve this for the old (pre-R2008a) uitable, download one of several available JTable sorter classes, or my TableSorter class (available here). Add the TableSorter.jar file to your static java classpath (via edit('classpath.txt')) or your dynamic classpath (javaaddpath('TableSorter.jar')).
% Display the uitable and get its underlying Java object handle [mtable,hcontainer] = uitable('v0', gcf, magic(3), {'A', 'B', 'C'}); % discard the 'v0' in R2007b and earlier jtable = mtable.getTable; % or: get(mtable,'table'); % We want to use sorter, not data model... % Unfortunately, UitablePeer expects DefaultTableModel not TableSorter so we need a modified UitablePeer class % But UitablePeer is a Matlab class, so use a modified TableSorter & attach it to the Model if ~isempty(which('TableSorter')) % Add TableSorter as TableModel listener sorter = TableSorter(jtable.getModel()); jtable.setModel(sorter); sorter.setTableHeader(jtable.getTableHeader()); % Set the header tooltip (with sorting instructions) jtable.getTableHeader.setToolTipText('<html> <b>Click</b> to sort up; <b>Shift-click</b> to sort down<br /> ...</html>'); else % Set the header tooltip (no sorting instructions...) jtable.getTableHeader.setToolTipText('<html> <b>Click</b> to select entire column<br /> <b>Ctrl-click</b> (or <b>Shift-click</b>) to select multiple columns </html>'); end
Sorted uitable - old version
New uitable sorting
The new uitable is based on JIDE’s com.jidesoft.grid.SortableTable and so has built-in sorting support – all you need to do is to turn it on. First get the underlying Java object using my FindJObj utility:
% Display the uitable and get its underlying Java object handle mtable = uitable(gcf, 'Data',magic(3), 'ColumnName',{'A', 'B', 'C'}); jscrollpane = findjobj(mtable); jtable = jscrollpane.getViewport.getView; % Now turn the JIDE sorting on jtable.setSortable(true); % or: set(jtable,'Sortable','on'); jtable.setAutoResort(true); jtable.setMultiColumnSortable(true); jtable.setPreserveSelectionsAfterSorting(true);
Note: the Matlab mtable handle has a hidden Sortable property, but it has no effect – use the Java property mentioned above instead. I assume that the hidden Sortable property was meant to implement the sorting behavior in R2008a, but MathWorks never got around to actually implement it, and so it remains this way to this day.
A more detailed report
I have prepared a 30-page report about using and customizing Matlab’s uitable, which greatly expands on the above. This report is available for a small fee here (please allow up to 48 hours for email delivery). The report includes the following (more details here):
- comparison of the old vs. the new uitable implementations
- description of the uitable properties and callbacks
- alternatives to uitable using a variety of technologies
- updating a specific cell’s value
- setting background and foreground colors for a cell or column
- using dedicated cell renderer and editor components
- HTML processing
- setting dynamic cell-specific tooltip
- setting dynamic cell-specific drop-down selection options
- using a color-selection drop-down for cells
- customizing scrollbars
- customizing column widths and resizing
- customizing selection behavior
- data sorting (expansion of today’s article)
- data filtering (similar to Excel’s data filtering control)
- merging table cells
- programmatically adding/removing rows
- numerous links to online resources
- overview of the JIDE grids package, which contains numerous extremely useful GUI controls and components
Related posts:
- Uitable customization report Matlab's uitable can be customized in many different ways. A detailed report explains how. ...
- Uitable cell colors A few Java-based customizations can transform a plain-looking data table into a lively colored one. ...
- Multi-line uitable column headers Matlab uitables can present long column headers in multiple lines, for improved readability. ...
- treeTable A description of a sortable, groupable tree-table control that can be used in Matlab is provided. ...