Customizing uifigures part 1

July 21, 2016 12 Comments

Last month, I posted an article that summarized a variety of undocumented customizations to Matlab figure windows. As I noted in that post, Matlab figures have used Java JFrames as their underlying technology since R14 (over a decade ago), but this is expected to change a few years from now with the advent of web-based uifigures. uifigures first became available in late 2014 with the new App Designer preview (the much-awaited GUIDE replacement), and were officially released in R2016a. AppDesigner is actively being developed and we should expect to see exciting new features in upcoming Matlab releases.

Matlab's new AppDesigner (a somewhat outdated screenshot)

However, while AppDesigner has become officially supported, the underlying technology used for the new uifigures remained undocumented. This is not surprising: MathWorks did a good job of retaining backward compatibility with the existing figure handle, and so a new uifigure returns a handle that programmatically appears similar to figure handles, reducing the migration cost when MathWorks decides (presumably around 2018-2020) that web-based (rather than Java-based) figures should become the default figure type. By keeping the underlying figure technology undocumented and retaining the documented top-level behavior (properties and methods of the figure handle), Matlab users who only use the documented interface should expect a relatively smooth transition at that time.
So does this mean that users who start using AppDesigner today (and especially in a few years when web figures become the default) can no longer enjoy the benefits of figure-based customization offered to the existing Java-based figure users (which I listed in last month’s post)? Absolutely not! All we need is to get a hook into the uifigure‘s underlying object and then we can start having fun.

The uifigure Controller

One way to do this is to use the uifigure handle’s hidden (private) Controller property (a matlab.ui.internal.controller.FigureController MCOS object whose source-code appears in %matlabroot%/toolbox/matlab/uitools/uicomponents/components/+matlab/+ui/+internal/+controller/).
Controller is not only a hidden but also a private property of the figure handle, so we cannot simply use the get function to get its value. This doesn’t stop us of course: We can get the controller object using either my getundoc utility or the builtin struct function (which returns private/protected properties as an undocumented feature):

>> hFig = uifigure('Name','Yair', ...);
 
>> figProps = struct(hFig);  % or getundoc(hFig)
Warning: Calling STRUCT on an object prevents the object from hiding its implementation details and should thus be
avoided. Use DISP or DISPLAY to see the visible public details of an object. See 'help struct' for more information.
(Type "warning off MATLAB:structOnObject" to suppress this warning.)
 
Warning: figure JavaFrame property will be obsoleted in a future release. For more information see
the JavaFrame resource on the MathWorks web site.
(Type "warning off MATLAB:HandleGraphics:ObsoletedProperty:JavaFrame" to suppress this warning.)
 
figProps =
                      JavaFrame: []
                    JavaFrame_I: []
                       Position: [87 40 584 465]
                   PositionMode: 'auto'
                            ...
                     Controller: [1x1 matlab.ui.internal.controller.FigureController]
                 ControllerMode: 'auto'
                            ...
 
>> figProps.Controller
ans =
  FigureController with properties:
 
       Canvas: []
    ProxyView: [1x1 struct]
 
>> figProps.Controller.ProxyView
ans =
            PeerNode: [1x1 com.mathworks.peermodel.impl.PeerNodeImpl]
    PeerModelManager: [1x1 com.mathworks.peermodel.impl.PeerModelManagerImpl]
 
>> struct(figProps.Controller)
Warning: Calling STRUCT on an object prevents the object from hiding its implementation details and should thus be
avoided. Use DISP or DISPLAY to see the visible public details of an object. See 'help struct' for more information.
(Type "warning off MATLAB:structOnObject" to suppress this warning.)
 
ans =
               PositionListener: [1x1 event.listener]
    ContainerPositionCorrection: [1 1 0 0]
                      Container: [1x1 matlab.ui.internal.controller.FigureContainer]
                         Canvas: []
                  IsClientReady: 1
              PeerEventListener: [1x1 handle.listener]
                      ProxyView: [1x1 struct]
                          Model: [1x1 Figure]
               ParentController: [0x0 handle]
      PropertyManagementService: [1x1 matlab.ui.internal.componentframework.services.core.propertymanagement.PropertyManagementService]
          IdentificationService: [1x1 matlab.ui.internal.componentframework.services.core.identification.WebIdentificationService]
           EventHandlingService: [1x1 matlab.ui.internal.componentframework.services.core.eventhandling.WebEventHandlingService]

I will discuss all the goodies here in a future post (if you are curious then feel free to start drilling in there yourself, I promise it won’t bite you…). However, today I wish to concentrate on more immediate benefits from a different venue:

The uifigure webwindow

uifigures are basically webpages rather than desktop windows (JFrames). They use an entirely different UI mechanism, based on HTML webpages served from a localhost webserver that runs CEF (Chromium Embedded Framework version 3.2272 on Chromium 41 in R2016a). This runs the so-called CEF client (apparently an adaptation of the CefClient sample application that comes with CEF; the relevant Matlab source-code is in %matlabroot%/toolbox/matlab/cefclient/). It uses the DOJO Javascript toolkit for UI controls visualization and interaction, rather than Java Swing as in the existing JFrame figures. I still don’t know if there is a way to combine the seemingly disparate sets of GUIs (namely adding Java-based controls to web-based figures or vice-versa).
Anyway, the important thing to note for my purposes today is that when a new uifigure is created, the above-mentioned Controller object is created, which in turn creates a new matlab.internal.webwindow. The webwindow class (%matlabroot%/toolbox/matlab/cefclient/+matlab/+internal/webwindow.m) is well-documented and easy to follow (although the non camel-cased class name escaped someone’s attention), and allows access to several important figure-level customizations.
The figure’s webwindow reference can be accessed via the Controller‘s Container‘s CEF property:

>> hFig = uifigure('Name','Yair', ...);
>> warning off MATLAB:structOnObject      % suppress warning (yes, we know it's naughty...)
>> figProps = struct(hFig);
>> controller = figProps.Controller;      % Controller is a private hidden property of Figure
>> controllerProps = struct(controller);
>> container = controllerProps.Container  % Container is a private hidden property of FigureController
container =
  FigureContainer with properties:
    FigurePeerNode: [1x1 com.mathworks.peermodel.impl.PeerNodeImpl]
         Resizable: 1
          Position: [86 39 584 465]
               Tag: ''
             Title: 'Yair'
              Icon: 'C:\Program Files\Matlab\R2016a\toolbox\matlab\uitools\uicomponents\resources\images…'
           Visible: 1
               URL: 'http://localhost:31417/toolbox/matlab/uitools/uifigureappjs/componentContainer.html…'
              HTML: 'toolbox/matlab/uitools/uifigureappjs/componentContainer.html'
     ConnectorPort: 31417
         DebugPort: 0
     IsWindowValid: 1
>> win = container.CEF   % CEF is a regular (public) hidden property of FigureContainer
win =
  webwindow with properties:
                             URL: 'http://localhost:31417/toolbox/matlab/uitools/uifigureappjs/component…'
                           Title: 'Yair'
                            Icon: 'C:\Program Files\Matlab\R2016a\toolbox\matlab\uitools\uicomponents\re…'
                        Position: [86 39 584 465]
     CustomWindowClosingCallback: @(o,e)this.Model.hgclose()
    CustomWindowResizingCallback: @(event,data)resizeRequest(this,event,data)
                  WindowResizing: []
                   WindowResized: []
                     FocusGained: []
                       FocusLost: []
                DownloadCallback: []
        PageLoadFinishedCallback: []
           MATLABClosingCallback: []
      MATLABWindowExitedCallback: []
             PopUpWindowCallback: []
             RemoteDebuggingPort: 0
                      CEFVersion: '3.2272.2072'
                 ChromiumVersion: '41.0.2272.76'
                   isWindowValid: 1
               isDownloadingFile: 0
                         isModal: 0
                  isWindowActive: 1
                   isAlwaysOnTop: 0
                     isAllActive: 1
                     isResizable: 1
                         MaxSize: []
                         MinSize: []
>> win.URL
ans =
http://localhost:31417/toolbox/matlab/uitools/uifigureappjs/componentContainer.html?channel=/uicontainer/393ed66a-5e34-41f3-8ac0-0b0f3b0738cd&snc=5C2353

An alternative way to get the webwindow is via the list of all webwindows stored by a central webwindowmanager:

webWindows = matlab.internal.webwindowmanager.instance.findAllWebwindows();  % manager method returning an array of all open webwindows
webWindows = matlab.internal.webwindowmanager.instance.windowList;           % equivalent alternative via manager's windowList property

Note that the controller, container and webwindow class objects, like most Matlab MCOS objects, have internal (hidden) properties/methods that you can explore. For example:

>> getundoc(win)
ans =
                   Channel: [1x1 asyncio.Channel]
       CustomEventListener: [1x1 event.listener]
           InitialPosition: [100 100 600 400]
    JavaScriptReturnStatus: []
     JavaScriptReturnValue: []
     NewWindowBeingCreated: 0
          NewWindowCreated: 1
           UpdatedPosition: [86 39 584 465]
              WindowHandle: 2559756
                    newURL: 'http://localhost:31417/toolbox/matlab/uitools/uifigureappjs/componentContai…'

Using webwindow for figure-level customizations

We can use the methods of this webwindow object as follows:

win.setAlwaysOnTop(true);   % always on top of other figure windows (a.k.a. AOT)
win.hide();
win.show();
win.bringToFront();
win.minimize();
win.maximize();
win.restore();
win.setMaxSize([400,600]);  % enables resizing up to this size but not larger (default=[])
win.setMinSize([200,300]);  % enables resizing down to this size but not smaller (default=[])
win.setResizable(false);
win.setWindowAsModal(true);
win.setActivateCurrentWindow(false);  % disable interaction with this entire window
win.setActivateAllWindows(false);     % disable interaction with *ALL* uifigure (but not Java-based) windows
result = win.executeJS(jsStr, timeout);  % run JavaScript

In addition to these methods, we can set callback functions to various callbacks exposed by the webwindow as regular properties (too bad that some of their names [like the class name itself] don’t follow Matlab’s standard naming convention, in this case by appending “Fcn” or “Callback”):

win.FocusGained = @someCallbackFunc;
win.FocusLost = @anotherCallbackFunc;

In summary, while the possible customizations to Java-based figure windows are more extensive, the webwindow methods appear to cover most of the important ones. Since these functionalities (maximize/minimize, AOT, disable etc.) are now common to both the Java and web-based figures, I really hope that MathWorks will create fully-documented figure properties/methods for them. Now that there is no longer any question whether these features will be supported by the future technology, and since there is no question as to their usefulness, there is really no reason not to officially support them in both figure types. If you feel the same as I do, please let MathWorks know about this – if enough people request this, MathWorks will be more likely to add these features to one of the upcoming Matlab releases.
Warning: the internal implementation is subject to change across releases, so be careful to make your code cross-release compatible whenever you rely on one of Matlab’s internal objects.
Note that I labeled this post as “part 1” – I expect to post additional articles on uifigure customizations in upcoming years.

12 Responses

Benjamin Berger August 1, 2016 at 16:09 Reply

Thanks a lot for your posts!
I’m currently beginning to create my first really big Matlab GUI and I still dont know, if I should use the new App Designer. The new App Designer has some very cool features, however, it also offers not the full functionality of the old programmatically way. For instance, no menu bar is available in App Designer, which is really annoying…
Maybe you could share your opinion on the pros and cons of App Designer in future posts, or maybe you find even an undocumented menu bar 😉
Anyway, thumbs up for your blog!
Ben

Yair Altman August 1, 2016 at 16:36 Reply

@Ben – at the moment, using programmatic GUI creation that relies on the old Java frame enables far greater customizability and functionality than the new web-based uifigures created by AppDesigner (AD). AD does offer an easy-to-use GUI layout editor and a few nice-looking widgets (knobs, dials and switches), but it also [currently] lacks many important functionalities compared to the old figures and controls. Moreover, if you know how to programmatically create and modify Matlab GUIs then you don’t need AD’s widgets, and if you know how to integrate Java widgets in Matlab GUIs then you could use one of the zillion widgets available online. So in essence, AppDesigner is excellent for simple GUI development, but not [currently] for highly-polished professional-looking GUIs.

That being said, AppDesigner is constantly being improved with each Matlab release. I’m almost certain that menus and toolbars will be added to uifigures soon. At some point in the near future I expect AD to be at least as powerful and useful as programmatic JFrame-based GUIs. There would always be some stuff that we would never be able to do with uifigures, but the time will soon come when AD and uifigure‘s benefits will outweigh those limitations. My guesstimate is that we’re ~1 year away from that point for simple GUIs, and ~2 years away for most advanced GUIs.

Of course, the importance of various features is different for different users, so for some users the balance point may have already arrived, and for others it may never arrive…
Benjamin Berger August 1, 2016 at 19:04 Reply

Thanks a lot for your thoughts!
Benjamin Berger August 1, 2016 at 20:43 Reply

If anybody is interested in a comparison of App Designer vs Standard figures in 2016a, I recommend these links here:

https://de.mathworks.com/matlabcentral/answers/279042-app-designer-s-editor-is-slow-and-gets-stuck-alot?s_tid=srchtitle

https://de.mathworks.com/matlabcentral/answers/283215-insert-image-in-appdesigner-gui?s_tid=srchtitle

https://de.mathworks.com/matlabcentral/answers/289578-how-to-share-data-between-gui-from-guide-and-app-from-app-designer?s_tid=srchtitle

https://de.mathworks.com/matlabcentral/answers/275827-how-to-zoom-in-out-on-the-figures-in-app-designer?s_tid=srchtitle

Ben

Davide Miani May 12, 2017 at 01:40 Reply

Update: if you are running MATLAB 2017a, you can reach the FCE properties in this way:

warning off MATLAB:structOnObject
figProps = struct(app.UIFigure);
controller = figProps.Controller;
controllerProps = struct(controller);
platformHost = controllerProps.PlatformHost;
platformHostProps = struct(platformHost);
win = platformHostProps.CEF;

Enjoy hacking AppDesigner 😉

HL SHI November 5, 2017 at 17:21 Reply

Dear Davide Miani,

According to your update, I can change the ico to my own ico file by:

win.Icon = 'D:workingSoftwareCopyrightmakingmsERP_Pretosongerp.ico';

But I find it did not work when I added the following code to function startupFcn(app)

% Code that executes after component creation
function startupFcn(app)
    figProps = struct(app.UIFigureERP);         
    controller = figProps.Controller;
    controllerProps = struct(controller);
    platformHost = controllerProps.PlatformHost;
    platformHostProps = struct(platformHost);
    win = platformHostProps.CEF;
    win.Icon = 'D:workingSoftwareCopyrightmakingmsERP_Pretosongerp.ico';
end

Jeffery Devereux December 27, 2017 at 16:32

Hl Shi,

by installing the 1 sec pause, I was able to get the controller array loaded. Otherwise it is empty. Still poking around with it however it did work. just set MyICO to your ‘Filename.ico’ file. Note: must use correct file format. Java would let you use a png but this is an easy conversion.

warning('off','MATLAB:structOnObject');
pause(1);
figProps = struct(FigHand);
controller = figProps.Controller;
controllerProps = struct(controller);
platformHost = controllerProps.PlatformHost;
platformHostProps = struct(platformHost);
win = platformHostProps.CEF;
win.Icon = [pwd '' MyICO];

Francisco Dias November 26, 2017 at 01:16 Reply

Hi everyone, I’m having trouble creating a mlapp that has a popup that is a mlapp also.
So in other others I have 2 appdesigner apps… “main” and “popup”.
when I press a button on the main I want the popup to well.. popup.. and act as a modal window…
so I cant continue using the main app until I close the popup one.

I tried messing around with the:

win.setWindowAsModal(true);

with no luck… can someone give me some tips? 😉
Xiangrui Li December 28, 2019 at 04:53 Reply
It seems the`Container` is removed. I see this error in R2019b:
container = controllerProps.Container; Reference to non-existent field 'Container'.
container = controllerProps.Container; Reference to non-existent field 'Container'.

Yair Altman December 28, 2019 at 18:02 Reply

Matlab recently modified the internal structure. You can now access the web-window (CEF) object as follows:

hFig = uifigure(...);
warning off MATLAB:structOnObject      % suppress warning (yes, we know it's naughty...)
figProps = struct(hFig);
controller = figProps.Controller;      % Controller is a private hidden property of Figure
controllerProps = struct(controller);
try  % up to R2019a    container = controllerProps.Container;catch  % R2019b or newer    container = controllerProps.PlatformHost;endwin = container.CEF;

The other mechanisms described in the post, namely using matlab.internal.webwindowmanager methods, still work to this day:

webWindows = matlab.internal.webwindowmanager.instance.findAllWebwindows();  % manager method returning an array of all open webwindows
webWindows = matlab.internal.webwindowmanager.instance.windowList;           % equivalent alternative via manager's windowList property

Xiangrui Li December 29, 2019 at 05:10 Reply
Hi Yair,
Thank you for digging into this. It seems I need following to get CEF
container = struct(controllerProps.PlatformHost);
container = struct(controllerProps.PlatformHost);

Eric Dziekonski October 8, 2020 at 18:23 Reply

This is fantastic! Thanks everyone!
To get access to CEF on 2019b, I had to take the advise of Jeffery Devereux and Xiangrui Li.

warning off MATLAB:structOnObject      % suppress warning (yes, we know it's naughty...)
drawnow;
figProps = struct(app.UIFigure);
controller = figProps.Controller;      % Controller is a private hidden property of Figure
controllerProps = struct(controller);
try  % up to R2019a
    container = controllerProps.Container;
catch  % R2019b or newer
    container = struct(controllerProps.PlatformHost);
end
drawnow;
win = container.CEF;

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.

Patrick Fitzgerald (1 day 22 hours ago): Just a heads up to anyone else digging around for help related to this: if you assign BackrgoundColor to a pushbutton-style uicontrol, it seems to prevent you from...
Vasiliy (17 days 18 hours ago): Hi Yair, i’m trying to use the MonthChooserPanel class. com.mathworks.mwswing.MJUtilit ies.initJIDE; handles.jPanel = com.jidesoft.combobox.MonthCho oserPanel;...
DM (17 days 18 hours ago): Hi Yair, I’m trying to use the MonthChooserPanel class. com.mathworks.mwswing.MJUtilit ies.initJIDE; handles.jPanel = com.jidesoft.combobox.MonthCho oserPanel; [handles.hPanel,...
Yair Altman (21 days 10 hours ago): @Alex – thanks, but keep in mind that new functions will only work on the recent Matlab releases. If your code needs to work on older Matlab releases, you could revert to...
Alex Churchill (21 days 11 hours ago): I was looking up how to do this exact task today. I was about to hold my nose and use the internal controllib function, when I happened to chance across a slightly newer...
Sebastian Hölz (27 days 17 hours ago): I have not investigated this in detail, but I think one way to go in new versions of Matlab (>2019b) might be to use listeners to suitable figure properties, e.g. fig =...
Prathep (27 days 20 hours ago): Hi Yair, Thanks for your introduction on Matlab Toostrip. Is there any way to add Matlab toolstrip for uifigures as you have done already for figure?
Josh (34 days 2 hours ago): Dear Yair, Small typo; you wrote >>Move lines up or down – CTRL + ALT + UP or DOWN allows you to move selected lines up or down but it’s actually ALT+SHIFT then UP/DOWN...
Yair Altman (40 days 21 hours ago): You can try to increase the Java heap memory size in the Matlab preferences (General => Java Heap Memory). Any changes to the settings will only take effect after restarting...
Thomas (40 days 22 hours ago): Hello, thanks for sharing! I currently receive the following memory error message when using savezip with a big object (Matlab R2020b, Windows 10). Error using...
Yair Altman (44 days 6 hours ago): Yerlan – either use menuItem1.setEnabled(0) or set(menuItem1,'Enabled',0)
Manzn (44 days 8 hours ago): Thank you man! you saved me, when there was no more light 😀
Yerlan (45 days 13 hours ago): Hello Mr. Altman, how can I disable menu items in the context menu? E.g. when I am trying to do this: menuItems = jmenu.getSubElements; menuItem1 = menuItems(1);...
Yair Altman (46 days 5 hours ago): Thanks for the note Eric – you forgot the crucial call to jTable.setLabelTable(labelTabl e) – I added it into your code snippet above.
Erik (47 days 17 hours ago): Thank you for this — I don’t know if this has been mentioned anywhere else before, but it could be useful to mention how to add custom labels to a jslider. I did the...

The uifigure Controller

The uifigure webwindow

Using webwindow for figure-level customizations

Related posts:

12 Responses

Leave a Reply