Invoking menu item callbacks

As noted above, a figure window’s menu items can be directly accessed. Once we access a menu item’s handle, we can extract its Callback property and directly invoke it (for example, using the semi-documented hgfeval function). Note that menu callbacks are kept in Callback, while toolbar callbacks are kept in ClickedCallback.

Menu callbacks generally use internal semi-documented functions (i.e., having a readable help section but no doc, online help, or official support), which are part of Matlab’s uitools folder. These functions are specific to each top-level menu tree: filemenufcn, editmenufcn, viewmenufcn, insertmenufcn, toolsmenufcn, desktopmenufcn, winmenu, and helpmenufcn implement the figure’s eight respective top-level menu trees’ callbacks. These functions accept an optional figure handle (otherwise, gcbf is assumed), followed by a string specifying the specific menu item whose action needs to be run. webmenufcn implements the Help menu’s Web Resources sub-menu callbacks in a similar manner.

Use of these functions makes it easy to invoke a menu action directly from our Matlab code: instead of accessing the relevant menu item and invoking its Callback, we simply find out the menu item string in advance and use it directly. For example,

filemenufcn FileClose;
editmenufcn(hFig,'EditPaste');

uimenufcn is a related fully-undocumented (built-in) function, available since Matlab R11 (late 1990s). It accepts a figure handle (or the zero [0] handle to indicate the desktop) and action name. For example, the fully-documented commandwindow function uses the following code to bring the Command Window into focus:

uimenufcn(0, 'WindowCommandWindow');

Customizing menus via uitools

makemenu is another semi-documented uitool function that enables easy creation of hierarchical menu trees with separators and accelerators. It is a simple and effective wrapper for uimenu. makemenu is a useful function that has been made obsolete (grandfathered) without any known replacement.

makemenu accepts four parameters: a figure handle, a char matrix of labels (‘>’ indicating sub item, ‘>>’ indicating sub-sub items etc.; ‘&’ indicating keyboard shortcut; ‘^x’ indicating an accelerator key; ‘-’ indicating a separator line), a char matrix of callbacks, and an optional char matrix of tags (empty by default). makemenu makes use of another semi-documented grandfathered function, menulabel, to parse the specified label components. makemenu returns an array of handles of the created uimenu items:

labels = str2mat('&File', ...    % File top menu
           '>&New^n', ...           % File=>New
           '>&Open', ...            % File=>Open
           '>>Open &document^d', ...    % File=>Open=>doc
           '>>Open &graph^g', ...       % File=>Open=>graph
           '>-------', ...          % File=>separator line
           '>&Save^s', ...          % File=>Save
           '&Edit', ...		% Edit top menu
           '&View', ...		% View top menu
           '>&Axis^a', ...          % View=>Axis
           '>&Selection region^r'); % View=>Selection
calls = str2mat('', ...		% no action: File top menu
           'disp(''New'')', ...
           '', ...			% no action: Open sub-menu
           'disp(''Open doc'')', ...
           'disp(''Open graph'')', ...
           '', ...			% no action: Separator
           'disp(''Save'')', ...
           '', ...			% no action: Edit top menu
           '', ...			% no action: View top menu
           'disp(''View axis'')', ...
           'disp(''View selection region'')');
handles = makemenu(hFig, labels, calls);
set(hFig,'menuBar','none');

A simple figure menu

Customizing menus via HTML

Since menu items share the same HTML/CSS support feature as all Java Swing labels, we can specify font size/face/color, bold, italic, underline, superscript/subscript, and practically any HTML formatting.

Note that some features, such as the font or foreground/background colors, have specific properties that we can set using the Java handle, instead of using HTML. The benefit of using HTML is that it enables setting all the formatting in a single property. HTML does not require using Java – just pure Matlab (see the following example).

Multi-line menu items can easily be done with HTML: simply include a <br> element in the label – the menu item will split into two lines and automatically resize vertically when displayed:

txt1 = '<html><b><u><i>Save</i></u>';
txt2 = '<font color="red"><sup>this file</sup></font></b></html>';
txt3 = '<br />this file as...';
set(findall(hFig,'tag','figMenuFileSave'),   'Label',[txt1,txt2]);
set(findall(hFig,'tag','figMenuFileSaveAs'), 'Label',[txt1,txt3]);

A multi-line HTML-rendered menu item

set(hMenuItem, 'Label',['<html>&2: C:\My Documents\doc.txt<br />'
   '<font size="-1" face="Courier New" color="red">&nbsp;&nbsp; '
   'Date: 15-Jun-2011 13:23:45<br />&nbsp;&nbsp; Size: 123 KB</font></html>']);

HTML-rendered menu items

Much more complex customizations can be achieved using Java. So stay tuned to part 2 of this mini-series…

Note: Menu customization is explored in depth in section 4.6 of my book.

1. Customizing menu items part 2 Matlab menu items can be customized in a variety of useful ways using their underlying Java object. ...
2. Customizing menu items part 3 Matlab menu items can easily display custom icons, using just a tiny bit of Java magic powder. ...
3. Customizing uitree nodes – part 1 This article describes how to customize specific nodes of Matlab GUI tree controls created using the undocumented uitree function...
4. Customizing uitree nodes – part 2 This article shows how Matlab GUI tree nodes can be customized with checkboxes and similar controls...

Figure visibility

Java components can only be placed onscreen when their containing Matlab figure has been made visible. This means that calls to javacomponent cannot be placed at the GUIDE-created *_OpeningFcn() function, because that function is invoked before the figure window is made visible.

Of course, we can always force the figure to become visible by setting the figure’s Visible property to 'on' in this function, before calling our javacomponents. But IMHO, a better option would be to simply place the javacomponents in the corresponding GUIDE-created *_OutputFcn() function, which is invoked after the figure window is made visible.

Auto-hiding with parent container

Java components are not automatically hidden with their ancestor container panel. This is also the root cause of the failure of Java components to disappear when switching tabs in a uitab.

One simple workaround for this that I often use is to link the Visible properties of the javacomponent container and the parent container:

jButton = javax.swing.JButton('click me!');
[jhButton, hContainer] = javacomponent(jButton, [100,100,60,30], hParent);
setappdata(hParent, 'linked_props__', linkprop([hParent,hContainer],'Visible'));

This has indeed been fixed in R2010b. If you ask me, this should have been standard behavior of javacomponent since the very beginning…

Although there is no need for the workaround in R2010b onward, I usually keep the workaround because it doesn’t hurt and enables backward compatibility for users who may have an older Matlab release.

Possible parent container types

javacomponent accepts parent handles that are figures, toolbars, uipanels, or uicontainers (some of these are not documented as possible parents in some Matlab releases, but they are). Since R2008a, parents of type uisplittool and uitogglesplittool can also be used. Unfortunately, frames are not uicontainers and, therefore, cannot be used as javacomponent parents.

Note: Due to a bug in R2007a, javacomponents cannot be added to uicontainers, since javacomponent.m checks if isa(hParent,'uicontainer') (and similarly for 'uiflowcontainer', 'uigridcontainer'), instead of isa(hParent,'hg.uicontainer') (and similarly for the others). If we modify javacomponent.m accordingly (add “hg.” in lines 98-100), this bug will be fixed. Since R2007b, isa(…,'hg.uicontainer') is equivalent to isa(…,'uicontainer'), so this fix is unnecessary.

Input parameters

Unlike many other Matlab functions, javacomponent does not accept optional parameter-value (P-V) pairs. If we want to customize the appearance of the Java component, it is better to create it , customize it, and only then to present it onscreen using javacomponent. If we first present the component and then customize it, there might be all sorts of undesirable flicker effects while the component is changing its properties.

One of the parameters that unfortunately cannot be customized before calling javacomponent is the component’s position onscreen. javacomponent only accepts a position vector in pixel units. To modify the component to use normalized units, we need to modify the container’s properties:

jButton = javax.swing.JButton('click me!');
[jhButton, hContainer] = javacomponent(jButton, [100,100,60,30], gcf);
set(hContainer, 'Units','norm');

Similarly, we can set the container’s UserData and ApplicationData only after the call to javacomponent.

Background color

The default background color of javacomponents is a slightly different shade of gray than the default uicontrol background color. Please refer to my recent article for a detailed discussion of this issue.

Vertical alignment

Java components are slightly mis-aligned vertically with combo-box (Style=’popup’) uicontrols, even when positioned using the same Y position. This is actually due to an apparent bug in Matlab’s implementation of the combo-box uicontrol, and not in the Java component’s: Apparently, the Matlab control does not obey its specified height and uses some other default height.

If we place javacomponents side-by-side with a regular Matlab popup uicontrols and give them all the same Y position, we can see this mis-alignment. It is only a few pixels, but the effect is visible and disturbing. To fix it, we need to add a small offset to the javacomponent‘s container’s Position property to make both the initial Y position slightly lower, and the height value slightly higher than the values for the corresponding Matlab combo-box control.

Callbacks

Unlike Matlab uicontrol callbacks, Java callbacks are activated even when the affected value does not change. Therefore, setting a value in the component’s callback could well cause an infinite loop of invoked callbacks.

Matlab programmers often use the practice of modifying component value within the callback function, as a means of fixing user-entered values to be within a certain data range, or in order to format the displayed value. This is relatively harmless in Matlab (if done correctly) since updating a Matlab uicontrol‘s value to the current value does not retrigger the callback. But since this is not the case with Java callbacks, users should beware not to use the same practice there. In cases where this cannot be avoided, users should at least implement some sort of callback re-entrancy prevention logic.

EDT

Java components typically need to use the independent Java Event processing Thread (EDT). EDT is very important for Matlab GUI, as explained in this article. Failure to use EDT properly in Matlab can lead to unexpected GUI behavior and even Matlab hangs or crashes.

If the javacomponent function is called in a very specific syntax format where the first input arg is a string (the name of the Java class to be created), then the newly-created component is placed on the EDT. However, this is not the normal manner in which javacomponent is used: A much more typical use-case is where javacomponent is passed a reference handle to a previously-created Java component. In such cases, it is the user’s responsibility to place the component on the EDT. Until R2008a this should be done using the awtcreate function; since R2008b, we can use the much simpler javaObjectEDT function (javaObjectEDT actually existed since R2008a, but was buggy on that release so I suggest using it only starting in R2008b; it became documented starting in R2009a). In fact, modern javacomponent saves us the trouble, by automatically using javaObjectEDT to auto-delegate the component onto the EDT, even if we happen to have created it on the MT.

The paragraph above may lead us to believe that we only need to worry about EDT in R2008a and earlier. Unfortunately, this is not the case. Modern GUI requires using many sub-components, that are attached to their main component (e.g., CellRenderers and CellEditors). javacomponent only bothers to place the main component on the EDT – not any of the sub-components. We need to handle these separately. Liberally auto-delegating components to the EDT seems like a safe and painless habit to have.

1. The javacomponent function Matlab's built-in javacomponent function can be used to display Java components in Matlab application - this article details its usages and limitations...
2. Javacomponent background color This article explains how to align Java component background color with a Matlab color....
3. 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....
4. Customizing uitree nodes – part 2 This article shows how Matlab GUI tree nodes can be customized with checkboxes and similar controls...

This is a great question, recently asked by a reader of this blog, so I wanted to expand on it in next week’s article. Before specifying the different reasons, let’s map the nature of undocumented aspects that we find in Matlab.

The term undocumented/unsupported (as opposed to mis-documentated or deprecated) actually refers to quite a large number of different types.
In the following list, the hyperlinks on the list-item titles lead to a list of corresponding articles on this website:

• Undocumented functions
  Matlab functions which appears nowhere in the documentation, are usually built-in functions (do not have an m-file) and can only be inferred from online CSSM posts or usage within one of the Matlab m-functions installed with Matlab (the latter being the usual case). None of these functions is officially supported by MathWorks. MEX is an important source for such functions.

• Semi-documented functions
  Matlab functionality which exists in Matlab m-functions installed with Matlab, but have their main comment separated from the H1 comment line, thereby hiding it from normal view (via Matlab’s help function). The H1 comment line itself is simply a standard warning that this function is not officially supported and may change in some future version. To see the actual help comment, simply edit the function (using Matlab’s edit function or any text editor) and place a comment sign (%) at the empty line between the H1 comment and the actual help section. The entire help section will then onward be visible via the help function:

          function [tree, container] = uitree(varargin)
          % WARNING: This feature is not supported in MATLAB
          % and the API and functionality may change in a future release.
  fix =>  %
          % UITREE creates a uitree component with hierarchical data in a figure window.
          %   UITREE creates an empty uitree object with default property values in
          %   a figure window.
          %...

  These functions are not documented in the full documentation (via Matlab’s doc function, or online). The odd thing is that some of these functions may appear in the category help output (for example, help(‘uitools’)), and in some cases may even have a fully-visible help section (e.g., help(‘setptr’)), but do not have any online help documentation (docsearch(‘setptr’) fails, and doc(‘setptr’) simply displays the readable help text).

  All these functions are officially unsupported by MathWorks, even when having a readable help section. The rule of thumb appears to be that a Matlab function is supported only if it has online documentation. Note, however, that in some rare cases a documentation discrepancy may be due to a MathWorks documentation error, not to unsupportability…

• Helper functions
  Many fully-supported Matlab functions use helper functions that have a specific use in the main (documented) function(s). Often, these helper functions are tightly-coupled to their documented parents and are useless as stand-alone functions. But quite a few of them have quite useful stand-alone use, as I’ve already shown in some past articles.

• Undocumented features and properties
  Features of otherwise-documented Matlab functions, which appear nowhere in the official documentation. You guessed it – these are also not supported by MathWorks… Like undocumented functions, you can only infer such features by the occasional CSSM post or a reference somewhere in Matlab’s m-code.

• Semi-documented features
  Features of otherwise-documented Matlab functions, which are documented in a separate section beneath the main help section, and nowhere else (not in the full doc not the online documentation). If you did not know in advance that these features existed, you could only learn of them by manually looking at Matlab’s m-files (which is what I do in most cases…).

• Undocumented properties
  Many Matlab objects have internal properties, which can be retrieved (via Matlab’s get function) and/or set (via the set function) programmatically. All these properties are fully documented. Many objects also possess hidden properties, some of which are very interesting and useful, but which are undocumented and (oh yes) unsupported. Like undocumented features, they can only be inferred from CSSM or existing code. In a recent article I described my getundoc utility, which lists these undocumented properties of specified objects.

• Internal Matlab classes
  Matlab uses a vast array of specialized Java classes to handle everything from algorithms to GUI. These classes are (of course) undocumented/unsupported. They can often be accessed directly from the Matlab Command Window or user m-files. GUI classes can be inferred by inspecting the figure frame’s Java components, and non-GUI classes can often be inferred from references in Matlab’s m-files.

• Matlab-Java integration
  Matlab’s GUI interface, as well as the Java-to-Matlab interface (JMI) is fully undocumented and unsupported. In addition to JMI, there are other mechanisms to run Matlab code from within Java (namely JMI, COM and DDE) – these are all unsupported and by-and-large undocumented.

• Matlab’s UDD mechanism
  UDD (Unified Data Definition?) is used extensively in Matlab as the internal object-oriented mechanism for describing object properties and functionalities. We can use UDD for a wide variety of uses. UDD was described in a series of articles here in early 2011.

Next week I will list the reasons that cause MathWorks to decide whether a particular feature or property should be documented or not.

1. Reasons for undocumented Matlab aspects There are many reasons for the numerous undocumented aspects in Matlab - this article explains them....
2. Undocumented cursorbar object Matlab's internal undocumented graphics.cursorbar object can be used to present dynamic data-tip cross-hairs...
3. uiundo – Matlab’s undocumented undo/redo manager The built-in uiundo function provides easy yet undocumented access to Matlab's powerful undo/redo functionality. This article explains its usage....
4. Undocumented XML functionality Matlab's built-in XML-processing functions have several undocumented features that can be used by Java-savvy users...

Using java components in Matlab is simple and easy, but there are a few annoying catches. One of these is the fact that the default Matlab figure background color ([0.8, 0.8, 0.8]) is a different shade of gray than the default uicontrol background color ([0.9255, 0.9137, 0.847]). javacomponents use the same background color as uicontrols.

hPanel = uipanel('units','pixe', 'pos',[30,30,200,100], 'title','Matlab uipanel');
jLabel = javax.swing.JLabel('Java Label');
[jhlabel,jContainer]=javacomponent(jLabel, [250,50,100,50], gcf);

Javacomponents use different default background color than figures

While Matlab users are familiar with updating Matlab colors, doing so with Java colors is a bit different. We have two basic ways to align the javacomponent background color with the figure’s: either change the figure’s Color property to the Java component’s bgcolor, or vice versa:

Changing the javacomponent‘s background color to the figure color

% Fix the Java component:
% Variant #1
bgcolor = get(gcf, 'Color');
jLabel.setBackground(java.awt.Color(bgcolor(1),bgcolor(2),bgcolor(3)));
 
% Variant #2
bgcolor = num2cell(get(gcf, 'Color'));
jLabel.setBackground(java.awt.Color(bgcolor{:}));
 
% Fix the Matlab panel uicontrol
set(hPanel, 'BackgroundColor', get(gcf,'Color'));

controls with fixed background colors

Changing the figure’s color to the javacomponent‘s background color

bgcolor = jLabel.getBackground.getComponents([]);
set(gcf, 'Color', bgcolor(1:3));

figure with modified color to match the controls

Look at the list of related posts below for other articles related to colors in Matlab.

1. Common javacomponent problems The javacomponent function is very useful for placing Java components on-screen, but has a few quirks. ...
2. The javacomponent function Matlab's built-in javacomponent function can be used to display Java components in Matlab application - this article details its usages and limitations...
3. Color selection components Matlab has several internal color-selection components that can easily be integrated in Matlab GUI...
4. cprintf – display formatted color text in the Command Window cprintf is a utility that utilized undocumented Matlab desktop functionalities to display color and underline-styled formatted text in the Command Window...

The bug

Try the following code snippet:

today = fix(now);
ts = timeseries(rand(1,201), datestr(today-200:today));
figure;
hPanel = uipanel('units','norm','pos',[.2,.2,.5,.5]);
hAxes = axes('Parent',hPanel, 'units','norm');
plot(ts, 'Parent',hAxes);

As you can see, the plot’s x-tick labels are all bunched together:

Timeseries plot bug (note x tick labels)

The workaround

I debugged the problem and traced it to line #317 of …\R2011b\toolbox\matlab\timeseries\@timeseries\plot.m (in the R2011b installation):

axpos = hgconvertunits(f,get(ax,'Position'),get(ax,'Units'),'normalized',f);

This line uses hgconvertunits to get the figure-based normalized units of the axes. hgconvertunits is an internal semi-documented helper function that convert a Handle-Graphics position vector in one set of units into another position vector in other units based on some other reference HG object. For example, it can tell me what the position of an internal control is in normalized figure units, even if the control is deeply nested within multiple panels. Which is exactly what it tries to do in this case.

Unfortunately, hgconvertunits apparently has a bug that causes it to return the parent-based normalized position values rather than the figure-based ones in this particular case. This causes the function to think that the axes is much bigger than it really is, and therefore it uses more x-tick labels than it should.

This hgconvertunits bug may very possibly affect numerous other Matlab functions that use this built-in function. The correct fix is to fix the hgconvertunits function. However, since this is an non-modifiable internal function, I found the following workaround for the timeseries plot only, by replacing the above line with the following:

axpos = hgconvertunits(f,getpixelposition(ax,f),'pixel','normalized',f);

Timeseries plot fix (note x tick labels)

Now the x-tick labels appear nicely, including during resize and zooming.

This problem occurs on R2011b. I was able to recreate the same problem and use the same fix back to R2010b. I do not know how far earlier the bug goes…

I reported the problem today (1-FEM0L7 for anyone interested). If I learn of a patch for hgconvertunits I will post an addendum on this page.

1. Plot LimInclude properties The plot objects' XLimInclude, YLimInclude, ZLimInclude, ALimInclude and CLimInclude properties are an important feature, that has both functional and performance implications....
2. Plot performance Undocumented inner plot mechanisms can be used to significantly improved plotting performance...
3. Controlling plot data-tips Data-tips are an extremely useful plotting tool that can easily be controlled programmatically....
4. Borderless button used for plot properties A borderless button can be used to add unobtrusive functionality to plot axes...

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>&nbsp;<b>Click</b> to sort up; <b>Shift-click</b> to sort down<br />&nbsp;...</html>');
 
else
   % Set the header tooltip (no sorting instructions...)
   jtable.getTableHeader.setToolTipText('<html>&nbsp;<b>Click</b> to select entire column<br />&nbsp;<b>Ctrl-click</b> (or <b>Shift-click</b>) to select multiple columns&nbsp;</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

1. 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...
2. Uitable cell colors A few Java-based customizations can transform a plain-looking data table into a lively colored one. ...
3. 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....
4. Tab panels – uitab and relatives This article describes several undocumented Matlab functions that support tab-panels...

We start by creating a simple Java button (a com.mathworks.mwswing.MJButton in this case) with the simple text ‘+’. The benefit of using com.mathworks.mwswing.MJButton rather than the standard javax.swing.JButton, which MJButton extends, is that MJButton added a FlyOverAppearance property to the standard JButton. This is a very handy feature that enables to present a border-less button, except upon mouse hove, in which case a shadow border is displayed. This is exactly the effect used to highlight toolbar buttons upon mouse hover. To emphasize the button’s action, we set a HAND_CURSOR cursor whenever the mouse hovers over the button.

This button is then displayed onscreen using the built-in semi-documented javacomponent function, at the axes origin position. We set the button’s callback property to uisetlineprops, which was adapted from a File Exchange submission by the same name:

axesPos = get(hAxes,'pos');
btLinePropsCbStr = ['uisetlineprops(findall(' num2str(hAxes,99) ',''type'',''line''))'];
btLinePropsPos = [axesPos(1:2)+0.003,0.03,0.03];
 
% Note: all the following code is just to have a specific cursor
% ^^^^ (HAND_CURSOR) when hovering over the button...
btLineprops = com.mathworks.mwswing.MJButton('+');
btLineprops.setBorder([]);
btLineprops.setBackground(java.awt.Color.white);
btLineprops.setCursor(java.awt.Cursor(java.awt.Cursor.HAND_CURSOR));
btLineprops.setFlyOverAppearance(true);
btLineprops.setToolTipText('Modify properties of plot lines');
[dummy,btContainer] = javacomponent(btLineprops,[0 0 1 1],hFig); %#ok
set(btLineprops, 'ActionPerformedCallback',btLinePropsCbStr);
set(btContainer, 'Units','Norm', 'Position',btLinePropsPos);

A borderless button used to modify plot properties

The benefit of using this simple trick is that the ‘+’ button is unobtrusive, and yet highly accessible. Of course, similar button can be used for a wide variety of callback functionalities, limited only by your imagination!

1. Plot LimInclude properties The plot objects' XLimInclude, YLimInclude, ZLimInclude, ALimInclude and CLimInclude properties are an important feature, that has both functional and performance implications....
2. 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...
3. Plot-type selection components Several built-in components enable programmatic plot-type selection in Matlab GUI - this article explains how...
4. UDD Properties UDD provides a very convenient way to add customizable properties to existing Matlab object handles...

I already wrote a series of articles on Matlab’s built-in semi-documented uitree (starting here), and I am on a constant lookout for additional interesting angles on uitree to post here. Brett Shoelson’s recent review of 2005′s Pick-of-the-Week utilities, provided me with such an opportunity.

One of 2005′s featured utilities, Structure Explorer by Hassan Lahdili, originally written using Microsoft’s TreeView ActiveX control, was apparently rewritten using Matlab’s Java-based uitree. This enables the utility to run on non-Windows platforms and have a more consistent look-and-feel with Matlab’s Java-based GUI:

Hassan Lahdili's Structure Explorer (click to enlarge)

Hassan’s ExploreStruct utility, in addition to being useful as-is, provides a very useful learning tool for uitree integration in Matlab GUI. This utility uses custom icons for different node types, custom callbacks for node expansion (NodeWillExpandCallback) and node selection (NodeSelectedCallback), and tree context (right-click) menu.

Unfortunately, it appears that the ExploreStruct utility has not been updated for compatibility with the latest Matlab releases. This causes numerous warning messages about not using ‘v0′ when calling uitree and uitreenode. I also had to add a call to drawnow following the uitree‘s creation in line #30, otherwise the tree did not appear (due to EDT issues). Also, I had to comment out line #83 (set(root,’UIContextMenu’, cmenu);) which caused an error (“There is no ‘UIContextMenu’ property in the ‘com.mathworks.hg.peer.UITreeNode’ class”) – the tree’s context-menu actually works even without this line.

Finally, I had to fix line #182 so that the node icons will appear correctly:

%pth = [matlabroot, '\work\exp_struct_icons\'];  %old
pth = [fileparts(which(mfilename)) '\exp_struct_icons\'];  %new

ExploreStruct is not documented and does not have extensive error-checking that I would like to see in real-world applications. But it is relatively easy to read and understand due to its use of internal functions and meaningful variable names.

Altogether, aside from the minor nuances mentioned above, I believe that readers who are interested in implementing custom tree objects in their Matlab GUI can learn a lot from this utility, and you can easily adapt its code for your own needs (or if you can’t, I am always willing to help).

1. Customizing uitree This article describes how to customize Matlab GUI tree controls created using the undocumented uitree function...
2. uitree This article describes the undocumented Matlab uitree function, which displays data in a GUI tree component...
3. Customizing uitree nodes – part 1 This article describes how to customize specific nodes of Matlab GUI tree controls created using the undocumented uitree function...
4. Customizing uitree nodes – part 2 This article shows how Matlab GUI tree nodes can be customized with checkboxes and similar controls...

handle2struct

Under the hood, hgsave uses the semi-documented built-in handle2struct function to convert the figure handle into a Matlab struct that is then stored with a simple save (the same function that saves MAT files) function call.

The fact that handle2struct is semi-documented means that the function is explained in a help comment (which can be seen via the help command), that is nonetheless not part of the official doc sections. It is an unsupported feature originally intended only for internal Matlab use (which of course doesn’t mean we can’t use it).

handle2struct merits a dedicated mention, since I can envision several use-cases for storing only a specific GUI handle (for example, a uipanel, a specific graph, or a set of GUI controls’ state). In this case, all we need to do is to call handle2struct with the requested parent handle, then save the returned structure. So simple, so powerful. handle2struct automatically returns all the non-default property information, recursively in all the handle’s children.

Note that features that are not properties of displayed handles (camera position, 3D rotation/pan/zoom states, annotations, axes-linking etc.) are not processed by handle2struct. For storing the states of these features, you need to use some specific handling – see the code within %matlabroot%\toolbox\matlab\graphics\private\hgsaveStructDbl.m for details. Basically, hgsaveStructDbl.m reads the state of all these features and temporarily stores them in the base handle’s ApplicationData property; handle2struct then reads them as any other regular handle property data, and then hgsaveStructDbl.m clears the temporary data from the handle’s ApplicationData. We can use the same trick for any other application state, of course.

struct2handle

handle2struct has a reverse function – the semi-documented struct2handle. I use it for creating dynamic preference panels: As in Matlab’s Preferences window, I have a list of preference topics and a set of corresponding options panels. In my case, it was easy to design each panel as a separate FIG file using GUIDE. In run-time, I simply load the relevant panel from its FIG file as described above, and place it onscreen in a dedicated uipanel using struct2handle. This enables very easy maintenance of preference panels, without sacrificing any functionality.

Matlab's preferences panels

Figure menus and toolbars are not normally stored by hgsave, unless you use the optional ‘all’ parameter (and correspondingly in hgload, if you choose to use it). handle2struct and handle2struct accept the same optional ‘all’ parameter as hgsave and hgload. Unfortunately, a warning message indicates that this option will be discontinued in some future Matlab version.

Which brings us to our final topic for today:

Matlab 8: Boldly going where no FIG has gone before…

Remember my post earlier this year about the new HG2 mechanism? I speculated that when MathWorks decides to release HG2, it will define this as a major Matlab release and label it Matlab 8.0.

The source code in hgsave.m appears to confirm my speculation. Here is the relevant code section (slightly edited for clarity), which speaks for itself:

% Decide which save code path to use
if ~feature('HGUsingMatlabClasses')   % <== existing HG
    % Warn if user passed in 'all' flag
    if SaveAll
        warning( 'MATLAB:hgsave:DeprecatedOption', ...
            'The ''all'' option to hgsave will be removed in a future release.');
    end
    hgS = hgsaveStructDbl(h, SaveAll);
    SaveVer = '070000';
    SaveOldFig = true;
 
else   % <== HG2
 
    % Warn if user passed in 'all' flag
    if SaveAll
        warning( 'MATLAB:hgsave:DeprecatedOption', ...
            'The ''all'' option to hgsave has been removed.');
    end
    if SaveOldFig
        hgS = hgsaveStructClass(h);
        SaveVer = '080000';
    else
        hgO = hgsaveObject(h);
        SaveVer = '080000';
    end
end
 
% Revision encoded as 2 digits for major revision,
% 2 digits for minor revision, and 2 digits for
% patch revision.  This is the minimum revision
% required to fully support the file format.
% e.g. 070000 means 7.0.0

As can be seen, when Matlab starts using HG2 (perhaps in 2011?), the top-level structure node will be called “hgS_080000″, indicating Matlab 8.0. QED.

As a side-note, note that in HG2/Matlab8, although the comment about using ‘all’ indicates that it has been removed, in practice it is still accepted (although not being used). This will enable your code to be backward-compatible whenever HG2 launches, and future-compatible today.

Have you used handle2struct or struct2handle? If so, please share your experience in a comment.

Let the upcoming 2011 be a year filled with revelations, announcements and fulfillment! Happy New Year everybody!

1. FIG files format FIG files are actually MAT files in disguise. This article explains how this can be useful in Matlab applications....
2. Matlab layout managers: uicontainer and relatives Matlab contains a few undocumented GUI layout managers, which greatly facilitate handling GUI components in dynamically-changing figures....
3. 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....
4. getundoc – get undocumented object properties getundoc is a very simple utility that displays the hidden (undocumented) properties of a specified handle object....

It so happens that only a few weeks ago I completed a consulting project which required exactly this. The project was to integrate a Matlab computational engine with a Java interface to Interactive Brokers (IB) – a well-known online brokerage firm. The idea was to use the Java interface to fetch real-time data about securities (stocks, bonds, options etc.), use a Matlab processing utility, then use the Java interface again to send Buy or Sell orders back to IB.

If you are interested in the final result (i.e., a complete and field-tested Matlab-IB interface), look here.

The challenge

A big challenge in this project (aside from handling quite a few IB interface quirks), was to propagate events from the Java interface to the Matlab application. This had to be done asynchronously, since events such as order execution can occur at any time following the order placement. Moreover, even simple requests such as retrieving security information (bid/ask prices for example) is handled by IB via Java events, not as simple function return values.

Handling Java-based events in Matlab is not a trivial task. Not only merely undocumented, but it is also not intuitive. I have spent quite a few hours trying to crack this issue. In fact, I believe it was one of my more challenging tasks in figuring out the undocumented aspects of the Matlab-Java interface. Few other challenges were as difficult, yet with a happy ending (Drag & Drop is a similar issue – I will describe it in another article sometime).

The solution

Fast-forward all the fruitless attempted variations, here is the bottom line. Refer to the following simple Java class example:

public class EventTest
{
    private java.util.Vector data = new java.util.Vector();
    public synchronized void addMyTestListener(MyTestListener lis) {
        data.addElement(lis);
    }
    public synchronized void removeMyTestListener(MyTestListener lis) {
        data.removeElement(lis);
    }
    public interface MyTestListener extends java.util.EventListener {
        void testEvent(MyTestEvent event);
    }
    public class MyTestEvent extends java.util.EventObject {
        private static final long serialVersionUID = 1L;
        public float oldValue,newValue;        
        MyTestEvent(Object obj, float oldValue, float newValue) {
            super(obj);
            this.oldValue = oldValue;
            this.newValue = newValue;
        }
    }
    public void notifyMyTest() {
        java.util.Vector dataCopy;
        synchronized(this) {
            dataCopy = (java.util.Vector)data.clone();
        }
        for (int i=0; i<dataCopy.size(); i++) {
            MyTestEvent event = new MyTestEvent(this, 0, 1);
            ((MyTestListener)dataCopy.elementAt(i)).testEvent(event);
        }
    }
}

When compiling EventTest.java, three class files are created: EventTest.class, EventTest$MyTestEvent.class and EventTest$MyTestListener.class. Place them on Matlab’s Java static classpath, using edit(‘classpath.txt’) (using the dynamic classpath causes many problems that using the static classpath solves). They can now be accessed as follows:

>> which EventTest
EventTest is a Java method  % EventTest constructor
 
>> evt = EventTest
evt =
EventTest@16166fc
 
>> evt.get
	Class = [ (1 by 1) java.lang.Class array]
	TestEventCallback = 
	TestEventCallbackData = []
 
	BeingDeleted = off
	ButtonDownFcn = 
	Children = []
	Clipping = on
	CreateFcn = 
	DeleteFcn = 
	BusyAction = queue
	HandleVisibility = on
	HitTest = on
	Interruptible = on
	Parent = []
	Selected = off
	SelectionHighlight = on
	Tag = 
	Type = EventTest
	UIContextMenu = []
	UserData = []
	Visible = on
 
>> set(evt)
	Class
	TestEventCallback: string -or- function handle -or- cell array
	...
 
>> set(evt,'TestEventCallback',@(h,e)disp(h))
 
>> get(evt)
	Class = [ (1 by 1) java.lang.Class array]
	TestEventCallback = [ (1 by 1) function_handle array]   <= ok
	TestEventCallbackData = []
	...
 
>> evt.notifyMyTest   % invoke Java event
              0.0009765625   % <= Matlab callback

Note how Matlab automatically converted the Java event testEvent, declared in interface MyTestListener, into a Matlab callback TestEventCallback (the first character is always capitalized). All Java events are automatically converted in this fashion, by appending a ‘Callback’ suffix. Here is a code snippet from R2008a’s \toolbox\matlab\uitools\@opaque\addlistener.m that shows this (slightly edited):

hSrc = handle(jobj,'callbackproperties');
allfields = sortrows(fields(set(hSrc)));
for i = 1:length(allfields)
   fn = allfields{i};
   if ~isempty(findstr('Callback',fn))
      disp(strrep(fn,'Callback',''));
   end
end
 
callback = @(o,e) cbBridge(o,e,response);
hdl = handle.listener(handle(jobj), eventName, callback);
function cbBridge(o,e,response)
   hgfeval(response, java(o), e.JavaEvent)
end

Note that hgfeval, which is used within the cbBridge callback function, is a semi-documented pure-Matlab built-in function, which I described a few weeks ago.

If several events have the same case-insensitive name, then the additional callbacks will have an appended underscore character (e.g., ‘TestEventCallback_’):

// In the Java class:
public interface MyTestListener extends java.util.EventListener
{
    void testEvent(MyTestEvent e);
    void testevent(TestEvent2 e);
}

% …and back in Matlab:
>> evt=EventTest; evt.get
	Class = [ (1 by 1) java.lang.Class array]
	TestEventCallback = 
	TestEventCallbackData = []
	TestEventCallback_ = 
	TestEventCallback_Data = [] 
	...

To complete this discussion, it should be noted that Matlab also automatically defines corresponding Events in the Java object’s classhandle. Unfortunately, classhandle events are not differentiated in a similar manner – in this case only a single event is created, named Testevent. classhandle events, and their relationship to the preceding discussion, will be described in Donn Scull’s upcoming series on UDD.

An alternative to using callbacks on Java events, as shown above, is to use undocumented handle.listeners:

hListener = handle.listener(handle(evt),'TestEvent',callback);

There are several other odds and ends, but this article should be sufficient for implementing a fully-functional Java event handling mechanism in Matlab. Good luck!

1. UDD Events and Listeners UDD event listeners can be used to listen to property value changes and other important events of Matlab objects...
2. uisplittool & uitogglesplittool callbacks Matlab's undocumented uisplittool and uitogglesplittool are powerful toolbar controls - this article explains how to customize their behavior...
3. UDD and Java UDD provides built-in convenience methods to facilitate the integration of Matlab UDD objects with Java code - this article explains how...
4. Uicontrol callbacks This post details undocumented callbacks exposed by the underlying Java object of Matlab uicontrols, that can be used to modify the control's behavior in a multitude of different events...