Undocumented Matlab » UI controls

Uitable cell colors

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

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

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

First pass – basic data table

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

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

Plain data table - so boooooring...

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

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

Second pass – auto-resizing that actually works…

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

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

Auto-resized columns that actually work

Third pass – adding colors

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

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

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

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

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

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

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

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

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

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

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

Finally something lively!

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

Related posts:
Uitable customization report In last week’s report about uitable sorting, I offered a report that I have written which covers uitable customization in detail. Several people have asked for more details about the...
Uitable sorting Matlab's uitables can be sortable using simple undocumented features...
Uitab colors, icons and images Matlab's semi-documented tab panels can be customized using some undocumented hacks...
Changing Matlab’s Command Window colors Matlab's Command Window foreground and background colors can be modified programmatically, using some of Matlab's undocumented internal Java classes. Here's how....

Tri-state checkbox

Yair Altman — Wed, 19 Oct 2011 14:04:20 +0000

When presenting information visually in graphical user interfaces (GUIs), we often need to present and enable interaction with state data (such as On/Off). In most cases, we would naturally use a checkbox to present the information and enable interaction. But What can we do if the data has three possible states. For example, Yes/No/Maybe, or: Full/Empty/Partial, or: Up/Down/Undetermined ?
Until today, Matlab GUIs had to resort to using drop-down (aka combo-box or popup-menu) or radio-button controls to present such information. However, would it not be nicer if we could still use a checkbox? Outside Matlab, such a control is known as a tri-state checkbox and many modern GUI frameworks support it. Well, surprise surprise, so does Matlab (although you would never guess it from the documentation).
CheckBoxTree
Last year, I have already described a built-in Matlab tree control whose nodes have tri-state checkboxes:
a regular MJTree (left) and a CheckBoxTree (right)
Today I will show how we can use these checkboxes as independent GUI controls.
Modifying the standard Matlab checkbox uicontrol
In order to modify the standard Matlab checkbox uicontrol, we need to first get its underlying Java component reference. This is done using the findjobj utility. We then update its UI wrapper to be the same as the CheckBoxTree‘s checkbox control.
To programmatically set a mixed state we update the ‘selectionState’ client property to SelectionState.MIXED (SelectionState also has the SELECTED and NOT_SELECTED values).
Here is an end-to-end example:
hCB = uicontrol('Style','checkbox', ...); jCB = findjobj(hCB); jCB.setUI(com.mathworks.mwswing.checkboxtree.TriStateButtonUI(jCB.getUI)); % Update the checkbox state to MIXED newState = com.mathworks.mwswing.checkboxtree.SelectionState.MIXED; jCB.putClientProperty('selectionState', newState); jCB.repaint;
Matlab checkboxes displaying mixed states
Displaying as an independent Java control
Instead of retrofitting a standard Matlab uicontrol as described above, we can directly use the standard javax.swing.JCheckBox which does not normally support tri-state (it only has two states), displaying it in our GUI with the built-in javacomponent function:
% Display the checkbox (UNSELECTED state at first) jCB = javax.swing.JCheckBox('JCheckBox - mixed',0); javacomponent(jCB, [10,70,150,20], gcf); % Update the checkbox state to MIXED import com.mathworks.mwswing.checkboxtree.* jCB.setUI(TriStateButtonUI(jCB.getUI)); jCB.putClientProperty('selectionState', SelectionState.MIXED); jCB.repaint;
Note that instead of using javax.swing.JCheckBox, we could use the internal Matlab class com.mathworks.mwswing.MJCheckBox, which directly extends JCheckBox and adds mnemonic (shortcut-key) support, but is otherwise fully compatible with JCheckBox. Actually, it is MJCheckBox which is the underlying Java component of the standard Matlab checkbox uicontrol.
Alternative controls
Now that we have seen that Matlab includes built-in support (well, at least support in the technical sense, not the official customer-support sense), would you be surprised to learn that it includes similar support in other internal components as well?
The internal Matlab class com.mathworks.mwt.MWCheckbox directly supports a tri-state (yes/no/maybe) checkbox, without any need to update its UI, as follows:
% Display the checkbox (UNSELECTED state at first) jCB = com.mathworks.mwt.MWCheckbox('MWCheckbox - mixed',0); javacomponent(jCB, [10,70,150,20], gcf); % Update the checkbox state to MIXED jCB.setMixedState(true); % Retrieve the current state isMixedFlag = jCB.isMixedState(); % true/false
MJCheckBox vs. MWCheckbox
Note that the State property, which controls the standard selected/unselected state, is entirely independent from the MixedState property. Both State and MixedState are boolean properties, so to get the actual checkbox state we need to query both of these properties.
Another internal Matlab class that we can use is JIDE’s com.jidesoft.swing.TristateCheckBox (which is pre-bundled in Matlab and is fully documented here).
There are many other tri-state checkbox alternatives available online (for example, here, here and here). We can easily include them in our Matlab GUI with the javacomponent function. Using external components we can be more certain of the compatibility issues in past and future Matlab releases. On the other hand, internal Matlab classes do have the advantage of being inherently accessible on all platforms of the same Matlab release, whereas non-Matlab components must be included in our deployment package.
Do you use any tri-state controls, either Matlab or external, in your work? If so, please share your experience in a comment below.

Related posts:
Recovering previous editor state Recovering the previous state of the Matlab editor and its loaded documents is possible using a built-in backup config file. ...
Determining axes zoom state The information of whether or not an axes is zoomed or panned can easily be inferred from an internal undocumented object....
JIDE Property Grids The JIDE components pre-bundled in Matlab enable creating user-customized property grid tables...
FindJObj GUI – display container hierarchy The FindJObj utility can be used to present a GUI that displays a Matlab container's internal Java components, properties and callbacks....

uisplittool & uitogglesplittool

Yair Altman — Thu, 09 Dec 2010 00:06:33 +0000

Matlab 7.6 (R2008a) and onward contain a reference to uisplittool and uitogglesplittool in the javacomponent.m and %matlabroot%/bin/registry/hg.xml files. These are reported as built-in functions by the which function, although they have no corresponding m-file as other similar built-in functions (note the double ‘t’, as in split-tool):
>> which uisplittool built-in (C:\Matlab\R2010b\toolbox\matlab\uitools\uisplittool)
These uitools are entirely undocumented, even today (R2010b). They puzzled me for a very long time. An acute reader (Jeremy Raymonds) suggested they are related to toolbars, like other uitools such as the uipushtool and uitoggletool. This turned out to be the missing clue that unveiled these useful tools:
So what are uisplittool and uitogglesplittool?
Both uisplittool and uitogglesplittool are basic Handle-Graphics building blocks used in Matlab toolbars, similarly to the well-documented uipushtool and uitoggletool.
uisplittool presents a simple drop-down, whereas uitogglesplittool presents a drop-down that is also selectable.
The Publish and Run controls on the Matlab Editor’s toolbar are examples of uisplittool, and so are the Brush / Select-Data control on the figure toolbar, and the plot-selection drop-down on the Matlab Desktop’s Workspace toolbar:
uisplittool in action in the Matlab Desktop
Adding uisplittool and uitogglesplittool to a toolbar
Adding a uisplittool and uitogglesplittool to a toolbar is done in a similar manner to adding uipushtools and uitoggletools:
hToolbar = findall(gcf,'tag','FigureToolBar'); hUndo=uisplittool('parent',hToolbar); % uisplittool hRedo=uitogglesplittool('parent',hToolbar); % uitogglesplittool
Like uipushtool and uitoggletool, uisplittool and uitogglesplittool also have unique Type property values, ‘uisplittool’ and ‘uitogglesplittool’ respectively. The handles can also be tested using the built-in isa function:
>> isa(handle(hUndo),'uisplittool') % or: 'uitogglesplittool' ans = 1 >> class(handle(hUndo)) ans = uisplittool
Just as with uipushtools and uitoggletools, the new buttons have an empty button-face appearance, until we fix their CData, Tooltip and similar settable properties:
% Load the Redo icon icon = fullfile(matlabroot,'/toolbox/matlab/icons/greenarrowicon.gif'); [cdata,map] = imread(icon); % Convert white pixels into a transparent background map(find(map(:,1)+map(:,2)+map(:,3)==3)) = NaN; % Convert into 3D RGB-space cdataRedo = ind2rgb(cdata,map); cdataUndo = cdataRedo(:,[16:-1:1],:); % Add the icon (and its mirror image = undo) to latest toolbar set(hUndo, 'cdata',cdataUndo, 'tooltip','undo','Separator','on', ... 'ClickedCallback','uiundo(gcbf,''execUndo'')'); set(hRedo, 'cdata',cdataRedo, 'tooltip','redo', ... 'ClickedCallback','uiundo(gcbf,''execRedo'')');
User-created uisplittool & uitogglesplittool toolbar buttons
Note that the controls can be created with these properties in a single command:
hUndo = uisplittool('parent',hToolbar, 'cdata',cdataRedo, ...);
Re-arranging the toolbar controls placement
Let us now re-arrange our toolbar buttons. Unfortunately, a bug causes uisplittools and uitogglesplittools to always be placed flush-left when the toolbar’s children are re-arranged (anyone at TMW reading this in time for the R2011a bug-parade selection?).
So, we can’t re-arrange the buttons at the HG-children level. Luckily, we can re-arrange directly at the Java level (note that until now, the entire discussion of uisplittool and uitogglesplittool was purely Matlab-based):
jToolbar = get(get(hToolbar,'JavaContainer'),'ComponentPeer'); jButtons = jToolbar.getComponents; for buttonId = length(jButtons)-3 : -1 : 7 % end-to-front jToolbar.setComponentZOrder(jButtons(buttonId), buttonId+1); end jToolbar.setComponentZOrder(jButtons(end-2), 5); % Separator jToolbar.setComponentZOrder(jButtons(end-1), 6); % Undo jToolbar.setComponentZOrder(jButtons(end), 7); % Redo jToolbar.revalidate;
Re-arranged uisplittool & uitogglesplittool toolbar buttons
(not as simple as it may sound)
Next week, I will combine the information in this article, with last year’s articles about uiundo, and show how we can create a dynamic figure toolbar drop-down of undo/redo events. Here is a preview to whet your appetite:
undo/redo buttons implemented using uisplittool

Related posts:
uisplittool & uitogglesplittool callbacks Matlab's undocumented uisplittool and uitogglesplittool are powerful toolbar controls - this article explains how to customize their behavior...
Figure toolbar components Matlab's toolbars can be customized using a combination of undocumented Matlab and Java hacks. This article describes how to access existing toolbar icons and how to add non-button toolbar components....
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....
Customizing uiundo This article describes how Matlab's undocumented uiundo undo/redo manager can be customized...

Panel-level uicontrols

Yair Altman — Wed, 24 Nov 2010 18:00:53 +0000

In one of my larger Matlab applications – Integration-lab Debriefing System (IDS, which shall be described in a future dedicated article) – I wanted to present a panel-level checkbox that applies to the entire panel contents. In my particular case, the IDS uipanel contained a Java table (another future topic) with multiple selectable rows, and I needed a global checkbox that selects all (or none) of them at once:
Panel-level ("Objects") checkbox
One way to do this is to calculate the checkbox’s desired position relative to the uipanel and place a regular checkbox-style uicontrol there. The checkbox can even be made a child of the uipanel with ‘normalized’ units, thereby moving and resizing it together with its uipanel parent when the later is moved or resized.
But there’s a much simpler method that want to share. It relies on the undocumented fact that the uipanel‘s title label is a simple hidden uicontrol child of the uipanel handle. This uicontrol handle can be found and simply transformed from a ‘style’='text’ control into a ‘style’='checkbox’ control, as follows:
% Prepare the panel hPanel = uipanel('position',[0.2,0.2,0.4,0.4], 'title','Objects'); % Get the title label's handle warning off MATLAB:Uipanel:HiddenImplementation % turn off warning hTitle = setdiff(findall(hPanel),hPanel); % retrieve title handle hTitle = get(hPanel,'TitleHandle'); % alternative, uses hidden prop % Modify the uicontrol style; add 20 pixel space for the checkbox newPos = get(hTitle,'position') + [0,0,20,0]; % in pixels set(hTitle, 'style','checkbox', 'value',1, 'pos',newPos);
Panel-level checkbox
Note that we can retrieve the title handle using either the uipanel‘s hidden property TitleHandle, or by scanning the panel’s children using findall. I prefer the TitleHandle approach because it does not require modification (minor as it might be) when the panel already contains other children.
The down-side is that since TitleHandle is an undocumented hidden property, it may change its name, its behavior or even be removed in some future Matlab release. In fact, there’s even a Matlab warning about this, unless you turn it off using:
warning off MATLAB:Uipanel:HiddenImplementation
We can use this approach for more complex options panels, as the following example illustrates. Here, we set radio-button controls rather than a checkbox control, and also modify the title color to blue:
% Main panel and basic alternative control hPanelMain = uipanel('pos',[.1,.1,.8,.8], 'Title','Main', 'units','norm'); hAlt1 = uicontrol('parent',hPanelMain, 'units','norm', 'pos',[.1,.8,.5,.1], 'style','radio', 'string','Alternative #1'); % Alternative options panel #2 hAlt2 = uipanel('parent',hPanelMain, 'units','norm', 'pos',[.07,.4,.5,.35], 'title','Alternative #2'); hAlt2Title = get(hAlt2, 'TitleHandle'); newPos = get(hAlt2Title,'position') + [0,0,20,0]; % in pixels set(hAlt2Title, 'style','radio', 'pos',newPos); hAlt2a = uicontrol('parent',hAlt2, 'units','norm', 'pos',[.2,.6,.7,.3], 'style','checkbox', 'string','Option 1'); hAlt2b = uicontrol('parent',hAlt2, 'units','norm', 'pos',[.2,.2,.7,.3], 'style','checkbox', 'string','Option 2'); % Alternative options panel #3 hAlt3 = uipanel('parent',hPanelMain, 'units','norm', 'pos',[.07,.05,.5,.3], 'title','Alternative #3'); hAlt3Title = get(hAlt3, 'TitleHandle'); newPos = get(hAlt3Title,'position') + [0,0,20,0]; % in pixels set(hAlt3Title, 'style','radio', 'pos',newPos, 'ForegroundColor','blue'); hAlt3a = uicontrol('parent',hAlt3, 'units','norm', 'pos',[.2,.5,.7,.3], 'style','popup', 'string',{'Option 3a','Option 3b','Option 3c'});
Advanced panel-level controls
Note that since the hAlt2Title and hAlt3Title radio-buttons are children of their respective uipanel parents, we cannot use a simple uibuttongroup to group them in a mutual-exclusion group. Instead, we must use a dedicated callback function. This is actually quite easy:
% Set the callback for all relevant radio-buttons hButtonGroup = [hAlt1, hAlt2Title, hAlt3Title]; set(hButtonGroup, 'Callback', {@SelectionCb, hButtonGroup}); % This is the callback function that manages mutual exclusion function SelectionCb(hSrc,hEvent,hButtonGroup) otherButtons = setdiff(hButtonGroup,hSrc); set(otherButtons,'value',0); set(hSrc,'value',1); % needed to prevent de-selection end

Related posts:
GUI integrated HTML panel Simple HTML can be presented in a Java component integrated in Matlab GUI, without requiring the heavy browser control....
Inactive Control Tooltips & Event Chaining Inactive Matlab uicontrols cannot normally display their tooltips. This article shows how to do this with a combination of undocumented Matlab and Java hacks....
Customizing Matlab labels Matlab's text uicontrol is not very customizable, and does not support HTML or Tex formatting. This article shows how to display HTML labels in Matlab and some undocumented customizations...
GUI integrated browser control A fully-capable browser component is included in Matlab and can easily be incorporated in regular Matlab GUI applications. This article shows how....

The javacomponent function

Yair Altman — Wed, 04 Aug 2010 18:00:59 +0000

In this blog I have often showed how using Java components can significantly improve Matlab GUI. Here is a simple reminder:
sample Java components integrated in Matlab figure window (click for details)
Matlab is highly integrated with Java, and Java classes can seamlessly be accessed from Matlab. However, displaying Java GUI objects, as opposed to using computational (non-displayable) Java classes, requires using Matlab’s built-in javacomponent function. I have often used this function in past articles here, and today I would like to describe it in more detail.
javacomponent
javacomponent, available since R14 (Matlab 7.0), is yet another semi-documented built-in function. This means that the function is explained in a comment within the function (which can be seen via the edit(‘javacomponent’) command), but nonetheless does not have official help or doc pages. It is an unsupported function originally intended only for internal Matlab use (which of course doesn’t mean we can’t use it).
javacomponent accepts a component class name (a string) or a reference to a previously-created component object, an optional pixel position parameter (default=[20,20,60,20], just like uicontrol; may also contain the strings ‘North’, ‘South’, ‘East’ or ‘West’), and an optional parent container handle (defaults to the current figure). javacomponent then adds the requested component as a child of the requested parent container and wraps it in a Matlab Handle-Graphics (HG) container. javacomponent returns two handles: the Matlab HG container handle and a reference (handle) to the Java component. Here are some sample invocation formats:
>> [jButton, hButton] = javacomponent('javax.swing.JButton') hButton = javahandle_withcallbacks.javax.swing.JButton jButton = 158.002197265625 >> javacomponent('javax.swing.JButton','North'); >> javacomponent(javax.swing.JButton('Click me!'),[50,40,80,30]); >> javacomponent(javax.swing.JButton('Click me!'),'East',hFig);
Note the difference between Java object creation and javacomponent: A pre-created Java object only resides in JVM (Java Virtual Machine) memory, not onscreen, until javacomponent is called to display it. javacomponent only creates objects when a class name (string) parameter is passed to it, as a convenience service to programmers. In practice, it is better to separate these two actions: create the Java object separately, and then pass the object’s reference handle to javacomponent for display. This enables easier error-trapping if the Java object cannot be created or fails to initialize, before attempting to display the object:
% Create and initialize a JScrollBar object try jScrollbar = javaObjectEDT('javax.swing.JScrollBar'); jScrollbar.setOrientation(jScrollbar.HORIZONTAL); catch error('Cannot create Java-based scroll-bar!'); end % Display the object onscreen try javacomponent(jScrollbar,'South'); catch error('Cannot display Java-base scroll-bar!'); end
Note that Java GUI object should always use the EDT (Event Dispatch Thread). The reasons for this were outlined in the recent Matlab-EDT article. For this reason, the JScrollBar is created using the built-in javaObjectEDT function, which exists since R2008a and became documented/supported in R2009a.
javacomponent accepts parent handles that are figures, toolbars, uipanels or uicontainers. Unfortunately, frames are not uicontainers and therefore cannot be used as javacomponent parents. Addendum Aug 6 2010: I made an incorrect statement in the original post here regarding uipanels, which has now been removed. I thank the reader who pointed this out to me.
Once the component has been created, even before it has been placed onscreen, it can be manipulated just like any other Java object. For example:
jButton.setText('Click again!'); % or: set(jButton,'text','…')
The component can also be manipulated to some extent via its HG container, which is of a special Matlab type (class) called hgjavacomponent. This includes getting/setting the component position, position units, visibility, resizing callback, tag, UserData etc:
set(hButton,'units','norm', 'position',[0.2,0.3,0.1,0.05]); set(hButton,'visible','off'); %note: on/off, not true/false as in Java set(hButton,'ResizeFcn',{@resizeCallbackFunc,param1,param2});
When adding Java components which are container classes (descendants of java.awt.Container), it is important to remember that only other Java components can be added to these containers. Matlab objects such as axes (for plots or images) and uicontrols cannot be added since they do not have a Container wrapper. Therefore, feel free to use these Java containers as long as their contained GUI is limited to Java components (JButton, JComboBox etc.). This limitation is very annoying – it would be very useful to be able to place Matlab axes or uicontrols within a JTabbedPane or JSplitPane. Instead, we need to rely on Matlab-based workarounds (uitab and uisplitpane) which are cumbersome compared to their Java counterparts.
javacomponent can be used to place not only Swing components but also Swing-extended components onscreen. Matlab itself almost never uses Swing components as-is, instead preferring to use MathWorks-derived extensions of these components, generally in the com.mathworks.mwswing or com.mathworks.widgets packages. These packages and their classes are all in the static Java classpath and are therefore automatically available for use by Matlab programmers.
Just like Matlab components, javacomponent can also display third-party or your own Swing-derived components. There are quite a few online sources for Swing components that can easily be incorporated in your Matlab application. Simply download the relevant class files, add them to your static (via classpath.txt) or dynamic (via javaaddpath) Java classpath, use javacomponent to display them, then use their reference handle to manipulate their appearance and behavior.
javacomponent, useful as it is, has several limitations. In its string variant (classname) it requires a fully-qualified classname that is not inferred automatically. It also has a different parameters format than uicontrol, which may confuse users. javacomponent also cannot display java.awt.Window components. Finally, it returns two handles – one is a handle() reference of the Java object; the second an HG handle (a double numeric value) of the automatically-created HG container – users are often confused as to which property should be set on which of these handles.
javacomponent-based utility functions
To overcome these limitations, I created UIComponent – a utility that merges uicontrol and javacomponent, available for download on the File Exchange. It accepts all uicontrol parameters and styles, as well as any other displayable Java (Swing/AWT) class. uicontrol‘s calling syntax was preserved for full backwards compatibility. uicomponent uses the built-in uicontrol whenever possible (for standard Matlab styles), and javacomponent for all other Java classes.
uicomponent returns the same two handles that javacomponent returns (namely, a Java reference handle and a numeric HG handle), modified to include each other’s properties and handles (yet another undocumented trick that merits a dedicated article). Here are some examples (more can be found in uicomponent‘s help comment):
uicomponent('style','edit', 'String','hello'); % a regular uicontrol uicomponent(hFig, 'style','edit', 'String','hello'); % specify parent uicomponent('style','jspinner','value',7); uicomponent('style','javax.swing.jslider','tag','myObj'); uicomponent('style','JComboBox',{1,pi,'text'},'editable',true);
Another File Exchange submission which aims to tackle some of javacomponent‘s limitations is Malcolm Lidierth’s JCONTROL. jcontrol uses Matlab’s new object-oriented class approach and has the benefit of returning just a single handle object, which aggregates the handles for both HG container and the contained Java object.

Related posts:
Common javacomponent problems The javacomponent function is very useful for placing Java components on-screen, but has a few quirks. ...
Javacomponent background color This article explains how to align Java component background color with a Matlab color....
The hgfeval function The semi-documented hgfeval function can be useful for callback chaining - this article explains how...
ismembc – undocumented helper function Matlab has several undocumented internal helper functions that can be useful on their own in some cases. This post presents the ismembc function....

Matlab and the Event Dispatch Thread (EDT)

Yair Altman — Wed, 10 Mar 2010 07:18:58 +0000

Once again I welcome guest blogger Matt Whitaker, with the long awaited EDT article.
Java Swing’s Event Dispatch Thread (EDT)
or: why does my GUI foul up?
Matlab for the most part is a single threaded environment. That is, all commands are executed sequentially along a single execution thread. The main exception to this are the Handle Graphics (GUI) components whose operations execute on the Java Event Dispatch Thread (EDT). EDT effects are reflected even in mundane Matlab GUI operations.
If we execute the code below we will probably see nothing until the loop completes and the figure appears with the text label showing ’10000′:
h = figure; txt = uicontrol('Parent',h, 'Style','text', 'String','1'); for n = 1:10000 set(txt,'String',int2str(n)) end %for
By adding a couple of drawnow commands we get the figure and text label to render and then we see the count progress to 10000.
h = figure; txt = uicontrol('Parent',h, 'Style','text', 'String','1'); drawnow; for n = 1:10000 set(txt,'String',int2str(n)); drawnow; end %for
The drawnow function allows the EDT queue to be flushed and the pending graphics operations to be evaluated. This will also happen with pause and several other commands.
If we want to use Swing (or AWT) components in our user interfaces we need to take this multi-threaded environment into account. The Swing toolkit designers decided to make all the Swing components thread un-safe in order to decrease their complexity. As a consequence, all access to Swing components should be done from the event dispatch thread (EDT), to ensure the operations are executed sequentially, at the exact order in which they were dispatched. Any action on a Swing component done on another thread (Matlab’s main processing thread in our case) risks a race-condition or deadlock with the EDT, which could (and often does) result in weird, non-deterministic and non-repetitive behavior – all of which should be avoided in any application which should behave in a precisely deterministic manner.
In Java, the usual pattern to accomplish EDT dispatching is to create a Runnable object, encapsulate the GUI code in the run method of the Runnable object, then pass the Runnable object to the static EventQueue.invokeLater (or EventQueue.invokeAndWait if we need to block operations to get a return value) method.
Runnable runnable = new Runnable() { public void run() { //GUI Code here } } EventQueue.invokeLater(runnable);
There are several functions in Matlab that implement this programming pattern for us: javaObjectEDT, javaMethodEDT, awtinvoke, awtcreate and javacomponent. JavaMethodEDT and javaObjectEDT were introduced in version R2008b (7.7) and are minimally and only partially documented although they have reasonably complete help comments. The other three are semi-documented (meaning they are unsupported but if you edit or type their m-file you’ll see a fairly detailed help section), and although there is some overlap in their functionality they are still available.
javaObjectEDT and javaMethodEDT
javaObjectEDT is the the preferred method since R2008b of creating swing components to be used on the EDT. An object created with javaObjectEDT will have all of its subsequent method calls run on the EDT. This is termed Auto Delegation. Auto-delegation greatly simplifies and increases the readability of code. Note that objects created as a result of method calls may not be implemented on the EDT.
If you have an existing Java object, you can pass it to javaObjectEDT at any time – all its subsequent calls will then onward run on the EDT. Note that this useful functionality is an under-documented javaObjectEDT feature: it is not mentioned in the main help section but only implied from the example.
% Create a button on the EDT btn = javaObjectEDT('javax.swing.JButton'); % this will run on EDT since btn was javaObjectEDT-created btn.setText('Button'); % Create a button NOT on the EDT btn2 = javax.swing.JButton; % Dangerous! call will run on main Matlab thread btn2.setText('Button2'); % modify btn2 so its methods will start running on the EDT javaObjectEDT(btn2); btn2.setText('Button2');
The following example shows the use of javaObjectEDT and javaMethodEDT in a more complex situation using a JTable:
function tableExample hFig = figure; drawnow; %need to get figure rendered %use Yair's createTable to add a javax.swing.JTable %http://www.mathworks.com/matlabcentral/fileexchange/14225-java-based-data-table %wrap ceateTable in javaObjectEDT to put the ensuing method calls on the EDT f = java.awt.Font(java.lang.String('Dialog'),java.awt.Font.PLAIN,14); headers = {'Selected','File','Analysis Routine','Task Status'}; tbl = javaObjectEDT(createTable(hFig,headers,[],false,'Font',f)); %set column 1 to use check boxes and set up a change callback tbl.setCheckBoxEditor(1); jtable = javaObjectEDT(tbl.getTable); %get the underlying Java Table. IMPORTANT: we need to put jtable on the EDT columnModel = javaObjectEDT(jtable.getColumnModel); %now we can now do direct calls safely on jtable selectColumn = javaObjectEDT(columnModel.getColumn(0)); selectColumnCellEditor = selectColumn.getCellEditor; chk = javaMethodEDT('getComponent',selectColumnCellEditor); set(chk,'ItemStateChangedCallback',@chkChange_Callback); %make column three a combo drop down analysisTable = {'Analysis1';'Analysis2';'Analysis3'}; cb = javaObjectEDT('com.mathworks.mwswing.MJComboBox',analysisTable); cb.setEditable(false); cb.setFont(f); set(cb,'ItemStateChangedCallback',@cbChange_Callback); editor = javaObjectEDT('javax.swing.DefaultCellEditor',cb); analysisColumn = javaObjectEDT(columnModel.getColumn(2)); analysisColumn.setCellEditor(editor); %set some column with restrictions selectColumn.setMaxWidth(100); analysisColumn.setPreferredWidth(300); %set the data SELECTED = java.awt.event.ItemEvent.SELECTED; tbl.setData({false,'file1','Analysis2','Analysis2';... true,'file2','Analysis3','Analysis3'}); drawnow; function cbChange_Callback(src,ev) %#ok jRow = jtable.getSelectedRow; stateChange = javaMethodEDT('getStateChange',ev); if stateChange == SELECTED newData = javaMethodEDT('getItem',ev); model = jtable.getModel; javaMethodEDT('setValueAt',model,newData,jRow,3); end %if end %cbChange function chkChange_Callback(src,ev) %#ok chkBox = javaMethodEDT('getItem',ev); if logical(javaMethodEDT('isSelected',chkBox)) beep; %put useful code here else beep; pause(0.1) beep; %put useful code here end %if end %chkChange_Callback end %tableExample
If you are running Matlab R2008a or later, javacomponent uses the javaObjectEDT function to create the returned objects so you do not have to do anything further to these objects to have their calls dispatched on the EDT. Users need to take care that objects added directly to the components created by javacomponent are on the EDT as well as specialized sub-components (e.g. CellRenderers and CellEditors). The overhead of calling javaMethodEDT is fairly small so if in doubt, use it.
javaObjectEDT and its kin first appeared in R2008a, although they only became supported in R2008b. Unfortunately, using them on R2008a sometimes causes hangs and all sorts of other mis-behaviors. This problem was fixed in the R2008b release, when javaObjectEDT became a fully-supported function. The problem with using javaObjectEDT in our application is that if it ever runs on an R2008a platform it might hang! (on Matlab release R2007b and earlier we will get an informative message saying that the javaObjectEDT function does not exist)
For this reason, I am using the following method in my projects:
function result = javaObjEDT(varargin) %Placeholder of Matlab's buggy javaObjectEDT function on R2008a % Programmed by Yair M. Altman: altmany(at)gmail.com % $Revision: 1.2 $ $Date: 2009/01/25 11:31:08 $ try try result = varargin{1}; catch result = []; end v = version; if str2double(v(1:3)) > 7.6 result = builtin('javaObjectEDT',varargin{:}); end catch % never mind end end
Note that javaMethodEDT has the method name as its first input argument, and the object name or reference as its second arg. This is inconsistent with many other Matlab/Java functions, which normally accept the target object as the first argument (compare: invoke, awtinvoke, notify etc.). It also means that we cannot use the familiar obj.javaMethodEDT(methodName) format.
One final note: when javaObjectEDT and javaMethodEDT first appeared in R2008a, they were complemented by the javaObjectMT and javaMethodMT functions, which create and delegate Java objects on the main Matlab computational thread. Their internal documentation says that there are cases when execution must occur on the MT rather than EDT, although I am personally not aware of any such case.
awtcreate and awtinvoke
For users with versions prior to R2008b the user must use the awtcreate function to create objects on the EDT. One huge disadvantage of this older function is that if you have to pass java objects in the parameter list you must use the very cumbersome JNI style notation. For example, for the simple task of setting a button label, one has to use:
btn = awtcreate('javax.swing.JButton'); awtinvoke(btn,'setText(Ljava/lang/String;)','click me')
The other disadvantage is that creating the object using awtcreate does not ensure that its subsequent method calls will be executed on the EDT. The awtinvoke function must be used for each call.
Also, both awtcreate and awtinvoke have some limitations due to bugs in the private parseJavaSignature function (for example, invoking methods which accept a java.lang.Object) which forces one to use the direct call to the method, using the main Matlab thread. This can result in the undesired effects described above. In this situation the best workaround is to call pause(0.01) to allow the event queue to clear.
Versions of javacomponent earlier than R2008a use awtcreate and objects created by these versions must have their subsequent methods called by awtinvoke to be used on the EDT.
A very rare CSSM thread discusses the usage of awtcreate and awtinvoke with some very interesting remarks by MathWorks personnel.
There is an interesting option in awtinvoke that was not carried over into the newer javaMethodEDT. This option allows the user to pass a function handle in the argument list along with its parameters. This option creates an undocumented com.mathworks.jmi.Callback object that has a delayed callback. The delayed callback is dispatched on the EDT so that it will be called once the java method used in awtinvoke is finished. Note that the actual function will still execute on the main Matlab thread the delayed callback will just control when it is called. However this may be useful at times. It is possible to put this functionality into a separate function we can call to delay execution until the event queue is cleared.
%CALLBACKONEDTQUEUE will place a callback on the EDT to asynchronously %run a function. %CALLBBACKONEDTQUEUE(FCN) will run function handle FCN once all previous %methods dispatched to the EDT have completed. %CALLBBACKONEDTQUEUE(FCN,ARG1,ARG2,...) ill run function handle FCN with %arguments ARG1,ARG2...once all previous methods dispatched to the EDT %have completed. %Note that the function is still executing on the main Matlab thread. This %function just delays when it will be called. function callbackOnEDTQueue(varargin) validateattributes(varargin{1},{'function_handle'},{}); callbackObj = handle(com.mathworks.jmi.Callback,'callbackProperties'); set(callbackObj,'delayedCallback',{@cbEval,varargin(:)}); callbackObj.postCallback; function cbEval(src,evt,args) %#ok feval(args{:}); end %cbEval end %callbackOnEDTQueue

Related posts:
Inactive Control Tooltips & Event Chaining Inactive Matlab uicontrols cannot normally display their tooltips. This article shows how to do this with a combination of undocumented Matlab and Java hacks....
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...
Customizing Matlab labels Matlab's text uicontrol is not very customizable, and does not support HTML or Tex formatting. This article shows how to display HTML labels in Matlab and some undocumented customizations...
Additional uicontrol tooltip hacks Matlab's uicontrol tooltips have several limitations that can be overcome using the control's underlying Java object....

Inactive Control Tooltips & Event Chaining

Yair Altman — Wed, 24 Feb 2010 22:34:46 +0000

Once again, I welcome guest blogger Matt Whitaker, who continues his series of articles.
In my last post I explored some tips on tooltips. One of these tips involved displaying tooltips on disabled uicontrols. I explained that displaying tooltips on inactive controls is problematic since Matlab appears to intercept mouse events to these inactive controls, so even setting the tooltip on the underlying Java object will not work: The java object appears not to receive the mouse-hover event and therefore does not “know” that it’s time to display the tooltip.
When Yair and I deliberated this issue, he pointed me to his comment on a previous article showing an undocumented Java technique (Java also has some…) for forcing a tooltip to appear using the ActionMap of the uicontrol’s underlying Java object to get at a postTip action. We discussed using a WindowButtonMotionFcn callback to see if the mouse was above the inactive control, then triggering the forced tooltip display. Yair then went on to remind me and I quote: “you’ll need to chain existing WindowButtonMotionFcn callbacks and take into account ModeManagers that override them.”
Frankly, having written code previously that handles callback chaining, I would rather poke myself in the eye with a fork!
The Image Processing Toolbox has the nice pair of iptaddcallback and iptremovecallback functions that largely handle these issues. But for general Matlab, there seemed to be no alternative until I remembered that events trigger callbacks. I decided to use a listener for the WindowButtonMotion event to detect the mouse motion. Event listeners were briefly explained two weeks ago and deserve a dedicated future article. The advantage of using an event listener is that we don’t disturb any existing WindowButtonMotionFcn callback. We still need to be somewhat careful that our listeners don’t do conflicting things, but it’s a lot easier than trying to manage everything through the single WindowButtonMotionFcn.
A demonstration of this appears below with some comments following (note that this code uses the FindJObj utility):
function inactiveBtnToolTip %Illustrates how to make a tooltip appear on an inactive control h = figure('WindowButtonMotionFcn',@windowMotion,'Pos',[400,400,200,200]); col = get(h,'color'); lbl = uicontrol('Style','text', 'Pos',[10,160,120,20], ... 'Background',col, 'HorizontalAlignment','left'); btn = uicontrol('Parent',h, 'String','Button', ... 'Enable','inactive', 'Pos',[10,40,60,20]); uicontrol('Style','check', 'Parent',h, 'String','Enable button tooltip', ... 'Callback',@chkTooltipEnable, 'Value',1, ... 'Pos',[10,80,180,20], 'Background',col); drawnow; %create the tooltip and postTip action jBtn = findjobj(btn); import java.awt.event.ActionEvent; javaMethodEDT('setToolTipText',jBtn,'This button is inactive'); actionMap = javaMethodEDT('getActionMap',jBtn); action = javaMethodEDT('get',actionMap,'postTip'); actionEvent = ActionEvent(jBtn, ActionEvent.ACTION_PERFORMED, 'postTip'); %get the extents plus 2 pixels of the control to compare to the mouse position btnPos = getpixelposition(btn)+[-2,-2,4,4]; %give a little band around the control left = btnPos(1); right = sum(btnPos([1,3])); btm = btnPos(2); top = sum(btnPos([2,4])); % add a listener on mouse movement events tm = javax.swing.ToolTipManager.sharedInstance; %tooltip manager pointListener = handle.listener(h,'WindowButtonMotionEvent',@figMouseMove); %inControl is a flag to prevent multiple triggers of the postTip action %while mouse remains in the button inControl = false; function figMouseMove(src,evtData) %#ok %get the current point cPoint = evtData.CurrentPoint; if cPoint(1) >= left && cPoint(1) <= right &&... cPoint(2) >= btm && cPoint(2) <= top if ~inControl %we just entered inControl = true; action.actionPerformed(actionEvent); %show the tooltip end %if else if inControl %we just existed inControl = false; %toggle to make it disappear when leaving button javaMethodEDT('setEnabled',tm,false); javaMethodEDT('setEnabled',tm,true); end %if end %if end %gpMouseMove function windowMotion(varargin) %illustrate that we can still do a regular window button motion callback set(lbl,'String',sprintf('Mouse position: %d, %d',get(h,'CurrentPoint'))); drawnow; end %windowMotion function chkTooltipEnable(src,varargin) if get(src,'Value') set(pointListener,'Enable','on'); else set(pointListener,'Enable','off'); end %if end %chkTooltipEnable end %inactiveBtnToolTip
Tooltip on an inactive button
Comments on the code:
The code illustrates that we can successfully add an additional listener to listen for mouse motion events while still carrying out the original WindowButtonMotionFcn callback. This makes chaining callbacks much easier.
The handle.listener object has an Enable property that we can use to temporarily turn the listener on and off. This can be seen in the chkTooltipEnable() callback for the check box in the code above. If we wanted to permanently remove the listener we would simply use delete(pointListener). Note that addlistener adds a hidden property to the object being listened to, so that the listener is tied to the object’s lifecycle. If you create a listener directly using handle.listener you are responsible for it’s disposition. Unfortunately, addlistener fails for HG handles on pre-R2009 Matlab releases, so we use handle.listener directly.
The code illustrates a good practice when tracking rapidly firing events like mouse movement of handling reentry into the callback while it is still processing a previous callback. Here we use a flag called inControl to prevent the postTip action being continuously fired while the mouse remains in the control.
I was unable to determine if there is any corresponding action for the postTip to dismiss tips so I resorted to using the ToolTipManager to toggle its own Enable property to cleanly hide the tooltip as the mouse leaves the control.
Each Matlab callback has an associated event with it. Some of the ones that might be immediately useful at the figure-level are WindowButtonDown, WindowButtonUp, WindowKeyPress, and WindowKeyRelease. They can all be accessed through handle.listener or addlistener as in the code above.
Unfortunately, events do not always have names that directly correspond to the callback names. In order to see the list of available events for a particular Matlab object, use the following code, which relies on another undocumented function – classhandle. Here we list the events for gcf:
>> get(get(classhandle(handle(gcf)),'Events'),'Name') ans = 'SerializeEvent' 'FigureUpdateEvent' 'ResizeEvent' 'WindowKeyReleaseEvent' 'WindowKeyPressEvent' 'WindowButtonUpEvent' 'WindowButtonDownEvent' 'WindowButtonMotionEvent' 'WindowPostChangeEvent' 'WindowPreChangeEvent'
Note that I have made extensive use of the javaMethodEDT function to execute Java methods that affect swing components on Swing’s Event Dispatch Thread. I plan to write about this and related functions in my next article.

Related posts:
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....
GUI integrated browser control A fully-capable browser component is included in Matlab and can easily be incorporated in regular Matlab GUI applications. This article shows how....
Matlab-Java interface using a static control The switchyard function design pattern can be very useful when setting Matlab callbacks to Java GUI controls. This article explains why and how....
Spicing up Matlab uicontrol tooltips Matlab uicontrol tooltips can be spiced-up using HTML and CSS, including fonts, colors, tables and images...

Additional uicontrol tooltip hacks

Yair Altman — Wed, 17 Feb 2010 17:25:52 +0000

Once again I’d like to welcome guest blogger Matthew Whitaker. Today Matt will discuss uicontrol tooltips hacks as the first of several posts that follow a logical thread culminating in the long promised article on the EDT.

A while back Yair wrote a cool article, Spicing up Matlab uicontrol tooltips, describing use of HTML formatting and images in uicontrol tooltips. I want to share some limitations I’ve seen with tooltips and their solution using the Matlab control’s underlying Java object.
Situation 1: Displaying a tooltip on disabled controls
One issue with the stock Matlab uicontrol tooltips is that if you turn the uicontrol’s Enable property to ‘inactive’ or ‘off’, its tooltip no longer displays. This is the behavior that we normally want, but occasionally we wish to display a tooltip on a disabled control, for example, to explain why the control is disabled.
You can use the findjobj utility to find the Java handle for the uicontrol. This handle can then be used to set the tooltip text. The tooltip will display if you disable the control using its Java handle’s Enabled property rather than the Matlab handle’s Enable property:
hButton = uicontrol('String','Button'); drawnow; jButton= findjobj(hButton); set(jButton,'Enabled',false); set(jButton,'ToolTipText','This is disabled for a reason');
As customary for Java objects, its properties can also be set using their corresponding accessor methods:
javaMethodEDT('setEnabled',jButton,false); javaMethodEDT('setToolTipText',jButton,'Button is disabled for a reason');
tooltip on a disabled uicontrol
Unfortunately, this hack does not work for ‘inactive’ controls. There is no direct Java analogy for inactive controls – it’s a Matlab extension. It appears that Matlab somehow intercepts the mouse events associated with inactive controls. My next post will show how event callback can be used to display tooltips for inactive controls.
As an alternative for inactive edit-box controls, we can simulate the inactive behavior by setting the Java object’s Editable property (or by using its setEditable() accessor method), then setting the tooltip. Note that the extremely-useful Java Editable property is unavailable in the Matlab handle, for some inexplicable reason:
hEditbox = uicontrol('String','Edit Text','Style','edit'); drawnow; jEditbox = findjobj(hEditbox); set(jEditbox,'Editable',false); set(jEditbox,'ToolTipText','Text is inactive for a reason');
tooltip on a non-editable editbox
Situation 2: Displaying a tooltip on truncated text
If we want to conditionally display a tooltip for an editbox uicontrol when the text exceeds the control’s width, we can use the TipWhenTruncatedEnabled property (or its corresponding setTipWhenTruncatedEnabled() method). This will display a tooltip with the editbox contents if the string is shown truncated. This saves the user having to scroll through the control to see its contents. I often use this for edit controls that may contain long path names:
hEditbox(1) = uicontrol('Style','edit','Units','norm','Pos',[0.1,0.8,0.4,0.05], 'String','Too Short'); hEditbox(2) = uicontrol('Style','edit','Units','norm','Pos',[0.1,0.7,0.2,0.05], 'String','Long Enough to Display a Tool Tip'); drawnow; jEditbox1 = findjobj(hEditbox(1)); jEditbox2 = findjobj(hEditbox(2)); set(jEditbox1,'TipWhenTruncatedEnabled',true); % property-based alternative javaMethod('setTipWhenTruncatedEnabled',jEditbox2,true); % method-based alternative
TipWhenTruncatedEnabled tooltip
The TipWhenTruncatedEnabled property property is also available for multi-line editboxes, but has (obviously) no effect when scrollbars are present. Also note that setting the TipWhenTruncatedEnabled property to true overrides any previous tooltip that might have been set for the editbox.
Finally, note that the TipWhenTruncatedEnabled property can also be set for the editbox component of popup-menu (aka drop-down) controls, after they have been set to be editable using their Java Editable property (note that both properties are false by default for Matlab uicontrols). In the following screenshot, the drop-down’s editbox component contained an HTML snippet, that is shown unformatted within the edit-box and HTML-formatted in the de-truncated tooltip:
de-truncated HTML-format tooltip
Situation 3: Controlling tooltip timing
As you have probably noticed, there is a slight delay between the time your mouse enters the control and when the tooltip actually appears. If you display a tooltip over a control for sufficiently long the tooltip will then disappear. Sometimes the default delays are too slow or fast for your application. These times can be controlled through the javax.swing.ToolTipManager. The ToolTipManager sets these parameters globally (including for your Matlab desktop components), but they are not persistent between sessions.
Some examples using the ToolTipManager:
btn = uicontrol('String','Button','Tooltip','This is a button.','Pos',[100,100,75,25]); txt = uicontrol('Style','edit','String','Edit Text','Tooltip','This is editable text','Pos',[100,50,75,25]); tm = javax.swing.ToolTipManager.sharedInstance; %static method to get ToolTipManager object initialDelay = javaMethodEDT('getInitialDelay',tm); %get the delay before display in milliseconds (=750 on my system) javaMethodEDT('setInitialDelay',tm,0); %set tooltips to appear immediately dismissDelay = javaMethodEDT('getDismissDelay',tm); %get the delay before the tooltip disappears (=10000 (10 sec) on my system) javaMethodEDT('setDismissDelay',tm,2000); %set the dismiss delay to 2 seconds javaMethodEDT('setEnabled',tm,false); %turns off all tooltips in system (including the Matlab desktop) javaMethodEDT('setEnabled',tm,true); javaMethodEDT('setInitialDelay',tm,initialDelay); javaMethodEDT('setDismissDelay',tm,dismissDelay);
Note that I have made extensive use of the undocumented built-in javaMethodEDT function to execute Java methods that affect Swing components on the Swing Event Dispatch Thread (EDT). I plan to write about EDT following my next post on event callback chaining.

Related posts:
Setting line position in an edit-box uicontrol Matlab uicontrols have many useful features that are only available via Java. Here's how to access them....
Customizing uicontrol border Matlab uicontrol borders can easily be modified - this article shows how...
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...
Spicing up Matlab uicontrol tooltips Matlab uicontrol tooltips can be spiced-up using HTML and CSS, including fonts, colors, tables and images...

Continuous slider callback

Yair Altman — Mon, 08 Feb 2010 09:13:39 +0000

Every few months, a CSSM forum reader asks how to set up a continuously-invoked slider callback: Matlab’s slider uicontrol invokes the user callback only when the mouse button is released, and not continuously while the slider’s thumb is dragged. This functionality was again referred-to yesterday, and I decided it merits a dedicated post.
There are three distinct simple ways to achieve continuous callbacks:
Using Java callbacks
As explained in an earlier article, Matlab uicontrols are basically Java Swing objects that possess a large number of useful callbacks. Matlab sliders’ underlying Java objects, which are really not JSliders but JScrollBars, have an AdjustmentValueChangedCallback property that is useful for our purposes and is accessible using the FindJObj utility. Simply download FindJObj from the File Exchange, and then:
hSlider = uicontrol('style','slider', ...); jScrollBar = findjobj(hSlider); jScrollBar.AdjustmentValueChangedCallback = @myCbFcn; % or: set(jScrollBar,'AdjustmentValueChangedCallback',@myCbFcn)
Where myCbFcn is the Matlab callback function that will be invoked continuously when the arrow buttons are depressed or the slider’s thumb is dragged.
Using an event listener
An alternative to the Java route is to use Matlab’s undocumented handle.listener function to listen to the slider’s Action event, as follows:
hListener = handle.listener(hSlider,'ActionEvent',@myCbFcn);
This alternative is used by Matlab’s own imscrollpanel function:
if isJavaFigure % Must use these ActionEvents to get continuous events fired as slider % thumb is dragged. Regular callbacks on sliders give only one event % when the thumb is released. hSliderHorListener = handle.listener(hSliderHor,... 'ActionEvent',@scrollHorizontal); hSliderVerListener = handle.listener(hSliderVer,... 'ActionEvent',@scrollVertical); setappdata(hScrollpanel,'sliderListeners',... [hSliderHorListener hSliderVerListener]); else % Unfortunately, the event route is only available with Java Figures, % so platforms without Java Figure support get discrete events only % when the mouse is released from dragging the slider thumb. set(hSliderHor,'callback',@scrollHorizontal) set(hSliderVer,'callback',@scrollVertical) end
Using a property listener
The handle.listener function can also be used to listen to property value changes. In our case, set a post-set listener, that gets triggered immediately following Value property updates, as follows:
hhSlider = handle(hSlider); hProp = findprop(hhSlider,'Value'); % a schema.prop object hListener = handle.listener(hhSlider,hProp,'PropertyPostSet',@myCbFcn);
In addition to ‘PropertyPostSet’, we could also listen on ‘PropertyPreSet’, which is triggered immediately before the property is modified. There are also corresponding ‘*Get’ options. In relatively old Matlab releases (I believe R2007b and earlier, but I’m not certain), the option names were simply ‘PostSet’, ‘PreSet’ etc., without the ‘Property’ prefix.
Do you know of any other way to achieve continuous callbacks? If so, I would be delighted to hear in the comments section below.

Related posts:
Controlling callback re-entrancy Callback reentrancy is a major problem for frequently-fired events. Luckily, it can easily be solved....
Inactive Control Tooltips & Event Chaining Inactive Matlab uicontrols cannot normally display their tooltips. This article shows how to do this with a combination of undocumented Matlab and Java hacks....
Setting listbox mouse actions Matlab listbox uicontrol can be modified to detect mouse events for right-click context menus, dynamic tooltips etc....
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...

Customizing listbox & editbox scrollbars

Yair Altman — Mon, 01 Feb 2010 17:40:03 +0000

A few days ago, a CSSM forum reader asked how to modify Matlab’s listbox scrollbars. Another user asked how to configure line-wrapping. I thought this is a good opportunity to describe how listbox and editbox scrollbars can be customized. The timing is particularly opportune, after I have recently described how the Matlab Editbox can be customized by accessing its underlying Java object using the FindJObj utility.
Both the listbox and the multi-line editbox uicontrols share a similar design: a multi-line Java control embedded within a JViewport within a JScrollPane (note that for historical reasons, the Java view-port class is called JViewport rather than the more standard camel-cased JViewPort). In addition to the view-port, the containing scroll-pane also contains two scrollbars (horizontal and vertical), as expected from standard Java scroll-panes.
JScrollPane components
Scrollbar policies
Control of the scroll-pane’s scrollbar behavior is done via the JScrollPane’s VerticalScrollBarPolicy and HorizontalScrollBarPolicy properties.
VerticalScrollBarPolicy accepts the self-explanatory values of:
VERTICAL_SCROLLBAR_ALWAYS (=22)
VERTICAL_SCROLLBAR_NEVER (=21)
and VERTICAL_SCROLLBAR_AS_NEEDED (=20)
HorizontalScrollBarPolicy accepts:
HORIZONTAL_SCROLLBAR_ALWAYS (=32)
HORIZONTAL_SCROLLBAR_NEVER (=31)
and HORIZONTAL_SCROLLBAR_AS_NEEDED (=30)
All these properties are static enumerated constants that can be referred using either their Java notation (e.g., JScrollPane.VERTICAL_SCROLLBAR_ALWAYS) or their equivalent numeric values. Using the non-numeric format is better, since it is more readable and the numeric values may change, but the choice is yours.
By default, Matlab implements a VerticalScrollBarPolicy of VERTICAL_SCROLLBAR_ALWAYS for sufficiently tall uicontrols (>20-25 pixels, which practically means always) and VERTICAL_SCROLLBAR_NEVER for shorter uicontrols.
For the horizontal scrollbar, Matlab implements a HorizontalScrollBarPolicy of HORIZONTAL_SCROLLBAR_NEVER for all editboxes and for narrow listboxes (<35 pixels), and HORIZONTAL_SCROLLBAR_AS_NEEDED for wide listboxes.
These settings are generally satisfactory. However, in some cases users may wish to modify the settings. For example, the default VerticalScrollBarPolicy setting of VERTICAL_SCROLLBAR_ALWAYS causes the vertical scrollbar to appear even when unneeded (the entire editbox content is visible). Also, we may wish to have a horizontal scrollbar on narrow listboxes and editboxes, something that the standard HORIZONTAL_SCROLLBAR_NEVER prevents. In both cases, a *_SCROLLBAR_AS_NEEDED policy might be more appropriate.
To modify these settings, we simply need to get the uicontrol’s underlying Java reference handle (using the FindJObj utility), and modify the appropriate property. For example:
% Create a multi-line (Max>1) editbox uicontrol hEditbox = uicontrol('style','edit', 'max',5, ...); % Get the Java scroll-pane container reference jScrollPane = findjobj(hEditbox); % Modify the scroll-pane's scrollbar policies % (note the equivalent alternative methods used below) set(jScrollPane,'VerticalScrollBarPolicy',20); % or: jScrollPane.VERTICAL_SCROLLBAR_AS_NEEDED jScrollPane.setHorizontalScrollBarPolicy(30); % or: jScrollPane.HORIZONTAL_SCROLLBAR_AS_NEEDED
default scrollbars (VERTICAL_SCROLLBAR_ALWAYS)

non-default scrollbars (VERTICAL_SCROLLBAR_AS_NEEDED)
Note that updating the uicontrol handle (hEditbox)’s Position property has the side-effect of automatically reverting the scrollbar policies to their default values (HORIZONTAL_SCROLLBAR_NEVER and VERTICAL_SCROLLBAR_ALWAYS/NEVER). This also happens whenever the uicontrol is resized interactively (by resizing its container figure window, for example). It is therefore advisable to set jScrollPane’s ComponentResizedCallback property to “unrevert” the policies:
cbStr = sprintf('set(gcbo,''VerticalScrollBarPolicy'',%d)', ... jScrollPane.VERTICAL_SCROLLBAR_AS_NEEDED); hjScrollPane = handle(jScrollPane,'CallbackProperties'); set(hjScrollPane,'ComponentResizedCallback',cbStr);
Line-wrapping
By default, line-wrapping is turned on, effectively disabling horizontal scrolling (which is why Matlab set the HorizontalScrollBarPolicy to HORIZONTAL_SCROLLBAR_NEVER. However, in some cases it may be more useful to turn line-wrapping off and horizontal scrolling on using the TextArea’s setWrapping() method. Here’s a usage example:
jViewPort = jScrollPane.getViewport; jEditbox = jViewPort.getComponent(0); jEditbox.setWrapping(false); % do *NOT* use set(...)!!! newPolicy = jScrollPane.HORIZONTAL_SCROLLBAR_AS_NEEDED; set(jScrollPane,'HorizontalScrollBarPolicy',newPolicy);
multi-line editbox with wrapping on
multi-line editbox with wrapping off
Notes:
setWrapping() only works for the default EditorKit, and fails for HTMLEditorKit – This is due to HTML’s inherent wrapping behavior, as can easily be seen in any browser webpage.
while setWrapping() may seem like a regular setter method for a Wrapping property, in reality it is not. Actually, set(jEditbox,’wrapping’,flag) may crash Matlab. So, always use the setWrapping(flag) method variant, which is entirely safe.

Related posts:
Rich Matlab editbox contents The Matlab editbox uicontrol does not handle HTML contents as do other uicontrols. In this article I show how this limitation can be removed....
Setting listbox mouse actions Matlab listbox uicontrol can be modified to detect mouse events for right-click context menus, dynamic tooltips etc....
Customizing uicontrol border Matlab uicontrol borders can easily be modified - this article shows how...
Customizing Matlab labels Matlab's text uicontrol is not very customizable, and does not support HTML or Tex formatting. This article shows how to display HTML labels in Matlab and some undocumented customizations...

Undocumented Matlab » UI controls

Uitable cell colors

First pass – basic data table

Second pass – auto-resizing that actually works…

Third pass – adding colors

Tri-state checkbox

CheckBoxTree

Modifying the standard Matlab checkbox uicontrol

Displaying as an independent Java control

Alternative controls

uisplittool & uitogglesplittool

So what are uisplittool and uitogglesplittool?

Adding uisplittool and uitogglesplittool to a toolbar

Re-arranging the toolbar controls placement

Panel-level uicontrols

The javacomponent function

javacomponent

javacomponent-based utility functions

Matlab and the Event Dispatch Thread (EDT)

Java Swing’s Event Dispatch Thread (EDT)
or: why does my GUI foul up?

javaObjectEDT and javaMethodEDT

awtcreate and awtinvoke

Inactive Control Tooltips & Event Chaining

Additional uicontrol tooltip hacks

Situation 1: Displaying a tooltip on disabled controls

Situation 2: Displaying a tooltip on truncated text

Situation 3: Controlling tooltip timing

Continuous slider callback

Using Java callbacks

Using an event listener

Using a property listener

Customizing listbox & editbox scrollbars

Scrollbar policies

Line-wrapping

Undocumented Matlab » UI controls

Uitable cell colors

First pass – basic data table

Second pass – auto-resizing that actually works…

Third pass – adding colors

Tri-state checkbox

CheckBoxTree

Modifying the standard Matlab checkbox uicontrol

Displaying as an independent Java control

Alternative controls

uisplittool & uitogglesplittool

So what are uisplittool and uitogglesplittool?

Adding uisplittool and uitogglesplittool to a toolbar

Re-arranging the toolbar controls placement

Panel-level uicontrols

The javacomponent function

javacomponent

javacomponent-based utility functions

Matlab and the Event Dispatch Thread (EDT)

Java Swing’s Event Dispatch Thread (EDT)or: why does my GUI foul up?

javaObjectEDT and javaMethodEDT

awtcreate and awtinvoke

Inactive Control Tooltips & Event Chaining

Additional uicontrol tooltip hacks

Situation 1: Displaying a tooltip on disabled controls

Situation 2: Displaying a tooltip on truncated text

Situation 3: Controlling tooltip timing

Continuous slider callback

Using Java callbacks

Using an event listener

Using a property listener

Customizing listbox & editbox scrollbars

Scrollbar policies

Line-wrapping

Java Swing’s Event Dispatch Thread (EDT)
or: why does my GUI foul up?