Last week, I described how to access existing Matlab figure toolbar icons and how to add non-button toolbar components. Today, I describe how the toolbar itself can be customized using undocumented functionality and properties.
All the important undocumented customizations can only be accessed via the toolbar’s Java handle, which is retrieved so:
hToolbar = findall(hFig,'tag','FigureToolBar'); jToolbar = get(get(hToolbar,'JavaContainer'),'ComponentPeer');
One interesting functionality is enabling a floating toolbar, via jToolbar.setFloatable(1). The toolbar can then be dragged from its docked position at the top of the figure menu, becoming enclosed in an independent floating window (a non-modal javax.swing.JDialog child of the parent figure, to be exact). Since this toolbar window has a very small initial size and no name, a simple immediate fix is required:
% Modify Java toolbar properties jToolbar.setFloatable(1); hjToolbar = handle(jToolbar,'CallbackProperties'); set(hjToolbar,'AncestorAddedCallback',@dockUndockCallbackFcn); % Sample dockUndockCallbackFcn function function dockUndockCallbackFcn(hjToolbar, eventdata) if hjToolbar.isFloating jToolbarWin = hjToolbar.getTopLevelAncestor; jToolbarWin.setTitle('Toolbar'); %jToolbarWin.setResizable(1); %if you wish manual resize jToolbarWin.setPreferredSize(java.awt.Dimension(380,57)); jToolbarWin.setSize(java.awt.Dimension(380,57)); jToolbar.revalidate; %repaint toolbar jToolbarWin.getParent.validate; %repaint parent figure end end
Re-docking a floating toolbar can be done by simply closing the floating window – the toolbar then reappears in its default (top) position within the parent figure window.
There are other interesting functions/properties available via the Java interface – readers are encouraged to explore via the methods, methodsview, inspect functions, or my uiinspect utility.
For example, addGap() can be used to add a transparent gap between the rightmost toolbar component and the window border: this gap is kept even if the window is shrunk to a smaller width – the rightmost components disappear, maintaining the requested gap.
setBackground() sets the background color that is seen beneath transparent pixels of button images and gaps. Non-transparent (opaque or colored) pixels are not modified. If the button icons are improperly created, the result looks bad:
jToolbar.setBackground(java.awt.Color.cyan); %or: Color(0,1,1)
This problem can be fixed by looping over the toolbar icons and modifying the pixel values from their default gray background to transparent. An example for this practice was given at the beginning of last week’s article.
setMorePopupEnabled() is used to specify the behavior when the window resizes to such a small width that one or more toolbar buttons need to disappear – by default (=1 or true) the chevron (>>) mark appears on the toolbar’s right, enabling display of the missing buttons, but this behavior can be overridden (0 or false) to simply crop the extra buttons.
setRollover() controls the behavior when the mouse passes (“rolls”) over toolbar buttons. The default parameter (1 or true), displays a 3-dimensional button border, creating an embossing effect; this can be overridden (0 or false) to use a different 3D effect:
% Set non-default Rollover, MorePopupEnabled jToolbar.setRollover(0); % or: set(jToolbar,'Rollover','off'); jToolbar.setMorePopupEnabled(0); % or: set(jToolbar,'MorePopupEnabled','off');
Remember that toolbars are simply containers for internal components, generally buttons and separators. These components may be accessed individually and manipulated. An example of such manipulation can be found in my FindJObj utility on the File Exchange, that lists the individual figure components: whenever the user selects a toolbar button (or any other Java component for that matter), its border is temporarily modified to a flashing red rectangle helping users understand the component’s location. Here’s the relevant code snip and screenshot (readers are encouraged to look at the actual code, which is more complex – FindJObj sub-function flashComponent()):
% Prepare the red border panel oldBorder = jComponent.getBorder; redBorder = javax.swing.border.LineBorder(java.awt.Color.red,2,0); redBorderPanel = javax.swing.JPanel; redBorderPanel.setBorder(redBorder); redBorderPanel.setOpaque(0); % transparent interior, red border redBorderPanel.setBounds(jComponent.getBounds); isSettable(compIdx) = ismethod(jComponent,'setBorder'); % flash by periodically displaying/hiding the panel for idx = 1 : 2*numTimes if idx>1, pause(delaySecs); end % don't pause at start visible = mod(idx,2); jParent = jComponent.getParent; % Most Java components allow modifying their borders if isSettable if visible % Set a red border jComp.setBorder(redBorder); try jComponent.setBorderPainted(1); catch, end else %if ~isempty(oldorder) % Remove red border by restoring the original border jComp.setBorder(oldBorder); end jComp.repaint; % Other Java components are highlighted by a transparent red- % border panel, placed on top of them in their parent's space elseif ~isempty(jParent) if visible % place the transparent red-border panel on top jParent.add(redBorderPanel); jParent.setComponentZOrder(redBorderPanel,0); else jParent.remove(redBorderPanel); end jParent.repaint; end end % idx flash loop
There are 3 features of this toolbar window that really interest me:
1) only the close button is shown in the top bar, not the minimize or restore button, does this mean it is possible to modify that top bar as well? (add and remove buttons there, or change callbacks)
2) when the toolbar is undocked, the figure name does not show up in the windows start bar. Does this mean we could have other “child” figures, that dont show up in the start bar?
3) the tool bar window stays on top of the figure, but not on top of any others.
I’m really interested to hear your thoughts
Any idea how to make changes to the default figure toolbar that apply for *all* figures, including new ones that have yet to be created?
@Jason – the top (detached) toolbar is customizable just like a docked toolbar. I’m afraid I don’t know how to modify Matlab windows to have similar decoration effects (no resize/minimize buttons), nor how to create other child windows. If and when I learn more, I’ll post updates here.
@Tim – place your customization code in figureToolbarCreateFcn.m. This is an internal Matlab function (in the %matlabroot%\toolbox\matlab\graphics\ folder) that is called whenever the default figure toolbar is created. Depending on your Matlab release version, you may need to update a different internal function.