Undocumented Matlab » Icons

Uitab colors, icons and images

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

A few months ago I published a post about Matlab’s semi-documented tab-panel functionality, where I promised a follow-up article on tab customizations. A reader of this blog asked a related question earlier today, so I decided it’s about time I fulfilled this promise.

As with most Matlab controls, the underlying Java component enables far greater customization than possible using plain Matlab. Today I will show three specific customizations. We start with a basic tab group, and get the underlying Java component:

% Prevent an annoying warning msg
warning off MATLAB:uitabgroup:OldVersion
 
% Prepare a tab-group consisting of two tabs
hTabGroup = uitabgroup; drawnow;
tab1 = uitab(hTabGroup, 'title','Panel 1');
a = axes('parent', tab1); surf(peaks);
tab2 = uitab(hTabGroup, 'title','Panel 2');
uicontrol(tab2, 'String','Close', 'Callback','close(gcbf)');
 
% Get the underlying Java reference (use hidden property)
jTabGroup = getappdata(handle(hTabGroup),'JTabbedPane');

Foreground & background tab colors

We can set the tab font color using setForeground() and setForegroundAt(), or via HTML. Note that setForegroundAt() overrides anything set by setForeground(). Also remember that Java uses 0-based indexing so tab #1 is actually the second tab:

% Equivalent manners to set a red tab foreground:
jTabGroup.setForegroundAt(1,java.awt.Color(1.0,0,0)); % tab #1
jTabGroup.setTitleAt(1,'Panel 2');
jTabGroup.setForeground(java.awt.Color.red);

Unfortunately, the corresponding setBackgroundAt(tabIndex,color) method has no visible effect, and the Matlab-extended tabs keep their white/gray backgrounds. A similar attempt to modify the tab’s BackgroundColor property fails, since Matlab made this property unmodifiable (=’none’). A simple solution is to use a CSS background:

% Equivalent manners to set a yellow tab background:
jTabGroup.setTitleAt(0,'Panel 1');
jTabGroup.setTitleAt(0,'Panel 1');

uitabgroup with non-default forground and background tab colors and fonts

We can set the foreground text color using the CSS color directive. Similarly, we can also set a background gradient image for the tabs, using the CSS background-image directive. Which leads us to our next customization:

Icon images

Icons and sub-components can be added to the tabs. Unfortunately, for some reason that I do not fully understand, jTabGroup.setIconAt() has no apparent effect. The solution is to set our own custom control as the requested tab, and add our icon (or other customizations) to it. Here is a simple example:

% Add an icon to tab #1 (=second tab)
icon = javax.swing.ImageIcon('C:\Yair\save.gif');
jLabel = javax.swing.JLabel('Tab #2');
jLabel.setIcon(icon);
jTabGroup.setTabComponentAt(1,jLabel);	% Tab #1 = second tab
 
% Note: icon is automatically grayed when label is disabled
jLabel.setEnabled(false);
jTabGroup.setEnabledAt(1,false);  % disable only tab #1

tab with a custom icon (enabled & disabled)

Close buttons

Now let’s try a more complex example, of adding a close (‘x’) button to one of the tabs. Generalizing this code snippet is left as an exercise to the reader:

% First let's load the close icon
jarFile = fullfile(matlabroot,'/java/jar/mwt.jar');
iconsFolder = '/com/mathworks/mwt/resources/';
iconURI = ['jar:file:/' jarFile '!' iconsFolder 'closebox.gif'];
icon = javax.swing.ImageIcon(java.net.URL(iconURI));
 
% Now let's prepare the close button: icon, size and callback
jCloseButton = handle(javax.swing.JButton,'CallbackProperties');
jCloseButton.setIcon(icon);
jCloseButton.setPreferredSize(java.awt.Dimension(15,15));
jCloseButton.setMaximumSize(java.awt.Dimension(15,15));
jCloseButton.setSize(java.awt.Dimension(15,15));
set(jCloseButton, 'ActionPerformedCallback',@(h,e)delete(tab2));
 
% Now let's prepare a tab panel with our label and close button
jPanel = javax.swing.JPanel;	% default layout = FlowLayout
set(jPanel.getLayout, 'Hgap',0, 'Vgap',0);  % default gap = 5px
jLabel = javax.swing.JLabel('Tab #2');
jPanel.add(jLabel);
jPanel.add(jCloseButton);
 
% Now attach this tab panel as the tab-group's 2nd component
jTabGroup.setTabComponentAt(1,jPanel);	% Tab #1 = second tab

tab with an attached close button

Next week’s article will conclude the series on Matlab’s uitab. Any particular customization you are interested in? Please do post a comment.

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

Figure toolbar components

Yair Altman — Thu, 27 Aug 2009 16:31:36 +0000

Toolbars are by now a staple of modern GUI design. An unobtrusive list of small icons enables easy access to multiple application actions without requiring large space for textual descriptions. Unfortunately, the built-in documented support for the Matlab toolbars is limited to adding icon buttons via the uipushtool and uitoggletool functions, and new toolbars containing them via the uitoolbar function. In this post I will introduce several additional customizations that rely on undocumented features.
This article will only describe figure toolbars. However, much of the discussion is also relevant to the desktop (Command Window) toolbars and interested users can adapt it accordingly.
Accessing toolbar buttons – undo/redo
Let’s start by adding undo/redo buttons to the existing figure toolbar. I am unclear why such an elementary feature was not included in the default figure toolbar, but this is a fact that can easily be remedied. In another post I describe uiundo, Matlab’s semi-documented support for undo/redo functionality, but for the present let’s assume we already have this functionality set up.
First, let’s prepare our icons, which are basically a green-filled triangle icon and its mirror image:
% 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],:);
Now let’s add these icons to the default figure toolbar:
% Add the icon (and its mirror image = undo) to the latest toolbar hUndo = uipushtool('cdata',cdataUndo, 'tooltip','undo', 'ClickedCallback','uiundo(gcbf,''execUndo'')'); hRedo = uipushtool('cdata',cdataRedo, 'tooltip','redo', 'ClickedCallback','uiundo(gcbf,''execRedo'')');
Undo/redo buttons
In the preceding screenshot, since no figure toolbar was previously shown, uipushtool added the undo and redo buttons to a new toolbar. Had the figure toolbar been visible, then the buttons would have been added to its right end. Since undo/redo buttons are normally requested near the left end of toolbars, we need to rearrange the toolbar buttons:
hToolbar = findall(hFig,'tag','FigureToolBar'); %hToolbar = get(hUndo,'Parent'); % an alternative hButtons = findall(hToolbar); set(hToolbar,'children',hButtons([4:end-4,2,3,end-3:end])); set(hUndo,'Separator','on');
Undo/redo buttons in their expected positions
We would normally preserve hUndo and hRedo, and modify their Tooltip and Visible/Enable properties in run-time, based on the availability and name of the latest undo/redo actions:
% Retrieve redo/undo object undoObj = getappdata(hFig,'uitools_FigureToolManager'); if isempty(undoObj) undoObj = uitools.FigureToolManager(hFig); setappdata(hFig,'uitools_FigureToolManager',undoObj); end % Customize the toolbar buttons latestUndoAction = undoObj.CommandManager.peekundo; if isempty(latestUndoAction) set(hUndo, 'Tooltip','', 'Enable','off'); else tooltipStr = ['undo' latestUndoAction.Name]; set(hUndo, 'Tooltip',tooltipStr, 'Enable','on'); end
We can easily adapt the method I have just shown to modify/update existing toolbar icons: hiding/disabling them etc. based on the application needs at run-time.
Adding non-button toolbar components – undo dropdown
A more advanced customization is required if we wish to present the undo/redo actions in a drop-down (combo-box). Unfortunately, since Matlab only enables adding uipushtools and uitoggletools to toolbars, we need to use a Java component. The drawback of using such a component is that it is inaccessible via the toolbar’s Children property (implementation of the drop-down callback function is left as an exercise to the reader):
% Add undo dropdown list to the toolbar jToolbar = get(get(hToolbar,'JavaContainer'),'ComponentPeer'); if ~isempty(jToolbar) undoActions = get(undoObj.CommandManager.UndoStack,'Name'); jCombo = javax.swing.JComboBox(undoActions(end:-1:1)); set(jCombo, 'ActionPerformedCallback', @myUndoCallbackFcn); jToolbar(1).add(jCombo,5); %5th position, after printer icon jToolbar(1).repaint; jToolbar(1).revalidate; end % Drop-down (combo-box) callback function function myUndoCallbackFcn(hCombo,hEvent) itemIndex = get(hCombo,'SelectedIndex'); % 0=topmost item itemName = get(hCombo,'SelectedItem'); % user processing needs to be placed here end
Undo dropdown list
Note that the javax.swing.JComboBox constructor accepts a cell-array of strings (undoActions in the snippet above). A user-defined dropdownlist might be constructed as follows (also see a related CSSM thread):
... dropdownStrings = {'here', 'there', 'everywhere'}; jCombo = javax.swing.JComboBox(dropdownStrings); set(jCombo, 'ActionPerformedCallback', @myUndoCallbackFcn); jToolbar(1).addSeparator; jToolbar(1).add(jCombo); % at end, following a separator mark jToolbar(1).repaint; jToolbar(1).revalidate; ...
A similar approach can be used to add checkboxes, radio-buttons and other non-button controls.
In next week’s post I will describe how the toolbar can be customized using undocumented functionality to achieve a non-default background, a floating toolbar (“palette”) effect and other interesting customizations. If you have any specific toolbar-related request, I’ll be happy to hear in the comments section below.

Related posts:
Figure toolbar customizations Matlab's toolbars can be customized using a combination of undocumented Matlab and Java hacks. This article describes how to customize the Matlab figure toolbar....
uicontrol side-effect: removing figure toolbar Matlab's built-in uicontrol function has a side-effect of removing the figure toolbar. This was undocumented until lately. This article describes the side-effect behavior and how to fix it....
uisplittool & uitogglesplittool Matlab's undocumented uisplittool and uitogglesplittool are powerful controls that can easily be added to Matlab toolbars - this article explains how...
uisplittool & uitogglesplittool callbacks Matlab's undocumented uisplittool and uitogglesplittool are powerful toolbar controls - this article explains how to customize their behavior...

Setting system tray popup messages

Yair Altman — Tue, 31 Mar 2009 23:09:25 +0000

Continuing my previous post about setting system-tray icons, I will now show how to set informational popup messages next to these icons.
Asynchronous informational messages can be presented next to the sys-tray icon, in a fashion similar to what we came to expect from modern programs. This could be used to indicate some unexpected event that was detected, or the end of a complex calculation phase. The message title, text and severity icon are all customizable.
Unfortunately, the Java method used to display messages, java.awt.TrayIcon.displayMessage(), expects an object of type java.awt.TrayIcon.MessageType, which is an enumeration within the TrayIcon class. However, Matlab’s dot-notation does not recognize what should have been the following correct notation, so we need to resort to Java reflection:
>> trayIcon.displayMessage('title','info msg',TrayIcon.MessageType.INFO); ??? No appropriate method or public field MessageType for class java.awt.TrayIcon >> trayIconClasses = trayIcon.getClass.getClasses; >> trayIconClasses(1) ans = class java.awt.TrayIcon$MessageType <= hurray!!! >> MessageTypes = trayIconClasses(1).getEnumConstants MessageTypes = java.awt.TrayIcon$MessageType[]: [java.awt.TrayIcon$MessageType] <= 1: ERROR [java.awt.TrayIcon$MessageType] <= 2: WARNING [java.awt.TrayIcon$MessageType] <= 3: INFO [java.awt.TrayIcon$MessageType] <= 4: NONE >> trayIcon.displayMessage('title','info msg',MessageTypes(3));
and another example, now with a WARNING icon:
If the title string is left empty, then neither title nor the severity icon will be displayed. The message can still be manually dismissed by clicking within its boundaries:

Informational popup messages are automatically aligned and positioned by the system. Messages are automatically dismissed by the system after some time, if not dismissed by the user first. The exact time is determined by system and user activity and other such external factors. Informational messages replace one another, if the previous message has still not been cleared by the user.
I have created a utility function called SYSTRAY, which is a convenience function that facilitates the setup and update of system tray icons and messages. SYSTRAY (with source code) can be downloaded from the File Exchange.
I would be happy to hear if and how you’re using the new system-tray functionality in your application – let me know below.

Related posts:
Setting system tray icons System-tray icons can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....
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....
Changing system preferences programmatically Matlab user/system preferences can be changed programmatically, from within your Matlab application or from the Matlab desktop command prompt. This post details how....
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....

Setting system tray icons

Yair Altman — Tue, 24 Mar 2009 20:47:54 +0000

Java 1.6, included in Matlab releases since Matlab 7.5 (R2007b), enables programmatic access to system tray icons on such systems that support this functionality (Windows, Linux and possibly others). If the SystemTray object indicates that it isSupported(), then a TrayIcon can be added, along with an associated tooltip and popup menu:
sysTray = java.awt.SystemTray.getSystemTray; if (sysTray.isSupported) myIcon = fullfile(matlabroot,'/toolbox/matlab/icons/matlabicon.gif'); iconImage = java.awt.Toolkit.getDefaultToolkit.createImage(myIcon); trayIcon = java.awt.TrayIcon(iconImage, 'initial tooltip'); trayIcon.setToolTip('click this icon for applicative context menu'); end
sample system tray icon
The icon image can be made to automatically resize to the system-tray dimensions, using the trayIcon.setImageAutoSize(true) method (by default the icon image will maintain its original size, getting cropped or appearing small as the case may be).
Of course, after initial setup, all the sys-tray icon’s properties (icon image, popup, tooltip etc.) can be modified with convenient set methods (setImage(), setPopupMenu(), setTooltip()) or via Matlab’s set() function.
Icon popup menus are very similar in concept to Matlab uicontextmenus. Unfortunately, they need to be programmed separately since Java does not accept uicontextmenu handles. This is actually quite easy, as the following code snippet shows:
% Prepare the context menu menuItem1 = java.awt.MenuItem('action #1'); menuItem2 = java.awt.MenuItem('action #2'); menuItem3 = java.awt.MenuItem('action #3'); % Set the menu items' callbacks set(menuItem1,'ActionPerformedCallback',@myFunc1); set(menuItem2,'ActionPerformedCallback',{@myfunc2,data1,data2}); set(menuItem3,'ActionPerformedCallback','disp(''action #3...'')'); % Disable one of the menu items menuItem2.setEnabled(0); % or: set(menuItem2,'Enabled','off'); % Add all menu items to the context menu (with internal separator) jmenu = java.awt.PopupMenu; jmenu.add(menuItem1); jmenu.add(menuItem2); jmenu.addSeparator; jmenu.add(menuItem3); % Finally, attach the context menu to the icon trayIcon.setPopupMenu(jmenu); % or: set(trayIcon,'PopupMenu',jmenu);
Tray icon context (right-click) menu
Unfortunately, neither the icon tooltip nor its popup menu supports HTML. The reason is that SystemTray is actually not part of Swing at all. The system-tray functionality resides in the java.awt package, and does not inherit javax.swing.JLabel’s (and Matlab uicontrols) support for HTML.
I have created a utility function called SYSTRAY, which is a convenience function that facilitates the setup and update of system tray icons. SYSTRAY (with source code) can be downloaded from the File Exchange.
In a separate post, I shall detail how informational pop-up messages can be attached to system-tray icons. This requires a bit of Java-hacking, so is beyond the scope of a single blog post.
Please note the new TODO page, which details my future posts. I would be happy to hear your requests for new topics, or telling me which topics you’d like to see earlier than others.
Addendum (May 15, 2009): A kind reader today left a comment on another post of this blog with a solution for some reported Java exceptions when using systray in Matlab R2008b onward.

Related posts:
Setting system tray popup messages System-tray icons and messages can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....
Uitab colors, icons and images Matlab's semi-documented tab panels can be customized using some undocumented hacks...
Changing system preferences programmatically Matlab user/system preferences can be changed programmatically, from within your Matlab application or from the Matlab desktop command prompt. This post details how....
Setting listbox mouse actions Matlab listbox uicontrol can be modified to detect mouse events for right-click context menus, dynamic tooltips etc....