Undocumented Matlab
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT

uisplittool & uitogglesplittool

December 8, 2010 9 Comments

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)

>> 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
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

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

>> 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'')');

% 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
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, ...);

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;

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
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
undo/redo buttons implemented using uisplittool

Related posts:

  1. uisplittool & uitogglesplittool callbacks – Matlab's undocumented uisplittool and uitogglesplittool are powerful toolbar controls - this article explains how to customize their behavior...
  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. Toolbar button labels – GUI toolbar button labels can easily be set and customized using underlying Java components. ...
  4. 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....
  5. Customizing uiundo – This article describes how Matlab's undocumented uiundo undo/redo manager can be customized...
  6. Customizing the standard figure toolbar, menubar – The standard figure toolbar and menubar can easily be modified to include a list of recently-used files....
Desktop Pure Matlab Toolbar uitools uiundo Undocumented function
Print Print
« Previous
Next »
9 Responses
  1. Yogesh December 9, 2010 at 10:51 Reply

    Thanks. I find this useful.

  2. Dan December 14, 2010 at 13:57 Reply

    out of topic, but thank you for your efforts.

    You are of great help to many Matlab practitioners!

    Best regards

    Dan

  3. cK August 23, 2011 at 19:55 Reply

    I was curious to know if there is a way to retain transparency of png images or even convert white pixels of a logo image into transparent background (it looks sweet on GUIs). I tried the following on a gif image and the image still gave a white background. Why doesnt it work?

    [cdata,map] = imread('logo.gif');
    map(find(map(:,1)+map(:,2)+map(:,3)==3)) = NaN;
    % Convert into 3D RGB-space
    cdata2 = ind2rgb(cdata,map);
    image(cdata2);

    [cdata,map] = imread('logo.gif'); map(find(map(:,1)+map(:,2)+map(:,3)==3)) = NaN; % Convert into 3D RGB-space cdata2 = ind2rgb(cdata,map); image(cdata2);

    • Yair Altman August 24, 2011 at 13:33 Reply

      @cK – Transparency only works in GUI controls. It is unfortunately not supported by Matlab’s image function that displays the image in Matlab plot axes.

  4. Customizing the standard figure toolbar, menubar | Undocumented Matlab January 9, 2013 at 13:12 Reply

    […] The idea here is to replace the standard toolbar “Open File” pushbutton with a new uisplittool button that will contain the MRU list in its picker-menu. […]

  5. Christina October 6, 2016 at 22:55 Reply

    I’m using this capability with 2013a but am having a problem with it crashing. I tried putting my code in the GUIDE OpeningFcn as well as the OutputFcn but get the same results. My code is as follows:

    color = java.awt.Color(0,0,0);
     
    % hToolbar = findall(gcf,'tag','hToolbar');
    jToolbar = get(get(handles.hToolbar,'JavaContainer'),'ComponentPeer');
     
    % Create a splittool for different options
    hLayout = uisplittool('parent',handles.hToolbar);       % uisplittool
     
    % Load the icon
    icon = fullfile(pwd,'icons','Icon.gif');
    [cdata,map] = imread(icon);
    map(find(map(:,1)+map(:,2)+map(:,3)==3)) = NaN;
     
    set(hLayout, 'tag','testingButton','cdata',ind2rgb(cdata,map), 'tooltip','Layout Types','Separator','on', ...
               'ClickedCallback',[]);
     
    jLayout = get(hLayout,'JavaContainer');
    jLayoutMenu = jLayout.getMenuComponent;
    imageToolkit = java.awt.Toolkit.getDefaultToolkit;
    for layoutInd = 1:3
        jMenuItem = handle(jLayoutMenu.add(['Layout ' num2str(layoutInd)]),'CallbackProperties');
        set(jMenuItem,'ActionPerformedCallback',{@changeLayout,layoutInd});
        myIcon = fullfile(pwd,'icons',['layout' num2str(layoutInd) '.gif']);
        jMenuItem.setIcon(javax.swing.ImageIcon(imageToolkit.createImage(myIcon)));
        jMenuItem.setBackground(color);
    end
     
    jToolbar.revalidate;

    color = java.awt.Color(0,0,0); % hToolbar = findall(gcf,'tag','hToolbar'); jToolbar = get(get(handles.hToolbar,'JavaContainer'),'ComponentPeer'); % Create a splittool for different options hLayout = uisplittool('parent',handles.hToolbar); % uisplittool % Load the icon icon = fullfile(pwd,'icons','Icon.gif'); [cdata,map] = imread(icon); map(find(map(:,1)+map(:,2)+map(:,3)==3)) = NaN; set(hLayout, 'tag','testingButton','cdata',ind2rgb(cdata,map), 'tooltip','Layout Types','Separator','on', ... 'ClickedCallback',[]); jLayout = get(hLayout,'JavaContainer'); jLayoutMenu = jLayout.getMenuComponent; imageToolkit = java.awt.Toolkit.getDefaultToolkit; for layoutInd = 1:3 jMenuItem = handle(jLayoutMenu.add(['Layout ' num2str(layoutInd)]),'CallbackProperties'); set(jMenuItem,'ActionPerformedCallback',{@changeLayout,layoutInd}); myIcon = fullfile(pwd,'icons',['layout' num2str(layoutInd) '.gif']); jMenuItem.setIcon(javax.swing.ImageIcon(imageToolkit.createImage(myIcon))); jMenuItem.setBackground(color); end jToolbar.revalidate;

    I think I’ve narrowed it down that the following line of code is what is causing it to crash:

    jLayout = get(hLayout,'JavaContainer');

    jLayout = get(hLayout,'JavaContainer');

    Any suggestions on how to remedy this??

    Thanks!

    • Christina October 6, 2016 at 23:30 Reply

      I forgot to mention that if I go into debug mode and step through each line of code, then it works perfectly. When I let it run on its own is when it crashes. Not sure if that makes a difference.

      • Yair Altman October 6, 2016 at 23:34

        Sounds like an EDT issue. Try adding drawnow and/or pause(0.1).

  6. Kees de Kapper April 7, 2017 at 10:12 Reply

    Dear Yair,

    Thank you for your extensive descriptions.
    However, I was wondering if it is possible to add icons to the jMenuItem in the uitogglesplittool or uisplittool?
    And secondly, is there a straight forward method to obtain the index of the selected jMenuItem.

    Many thanks for your consideration.
    All the Best,
    Kees

Leave a Reply
HTML tags such as <b> or <i> are accepted.
Wrap code fragments inside <pre lang="matlab"> tags, like this:
<pre lang="matlab">
a = magic(3);
disp(sum(a))
</pre>
I reserve the right to edit/delete comments (read the site policies).
Not all comments will be answered. You can always email me (altmany at gmail) for private consulting.

Click here to cancel reply.

Useful links
  •  Email Yair Altman
  •  Subscribe to new posts (feed)
  •  Subscribe to new posts (reader)
  •  Subscribe to comments (feed)
 
Accelerating MATLAB Performance book
Recent Posts

Speeding-up builtin Matlab functions – part 3

Improving graphics interactivity

Interesting Matlab puzzle – analysis

Interesting Matlab puzzle

Undocumented plot marker types

Matlab toolstrip – part 9 (popup figures)

Matlab toolstrip – part 8 (galleries)

Matlab toolstrip – part 7 (selection controls)

Matlab toolstrip – part 6 (complex controls)

Matlab toolstrip – part 5 (icons)

Matlab toolstrip – part 4 (control customization)

Reverting axes controls in figure toolbar

Matlab toolstrip – part 3 (basic customization)

Matlab toolstrip – part 2 (ToolGroup App)

Matlab toolstrip – part 1

Categories
  • Desktop (45)
  • Figure window (59)
  • Guest bloggers (65)
  • GUI (165)
  • Handle graphics (84)
  • Hidden property (42)
  • Icons (15)
  • Java (174)
  • Listeners (22)
  • Memory (16)
  • Mex (13)
  • Presumed future risk (394)
    • High risk of breaking in future versions (100)
    • Low risk of breaking in future versions (160)
    • Medium risk of breaking in future versions (136)
  • Public presentation (6)
  • Semi-documented feature (10)
  • Semi-documented function (35)
  • Stock Matlab function (140)
  • Toolbox (10)
  • UI controls (52)
  • Uncategorized (13)
  • Undocumented feature (217)
  • Undocumented function (37)
Tags
ActiveX (6) AppDesigner (9) Callbacks (31) Compiler (10) Desktop (38) Donn Shull (10) Editor (8) Figure (19) FindJObj (27) GUI (141) GUIDE (8) Handle graphics (78) HG2 (34) Hidden property (51) HTML (26) Icons (9) Internal component (39) Java (178) JavaFrame (20) JIDE (19) JMI (8) Listener (17) Malcolm Lidierth (8) MCOS (11) Memory (13) Menubar (9) Mex (14) Optical illusion (11) Performance (78) Profiler (9) Pure Matlab (187) schema (7) schema.class (8) schema.prop (18) Semi-documented feature (6) Semi-documented function (33) Toolbar (14) Toolstrip (13) uicontrol (37) uifigure (8) UIInspect (12) uitools (20) Undocumented feature (187) Undocumented function (37) Undocumented property (20)
Recent Comments
  • Nicholas (6 days 13 hours ago): Hi Yair, Thanks for the reply. I am on Windows 10. I also forgot to mention that this all works wonderfully out of the editor. It only fails once compiled. So, yes, I have tried a...
  • Nicholas (6 days 13 hours ago): Hi Yair, Thanks for the reply. I am on Windows 10. I also forgot to mention that this all works wonderfully out of the editor. It only fails once compiled. So, yes, I have tried a...
  • Yair Altman (6 days 20 hours ago): Nicholas – yes, I used it in a compiled Windows app using R2022b (no update). You didn’t specify the Matlab code location that threw the error so I can’t help...
  • Nicholas (7 days 17 hours ago): Hi Yair, Have you attempted your displayWebPage utility (or the LightweightHelpPanel in general) within a compiled application? It appears to fail in apps derived from both R2022b...
  • João Neves (10 days 21 hours ago): I am on matlab 2021a, this still works: url = struct(struct(struct(struct(hF ig).Controller).PlatformHost). CEF).URL; but the html document is empty. Is there still a way to do...
  • Yair Altman (13 days 20 hours ago): Perhaps the class() function could assist you. Or maybe just wrap different access methods in a try-catch so that if one method fails you could access the data using another...
  • Jeroen Boschma (13 days 23 hours ago): Never mind, the new UI components have an HTML panel available. Works for me…
  • Alexandre (14 days 0 hours ago): Hi, Is there a way to test if data dictionnatry entry are signal, simulink parameters, variables … I need to access their value, but the access method depends on the data...
  • Nicholas (14 days 14 hours ago): In case anyone is looking for more info on the toolbar: I ran into some problems creating a toolbar with the lightweight panel. Previously, the Browser Panel had an addToolbar...
  • Jeroen Boschma (17 days 21 hours ago): I do not seem to get the scrollbars (horizontal…) working in Matlab 2020b. Snippets of init-code (all based on Yair’s snippets on this site) handles.text_explorer...
  • Yair Altman (45 days 23 hours ago): m_map is a mapping tool, not even created by MathWorks and not part of the basic Matlab system. I have no idea why you think that the customizations to the builtin bar function...
  • chengji chen (46 days 5 hours ago): Hi, I have tried the method, but it didn’t work. I plot figure by m_map toolbox, the xticklabel will add to the yticklabel at the left-down corner, so I want to move down...
  • Yair Altman (53 days 22 hours ago): @Alexander – this is correct. Matlab stopped including sqlite4java in R2021b (it was still included in 21a). You can download the open-source sqlite4java project from...
  • Alexander Eder (59 days 18 hours ago): Unfortunately Matlab stopped shipping sqlite4java starting with R2021(b?)
  • K (66 days 5 hours ago): Is there a way to programmatically manage which figure gets placed where? Let’s say I have 5 figures docked, and I split it into 2 x 1, I want to place 3 specific figures on the...
Contact us
Captcha image for Custom Contact Forms plugin. You must type the numbers shown in the image
Undocumented Matlab © 2009 - Yair Altman
This website and Octahedron Ltd. are not affiliated with The MathWorks Inc.; MATLAB® is a registered trademark of The MathWorks Inc.
Scroll to top