Editing Matlab arrays in-place can be an important technique for optimizing calculations, especially when handling data that use large blocks of memory. The Matlab language itself has some limited support for in-place editing, but when we are really concerned with speed we often turn to writing C/C++ extensions using the Mex interface. Unfortunately, editing arrays in-place from Mex extensions is not officially supported in Matlab, and doing it incorrectly can cause data inconsistencies or can even cause Matlab to crash. In this article, I will introduce the problem and show a simple solution that exhibit the basic implementation details of Matlab’s internal copy-on-write mechanism.

Why edit in-place?

To demonstrate the techniques in this article, I use the fast_median function, which is part of my nth_element package on Matlab’s File Exchange. You can download the package and play with the code if you want. The examples are fairly self-explanatory, so if you do not want to try the code you should be okay just following along.

Let us try a few function calls to see how editing in-place can save time and memory:

>> A = rand(100000000, 1);
>> tic; median(A); toc    
Elapsed time is 4.122654 seconds.
 
>> tic; fast_median(A); toc
Elapsed time is 1.646448 seconds.
 
>> tic; fast_median_ip(A); toc
Elapsed time is 0.927898 seconds.

If you try running this, be careful not to make A too large; tune the example according to the memory available on your system. In terms of the execution time for the different functions, your mileage may vary depending on factors such as: your system, what Matlab version you are running, and whether your test data is arranged in a single vector or a multicolumn array.

This example illustrates a few general points: first, fast_median is significantly faster than Matlab’s native median function. This is because fast_median uses a more efficient algorithm; see the nth_element page for more details. Besides being a shameless plug, this demonstrates why we might want to write a Mex function in the first place: rewriting the median function in pure Matlab would be slow, but using C++ we can significantly improve on the status quo.

The second point is that the in-place version, fast_median_ip, yields an additional speed improvement. What is the difference? Let us look behind the scenes; here are the CPU and memory traces from my system monitor after running the above:

Memory and CPU usage for median vs. fast_median_ip

You can see four spikes in CPU use, and some associated changes in memory allocation:

The first spike in CPU is when we created the test data vector; memory use also steps up at that time.

The second CPU spike is the largest; that is Matlab’s median function. You can see that over that period memory use stepped up again, and then stepped back down; the median function makes a copy of the entire input data, and then throws its copy away when it is finished; this is expensive in terms of time and resources.

The fast_median function is the next CPU spike; it has a similar step up and down in memory use, but it is much faster.

Finally, in the case of fast_median_ip we see something different; there is a spike in CPU use, but memory use stays flat; the in-place version is faster and more memory efficient because it does not make a copy of the input data.

There is another important difference with the in-place version; it modifies its input array. This can be demonstrated simply:

>> A = randi(100, [10 1]);
>> A'
ans = 39    42    98    25    64    75     6    56    71    89
 
>> median(A)
ans = 60
 
>> fast_median(A)
ans = 60
>> A'
ans = 39    42    98    25    64    75     6    56    71    89
 
>> fast_median_ip(A)
ans = 60
>> A'
ans = 39     6    25    42    56    64    75    71    98    89

As you can see, all three methods get the same answer, but median and fast_median do not modify A in the workspace, whereas after running fast_median_ip, input array A has changed. This is how the in-place method is able to run without using new memory; it operates on the existing array rather than making a copy.

Pitfalls with in-place editing

Modifying a function’s input is common in many languages, but in Matlab there are only a few special conditions under which this is officially sanctioned. This is not necessarily a bad thing; many people feel that modifying input data is bad programming practice and makes code harder to maintain. But as we have shown, it can be an important capability to have if speed and memory use are critical to an application.

Given that in-place editing is not officially supported in Matlab Mex extensions, what do we have to do to make it work? Let us look at the normal, input-copying fast_median function as a starting point:

void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[]) {
   mxArray *incopy = mxDuplicateArray(prhs[0]);
   plhs[0] = run_fast_median(incopy);
}

This is a pretty simple function (I have taken out a few lines of boiler plate input checking to keep things clean). It relies on helper function run_fast_median to do the actual calculation, so the only real logic here is copying the input array prhs[0]. Importantly, run_fast_median edits its inputs in-place, so the call to mxDuplicateArray ensures that the Mex function is overall well behaved, i.e. that it does not change its inputs.

Who wants to be well behaved though? Can we save time and memory just by taking out the input duplication step? Let us try it:

void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[]) {
   plhs[0] = run_fast_median(const_cast<mxarray *>(prhs[0]));  // </mxarray>
}

Very bad behavior; note that we cast the original const mxArray* input to a mxArray* so that the compiler will let us mess with it; naughty.

But does this accomplish edit in-place for fast_median? Be sure to save any work you have open and then try it:

>> mex fast_median_tweaked.cpp
>> A = randi(100,[10 1]);
>> fast_median_tweaked(A)
ans = 43

Hmm, it looks like this worked fine. But in fact there are subtle problems:

>> A = randi(100,[10 1]);
>> A'
ans = 65    92    14    26    41     2    45    85    53     2
>> B = A;
>> B'
ans = 65    92    14    26    41     2    45    85    53     2
 
>> fast_median_tweaked(A)
ans = 43
>> A'
ans = 2     2    41    26    14    45    65    85    53    92
>> B'
ans = 2     2    41    26    14    45    65    85    53    92

Uhoh, spooky; we expected that running fast_median_tweaked would change input A, but somehow it has also changed B, even though B is supposed to be an independent copy. Not good. In fact, under some conditions this kind of uncontrolled editing in-place can crash the entire Matlab environment with a segfault. What is going on?

Matlab’s copy-on-write mechanism

The answer is that our simple attempt to edit in-place conflicts with Matlab’s internal copy-on-write mechanism. Copy-on-write is an optimization built into Matlab to help avoid expensive copying of variables in memory (actually similar to what we are trying to accomplish with edit in-place). We can see copy-on-write in action with some simple tests:

Matlab's Copy-on-Write memory and CPU usage

% Test #1: update, then copy
>> tic; A = zeros(100000000, 1); toc
Elapsed time is 0.588937 seconds.
>> tic; A(1) = 0; toc
Elapsed time is 0.000008 seconds.
>> tic; B = A; toc   
Elapsed time is 0.000020 seconds.
 
% Test #2: copy, then update
>> clear
>> tic; A = zeros(100000000, 1); toc
Elapsed time is 0.588937 seconds.
>> tic; B = A; toc   
Elapsed time is 0.000020 seconds.
>> tic; A(1) = 0; toc
Elapsed time is 0.678160 seconds.

In the first set of operations, time and memory are used to create A, but updating A and “copying” A into B take no memory and essentially no time. This may come as a surprise since supposedly we have made an independent copy of A in B; why does creating B take no time or memory when A is clearly a large, expensive block?

The second set of operations makes things more clear. In this case, we again create A and then copy it to B; again this operation is fast and cheap. But assigning into A at this point takes time and consumes a new block of memory, even though we are only assigning into a single index of A. This is copy-on-write: Matlab tries to save you from copying large blocks of memory unless you need to. So when you first assign B to equal A, nothing is copied; the variable B is simply set to point to the same memory location already used by A. Only after you try to change A (or B), does Matlab decide that you really need to have two copies of the large array.

There are some additional tricks Matlab does with copy-on-write. Here is another example:

>> clear
>> tic; A{1} = zeros(100000000, 1); toc
Elapsed time is 0.573240 seconds.
>> tic; A{2} = zeros(100000000, 1); toc
Elapsed time is 0.560369 seconds.
 
>> tic; B = A; toc                     
Elapsed time is 0.000016 seconds.
 
>> tic; A{1}(1) = 0; toc               
Elapsed time is 0.690690 seconds.
>> tic; A{2}(1) = 0; toc
Elapsed time is 0.695758 seconds.
 
>> tic; A{1}(1) = 0; toc
Elapsed time is 0.000011 seconds.
>> tic; A{2}(1) = 0; toc
Elapsed time is 0.000004 seconds.

This shows that for the purposes of copy-on-write, different elements of cell array A are treated independently. When we assign B equal to A, nothing is copied. Then when we change any part of A{1}, that whole element must be copied over. When we subsequently change A{2}, that whole element must also be copied over; it was not copied earlier. At this point, A and B are truly independent of each other, as both elements have experienced copy-on-write, so further assignments into either A or B are fast and require no additional memory.

Try playing with some struct arrays and you will find that copy-on-write also works independently for the elements of structs.

Reconciling edit in-place with copy-on-write: mxUnshareArray

Now it is clear why we cannot simply edit arrays in-place from Mex functions; not only is it naughty, it fundamentally conflicts with copy-on-write. Naively changing an array in-place can inadvertently change other variables that are still waiting for a copy-on-write, as we saw above when fast_median_tweaked inadvertently changed B in the workspace. This is, in the best case, an unmaintainable mess. Under more aggressive in-place editing, it can cause Matlab to crash with a segfault.

Luckily, there is a simple solution, although it requires calling internal, undocumented Matlab functions.

Essentially what we need is a Mex function that can be run on a Matlab array that will do the following:

1. Check whether the current array is sharing data with any other arrays that are waiting for copy-on-write.
2. If the array is shared, it must be unshared; the underlying memory must be copied and all the relevant pointers need to be fixed so that the array we want to work on is no longer accessible by anyone else.
3. If the array is not currently shared, simply proceed; the whole point is to avoid copying memory if we do not need to, so that we can benefit from the efficiencies of edit in-place.

If you think about it, this is exactly the operation that Matlab needs to run internally when it is deciding whether an assignment operation requires a copy-on-write. So it should come as no surprise that such a Mex function already exists in the form of a Matlab internal called mxUnshareArray. Here is how you use it:

extern "C" bool mxUnshareArray(mxArray *array_ptr, bool noDeepCopy);
 
void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[]) {
   mxUnshareArray(const_cast<mxarray *>(prhs[0]), true);  //</mxarray>
   plhs[0] = run_fast_median(const_cast<mxarray *>(prhs[0]));  //</mxarray>
}

This is the method actually used by fast_median_ip to efficiently edit in-place without risking conflicts with copy-on-write. Of course, if the array turns out to need to be unshared, then you do not get the benefit of edit in-place because the memory ends up getting copied. But at least things are safe and you get the in-place benefit as long as the input array is not being shared.

Further topics

The method shown here should allow you to edit normal Matlab numerical or character arrays in-place from Mex functions safely. For a Mex function in C rather than C++, omit the “C” in the extern declaration and of course you will have to use C-style casting rather than const_cast. If you need to edit cell or struct arrays in-place, or especially if you need to edit subsections of shared cell or struct arrays safely and efficiently while leaving the rest of the data shared, then you will need a few more tricks. A good place to get started is this article by Benjamin Schubert.

Unfortunately, over the last few years Mathworks seems to have decided to make it more difficult for users to access these kinds of internal methods to make our code more efficient. So be aware of the risk that in some future version of Matlab this method will no longer work in its current form.

Ultimately much of what is known about mxUnshareArray as well as the internal implementation details of how Matlab keeps track of which arrays are shared goes back to the work of Peter Boettcher, particularly his headerdump.c utility. Unfortunately, it appears that HeaderDump fails with Matlab releases >=R2010a, as Mathworks have changed some of the internal memory formats – perhaps some smart reader can pick up the work and adapt HeaderDump to the new memory format.

In a future article, I hope to discuss headerdump.c and its relevance for copy-on-write and edit in-place, and some other related tools for the latest Matlab releases that do not support HeaderDump.

1. Undocumented profiler options The Matlab profiler has some undocumented options that facilitate debugging memory bottlenecks and JIT (Just-In-Time Java compilation) problems....
2. Matlab-Java memory leaks, performance Internal fields of Java objects may leak memory - this article explains how to avoid this without sacrificing performance. ...
3. JMI – Java-to-Matlab Interface JMI enables calling Matlab functions from within Java. This article explains JMI's core functionality....
4. Matlab callbacks for Java events Events raised in Java code can be caught and handled in Matlab callback functions - this article explains how...

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. Matlab callbacks for Java events Events raised in Java code can be caught and handled in Matlab callback functions - this article explains how...

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:

• 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...

Well, at least not officially

The following trick restores the docking controls to figures in R2008a-compiled applications, enabling figure docking. Simply add one or both of the following alternatives in your application, after the figure has been created:

% Alternative #1 - uses pure Matlab
set(hFig, 'DockControls', 'on');
 
% Alternative #2 - uses the underlying Java frame
jFrame = get(handle(hFig), 'JavaFrame');
try
   % This works up to R2011a
   jFrame.fFigureClient.setClientDockable(true);
catch
   % This works from R2008b and up
   jFrame.fHG1Client.setClientDockable(true);
end

where hFig is the figure handle. This will have no effect for the regular interpreted (non-compiled) run of the application, where these controls are ‘on’ by default. But in the compiled application, although it may erroneously report that the controls are ‘on’, they are in fact ‘off’, so turning them ‘on’ fixes the problem.

Matlab figure docking control

Note: the two variants in alternative #2 above are actually identical, it is simply that the relevant field name has changed: Up to R2008a, only the fFigureClient existed; in R2008b, the fHG1Client field was added, which was simply an alias for fFigureClient, holding the same reference handle, so either of these fields could be used (a corresponding fHG2Client was also added – more on HG1 and HG2 here). In R2011b (at least the pre-release), the fFigureClient alias field was dropped and only fHG1Client remained. While the field name has changed, the underlying docking functionality appears to have remained stable over all these releases. For the record, in answer to a user question below, these fields can be listed using the built in fieldnames function:

% R2008b - R2011a:
>> fieldnames(jFrame)
ans = 
    'fFigureClient'
    'fHG2Client'
    'fHG1Client'
    'fUseHG2'
    'UICONTROLBACKGROUND_OS'
    'UICONTROLBACKGROUND_COMPATIBLE'

I was reminded of this trick by Aurélien’s recent comment, where he mentions MathWorks so-called workaround for this problem, which (IMHO) is really not a work-around at all: MathWorks advises to modify our application to use – would you believe this – tabbed panels to “dock” the separate figures contents onto separate panels. Not to mention the fact that this so-called “solution” relies on undocumented and unsupported Matlab functionality (that of tabbed-panels) and requires major rework of existing applications, it also results in far inferior look-and-feel than simple docking as G-d intended…

Since I have demonstrated above that the docking functionality actually exists in compiled apps just as in the interpreted m-file apps, I do not understand why MathWorks took such great pains to prevent this important functionality in the compiler. There must be some important reason for this, but I cannot think of any. Perhaps if there is enough public demand, MathWorks will agree to return the docking functionality.

Unfortunately, I recently discovered that in the most recent compiler, that ships with R2011a, alternative #1 above (which uses pure Matlab) no longer works. Sometime between R2008a and R2011a MathWorks discovered my first back-door and closed it. Such a pity…

Luckily, alternative #2 (which uses the underlying Java frame object) seems to still work, even on R2011a.

I still haven’t tested this on R2011b’s compiler (whose pre-release has become available for download yesterday), but hopefully the trick above will continue to work on R2011b and on subsequent releases – please tell me if you find out otherwise.

1. Minimize/maximize figure window Matlab figure windows can easily be maximized, minimized and restored using a bit of undocumented magic powder...
2. FindJObj – find a Matlab component’s underlying Java object The FindJObj utility can be used to access and display the internal components of Matlab controls and containers. This article explains its uses and inner mechanism....
3. Blurred Matlab figure window Matlab figure windows can be blurred using a semi-transparent overlaid window - this article explains how...
4. JMI wrapper – local MatlabControl part 2 An example using matlabcontrol for calling Matlab from within a Java class is explained and discussed...

I posted a short comment mentioning my experience of using the catalog programmatically as another use-case that might be taken into consideration. Today, I would like to expand that short comment and explain how built-in plot-selection components can be used in our Matlab GUI programs.

Built-in plot selection components

PlotTypeCombo is a plot-function selector is that is one of my personal favorite controls for embedding in a Matlab application:

% Present the PlotCombo control
import com.mathworks.mlwidgets.graphics.*
jPlotCombo = PlotTypeCombo;
pos = [100,100,170,50];
[jhPlotCombo,hPanel] = javacomponent(jPlotCombo,pos,gcf);
set(jhPlotCombo,'ActionPerformedCallback',@myCBFcn);
 
% Callback function to process PlotCombo selections
function myCBFcn(jObject,jEventData)
   newPlotFunc = jObject.getSelectedItem.getName.char;
   %Now do something useful with the selected function
end  % myCBFcn

PlotCatalog is a dialog window that presents the plot functions catalog:

com.mathworks.mlwidgets.graphics.PlotCatalog.getInstance.show

  

PlotTypeCombo and PlotCatalog

Usage example

For one application that I developed for a client, I implemented a dynamic report page that enables users to select the plotting function using a PlotTypeCombo. When users select a non-default function (e.g. stairs or loglog), that function is automatically added to the combo-box for possible future reuse. I implemented this as follows:

% Add the specified plotFunc to a PlotTypeCombo control
function updatePlotCombo(plotCombo, plotFunc)
 
   % Convert plotFunc (a Matlab string) into a Java PlotSignature
   import com.mathworks.mlwidgets.graphics.*
   plotSig = PlotMetadata.getPlotSignature(plotFunc);
 
   % Get the list of all existing plot types in the combo box
   existingPlotTypes = {};
   for plotIdx = 0 : plotCombo.ItemCount-1
      nextItem = plotCombo.getItemAt(plotIdx);
      if isjava(nextItem)
         nextItem = char(nextItem.getName);
      end
      existingPlotTypes = [existingPlotTypes, nextItem];
   end
 
   % If the new plotType is NOT already in the list
   if isempty(strmatch(plotType,existingPlotTypes,'exact'))
      % Add the new plotType to the list just prior to the end,
      % so that "More plots..." will always be last
      plotCombo.insertItemAt(plotSig,plotCombo.ItemCount-1);
   end
 
   % Set the currently-selected item to be the requested plotType
   % Note: temporarily disable callbacks to prevent involuntary action
   plotCombo.ActionPerformedCallback = [];
   plotCombo.setSelectedItem(plotSig);
   plotCombo.ActionPerformedCallback = @myCBFcn;  % selection callback
end  % updatePlotCombo

Usage of this function would then be as simple as invoking the updatePlotCombo() function:

updatePlotCombo(jhPlotCombo,'stairs');

Dynamic plot selection example

Plot signatures

The astute reader will have noticed from the updatePlotCombo() function above, that the PlotTypeCombo items are plot-signature objects. Different plot functions expect a different set of input arguments (a.k.a. signature). This information is kept and can be queried from the PlotMetadata class:

>> com.mathworks.mlwidgets.graphics.PlotMetadata.listAllSignatures
ans =
[area, bar, bar (stacked), barh (stacked), barh, comet, compass, errorbar, 
 feather, loglog, plot, plot N series, plot N series against T, plot3, plotmatrix, plotyy, 
 polar, quiver, quiver3, ribbon, scatter, scatter3, semilogx, semilogy, 
 stairs, stem, stem3, null, contour, contour3, contourf, image, 
 imagesc, mesh, meshc, meshz, pcolor, plot against first column, surf, surfc, 
 surfl, waterfall, null, contour, contour3, contourf, image, imagesc, 
 mesh, meshc, meshz, pcolor, plot against first column, surf, surfc, surfl, waterfall]
 
>> plotFunc = 'surf';  % for example
>> plotSig = PlotMetadata.getPlotSignature(plotFunc);
>> args = cell(plotSig.getArgs)';
args = 
    [1x1 com.mathworks.mlwidgets.graphics.PlotArgDescriptor]    
    [1x1 com.mathworks.mlwidgets.graphics.PlotArgDescriptor]
    [1x1 com.mathworks.mlwidgets.graphics.PlotArgDescriptor]    
    [1x1 com.mathworks.mlwidgets.graphics.PlotArgDescriptor]
 
>> argsStruct = [];  % initialize
>> for argsIdx = 1 : length(args)
      argsStruct(argsIdx).axis = char(args{argsIdx}.getAxis);
      argsStruct(argsIdx).name = char(args{argsIdx}.getName);
      argsStruct(argsIdx).label = char(args{argsIdx}.getLabel);
      argsStruct(argsIdx).dims = args{argsIdx}.getNumDimensions;
      argsStruct(argsIdx).reqObj = args{argsIdx}.getRequired;
      req = argsStruct(argsIdx).reqObj;
      argsStruct(argsIdx).requiredFlag = req.equals(req.REQUIRED);
   end
 
>> disp(argsStruct(1))			% Info about the first input argument
            axis: 'X'
            name: 'X'
           label: 'X Data Source'
            dims: [2x1 int32]
          reqObj: [1x1 com.mathworks.mlwidgets.graphics.PlotArgDescriptor$RequiredType]
    requiredFlag: 0
 
>> disp({argsStruct.axis})		% axis info of all input arguments
    'X'    'Y'    'Z'    ''
 
>> disp({argsStruct.name})		% name of all input arguments
    'X'    'Y'    'Z'    'C'
 
>> disp({argsStruct.label})	% data label of all input arguments
    'X Data Source'    'Y Data Source'    'Z Data Source'    'Color'
 
>> disp({argsStruct.dims})		% dimensionality of all input args
    [2x1 int32]    [2x1 int32]    [2]    [2]
 
>> disp({argsStruct.requiredFlag})	% is any input arg mandatory?
    [0]    [0]    [1]    [0]

This signature data can be queried for each separate plot type. In fact, I use this mechanism above so that whenever the user changes the plot-type in the PlotTypeCombo, the usage label text beneath the combo-box is updated with the specific plot’s signature information:

Dynamic plot signature data

1. Color selection components Matlab has several internal color-selection components that can easily be integrated in Matlab GUI...
2. Date selection components The JIDE package, pre-bundled in Matlab, contains several GUI controls for selecting dates - this article explains how they can be used...
3. Borderless button used for plot properties A borderless button can be used to add unobtrusive functionality to plot axes...
4. Setting status-bar components Matlab status-bars are Java containers in which we can add GUI controls such as progress-bars, not just simple text labels...

Introduction to the UDD-Java relationship

Over the course of this series we have mentioned connections between UDD and Java. In UDD Events and Listeners we described how in Matlab each Java object can have a UDD companion. In Hierarchical Systems with UDD we briefly noted that a UDD hierarchy may be passed to Java. This suggests that there is a two way relationship between between UDD and Java.

In this article we will use some undocumented built-in methods such as java and classhandle to explore the UDD-Java relationship. We have used built-in methods for UDD objects before. We have also mentioned the importance of studying code from The MathWorks. When you come across something that looks like it may be a UDD method you can check with the which command:

>> which java -all
C:\MATLAB\R2010b\toolbox\matlab\general\java.m
java is a built-in method                               % javahandle.com.mathworks.hg.peer.Echo method
java is a built-in method                               % ui.figure method
java is a built-in method                               % hg2utils.HGHandle method
java is a built-in method                               % JavaVisible method
java is a built-in method                               % hg.figure method
java is a built-in method                               % hg.GObject method
java is a built-in method                               % schema.class method
java is a built-in method                               % handle.handle method
java is a built-in method                               % schema.method method
C:\MATLAB\R2010b\toolbox\rptgen\rptgen\@sgmltag\java.m  % sgmltag method

If you find schema.class in the comments for built-in methods, then the method is a general UDD method.

UDD javahandle companions for Java object

Whenever a Java class is instantiated in Matlab, it is possible to create a companion UDD object. The created companion can be in either the javahandle or the javahandle_withcallbacks package. The primary reason for creating the companion object is to avoid memory leaks when attaching a Matlab callback to a callback property. It makes sense in general to use the javahandle_withcallbacks package.

>> % creage a java instance and the companion UDD object
>> javaFrame = javax.swing.JFrame;
 
>> % dot notation
>> javaFrameUDD = javaFrame.handle('CallbackProperties');
 
>> % or Matlab notation
>> javaFrameUDD = handle(javaFrame,'CallbackProperties');

We can use the built-in classhandle method to inspect our UDD companion object. This can be used, for example, to obtain a list of the events that the Java class generates:

>> % use classhandle to list a java classes events
>> jch = javaFrame.handle.classhandle;
 
>> for index = 1:numel(jch.Events), disp(jch.Events(index).Name); end
MouseWheelMoved
MouseClicked
MouseEntered
MouseExited
MousePressed
MouseReleased
WindowGainedFocus
WindowLostFocus
WindowActivated
WindowClosed
WindowClosing
WindowDeactivated
WindowDeiconified
WindowIconified
WindowOpened
ComponentHidden
ComponentMoved
ComponentResized
ComponentShown
MouseDragged
MouseMoved
ComponentAdded
ComponentRemoved
AncestorMoved
AncestorResized
FocusGained
FocusLost
WindowStateChanged
HierarchyChanged
CaretPositionChanged
InputMethodTextChanged
PropertyChange
KeyPressed
KeyReleased
KeyTyped
 
>> % Use one of the object's callbacks
>> set(javaFrameUDD,'WindowGainedFocusCallback',@myCallbackFcn);

If we do not wish to use callback properties, then we can create our UDD companion in the javahandle package and use handle.listener to respond to events.

javaFrame = javax.swing.JFrame;
javaFrameUDD = javaFrame.handle;
lis = handle.listener(javaFrameUDD,'WindowGainedFocus',@myCallbackFcn);

Passing UDD objects to Java code

You can pass any UDD object to your Java classes in Matlab. Matlab will create a Java bean adapter for the UDD object. The bean adapter created is a subclass of com.MathWorks.jmi.bean.UDDObject. UDDObject implements the Java interfaces com.MathWorks.jmi.bean.DynamicProperties, com.MathWorks.jmi.bean.MTObject, com.MathWorks.jmi.bean.TreeObject, and com.mathworks.services.Browseable.

The generated bean adapter will have the methods of the parent class the methods of the UDD class, as well as set and get methods for the class properties. To understand how this works, let’s start with our simple.object and use the java method to inspect the bean adapter:

>> myObj = simple.object('myObj', 2);
 
>> % using dot notation with the java method 
>> myObj.java.getClass
ans =
class objectBeanAdapter0
 
>> myObj.java.methods
 
Methods for class objectBeanAdapter0:
 
acquireReference                    createNullMatlabObjectListener      lastDown                            
addBelow                            createNullPropertyChangeListener    left                                
addBrowseableListener               dialog                              notify                              
addFirstBelow                       disp                                notifyAll                           
addLeft                             dispose                             objectBeanAdapter0                  
addMatlabObjectListener             equals                              releaseReference                    
addObjectPropertyChangeListener     findProperty                        removeBrowseableListener            
addRight                            firstDown                           removeMatlabObjectListener          
browseableCanHaveChildren           getChildAt                          removeObjectPropertyChangeListener  
browseableChild                     getChildCount                       right                               
browseableChildCount                getClass                            setDirtyFlag                        
browseableChildFetchCount           getClassName                        setDynamicPropertyValue             
browseableChildren                  getDynamicProperties                setName                             
browseableDataObject                getDynamicPropertyValue             setPropertyValue                    
browseableDisplayObject             getIndex                            setThreadSafetyCheckLevel           
browseableHasChildren               getIndexOfChild                     setValue                            
browseableNChildren                 getName                             toString                            
browseableNextNSiblings             getNewInstance                      up                                  
browseableNextSibling               getPropertyValue                    updateCache                         
browseableParent                    getValue                            updateChildCount                    
browseablePrevNSiblings             hashCode                            updateIndex                         
browseablePrevSibling               isDirty                             wait                                
checkThreadSafety                   isLeaf                              
clearDirtyFlag                      isObservable                        
compareTo                           isValid

The parent class has added a large number of methods to the bean adapter for our original class. By looking at the list we can see our dialog and disp methods. There are also getName, setName, getValue, and setValue methods for our classes properties. The rest of the methods were inherited from the base UDDObject superclass. We can use any superclass method directly with the bean adapter object. For example:

>> myObj.java.getPropertyValue('Name')
ans =
myObj

Java interface class

To be able to use our UDD object in user-written Java code, we need a Java interface class for it. While we could manually write an interface file, UDD provides a very handy convenience method to automatically create the interface file. For this, we use the classhandle method again. The schema.class object obtained using classhandle has a method called createJavaInterface that takes two string arguments: the Java interface classname, and the folder in which to place the interface file. The steps to create and use this interface file are:

1. Create and test your UDD class
2. Create a Java interface file using schema.class‘s CreateJavaInterface
3. Modify your UDD class definition file (schema.m) to reference the Java interface file
4. Create the Java code that uses your class

For example, to create a Java interface file for the simple object we created above, use the following commands in Matlab:

classH = classhandle(myObj);
classH.createJavaInterface('simpleObjectInterface',pwd);

This will create the following simpleObjectInterface.java file in the current working directory:

public interface simpleObjectInterface 
       extends com.mathworks.jmi.bean.TreeObject
{
    /* Properties */
    public java.lang.String getName();
    public void setName(java.lang.String value);
 
    public double getValue();
    public void setValue(double value);
 
    /* Methods */
    public void dialog();
    public void disp();
}

The interface file contains set and get accessor methods for our UDD object properties, and Java prototypes for the UDD methods (in our case, dialog and disp).

The next step is to modify our class definition file (schema.m) to reference the Java interface file we have created. This modification provides the information that Matlab needs to create the bean adapter that implements the Java interface:

simpleClass = schema.class(simplePackage, 'object');
simpleClass.JavaInterfaces = { 'simpleObjectInterface' };

We can verify that the generated bean adapter implements the interface using Java Reflection techniques. As always when we have made changes to the class definition file, we need to use the clear classes command, and then recreate our objects:

>> myObj = simple.object('myObj', pi)
myObj =
  Name: myObj
 Value: 3.141593
 
>> myObjBean = java(myObj) 
myObjBean =
  Name: myObj
 Value: 3.141593
 
>> interfaces = myObjBean.getClass.getInterfaces 
interfaces =
java.lang.Class[]:
    [java.lang.Class]
 
>> interfaces(1) 
ans =
interface simpleObjectInterface

Using UDD in Java

Let’s create a simple Java class that illustrates passing a UDD object to Java. Here we will just have two methods: The first gets the Value property from a class instance and doubles it; the second launches the class instance dialog:

public class accessUDDClass 
{
  double localValue;
 
  public void accessUDDClass() { 
  }
 
  public void doubleValue(simpleObjectInterface UDDObj) {
    localValue = UDDObj.getValue();
    UDDObj.setValue(2*localValue);
  }
 
  public void launchDialog(simpleObjectInterface UDDObj) {
    UDDObj.dialog();
  }
}

If we have set up the Java compiler and environment variables correctly, we can compile our interface and Java class files from inside Matlab using the system command (alternately, we can compile using any external Java compiler or IDE):

>> system('javac accessUDDClass.java simpleObjectInterface.java')
ans =
     0

Now test our simple Java class with the UDD object created earlier:

>> javaObj = accessUDDClass
javaObj =
accessUDDClass@eb9b73
 
>> javaObj.doubleValue(myObj)  % pi => 2*pi
 
>> myObj
myObj =
  Name: myObj
 Value: 6.283185

This concludes the UDD series. I would like to thank Yair for his help in preparing and presenting this information.

Editor’s note

I would like to thank Donn for his enourmously detailed work on UDD, and for preparing it in easy-to-follow articles. I can personally attest to the huge time investment it has taken him. I trully believe he deserves a warm “thank you” from the Matlab community. Please visit Donn’s website, or add a short comment below.

In the following weeks, I return to the regular stuff that made this website famous: solving day-to-day Matlab problems using simple undocumented built-in Matlab gems.
- Yair

1. Matlab callbacks for Java events Events raised in Java code can be caught and handled in Matlab callback functions - this article explains how...
2. JMI – Java-to-Matlab Interface JMI enables calling Matlab functions from within Java. This article explains JMI's core functionality....
3. FindJObj – find a Matlab component’s underlying Java object The FindJObj utility can be used to access and display the internal components of Matlab controls and containers. This article explains its uses and inner mechanism....
4. Fixing a Java focus problem Java components added to Matlab GUIs do not participate in the standard focus cycle - this article explains how to fix this problem....

JGraph

JGraph is an open-source Java library that helps visualize graph-theory objects and connectors. Note that in today’s article we discuss graphs in the sense of connected object trees, not graphs in the sense of x-vs.-y data charts.

To use JGraph, download the JGraphx zip file, then extract the zip file. You’ll get a jgraphx/ subfolder containing separate sub-folders with docs, examples, source-code and a lib/ sub-folder with a jgraphx.jar file. To use JGraph in Matlab, load jgraphx.jar into Matlab’s Java classpath (there is no need to use the static classpath in this case, although you can of course do so if you like):

javaaddpath('jgraphx/lib/jgraphx.jar');

We can now run Scott Koch’s example of using JGraph in Matlab:

% Make the graph object
graph = com.mxgraph.view.mxGraph;
 
% Get the parent cell
parent = graph.getDefaultParent();
 
% Group update
graph.getModel().beginUpdate();
 
% Add some child cells
v1 = graph.insertVertex(parent, '', 'Hello', 240, 150, 80, 30);
v2 = graph.insertVertex(parent, '', 'World', 20,   20, 80, 30);
graph.insertEdge(parent, '', 'Edge', v1, v2);
graph.getModel().endUpdate();
 
% Get scrollpane
graphComponent = com.mxgraph.swing.mxGraphComponent(graph);
 
% Make a figure and stick the component on it
f = figure('units','pixels');
pos = get(f,'position'); 
mypanel = javax.swing.JPanel(java.awt.BorderLayout);
mypanel.add(graphComponent);
[obj, hcontainer] = javacomponent(mypanel, [0,0,pos(3:4)], f);

JGraph example within a Matlab figure (the graph is fully interactive)

And some more complex JGraph examples, taken from the “official” samples gallery:

JGraph samples (click for details)

JGraphT

JGraphT is another open-source Java-based library. JGraphT is a non-GUI library that provides underlying graph-theory objects and algorithms. These can be used in conjunction with the JGraph visualization library.

The Matlab File Exchange has a submission that wraps JGraphT within Matlab. Apparently, this Matlab utility is a wrapper for the non-GUI JGraphT, but I see no reason not to use JGraph’s GUI visualization capabilities, since JGraphT has an extremely simple JGraph adapter.

BDE

BDE (Block Diagram Editor?) is an internal Matlab Java class library that has been included in Matlab releases for many years, to this day. Judging from the size of this library file (%matlabroot%/java/jar/bde.jar), MathWorks continues to develop BDE, which grows from one release to another.

BDE can be used to present and edit block diagrams. The diagrams themselves are stored in XML files in a BDE/ subfolder beneath the user’s prefdir folder. However, I do not know how these diagrams can be used. Here’s a simple usage example:

bde = com.mathworks.bde.clients.BDEDesktop;  % fails in R2009b+
diagram = com.mathworks.bde.diagram.Diagram;
client = com.mathworks.bde.clients.DiagramViewDTClient('YMA',diagram);
bde.addClient(client,'YMA');

BDE sample diagram (click for details)

Note: In Matlab release R2009b, BDE apparently had a major redesign, and the above code no longer works.

I would be happy if anyone could enlighten me regarding the possible usage of BDE, or how it can be ran in one of the latest releases. Please leave a comment below.

1. Syntax highlighted labels & panels Syntax-highlighted labels and edit-boxes can easily be displayed in Matlab GUI - this article explains how. ...
2. Plot-type selection components Several built-in components enable programmatic plot-type selection in Matlab GUI - this article explains how...
3. Uitable sorting Matlab's uitables can be sortable using simple undocumented features...
4. Advanced JIDE Property Grids JIDE property grids can use complex cell renderer and editor components and can signal property change events asynchronously to Matlab callbacks...

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. 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...
4. UDD and Java UDD provides built-in convenience methods to facilitate the integration of Matlab UDD objects with Java code - this article explains how...

Last week, a reader of that article posted a comment asking how to customize the context (right-click) menu with some user-defined actions. The user has found that modifying the menu via the regular table handles gets reset automatically.

Today’s article will describe an easy and effective way to add user-defined actions to the Workspace table, for specific object types.

The trick is not to modify the context-menu directly. As the reader above has noticed, this menu is automatically recreated on the fly, so no change will be persistent. Instead, we modify Matlab’s internal registry of class-specific context-menus. This is done in several prefspanel.m files in the Matlab codebase (For example: \toolbox\matlab\audiovideo\prefspanel.m and \toolbox\signal\signal\prefspanel.m).

The mechanism relies on the following Java method, which is unsupported and undocumented, yet has existed in the present form for the past several releases:

classes = {'double', 'java.lang.Object'};
menuName = 'My context-menu';
menuItems = {'Inspect', 'Properties', '-', 'class name'};
menuActions = {'inspect($1)', 'get($1)', '', 'class($1)'};
com.mathworks.mlwidgets.workspace.MatlabCustomClassRegistry.registerClassCallbacks(classes,menuName,menuItems,menuActions);

Customizable Workspace table context-menu

Once you have found your particular context-menu configuration useful, place the short customization code in your startup.m file so that the change becomes permanent in all future Matlab sessions.

A few other supporting static methods are available in the com.mathworks.mlwidgets.workspace.MatlabCustomClassRegistry class: getClassCallbacksInformation (className), registerSimilarClassCallbacks(newClassNames,definedClassName) and unregisterClassCallbacks(definedClassName). For example:

com.mathworks.mlwidgets.workspace.MatlabCustomClassRegistry.getClassCallbacksInformation('double')
 
ans =
java.lang.Object[]:
    'My context-menu'
    [4 element array]        % = menuItems
    [4 element array]        % = menuActions

1. Adding a context-menu to a uitree uitree is an undocumented Matlab function, which does not easily enable setting a context-menu. Here's how to do it....
2. Customizing Matlab’s Workspace table The Matlab Desktop's Workspace pane table can be customized, as described here...
3. Customizing help popup contents The built-in HelpPopup, available since Matlab R2007b, has a back-door that enables displaying arbitrary text, HTML and URL web-pages....
4. Context-Sensitive Help Matlab has a hidden/unsupported built-in mechanism for easy implementation of context-sensitive help...

The graphics.cursorbar object answers a very basic need that is often encountered in graph exploration: displaying data values together with horizontal/vertical cross-hairs, similarly to ginput.

While Matlab has provided the data-cursor mode for a long time, the cross-hair feature is still missing as of R2010b. Many CSSM newsgroup readers have asked about this missing feature. Some recent examples: here, here, and here.

DataMatrix

To answer this need I have created the DataMatrix utility, which is available on the Matlab File Exchange:

DataMatrix: customizable data tooltip & cross-hairs

DataMatrix displays matlab’s standard data-cursor tooltip together with dotted cross-hairs, both of which move with the mouse pointer. DataMatrix is actually based mostly on fully-documented stuff: the undocumented aspects are secondary to the main program flow and mostly just ensure old releases compatibility and correct behavior in the presence of some figure modes.

graphics.cursorbar

When I created DataMatrix in 2007, I had no idea that graphics.cursorbar already existed. graphics.cursorbar is an internal Matlab object, that is undocumented and unsupported. It has several advantages over DataMatrix, being more customizable in the cross-hairs and data marker, although not enabling to customize the tooltip text nor to present both cross-hairs (only horizontal/vertical, not both). It is one of the earliest examples of Matlab’s old class system (schema-based).

We initialize a graphics.cursorbar object by supplying an axes (not very useful) or plot-line handle (more useful). The cursorbar handle can be customized using properties such as BottomMarker, TopMarker, CursorLineColor, CursorLineStyle, CursorLineWidth, TargetMarkerSize, TargetMarkerStyle, ShowText, Orientation, Position (Position is a hidden property) etc., as well as the regular HG properties (UserData, Visibility, Parent etc.).

Once the cursor-bar is created, it can be dragged and moved via the mouse cursor, as the following code snippet and animated gif show:

t=0:.01:7; hp=plot(t,sin(t));
hCursorbar = graphics.cursorbar(hp); drawnow
hCursorbar.CursorLineColor = [.9,.3,.6]; % default=[0,0,0]='k'
hCursorbar.CursorLineStyle = '-.';       % default='-'
hCursorbar.CursorLineWidth = 2.5;        % default=1
hCursorbar.Orientation = 'vertical';     % =default
hCursorbar.TargetMarkerSize = 12;        % default=8
hCursorbar.TargetMarkerStyle = 'o';      % default='s' (square)

Matlab's internal cursorbar object

Comments within the internal code (%matlabroot%\toolbox\matlab\graphics\@graphics\@cursorbar\*.m) suggest that graphics.cursorbar has been around since 2003 at least, although I have not checked such old releases. The presented tooltip resembles one of the old data tips, not one of the modern ones. In addition, as far as I can tell, graphics.cursorbar is not used within the Matlab code corpus. For these reasons it would not surprise me at all to find that MathWorks will remove this feature in some near future release. Until then – have fun using it!

Can you find a good use for graphics.cursorbar? if so, please let us know by posting a comment below.

1. getundoc – get undocumented object properties getundoc is a very simple utility that displays the hidden (undocumented) properties of a specified handle object....
2. FindJObj – find a Matlab component’s underlying Java object The FindJObj utility can be used to access and display the internal components of Matlab controls and containers. This article explains its uses and inner mechanism....
3. Types of undocumented Matlab aspects This article lists the different types of undocumented/unsupported/hidden aspects in Matlab...
4. 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....