Customizing uifigures part 1 - Undocumented Matlab (2024)

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

Customizing uifigures part 1 - Undocumented Matlab (1)

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 beavoided. 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 seethe 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.Controllerans = FigureController with properties: Canvas: [] ProxyView: [1x1 struct]>> figProps.Controller.ProxyViewans = 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 beavoided. 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 FigureControllercontainer = 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 FigureContainerwin = 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.URLans =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 webwindowswebWindows = 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 windowwin.setActivateAllWindows(false); % disable interaction with *ALL* uifigure (but not Java-based) windowsresult = 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.

Related posts:

  1. Customizing uifigures part 3 As I have repeatedly posted in recent years, Matlab is advancing towards web-based GUI. The basic underlying technology is more-or-less stable: an HTML/Javascript webpage that is created-on-the-fly and rendered in a stripped-down browser window (based on Chromium-based jxBrowser in recent...
  2. Customizing uifigures part 2 Matlab's new web-based uifigures can be customized using custom CSS and Javascript code. ...
  3. Customizing web-GUI uipanel We can customize Matlab's new web-based GUI panels in many interesting ways. Here's how... ...
  4. Customizing print setup Matlab figures print-setup can be customized to automatically prepare the figure for printing in a specific configuration...
  5. Customizing uiundo This article describes how Matlab's undocumented uiundo undo/redo manager can be customized...
  6. Customizing histogram plots Basic bar charts and histogram plots can be customized in important aspects. ...

AppDesigner GUI Pure Matlab uifigure

Print
22 Responses
  1. Customizing uifigures part 1 - Undocumented Matlab (3)

    Benjamin BergerReply

    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

  • Customizing uifigures part 1 - Undocumented Matlab (7)

    Davide MianiReply

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

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

    Enjoy hacking AppDesigner 😉

    • Customizing uifigures part 1 - Undocumented Matlab (8)

      HL SHIReply

      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 creationfunction 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
      • Customizing uifigures part 1 - Undocumented Matlab (9)

        Jeffery Devereux

        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];
  • Customizing uifigures part 1 - Undocumented Matlab (10)

    Francisco DiasReply

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

    • Customizing uifigures part 1 - Undocumented Matlab (11)

      Danila BerezinReply

      Hi I have a similar issue. Did you find a workaround for this?

      • Customizing uifigures part 1 - Undocumented Matlab (12)

        Yair Altman

        try to use the waitfor function

  • Customizing uifigures part 1 - Undocumented Matlab (13)

    Xiangrui LiReply

    It seems the`Container` is removed. I see this error in R2019b:

    container = controllerProps.Container;Reference to non-existent field 'Container'.
    • Customizing uifigures part 1 - Undocumented Matlab (14)

      Yair AltmanReply

      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 FigurecontrollerProps = 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 webwindowswebWindows = matlab.internal.webwindowmanager.instance.windowList; % equivalent alternative via manager's windowList property
  • Customizing uifigures part 1 - Undocumented Matlab (15)

    Xiangrui LiReply

    Hi Yair,
    Thank you for digging into this. It seems I need following to get CEF

    container = struct(controllerProps.PlatformHost);
  • Customizing uifigures part 1 - Undocumented Matlab (16)

    Eric DziekonskiReply

    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 FigurecontrollerProps = struct(controller);try % up to R2019a container = controllerProps.Container;catch % R2019b or newer container = struct(controllerProps.PlatformHost);enddrawnow;win = container.CEF;
  • Customizing uifigures part 1 - Undocumented Matlab (17)

    PaulReply

    Is there a way to intergrade the toolstrip or toolgroup (java based) to the uifigure? I am trying to figure out if I should go for the undocumented toolgroup or App Designer. App Designer seems to be improved a lot and the editor is nice, but I also like the look of toolstrip. I feel that these two should be able to co-exist. We are able to use all the toolgroup app (PIDTuner etc…) on matlab-online so I assume there is a way to render the java based app to web-based(?).

    thanks

    • Customizing uifigures part 1 - Undocumented Matlab (18)

      Yair AltmanReply

      @Paul – There must be a way to use a toolstrip in uifigures, because many Matlab apps use uifigures with a toolstrip. But I have not [yet] discovered how to add a toolstrip to uifigures – only to Java-based windows (tool-group and regular figures).

    • Customizing uifigures part 1 - Undocumented Matlab (19)

      TReply

      Mathworks has indeed been migrating its Java-based apps (like the PIDtuner, as you mentioned) to html-based ones (uifigures) so that they can be used in Matlab online. If you drill a bit into the code of any of these apps you will find that they are using an AppContainer object which already has a toolstrip (empty) attached. Toolstrip elements have the same syntax as the ones used in Java apps:

      % Create the appapp = matlab.ui.container.internal.AppContainer();% Create a tabgroup with a tabtabGroup = matlab.ui.internal.toolstrip.TabGroup();tab = matlab.ui.internal.toolstrip.Tab();tabGroup.Tag = 'myTabGroup';tab.Tag = 'myTab';tab.Title = 'Tab#1';% Add tab to group and group to apptabGroup.add(tab);app.addTabGroup(tabGroup);% Make app visibleapp.Visible = true;

      I’d 100% recommend you to work with this AppContainer, since it offers more possibilities than the normal Java-based one. Besides the toolstrip (same syntax as for Java, so Yairs 9 posts on it should still be relevant), you can insert uifigures as draggable panels to the left/right/bottom of the app (way better than the java-based DataBrowser) and control the layout of the app grid. Plus, you can use custom html/javascript objects (using the uihtml component) inside the app which in my view are easier to code and customize.

      Only downside is that everything is undocumented and you’d need to investigate a lot on the AppContainer API. I have already looked my fair bit into it, so I could probably help

      • Customizing uifigures part 1 - Undocumented Matlab (20)

        Kevin

        Any ideas on why this bit of code looks fine in say R2020b but produces an incorrect image in R2019b? I’m not seeing any error printouts that suggest it’s unhappy with the inputs.

      • Customizing uifigures part 1 - Undocumented Matlab (21)

        Yair Altman

        It is not clear from your comment which code exactly you are referring to and what you see differently in 19b vs. 20b, so I cannot assist with your specific query.
        In general I can say that it is not surprising that undocumented things that work in one Matlab release don’t work exactly the same way on a different release.

      • Customizing uifigures part 1 - Undocumented Matlab (22)

        KEVIN

        I apologize, I intended my response to fall under ‘T’ but did not seem to work.

        I was referring to the bit of code posted by ‘T’ regarding the toolgroup and appcontainer. If I run that snippet of code they posted in R2019b, the figure generated is all wrong, but works fine in R2020b. I have the deep learning toolbox and their Deep Network Designer tool (which looks fine in R2019b and R2020b) very much appears to be built on an AppContainer type framework , however when drilling through the source code there’s not much to go on, and it’s not even like they p-coded or encrypted it. It seems like maybe it’s javascript based, but even searching through that bit of code I can’t find terms that match buttons in the TabGroup. I was more or less just looking for examples on how to build out the appcontainer into a more formidable GUI, was at least able to figure out how to add Figures to panels and tabbed figures, probably sufficient for moving forward. R2019b would be a nice to have but maybe too much of a leap in versions for these features.

  • Customizing uifigures part 1 - Undocumented Matlab (23)

    EricReply

    Hey @Kevin, can you share your code about create group of figures in the AppContainer? The container of multiples uifigures could be an amazing improvement over AppDesigner and its only uifigure, opening a lot of possibilities…

  • Customizing uifigures part 1 - Undocumented Matlab (24)

    Eric DelgadoReply
  • 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.
    Customizing uifigures part 1 - Undocumented Matlab (2024)
    Top Articles
    Latest Posts
    Article information

    Author: Sen. Emmett Berge

    Last Updated:

    Views: 5545

    Rating: 5 / 5 (80 voted)

    Reviews: 95% of readers found this page helpful

    Author information

    Name: Sen. Emmett Berge

    Birthday: 1993-06-17

    Address: 787 Elvis Divide, Port Brice, OH 24507-6802

    Phone: +9779049645255

    Job: Senior Healthcare Specialist

    Hobby: Cycling, Model building, Kitesurfing, Origami, Lapidary, Dance, Basketball

    Introduction: My name is Sen. Emmett Berge, I am a funny, vast, charming, courageous, enthusiastic, jolly, famous person who loves writing and wants to share my knowledge and understanding with you.