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 (Comand 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 a future post I will 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.
