Undocumented Matlab » HTML

Multi-line tooltips

Yair Altman — Thu, 03 Nov 2011 02:05:36 +0000

I often use tooltips in my Matlab GUIs. They are a fantastically intuitive and unobtrusive visual helper for users to understand the GUI. In this blog, I have already posted several articles about how to tweak tooltip contents (here, here, and here). Today I would like to expand on one of the aspects that were already covered, namely that of multi-line tooltips.

Basic multi-line tooltips

The basic multi-line tooltip consists of a simple string that includes the newline character. for example:

set(hControl, 'TooltipString', ['this is line 1' 10 'and this is line 2'])

Or better (platform independent):

set(hControl, 'TooltipString', sprintf('this is line 1\nand this is line 2'))

A simple multi-line tooltip string

As can be seen, this is very simple to set up. Unfortunately, the font cannot be customized. Which leads us to:

HTML-rendered multi-line tooltips

Tooltips, like most other Matlab controls, supports HTML rendering. This is a natural corollary of the fact that Java Swing, on which all Matlab controls are based, automatically supports HTML. All we need to do is to add ‘‘ at the very beginning of our tooltip string, and then we can embed HTML tags within the rest of the string:

set(hControl, 'tooltipString', 'line #1
line#2');

Multi-line HTML'ed tooltip

And a more sophisticated example, used within my createTable utility on the File Exchange:

A more complex multi-line HTML-based tooltip

Note that there is no need to close the final HTML tags in the tooltip string, although it’s not an error to do so (as I have done above).

The problem with formatted multi-line tooltip

Unfortunately, none of these two methods work when we wish to display formatted multi-line tooltips. For example, suppose that we wish to display struct data in a tooltip:

>> myData = struct('a',pi, 'b',-4, 'very_long_field_name','short txt')
myData = 
                       a: 3.14159265358979
                       b: -4
    very_long_field_name: 'short txt'
 
>> myDataStr = evalc('disp(myData)');
>> set(hControl, 'TooltipString', myDataStr);

Badly-formatted multi-line tooltip

If we try to use HTML, the result looks even worse, because if the HTML-renderer detects a newline character embedded in the string, it simply uses the regular (non-HTML) renderer:

set(hControl, 'TooltipString', ['' myDataStr ''])

Failure to parse a string using HTML

Even if we fix this by replacing all line-separators with ‘‘, we still get a badly-formatted tooltip, because HTML ignores all white spaces:

>> myDataStr2 = strrep(myDataStr, sprintf('\n'), '
');
>> set(hControl, 'TooltipString', ['' myDataStr2 ''])

Badly-formatted multi-line tooltip

(you can see that it’s HTML-formatted by the fact that the tooltip contents do not have internal margins like in the non-HTML tooltip above)

Fixed-width font multi-line tooltips

We now recall the HTML

tag, which tells HTML not to ignore white-spaces. In most web browsers, it also defaults to using a fixed-width font. Unfortunately, this is not the case here:

set(hControl, 'TooltipString', ['' myDataStr2])

Still not quite right...

Which brings us to the final customization of the day, namely explicitly forcing the tooltip to use a fixed-width font:

set(hControl, 'TooltipString', ['' myDataStr2 ''])

Finally - a well-formatted multi-line tooltip

Even more powerful customizations can be achieved using CSS rather than pure HTML. This will be discussed a future article.

Spicing up Matlab uicontrol tooltips Matlab uicontrol tooltips can be spiced-up using HTML and CSS, including fonts, colors, tables and images...
Multi-column (grid) legend This article explains how to use undocumented axes listeners for implementing multi-column plot legends...
Inactive Control Tooltips & Event Chaining Inactive Matlab uicontrols cannot normally display their tooltips. This article shows how to do this with a combination of undocumented Matlab and Java hacks....
Performance: scatter vs. line In many circumstances, the line function can generate visually-identical plots as the scatter function, much faster...

Uitable cell colors

Yair Altman — Thu, 27 Oct 2011 01:51:53 +0000

A client recently asked me to develop an application that will help discover technical indicators for trading on the stock market. The application was very data-intensive and the analysis naturally required visual presentations of number-crunching results in a readable manner. One of the requirements was to present numeric results in a data table, so we naturally use uitable for this.

Today I will show how using some not-so-complex Java we can transform the standard Matlab uitable into something much more useful.

First pass – basic data table

We start by displaying the data in a simple uitable. The essence of the relevant code snippet was something like this:

headers = {'Periods', ...
           'Any period
returns', ...
           'Avg return
signal', ...
           'Avg
gain', ...
           'Avg
draw', ...
           'Gain/draw
ratio', ...
           'Max
gain', ...
           'Max
draw', ...
           'Random
% pos', ...
           'Signal
% pos', ...
           'Payout', '% p-value'};
hTable = uitable('Data',data, 'ColumnEditable',false, ...
           'ColumnName',headers, 'RowName',[], ...
           'ColumnFormat',['numeric',repmat({'bank'},1,11)], ...
           'ColumnWidth','auto', ...
           'Units','norm', 'Position',[0,.75,1,.25]);

Plain data table - so boooooring...

We can see from this simple example how I have used HTML to format the header labels into two rows, to enable compact columns. I have already described using HTML formatting in Matlab controls in several articles on this website. I have not done this here, but you can easily use HTML formatting for other effect such as superscript (^{), subscript (_{), bold (), italic (), font sizes and colors () and other standard HTML effects.}}

Even with the multi-line headers, the default column width appears to be too wide. This is apparently an internal Matlab bug, not taking HTML into consideration. This causes only part of the information to be displayed on screen, and requires the user to either scroll right and left, or to manually resize the columns.

Second pass – auto-resizing that actually works…

To solve the auto-resizing issue, we resort to a bit of Java magic powder. We start by using the findjobj utility to get the table’s underlying Java reference handle. This is the containing scrollpane, and we are interested in the actual data table inside. We then use the setAutoResizeMode, as described in the official Java documentation.

jScroll = findjobj(hTable);
jTable = jScroll.getViewport.getView;
jTable.setAutoResizeMode(jTable.AUTO_RESIZE_SUBSEQUENT_COLUMNS);

Auto-resized columns that actually work

Third pass – adding colors

There are still quite a few other customizations needed here: enable sorting; remove the border outline; set a white background; set row (rather than cell) selection and several other fixes that may seem trivial by themselves but together giver a much more stylish look to the table’s look and feel. I’ll skip these for now (interested readers can read all about them, and more, in my detailed uitable customization report).

One of the more important customizations is to add colors depending on the data. In my client’s case, there were three requirements:

data that could be positive or negative should be colored in green or red foreground color respectively
large payouts (abs > 2) should be colored in blue
data rows that have statistical significance (%p-value < 5) should have a yellow background highlight

While we could easily use HTML or CSS formatting to do this, this would be bad for performance in a large data table, may cause some issues when editing table cells or sorting columns. I chose to use the alternative method of cell renderers.

ColoredFieldCellRenderer is a simple table cell renderer that enables setting cell-specific foreground/background colors and tooltip messages (it also has a few other goodies like smart text alignment etc.). This requires some Java knowledge to program, but in this case you can simply download the ColoredFieldCellRenderer.zip file and use it, even if you don’t know Java. The source code is included in the zip file, for anyone who is interested.

After using javaaddpath to add the zip file to the dynamic Java classpath (you can add it to the static classpath.txt file instead), the contained Java class file is available for use in Matlab. We configure it according to our data and then assign it to all our table’s columns.

Java savvy readers might complain that the data-processing should perhaps be done in the renderer class rather than in Matlab. I have kept it in Matlab because this would enable very easy modification of the highlighting algorithm, without any need to modify the generic Java renderer class.

Unfortunately, in the new uitable design (the version available since R2008a), JIDE and Matlab have apparently broken the standard MVC approach by using a table model that not only controls the data but also sets the table’s appearance (row-striping background colors, for example), and disregards column cell-renderers. In order for our custom cell renderer to have any effect, we must therefore replace Matlab’s standard DefaultUIStyleTableModel with a simple DefaultTableModel. This in itself is not enough – we also need to ensure that the uitable has an empty ColumnFormat property, because if it is non-empty then it overrides our cell-renderer.

In the following code, note that Java row and column indices start at 0, not at 1 like in Matlab. We need to be careful about indices when programming java in Matlab.

The rest of the code should be pretty much self explanatory (again – more details can be found in the above-mentioned report):

% Initialize our custom cell renderer class object
javaaddpath('ColoredFieldCellRenderer.zip');
cr = ColoredFieldCellRenderer(java.awt.Color.white);
cr.setDisabled(true);  % to bg-color the entire column
 
% Set specific cell colors (background and/or foreground)
for rowIdx = 1 : size(data,1)
 
  % Red/greed foreground color for the numeric data
  for colIdx = 2 : 8
    if data(rowIdx,colIdx) < 0
      cr.setCellFgColor(rowIdx-1,colIdx-1,java.awt.Color(1,0,0));    % red
    elseif data(rowIdx,colIdx) > 0
      cr.setCellFgColor(rowIdx-1,colIdx-1,java.awt.Color(0,0.5,0));  % green
    end
  end
 
  % Yellow background for significant rows based on p-value
  if data(rowIdx,12) < = 5 && data(rowIdx,11)~=0
    for colIdx = 1 : length(headers)
      cr.setCellBgColor(rowIdx-1,colIdx-1,java.awt.Color(1,1,0));    % yellow
    end
  end
 
  % Bold blue foreground for significant payouts
  if abs(data(rowIdx,11)) >= 2
    cr.setCellFgColor(rowIdx-1,10,java.awt.Color(0,0,1));    % blue
 
    % Note: the following could easily be done in the renderer, just like the colors
    boldPayoutStr = ['' num2str(data(rowIdx,11),'%.2f') ''];
    %jTable.setValueAt(boldPayoutStr,rowIdx-1,10);  % this is no good: overridden when table model is replaced below...
    dataCells{rowIdx,11} = boldPayoutStr;
  end
end
 
% Replace Matlab's table model with something more renderer-friendly...
jTable.setModel(javax.swing.table.DefaultTableModel(dataCells,headers));
set(hTable,'ColumnFormat',[]);
 
% Finally assign the renderer object to all the table columns
for colIdx = 1 : length(headers)
  jTable.getColumnModel.getColumn(colIdx-1).setCellRenderer(cr);
end

Finally something lively!

This may not take a beauty contest prize, but you must admit that it now looks more useful than the original table at the top of this article.

Related posts:
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...
Uitable sorting Matlab's uitables can be sortable using simple undocumented features...
Uitab colors, icons and images Matlab's semi-documented tab panels can be customized using some undocumented hacks...
Changing Matlab’s Command Window colors Matlab's Command Window foreground and background colors can be modified programmatically, using some of Matlab's undocumented internal Java classes. Here's how....

Uitable customization report

Yair Altman — Wed, 03 Aug 2011 18:00:25 +0000

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 so in today’s post I will discuss in a bit more detail the highlights of what can be achieved to customize Matlab uitables. For the fine details, well, get the report…
1. Introduction
Here I discuss the evolution of the uitable control over the past decade, from its initially semi-documented status to today. I explain the similarities and differences between the control’s versions and explain how they can both be accessed today.
I also provide references to online resources for both Matlab’s uitable‘s underlying Java components, as well as multiple alternatives using different technologies, that have been used and reported over the years.
2. Customizing uitable
In this section I explore the sub-component hierarchy of the uitable control (both new and old). I show how the scrollbar sub-components can be accessed (this will be used in section 4 below), as well as the table header and data grid.
annotated uitable sub-components
I explain how individual cells can be modified without requiring the entire data set to be updated. This is very important in large data sets, to prevent flicker and improve performance.
I show how HTML can be used to format data cell contents (even images) and tooltips:
uitable with HTML cell contents and tooltip
I then explain the role of the cell-renderer in the visual appearance of the cell, and of cell-editors in the way that cells interact with the user for data modification. I explain such customizations from the simple (setting a column’s background color) to the complex (cell-specific tooltips and colors; color-selection cell-editor):
uitable with a non-standard cell-renderer (left) and cell-editor (right)

uitable with custom CellRenderer and CellEditor
3. Table callbacks
This section presents the different callback properties that are settable in the old and new uitable, for events such as cell selection, data modification, key press, and mouse click. The discussion includes a working code example for validating user input and reverting invalid edits. The section also includes a discussion of how to avoid and overcome problems that may occur with the callback execution.
4. Customizing scrollbars, column widths and selection behavior
This section explains how to control the scrollbars behavior. For example, hiding the horizontal (bottom) scrollbar, automatically displaying it when the data width is larger than the table width. I also show how to control the column widths.
I then show how to customize the data selection policy: Can multiple cells be selected? perhaps only one cell at a time? or maybe a single large interval of cells? – this is all customizable. I then explain how the selection can be done and accessed programmatically. Ever wanted to set the cursor on cell A1 after some system event has occurred? – this will show you how to do it. Ever wanted to use non-standard selection colors (background/foreground)? – this can also be done.
5. Data sorting
Table sorting was discussed in last week’s article. This section expands on that article, and explains how the sorting can be customized, controlled, and accessed programmatically, and how sorted rows can be retrieved by the user.
Multi-column sorting with blue sort-order numbers
6. Data filtering
Data filtering is the ability to filter only a specified sub-set of rows for display (just like in Excel). This section explains how to do it (it’s so easy!).
uitable data filtering
7. JIDE customizations
The new uitable is based on an underlying JIDE table. This sectino explains how we can use this to our advantage for some simple and useful. Customization.
For example: have you wondered some time why is it that columns can only be resized by dragging the tiny divider in the table header? Why can’t the columns and rows be resized by dragging the grid lines? Well, it turns out that they can, with just a tiny bit of JIDE magic powder, explained here:
Resizing columns
Similarly, this section explains how we can use JIDE to merge together adjacent cells:
Example of two table cell-spans (1x2 and 2x2)
8. Controlling the table structure (adding/removing rows)
This section discusses the matter of dynamically adding and removing table rows. While this is easy to do in the old uitable, this is unfortunately not the case in the new uitable.
9. Final remarks
Here I present a workaround for a long-time table bug. Also, I present my createTable utility that wraps table creation in Matlab:
createTable utility screenshot (note the action buttons, sortable columns, and customized CellEditor)
Appendix – JIDE Grids
Finally, this appendix presents an overview of the wide array of components provided by JIDE and available in Matlab. uitable uses only one of these components (the SortableTable). In fact, there are many more such controls that we can use in our GUIs.
These include a wide selection of combo-box (drop-down) controls – calculator, file/folder selection, date selection, color selection, multi-elements selection etc. In addition, a very wide selection of lists, trees and table types is available.
Also included is a set of specialized editbox controls for accepting IP addresses and credit card numbers:
IP address and credit-card entry boxes
While not explaining all these controls in detail (this could take hundreds of pages), this section does say a few words on each of them, and includes links to online resources for further exploration.

Related posts:
Uitable sorting Matlab's uitables can be sortable using simple undocumented features...
Uitable cell colors A few Java-based customizations can transform a plain-looking data table into a lively colored one. ...
GUIDE customization Matlab's GUI Design Editor (GUIDE) has several interesting undocumented features. This post describes how to customize GUIDE rulers....
Button customization Matlab's button uicontrols (pushbutton and togglebutton) are basically wrappers for a Java Swing JButton object. This post describes how the buttons can be customized using this Java object in ways...

Uitable sorting

Yair Altman — Tue, 26 Jul 2011 18:00:01 +0000

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(' Click to sort up; Shift-click to sort down
...'); else % Set the header tooltip (no sorting instructions...) jtable.getTableHeader.setToolTipText(' Click to select entire column
Ctrl-click (or Shift-click) to select multiple columns '); 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:
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 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...
Uitable cell colors A few Java-based customizations can transform a plain-looking data table into a lively colored one. ...
Matlab and the Event Dispatch Thread (EDT) The Java Swing Event Dispatch Thread (EDT) is very important for Matlab GUI timings. This article explains the potential pitfalls and their avoidance using undocumented Matlab functionality....
Tab panels – uitab and relatives This article describes several undocumented Matlab functions that support tab-panels...

Uitab colors, icons and images

Yair Altman — Wed, 10 Nov 2010 18:00:01 +0000

A few months ago I published a post about Matlab’s semi-documented tab-panel functionality, where I promised a follow-up article on tab customizations. A reader of this blog asked a related question earlier today, so I decided it’s about time I fulfilled this promise.
As with most Matlab controls, the underlying Java component enables far greater customization than possible using plain Matlab. Today I will show three specific customizations. We start with a basic tab group, and get the underlying Java component:
% Prevent an annoying warning msg warning off MATLAB:uitabgroup:OldVersion % Prepare a tab-group consisting of two tabs hTabGroup = uitabgroup; drawnow; tab1 = uitab(hTabGroup, 'title','Panel 1'); a = axes('parent', tab1); surf(peaks); tab2 = uitab(hTabGroup, 'title','Panel 2'); uicontrol(tab2, 'String','Close', 'Callback','close(gcbf)'); % Get the underlying Java reference (use hidden property) jTabGroup = getappdata(handle(hTabGroup),'JTabbedPane');
Foreground & background tab colors
We can set the tab font color using setForeground() and setForegroundAt(), or via HTML. Note that setForegroundAt() overrides anything set by setForeground(). Also remember that Java uses 0-based indexing so tab #1 is actually the second tab:
% Equivalent manners to set a red tab foreground: jTabGroup.setForegroundAt(1,java.awt.Color(1.0,0,0)); % tab #1 jTabGroup.setTitleAt(1,'Panel 2'); jTabGroup.setForeground(java.awt.Color.red);
Unfortunately, the corresponding setBackgroundAt(tabIndex,color) method has no visible effect, and the Matlab-extended tabs keep their white/gray backgrounds. A similar attempt to modify the tab’s BackgroundColor property fails, since Matlab made this property unmodifiable (=’none’). A simple solution is to use a CSS background:
% Equivalent manners to set a yellow tab background: jTabGroup.setTitleAt(0,'
Panel 1'); jTabGroup.setTitleAt(0,'
Panel 1');
uitabgroup with non-default forground and background tab colors and fonts
We can set the foreground text color using the CSS color directive. Similarly, we can also set a background gradient image for the tabs, using the CSS background-image directive. Which leads us to our next customization:
Icon images
Icons and sub-components can be added to the tabs. Unfortunately, for some reason that I do not fully understand, jTabGroup.setIconAt() has no apparent effect. The solution is to set our own custom control as the requested tab, and add our icon (or other customizations) to it. Here is a simple example:
% Add an icon to tab #1 (=second tab) icon = javax.swing.ImageIcon('C:\Yair\save.gif'); jLabel = javax.swing.JLabel('Tab #2'); jLabel.setIcon(icon); jTabGroup.setTabComponentAt(1,jLabel); % Tab #1 = second tab % Note: icon is automatically grayed when label is disabled jLabel.setEnabled(false); jTabGroup.setEnabledAt(1,false); % disable only tab #1

tab with a custom icon (enabled & disabled)
Close buttons
Now let’s try a more complex example, of adding a close (‘x’) button to one of the tabs. Generalizing this code snippet is left as an exercise to the reader:
% First let's load the close icon jarFile = fullfile(matlabroot,'/java/jar/mwt.jar'); iconsFolder = '/com/mathworks/mwt/resources/'; iconURI = ['jar:file:/' jarFile '!' iconsFolder 'closebox.gif']; icon = javax.swing.ImageIcon(java.net.URL(iconURI)); % Now let's prepare the close button: icon, size and callback jCloseButton = handle(javax.swing.JButton,'CallbackProperties'); jCloseButton.setIcon(icon); jCloseButton.setPreferredSize(java.awt.Dimension(15,15)); jCloseButton.setMaximumSize(java.awt.Dimension(15,15)); jCloseButton.setSize(java.awt.Dimension(15,15)); set(jCloseButton, 'ActionPerformedCallback',@(h,e)delete(tab2)); % Now let's prepare a tab panel with our label and close button jPanel = javax.swing.JPanel; % default layout = FlowLayout set(jPanel.getLayout, 'Hgap',0, 'Vgap',0); % default gap = 5px jLabel = javax.swing.JLabel('Tab #2'); jPanel.add(jLabel); jPanel.add(jCloseButton); % Now attach this tab panel as the tab-group's 2nd component jTabGroup.setTabComponentAt(1,jPanel); % Tab #1 = second tab
tab with an attached close button
Next week’s article will conclude the series on Matlab’s uitab. Any particular customization you are interested in? Please do post a comment.

Related posts:
Uitab customizations This article shows several customizations that can be done to Matlab's undocumented tab-panels functionality...
Tab panels – uitab and relatives This article describes several undocumented Matlab functions that support tab-panels...
Setting system tray icons System-tray icons can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....
Uitable cell colors A few Java-based customizations can transform a plain-looking data table into a lively colored one. ...

Customizing uitree nodes – part 1

Yair Altman — Wed, 25 Aug 2010 18:00:20 +0000

In my previous posts, I introduced the semi-documented uitree function that enables displaying data in a hierarchical (tree) control in Matlab GUI, and showed how it can be customized. Today, I will continue by describing how specific uitree nodes can be customized.
To start the discussion, let’s re-create last week’s simple uitree:
% Fruits fruits = uitreenode('v0', 'Fruits', 'Fruits', [], false); fruits.add(uitreenode('v0', 'Apple', 'Apple', [], true)); fruits.add(uitreenode('v0', 'Pear', 'Pear', [], true)); fruits.add(uitreenode('v0', 'Banana', 'Banana', [], true)); fruits.add(uitreenode('v0', 'Orange', 'Orange', [], true)); % Vegetables veggies = uitreenode('v0', 'Veggies', 'Vegetables', [], false); veggies.add(uitreenode('v0', 'Potato', 'Potato', [], true)); veggies.add(uitreenode('v0', 'Tomato', 'Tomato', [], true)); veggies.add(uitreenode('v0', 'Carrot', 'Carrot', [], true)); % Root node root = uitreenode('v0', 'Food', 'Food', [], false); root.add(veggies); root.add(fruits); % Tree figure('pos',[300,300,150,150]); mtree = uitree('v0', 'Root', root);

User-created tree
Labels
Node labels (descriptions) can be set using their Name property (the second uitreenode data argument). Note that the horizontal space allotted for displaying the node name will not change until the node is collapsed or expanded. So, if the new name requires more than the existing space, it will be displayed as something like “abc…”, until the node is expanded or collapsed.
Node names share the same HTML support feature as all Java Swing labels. Therefore, we can specify font size/face/color, bold, italic, underline, super-/sub-script etc.:
txt1 = 'abra'; txt2 = '^kadabra'; node.setName([txt1,txt2]);
HTML-enriched tree nodes
Icons
Tree-node icons can be specified during node creation, as the third data argument to uitreenode, which accepts an icon-path (a string):
iconPath = fullfile(matlabroot,'/toolbox/matlab/icons/greenarrowicon.gif'); node = uitreenode('v0',value,name,iconPath,isLeaf);
Tree node icons can also be created or modified programmatically in run-time, using Matlab’s im2java function. Icons can also be loaded from existing files as follows (real-life programs should check and possibly update jImage’s size to 16 pixels, before setting the node icon, otherwise the icon might get badly cropped; also note the tree-refreshing action):
jImage = java.awt.Toolkit.getDefaultToolkit.createImage(iconPath); veggies.setIcon(jImage); veggies.setIcon(im2java(imread(iconPath))); % an alternative % refresh the veggies node (and all its children) mtree.reloadNode(veggies);
Setting node icon
Behavior
Nodes can be modified from leaf (non-expandable) to parent behavior (=expandable) by setting their LeafNode property (a related property is AllowsChildren):
set(node,'LeafNode',false); % =expandable node.setLeafNode(0); % an alternative
One of the questions I was asked was how to “disable” a specific tree node. One way would be to modify the tree’s ExpandFcn callback. Another way is to use a combination of HTML rendering and the node’s AllowsChildren property:
label = char(veggies.getName); veggies.setName(['' label]); veggies.setAllowsChildren(false); t.reloadNode(veggies);
Disabled node
Another possible behavioral customization is adding a context-menu to a uitree. We can set node-specific tooltips using similar means.
Answering a reader’s request from last week, tree nodes icons can be used to present checkboxes, radio buttons and other similar node-specific controls. This can actually be done in several ways, that will be explored in next week’s article.
There are numerous other possible customizations – if readers are interested, perhaps I will describe some of them in future articles. If you have any special request, please post a comment below.

Related posts:
Customizing uitree nodes – part 2 This article shows how Matlab GUI tree nodes can be customized with checkboxes and similar controls...
Customizing uitree This article describes how to customize Matlab GUI tree controls created using the undocumented uitree function...
uitree This article describes the undocumented Matlab uitree function, which displays data in a GUI tree component...
An interesting uitree utility ExploreStruct is a utility that shows how custom uitrees can be integrated in Matlab GUI...

Syntax highlighted labels & panels

Yair Altman — Wed, 14 Jul 2010 16:02:26 +0000

A few weeks ago, a reader of my article about rich Matlab editbox contents asked whether it is possible to display syntax-highlighted contents, i.e. contents whose color changes based on its underlying text, often called syntax hilite in affection. I gave a very specific answer in a reply comment, which I expand in today’s full-length article.
Matlab has two built-in Java classes that can present syntax-highlighted text: SyntaxTextLabel presents single-line labels, while SyntaxTextPane presents a multi-line editor pane. Both of these classes support C, HTML/XML, Java and Matlab syntax highlighting, as well as standard plaint-text. Some related JIDE classes are also described.
SyntaxTextLabel
SyntaxTextLabel is used to display a syntax-highlighted single-line text label according to the specified programming language: C_STYLE, HTML_STYLE, JAVA_STYLE, PLAIN_STYLE and of course M_STYLE for Matlab code:
str = 'for id=1:3, set(h(id),''string'',num2str(id)); end % Matlab code'; codeType = com.mathworks.widgets.SyntaxTextLabel.M_STYLE; jCodeLabel = com.mathworks.widgets.SyntaxTextLabel(str,codeType) [jhLabel,hContainer] = javacomponent(jCodeLabel,[10,10,300,20],gcf);
SyntaxTextLabels (different code styles)
StyledLabel
More flexibility in the displayed label styles can be achieved with HTML/CSS, and the bundled JIDE class com.jidesoft.swing.StyledLabel provides even more flexibility:
import java.awt.* import com.jidesoft.swing.* str = 'Mixed Underlined Strikethrough Super and Subscript combo Styles'; com.mathworks.mwswing.MJUtilities.initJIDE; jStyledLabel = StyledLabel(str); styles = [StyleRange(0,5, Font.BOLD, Color.BLUE), ... StyleRange(6,10, Font.PLAIN,StyleRange.STYLE_UNDERLINED),... StyleRange(17,13,Font.PLAIN, Color.RED, ... StyleRange.STYLE_STRIKE_THROUGH), ... StyleRange(31,5, Font.PLAIN, Color.BLUE, ... StyleRange.STYLE_SUPERSCRIPT), ... StyleRange(37,3, Font.ITALIC, Color.BLACK), ... StyleRange(41,9, Font.PLAIN, Color.BLUE, ... StyleRange.STYLE_SUBSCRIPT), ... StyleRange(51,5, Font.PLAIN, StyleRange.STYLE_WAVED + ... StyleRange.STYLE_STRIKE_THROUGH)]; jStyledLabel.setStyleRanges(styles); [jhLabel,hContainer] = javacomponent(jStyledLabel,[10,10,300,20],gcf);
JIDE StyledLabel (different font styles)
StyledLabels have subclasses that can be used to present styled text in tables, trees or lists. JIDE also provides the convenient StyledLabelBuilder, which enables easy multi-style text construction.
Finally, JIDE provides the ClickThroughStyledLabel, a StyledLabel extension that allows setting a target component, so that mouse clicks on the label will actually trigger the target component. This can be useful in forms where components have adjacent descriptive labels.
SyntaxTextPane
Multi-line syntax-highlighted code can be displayed with Matlab’s SyntaxTextPane class. SyntaxTextPane uses MIME types rather than styles for syntax-highlighting, but the end-result appears similar:
jCodePane = com.mathworks.widgets.SyntaxTextPane; codeType = jCodePane.M_MIME_TYPE; % ='text/m-MATLAB' jCodePane.setContentType(codeType) str = ['% create a file for output\n' ... '!touch testFile.txt\n' ... 'fid = fopen(''testFile.txt'', ''w'');\n' ... 'for i=1:10\n' ... ' % Unterminated string:\n' ... ' fprintf(fid,''%6.2f \\n, i);\n' ... 'end']; str = sprintf(strrep(str,'%','%%')); jCodePane.setText(str) jScrollPane = com.mathworks.mwswing.MJScrollPane(jCodePane); [jhPanel,hContainer] = javacomponent(jScrollPane,[10,10,300,100],gcf);
SyntaxTextPane panel (Matlab MIME type)
The nice thing about SyntaxTextPane is that it syntax-highlights on-the-fly as you type or edit in the SyntaxTextPane (assuming you have not disabled editing with the setEditable(flag) method). This is exactly the behavior we have come to expect in the full-blown Matlab editor, and can now be embedded as a simple panel within our GUI.
Despite its misleadingly-simple look, SyntaxTextPane actually has most capabilities of the full-blown editor, not just syntax highlighting. This includes multiple undo/redo actions; smart indentation/commenting; automatic indication of corresponding block elements (if-end, for-end, etc. – also known as delimiter matching); search/replace, drag-and-drop and cut-copy-paste support; and many more.
Interested readers can use the uiinspect and checkClass utilities to explore the full capabilities offered by SyntaxTextPane. In this respect it would be helpful to also look at its super-class (SyntaxTextPaneBase) and the related SyntaxTextPaneUtilities class.
Summary
These Java classes are examples of built-in classes that can be used in Matlab applications, enabling a much richer GUI experience than possible using the standard (documented/supported) Matlab widgets.
As I have shown above, using these classes is extremely easy, and requires absolutely no Java knowledge. On the flip side, these internal Matlab classes may easily break in any future Matlab release, so be extra careful when deciding to use them. Future articles in this website will describe other similarly-useful built-in classes.
Have you found any other useful built-in Matlab class? If so, please post a comment.

Related posts:
Customizing Matlab labels Matlab's text uicontrol is not very customizable, and does not support HTML or Tex formatting. This article shows how to display HTML labels in Matlab and some undocumented customizations...
Tab panels – uitab and relatives This article describes several undocumented Matlab functions that support tab-panels...
Uitable sorting Matlab's uitables can be sortable using simple undocumented features...
Rich Matlab editbox contents The Matlab editbox uicontrol does not handle HTML contents as do other uicontrols. In this article I show how this limitation can be removed....

GUI integrated HTML panel

Yair Altman — Tue, 15 Dec 2009 12:30:16 +0000

Last week, I explained how a browser control can be integrated in Matlab GUI applications. Sometimes we only need to display simple HTML, for which a full browser seems like overkill. Moreover, we may wish to edit the displayed contents, which cannot be done using the browser control. The solution is to use a standard Java Swing JEditorPane control, which is an editable HTML-aware control.
Oddly enough, it was only yesterday that Mikhail, a known Matlab Java specialist on the CSSM newsgroup, posted an example for this as answer to a question on the StackOverflow forum (slightly edited for clarity):
mytext = [''...''...''...'

Month Savings

January $100

']; % Create a figure with a scrollable JEditorPane hfig = figure(); je = javax.swing.JEditorPane('text/html', mytext); jp = javax.swing.JScrollPane(je); [hcomponent, hcontainer] = javacomponent(jp, [], hfig); set(hcontainer, 'units', 'normalized', 'position', [0,0,1,1]); % Turn anti-aliasing on (R2006a, Java 5.0) java.lang.System.setProperty('awt.useSystemAAFontSettings', 'on'); je.setFont(java.awt.Font('Arial', java.awt.Font.PLAIN, 13)); je.putClientProperty(javax.swing.JEditorPane.HONOR_DISPLAY_PROPERTIES, true); % This only works on Java 1.5 (Matlab R14SP2 to R2007a): je.putClientProperty(com.sun.java.swing.SwingUtilities2.AA_TEXT_PROPERTY_KEY, true);
Editable HTML-aware JEditorPane
Mikhail’s code included setting SwingUtilities2′s AA_TEXT_PROPERTY_KEY property for anti-aliased fonts. Unfortunately, SwingUtilities2 was an unsupported and undocumented internal class in Java 1.5 (undocumented/unsupported by Sun, not MathWorks for a change…) and completely disappeared in Java 1.6 (which is bundled with Matlab R2007b onward). Therefore, SwingUtilities2 and its antialias property can only be used on Matlab releases R14SP2 (7.0.4) through R2007a (7.4) – other Matlab versions will throw an error.
Alternately, use JIDE’s AA_TEXT_PROPERTY_KEY (JIDE is bundled with Matlab and this is supported even on new Matlab releases – I will present JIDE in future articles).
property = com.jidesoft.swing.JideSwingUtilities.AA_TEXT_PROPERTY_KEY; je.putClientProperty(property, true);
Or, simply add the following switch to your java.opt file:
-Dswing.aatext=true
With this switch, you no longer need to set anti-aliasing separately for each component. It is entirely harmless to set this switch even on Matlab/Java versions that do not support it (the switch is simply ignored in these cases).
Note that while JEditorPane’s support for HTML is extensive, it is incomplete. It also does not contain a JavaScript engine or other web-related features we have come to expect in a browser. For the more complex stuff we can use the browser control as explained in last week’s article.
Matlab’s own multi-line editbox uicontrol uses JEditorPane (or actually its derived-class JTextPane) as an underlying component. This means that the simple-looking Matlab editbox is actually a powerful HTML-aware component. In order to use these hidden undocumented features we need the editbox’s underlying JTextPane handle. This is done using the FindJObj utility, which will be described in my next article. Following that, I will show how to customize Matlab’s dull-looking editbox into something much more powerful. Here’s a sample, to help you stay tuned:
HTML contents in a regular Matlab editbox

Related posts:
GUI integrated browser control A fully-capable browser component is included in Matlab and can easily be incorporated in regular Matlab GUI applications. This article shows how....
HTML support in Matlab uicomponents Matlab uicomponents support HTML and CSS, enabling colored items, superscript/subscript, fonts, bold/italic/underline and many other modifications...
Panel-level uicontrols Matlab's uipanel contains a hidden handle to the title label, which can be modified into a checkbox or radio-button control...
Customizing Matlab labels Matlab's text uicontrol is not very customizable, and does not support HTML or Tex formatting. This article shows how to display HTML labels in Matlab and some undocumented customizations...

GUI integrated browser control

Yair Altman — Wed, 09 Dec 2009 15:35:21 +0000

Last week, I described the built-in PopupPanel object, and showed how it can be used to present popup messages with HTML content and even entire webpages. I explained that PopupPanel uses an internal browser object to achieve this. In fact, Matlab’s browser object predates PopupPanel by many years and quite a few releases. This browser object can be used as a stand-alone component that we can easily embed in our Matlab GUI applications.
Here is a simple example in which a Matlab Listbox uicontrol is used to select the contents of an adjacent browser component:
% Create a blank figure window f=figure('Name','Browser GUI demo','Num','off','Units','norm'); % Add the browser object on the right jObject = com.mathworks.mlwidgets.html.HTMLBrowserPanel; [browser,container] = javacomponent(jObject, [], f); set(container, 'Units','norm', 'Pos',[0.3,0.05,0.65,0.9]); % Add the URLs listbox on the left urls = {'www.cnn.com','www.bbc.co.uk','myLocalwebpage.html',... 'www.Mathworks.com', 'UndocumentedMatlab.com'}; hListbox = uicontrol('style','listbox', 'string',urls, ... 'units','norm', 'pos',[0.05,0.05,0.2,0.9], ... 'userdata',browser); % Set the listbox's callback to update the browser contents cbStr=['strs = get(gcbo,''string''); ' ... 'url = strs{get(gcbo,''value'')};' ... 'browser = get(gcbo,''userdata''); ' ... 'msg=[''
Loading '' url '' - please wait''];'... 'browser.setHtmlText(msg); pause(0.1); drawnow;'... 'browser.setCurrentLocation(url);']; set(hListbox,'Callback',cbStr);
Browser object integrated in Matlab GUI
In this simple example, we can see how the Java browser object can easily be controlled by Matlab. Specifically, we use two modes of the browser: first we present an HTML message (‘Loading www.cnn.com – please wait‘) and then replacing this content with the actual webpage, if accessible. If the webpage is not accessible, an error message is displayed:
Browser message when webpage is missing
We can easily expand this simple example to display any HTML message or webpage, in a seamless integration within our GUI.
Now, who ever said that Matlab GUI looks static or boring???
In an unrelated note, I would like to extend good wishes to Ken Orr, who has left the Mathworks Desktop development team to join Apple a few days ago. You probably know Ken from his good work on the Desktop and the official Matlab Desktop blog. Hopefully, in his new position Ken will be able to influence Mac Java in a way that will reduce the numerous recurring issues that afflict Matlab Mac releases.

Related posts:
GUI integrated HTML panel Simple HTML can be presented in a Java component integrated in Matlab GUI, without requiring the heavy browser control....
Inactive Control Tooltips & Event Chaining Inactive Matlab uicontrols cannot normally display their tooltips. This article shows how to do this with a combination of undocumented Matlab and Java hacks....
Matlab-Java interface using a static control The switchyard function design pattern can be very useful when setting Matlab callbacks to Java GUI controls. This article explains why and how....
Customizing Matlab labels Matlab's text uicontrol is not very customizable, and does not support HTML or Tex formatting. This article shows how to display HTML labels in Matlab and some undocumented customizations...

Customizing help popup contents

Yair Altman — Mon, 30 Nov 2009 16:37:30 +0000

A few days ago, I was asked by a reader how to programmatically display the popup help window and customize it with arbitrary contents. This help window displays the doc-page associated with the current Command Window or Editor text.
Help popup
To programmatically display this help popup, a modeless MJDialog Java window, we need to run the following on Matlab releases that support these windows (R2007b onward):
jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance; jTextArea = jDesktop.getMainFrame.getFocusOwner; jClassName = 'com.mathworks.mlwidgets.help.HelpPopup'; jPosition = java.awt.Rectangle(0,0,400,300); helpTopic = 'surf'; javaMethodEDT('showHelp',jClassName,jTextArea,[],jPosition,helpTopic);
Where:
1) jPosition sets popup’s pixel size and position (X,Y,Width,Height). Remember that Java counts from the top down (contrary to Matlab) and is 0-based. Therefore, Rectangle(0,0,400,300) is a 400×300 window at the screen’s top-left corner.
2) helpTopic is the help topic of your choice (the output of the doc function). To display arbitrary text, you can create a simple .m file that only has a main help comment with your arbitrary text, which will be presented in the popup.
3) on R2011b, we could simplify the above code snippet with the following replacement:
helpUtils.errorDocCallback('surf')
4) on R2007b, we need to use the equivalent but more cumbersome awtinvoke function instead of javaMethodEDT:
jniSig = 'showHelp(Ljavax.swing.JComponent;Lcom.mathworks.mwswing.binding.KeyStrokeList;Ljava.awt.Rectangle;Ljava.lang.String;)'; awtinvoke(jClassName,jniSig,jTextArea,[],jPosition,helpTopic);
For example, if we had a sample.m file with the following contents:
function sample % The text in this function's main comment will be presented in the % help popup. Hyperlinks % are supported, but unfortunately not full-fledged HTML.
Then we would get this result:
User-created arbitrary text
Well, it does get the message across, but looks rather dull. It would be nice if this could be improved to provide full-scale HTML support. Unfortunately, Matlab documentation says this cannot be done:
The doc function is intended only for reference pages supplied by The MathWorks. The exception is the doc UserCreatedClassName syntax. doc does not display HTML files you create yourself. To display HTML files for functions you create, use the web function.
Luckily for us, there is an undocumented back-door to do this: The idea is to search all visible Java windows for the HelpPopup, then move down its component hierarchy to the internal web browser (a com.mathworks.mlwidgets.html.HTMLBrowserPanel object), then update the content with our arbitrary HTML or a webpage URL:
% Find the Help popup window jWindows = com.mathworks.mwswing.MJDialog.getWindows; jPopup = []; for idx=1 : length(jWindows) if strcmp(get(jWindows(idx),'Name'),'HelpPopup') if jWindows(idx).isVisible jPopup = jWindows(idx); break; end end end % Update the popup with selected HTML html=['Full HTML support: bold, '... 'italic, hyperlink, ' ... 'symbols (∀β) etc.']; if ~isempty(jPopup) browser = jPopup.getContentPane.getComponent(1).getComponent(0); browser.setHtmlText(html); end
Help popup with HTML content
We can display HTML content and highlight certain keywords using the setHtmlTextAndHighlightKeywords method:
browser.setHtmlTextAndHighlightKeywords(html,{'support','symbols'});
HTML content with highlighting
Instead of specifying the HTML content, we can point this browser to a web-page URL (no need for the “http://” prefix):
browser.setCurrentLocation('UndocumentedMatlab.com');
Help popup browser displaying a URL web-page
The HTMLBrowserPanel includes a full-fledged browser (which may be different across Matlab releases/platforms). This browser supports HTML, CSS, JavaScript and other web-rendering aspect that we would expect from a modern browser. Being a full-fledged browser, we have some control over its appearance e.g., addAddressBox(1,1) and other internal methods. Interested readers may use my UiInspect utility to explore these options.
As a technical note, HTMLBrowserPanel is actually only a JPanel that contains the actual Mozilla browser. Luckily for us, MathWorks extended this panel class with the useful methods presented above, that forward the user requests to the actual internal browser. This way, we don’t need to get the actual browser reference (although you can, of course).
I have created a utility function that encapsulates all the above, and enables display of Matlab doc pages, as well as arbitrary text, HTML or webpages. This popupPanel utility can now be downloaded from the Matlab File Exchange.
An interesting exercise left for the readers, is adapting the main heavy-weight documentation window to display user-created HTML help pages. This can be achieved by means very similar to those shown in this article.
Of course, as the official documentation states, we could always use the fully-supported web function to display our HTML or URLs. Under the hood, web uses exactly the same HTMLBrowserPanel as out HelpPopup. The benefit of using the methods shown here is the use of a lightweight undecorated popup window which looks well-integrated with the existing Matlab help.
Please note that the HelpPopup implementation might change without warning between Matlab releases. An entirely separate, although related, implementation is Matlab’s built-in context-sensitive help system, which I described some months ago. That implementation did not rely on Java and worked on much earlier Matlab releases.

Related posts:
Setting system tray popup messages System-tray icons and messages can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....
Customizing Workspace context-menu Matlab's Workspace table context-menu can be configured with user-defined actions - this article explains how....
Rich Matlab editbox contents The Matlab editbox uicontrol does not handle HTML contents as do other uicontrols. In this article I show how this limitation can be removed....
Customizing Matlab’s Workspace table The Matlab Desktop's Workspace pane table can be customized, as described here...