Undocumented Matlab

I last week’s post, Setting status-bar text, I showed how to set the status-bar text in Matlab figures and the main desktop. But Matlab status-bars are Java containers in which we can add GUI controls, not just simple text labels. In this post I will show how to do this for Matlab 7 figures.

Let’s return to the two alternatives I’ve presented in my previous post for setting a Matlab 7 figure status-bar text:

% Alternative #1 (hFig = requested figure's handle)
jFrame = get(hFig,'JavaFrame');
jFigPanel = get(jFrame,'FigurePanelContainer');
jRootPane = jFigPanel.getComponent(0).getRootPane;
jRootPane = jRootPane.getTopLevelAncestor;
statusbarObj = jRootPane.getStatusBar;
statusbarObj.setText(statusText);
jRootPane.setStatusBarVisible(1);
 
% Alternative #2
jFrame = get(hFig,'JavaFrame');
jRootPane = jFrame.fFigureClient.getWindow;
statusbarObj = com.mathworks.mwswing.MJStatusBar;
jRootPane.setStatusBar(statusbarObj);
statusbarObj.setText(statusText);

The first alternative uses the default status-bar (a com.mathworks.mwswing.MJStatusBar object) which Matlab automatically creates with each figure. This object is created as invisible, so we need to set its text (via its setText method), and then make it visible (via its ancestor’s root-pane’s setStatusBarVisible method – setting the object itself to visible is not enough). The alternative is to replace the default status-bar object with a user-specified container (in this case, we use a new instance of com.mathworks.mwswing.MJStatusBar).

Last week I forgot to mention that only the second alternative works in the general case – it appears that the first alternative often fails because figures are not created with the default statusbar on many platforms/Matlab release (I’m not sure exactly which). My StatusBar utility on the MathWorks File Exchange, which I mentioned in last week’s post, takes care of these nuances, and automatically creates the status bar object if it is missing.

In any case, using these two code snippets as a baseline, we can customize any Java container that we wish. We are not limited to text labels. The default ststusbar container, MJStatusBar, only includes a single JLabel-derived component that stores the text message. We can add other components to this container. For example, let’s add a simple progress-bar:

jFrame = get(hFig,'JavaFrame');
jRootPane = jFrame.fFigureClient.getWindow;
statusbarObj = com.mathworks.mwswing.MJStatusBar;
 
% Add a progress-bar to left side of standard MJStatusBar container
jProgressBar = javax.swing.JProgressBar;
set(jProgressBar, 'Minimum',0, 'Maximum',500, 'Value',234);
statusbarObj.add(jProgressBar,'West');  % 'West' => left of text; 'East' => right
% Beware: 'East' also works but doesn't resize automatically
 
% Set this container as the figure's status-bar
jRootPane.setStatusBar(statusbarObj);
 
% Note: setting setStatusBarVisible(1) is not enough to display the status-bar
% - we also need to call setText(), even if only with an empty string ''
statusbarObj.setText('testing 123...');
jRootPane.setStatusBarVisible(1);

Status bar with a simple progress-bar

We can of course use the progress-bar and status-bar handles to modify their appearance within our code, for example within some loop. For example:

numIds = length(allIds);
set(jProgressBar, 'StringPainted','on', 'Maximum',numIds, 'Value',0);
for id = 1 : numIds
 
   % Update status bar
   set(jProgressBar, 'StringPainted','on', 'Value',id);
   msg = 'Processing %d of %d (%.1f%%)...';
   statusbarObj.setText(sprintf(msg,id,numIds,100*id/numIds));
 
   % do something useful...
 
end  % for all Ids
 
% Some final status-bar updates...
% Hide the progress-bar
jProgressBar.setVisible(0);
 
% Hide the corner grip
cornerGrip = statusbarObj.getParent.getComponent(0);
cornerGrip.setVisible(0);  % or: set(cornerGrip,'Visible','off')
 
% Set a red foreground & yellow background to status bar text
statusbarObj.setText('All done - congratulations!!!');
statusbarTxt = statusbarObj.getComponent(0);
statusbarTxt.setForeground(java.awt.Color.red);
set(statusbarTxt,'Background','yellow');
set(statusbarTxt,'Background',[1,1,0]);  % an alternative…

Modifying status bar properties in run-time

The progress-bar component was just a simple example of how to present non-intrusive controls/information in the figure status bar. Other controls (buttons, checkboxes etc.) can similarly be added.

Note that the status-bar’s corner-grip (at its far right) is not a sub-component of the statusbarObj object like the label, but rather of its parent JPanel container. This is easily be seen using my FindJObj utility on the MathWorks File Exchange:

Status bar with a simple progress-bar

One final note: The status bar is 20 pixels high across the entire bottom of the figure. It hides everything between pixel heights 0-20, even parts of uicontrols, regardless of who was created first or the relative ComponentZOrder in the frame’s ContentPane:

% Add a "Next phase" button to the right of the text
jb = javax.swing.JButton('Next phase >');
jbh = handle(jb,'CallbackProperties');
set(jbh, 'ActionPerformedCallback', @nextPhaseFunction);
statusbarObj.add(jb,'East');
%note: we might need jRootPane.setStatusBarVisible(0)
% followed by jRootPane.setStatusBarVisible(1) to repaint
 
% Add a simple Matlab uicontrol, obscured by the status-bar
hb = uicontrol('string','click me!', 'position',[10,15,70,30]);

Adding controls inside and outside the status-bar

If you have made interesting use of Matlab’s status-bar, please share them in the comments section below.

Related posts:

1. Setting status-bar text The Matlab desktop and figure windows have a usable statusbar which can only be set using undocumented methods. This post shows how to set the status-bar text....
2. 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....
3. 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...
4. Setting listbox mouse actions Matlab listbox uicontrol can be modified to detect mouse events for right-click context menus, dynamic tooltips etc....
5. 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....
6. Setting system tray icons System-tray icons can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....

Tags: FindJObj, GUI, Java, JavaFrame

Categories: Figure window, GUI, Java, Medium risk of breaking in future versions

This entry was posted on Thursday, July 30th, 2009 at 3:09 am PST
You can follow any responses to this entry through the RSS 2.0 feed.
You can leave a response, or trackback from your own site.

(No Ratings Yet)  Loading ...

Print