- Undocumented Matlab - https://undocumentedmatlab.com -

Matlab toolstrip – part 9 (popup figures)

Posted By Yair Altman On February 10, 2019 | 6 Comments

In previous posts [1] I showed how we can create custom Matlab app toolstrips using various controls. Today I will show how we can incorporate popup forms composed of Matlab figures into our Matlab toolstrip. These are similar in concept to drop-down and gallery selectors, in the sense that when we click the toolstrip button a custom popup is displayed. In the case of a popup form, this is a fully-customizable Matlab GUI figure.

Popup figure in Matlab toolstrip

Toolstrips can be a bit complex to develop so I’m proceeding slowly, with each post in the miniseries building on the previous posts. I encourage you to review the earlier posts in the Toolstrip miniseries [1] before reading this post.
Also, remember to add the following code snippet at the beginning of your code so that the relevant toolstrip classes will be recognized by Matlab:

import matlab.ui.internal.toolstrip.*

Main steps and usage example

To attach a figure popup to a toolstrip control, follow these steps:

  1. Create a new figure, using GUIDE or the figure function. The figure should typically be created modal and non-visible, unless there’s a good reason to avoid this. Note that the figure needs to be a legacy (Java-based) figure, created with GUIDE or the figure function — web-based uifigure (created with AppDesigner or the uifigure function) is not [currently] supported.
  2. Create a callback function that opens and initializes this figure, and then moves it to the expected screen location using the following syntax: hToolGroup.showFigureDialog(hFig,hAnchor), where hFig is the figure’s handle, and hAnchor is the handle for the triggering toolstrip control.
  3. Attach the callback function to the triggering toolstrip control.

Here’s a simple usage example, in which I present a file-selector popup:

% Create a toolstrip section, column & push-button
hSection = hTab.addSection('Popup');
hColumn = hSection.addColumn();
hButton = Button('Open',Icon.OPEN_24);
hButton.ButtonPushedFcn = {@popupFigure,hButton};  % attach popup callback to the button
% Callback function invoked when the toolstrip button is clicked
function popupFigure(hAction, hEventData, hButton)
    % Create a new non-visible modal figure
    hFig = figure('MenuBar','none', 'ToolBar','none', 'WindowStyle','modal', ...
                  'Visible','off', 'NumberTitle','off', 'Name','Select file:');
    % Add interactive control(s) to the figure (in this case, a file chooser initialized to current folder)
    jFileChooser = handle(javaObjectEDT(javax.swing.JFileChooser(pwd)), 'CallbackProperties');
    [jhFileChooser, hComponent] = javacomponent(jFileChooser, [0,0,200,200], hFig);
    set(hComponent, 'Units','normalized', 'Position',[0,0,1,1]);  % resize component within containing figure
    % Set popup control's callback (in this case, display the selected file and close the popup)
    jhFileChooser.ActionPerformedCallback = @popupActionPerformedCallback;
    function popupActionPerformedCallback(jFileChooser, jEventData)
        fprintf('Selected file: %s\n', char(jFileChooser.getSelectedFile));
    % Display the popup figure onscreen, just beneath the triggering button
    % Wait for the modal popup figure to close before resuming GUI interactivity

This leads to the popup figure as shown in the screenshot above.
The popup figure initially appears directly beneath the triggering button. The figure can then be moved away from that position, by dragging its title bar or border frame.
Note how the popup is an independent heavy-weight figure window, having a border frame, title bar and a separate task-bar icon. Removing the border frame and title-bar of Matlab figures can be done using an undocumented visual illusion [2] – this can make the popup less obtrusive, but also prevent its moving/resizing. An entirely different and probably better approach is to present a light-weight popup panel using the Toolpack framework, which I plan to discuss in the following post(s). The PopupPanel container [3] that I discussed in another post cannot be used, because it is displayed as a sub-component of a Matlab figure, and in this case the popup is not attached to any figure (the toolstrip and ToolGroup are not Matlab figures, as explained here [4]).
The astute reader may wonder why I bothered going to all the trouble of displaying a modal popup with a JFileChooser, when I could have simply used the built-in uigetfile or uiputfile functions in the button’s callback. The answer is that (a) this mechanism displays the popup directly beneath the triggering button using hToolGroup.showFigureDialog(), and also (b) enables complex popups (dialogs) that have no direct builtin Matlab function (for example, a file-selector with preview [5], or a multi-component input form [6]).

Compatibility considerations for R2018a or older

In Matlab releases R2018a or older that do not have the hToolGroup.showFigureDialog() function, you can create it yourself in a separate showFigureDialog.m file, as follows:

function showFigureDialog(hToolGroup, hFig, hAnchor)
    %   showFigureDialog - Display a figure-based dialog below a toolstrip control.
    %   Usage example:
    %       showFigureDialog(hToolGroup, hFig, hAnchor);
    %   where:
    %       "hToolGroup" must be a "matlab.ui.internal.desktop.ToolGroup" handle
    %       "hFig" must be a "figure" handle, not a "uifigure"
    %       "hAnchor" must be a "matlab.ui.internal.toolstrip.***" handle
    %hWarn = ctrlMsgUtils.SuspendWarnings('MATLAB:HandleGraphics:ObsoletedProperty:JavaFrame'); %#ok
    hWarn = warning('off','MATLAB:HandleGraphics:ObsoletedProperty:JavaFrame');
    jf = get(hFig, 'JavaFrame');
    if isempty(jf)
        error('UI figure cannot be added to "ToolGroup". Use a regular figure instead.')
        screen_size = get(0,'ScreenSize');
        old_pos = get(hFig,'OuterPosition');
        dpi_ratio = com.mathworks.util.ResolutionUtils.scaleSize(100)/100;
        jAnchor = hToolGroup.ToolstripSwingService.Registry.getWidgetById(hAnchor.getId());
        pt = javaMethodEDT('getLocationOnScreen',jAnchor); % pt is anchor top left
        pt.y = pt.y + jAnchor.getVisibleRect().height;     % pt is anchor bottom left
        new_x = pt.getX()/dpi_ratio-5;                           % figure outer left
        new_y = screen_size(end)-(pt.getY/dpi_ratio+old_pos(4)); % figure outer bottom
        hFig.OuterPosition = [new_x new_y old_pos(3) old_pos(4)];
        hFig.Visible = 'on';

Under the hood of showFigureDialog()

How does showFigureDialog() know where to place the figure, directly beneath the triggering toolstrip anchor?
The answer is really quite simple, if you look at this method’s source-code in %matlabroot%/toolbox/matlab/toolstrip/+matlab/+ui/+internal/+desktop/ToolGroup.m (around line 500, depending on the Matlab release).
The function first checks whether the input hFig handle belongs to a figure or uifigure, and issues an error message in case it’s a uifigures (only legacy figures are currently supported).
Then the function fetches the toolstrip control’s underlying Java control handle using the following code (slightly modified for clarity), as explained here [7]:

jAnchor = hToolGroup.ToolstripSwingService.Registry.getWidgetById(hAnchor.getId());

Next, it uses the Java control’s getLocationOnScreen() to get the control’s onscreen position, accounting for monitor DPI variation that affects the X location.
The figure’s OuterPosition property is then set so that the figure’s top-left corner is exactly next to the control’s bottom-left corner.
Finally, the figure’s Visible property is set to ‘on’ to make the figure visible in its new position.
The popup figure’s location is recomputed by showFigureDialog() whenever the toolstrip control is clicked, so the popup figure is presented in the expected position even when you move or resize the tool-group window.

Toolstrip miniseries roadmap

The following post(s) will present the Toolpack framework. Non-figure (lightweight) popup toolpack panels can be created, which appear more polished/stylish than the popup figures that I presented today. The drawdown is that toolpack panels may be somewhat more complex to program than figures, and IMHO are more likely to change across Matlab releases. In addition to the benefit of popup toolpack panels, toolpack presents an alternative way for toolstrip creation and customization, enabling programmers to choose between using the toolstrip framework (that I discussed so far), and the new toolpack framework.
In a succeeding post, I’ll discuss toolstrip collapsibility, i.e. what happens when the user resizes the window, reducing the toolstrip width. Certain toolstrip controls will drop their labels, and toolstrip sections shrink into a drop-down. The priority of control/section collapsibility can be controlled, so that less-important controls will collapse before more-important ones.
In future posts, I plan to discuss docking layout, DataBrowser panel, QAB (Quick Access Bar), underlying Java controls, and adding toolstrips to figures – not necessarily in this order.
Matlab toolstrips can be a bit complex, so I plan to proceed in small steps, each post building on top of its predecessors.
If you would like me to assist you in building a custom toolstrip or GUI for your Matlab program, please let me know [8].

Categories: Figure window, GUI, High risk of breaking in future versions, Java, Undocumented feature

6 Comments (Open | Close)

6 Comments To "Matlab toolstrip – part 9 (popup figures)"

#1 Comment By karthik On March 18, 2019 @ 17:17

yair, i am an ardent follower of your undocumented matlab work. i love your present posts on tool strips. Am trying to implement the last post on file chooser using push button call back. however, i receive the following error:
Undefined variable "hToolGroup" or class "hToolGroup.showFigureDialog".
Warning: Error occurred while evaluating listener callback.

hToolGroup is not recognized inside the callback as it is not passed i guess. can you help me out?

Also, I have matlab 2018a in which toolgroup.m doesnt have hToolGroup.showFigureDialog(hFig,hButton); instead it has hToolGroup.showTearOffDialog(hFig,hButton);

#2 Comment By Yair Altman On March 22, 2019 @ 11:29

@Karthik – you can pass hToolGroup as an extra parameter to your callback function when you set it up, using cell-array notation ( [15]).

I plan to discuss tear-off dialogs in my next post in this Toolstrip mini-series, when I will discuss the Toolpack framework. The General idea is that hToolGroup.showFigureDialog() accepts a figure as input parameter and then displays it, while hToolGroup.showTearOffDialog() accepts a Toolpack panel as input (not hFig as you thought) and then displays it.

In Matlab releases R2018a or older that do not have the hToolGroup.showFigureDialog() function, you can create it yourself in a separate showFigureDialog.m file. I added [16] in the main post that explains how.

#3 Comment By Arash Marashian On April 17, 2019 @ 19:40

Dear Yair, Thank you for your information.
I have a question in “showcaseMPCDesigner.m”, we have a function named “createDialog”, that makes a local popup.
I want to make sth like that, so it has 10 text-fields with a label and has a callback function.
At first, I can’t make more than 3 text-fields, and second of all, I can’t make a callback function.

I’ll be glad if you can help me.

#4 Comment By Gebhard Stopper On April 30, 2019 @ 10:08

I really love this mini series! (I’ve been looking for something like this for quite a while)

I have two questions about the toolstrip:
1) (How) Is it possible to embed e.g. a Tree control into the DataBrowser
2) How can I modify to small toolbar in the top right corner of the ToolStrip (e.g. exchange Icons/Buttons).


#5 Comment By alain barraud On October 2, 2019 @ 11:52

Hi yair,
I have tested your miniserie. All works fine with R2019b except some built in demos (as noted by many users) which require older releases.
You say that toolstrip can be also attached to figure and uifigure. What is the equivalent of
hToolGroup.addTabGroup(hTabGroup) for these windows container?

We are all impatient to read the future “part 10”.

Best regards

#6 Comment By Menno On February 28, 2020 @ 15:25

Dear Yair,

As an experienced Matlab user, I have been following your site for quite some time now. With your great series of articles on the Toolstrip, I managed to build a professionally looking app from scratch in an afternoon. Thanks for all the information and tips and tricks; without these it would have been so much more work! As many of your readers, I am really looking forward to Part 10(+).

Article printed from Undocumented Matlab: https://undocumentedmatlab.com

URL to article: https://undocumentedmatlab.com/articles/matlab-toolstrip-part-9-popup-figures

URLs in this post:

[1] previous posts: https://undocumentedmatlab.com/blog/tag/toolstrip

[2] undocumented visual illusion: https://undocumentedmatlab.com/blog/frameless-undecorated-figure-windows

[3] PopupPanel container: https://undocumentedmatlab.com/blog/builtin-popuppanel-widget

[4] as explained here: https://undocumentedmatlab.com/blog/matlab-toolstrip-part-2-toolgroup-app

[5] file-selector with preview: https://undocumentedmatlab.com/blog/uigetfile-uiputfile-customizations

[6] multi-component input form: https://undocumentedmatlab.com/blog/using-spinners-in-matlab-gui

[7] as explained here: https://undocumentedmatlab.com/blog/matlab-toolstrip-part-4-control-customization#Java

[8] please let me know: https://undocumentedmatlab.com/consulting

[9] Matlab toolstrip – part 4 (control customization) : https://undocumentedmatlab.com/articles/matlab-toolstrip-part-4-control-customization

[10] Matlab toolstrip – part 2 (ToolGroup App) : https://undocumentedmatlab.com/articles/matlab-toolstrip-part-2-toolgroup-app

[11] Matlab toolstrip – part 8 (galleries) : https://undocumentedmatlab.com/articles/matlab-toolstrip-part-8-galleries

[12] Matlab toolstrip – part 5 (icons) : https://undocumentedmatlab.com/articles/matlab-toolstrip-part-5-icons

[13] Matlab toolstrip – part 3 (basic customization) : https://undocumentedmatlab.com/articles/matlab-toolstrip-part-3-basic-customization

[14] Matlab toolstrip – part 7 (selection controls) : https://undocumentedmatlab.com/articles/matlab-toolstrip-part-7-selection-controls

[15] : https://www.mathworks.com/help/matlab/creating_plots/callback-definition.html#buhztrs-11

[16] : https://undocumentedmatlab.com/blog/matlab-toolstrip-part-9-popup-figures#compatibility

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.