Frameless (undecorated) figure windows

March 19, 2015 12 Comments

All Matlab figures have a standard frame around them, consisting of a border and title bar. In some cases it could be useful to present a figure window, displaying only the contents without the border and title bar. Such a borderless (undecorated) window is not possible in Matlab. Well, at least not in supported/documented Matlab…
Readers of this blog and/or my Matlab-Java programming book are aware that Matlab’s GUI is based on Java Swing. In the end, every Matlab figure window is a simple Java JFrame, and JFrames have a setUndecorated(true) method that can be called to remove the border and title bar.

An undecorated Matlab figure window

Attempt #1 – direct invocation

Unfortunately, we cannot directly call setUndecorated in Matlab, because it only works when the JFrame has not yet been displayed:

% Get the figure's underlying Java JFrame reference handle
>> mjf = get(handle(gcf), 'JavaFrame');
>> jWindow = mjf.fHG2Client.getWindow  % or: mjf.getAxisComponent.getTopLevelAncestor
jWindow =
com.mathworks.hg.peer.FigureFrameProxy$FigureFrame[fClientProxyFrame,740,-761,576x509,...]
 
% Try to remove decoration
>> jWindow.setUndecorated(true)
Java exception occurred:
java.awt.IllegalComponentStateException: The frame is displayable.
	at java.awt.Frame.setUndecorated(Unknown Source)

On the other hand, if we try to call setUndecorated on a new invisible figure then we’d see that the JFrame component is not yet created by Matlab:

% Create a simple Matlab figure
hFig = figure('Name','Plot example', 'Visible','off');
 
% Get the underlying Java JFrame reference handle (empty)
>> mjf = get(handle(hFig),'JavaFrame');
>> jWindow = mjf.getAxisComponent.getTopLevelAncestor
jWindow =
     []
>> jWindow = mjf.fHG2Client.getWindow
jWindow =
     []
 
>> jWindow.setUndecorated(true)
Attempt to reference field of non-structure array.

So we have a catch-22 situation: we can’t call setUndecorated until the JFrame is created, but Matlab only creates it when it displays the figure window, and then it’s too late to undecorate…

Attempt #2 – reparenting: an optical illusion

One way that I found around this problem is to reparent the Matlab JFrame‘s content onto a pure Java JFrame that has been made undecorated. To hide the Matlab figure after creating the JFrame, we can simply move the figure’s position to be outside the visible monitor area:

% Create a simple Matlab figure (visible, but outside monitor area)
t = 0 : 0.01 : 10;
hFig = figure('Name','Plot example', 'ToolBar','none', 'MenuBar','none');
hLine = plot(t, cos(t));
hButton = uicontrol('String','Close', 'Position',[307,0,45,16]);
% Ensure that everything is rendered, otherwise the following will fail
drawnow;
% Get the underlying Java JFrame reference handle
mjf = get(handle(hFig), 'JavaFrame');
jWindow = mjf.fHG2Client.getWindow;  % or: mjf.getAxisComponent.getTopLevelAncestor
% Get the content pane's handle
mjc = jWindow.getContentPane;
mjr = jWindow.getRootPane;  % used for the offset below
% Create a new pure-Java undecorated JFrame
figTitle = jWindow.getTitle;
jFrame = javaObjectEDT(javax.swing.JFrame(figTitle));
jFrame.setUndecorated(true);
% Move the JFrame's on-screen location just on top of the original
jFrame.setLocation(mjc.getLocationOnScreen);
% Set the JFrame's size to the Matlab figure's content size
%jFrame.setSize(mjc.getSize);  % slightly incorrect by root-pane's offset
jFrame.setSize(mjc.getWidth+mjr.getX, mjc.getHeight+mjr.getY);
% Reparent (move) the contents from the Matlab JFrame to the new JFrame
jFrame.setContentPane(mjc);
% Make the new JFrame visible
jFrame.setVisible(true);
% Hide the Matlab figure by moving it off-screen
pos = get(hFig,'Position');
set(hFig, 'Position',[-1000,-1000,pos(3:4)]);
drawnow;

Matlab figures are not pure JFrame but rather a subclass (com.mathworks.widgets.desk.DTSingleClientFrame). So instead of creating a new JFrame, we could create a new instance of Matlab’s class instead, potentially solving a few problems:

jDesktop = com.mathworks.mde.desk.MLDesktop.getInstance;
jFrame = javaObjectEDT(com.mathworks.widgets.desk.DTSingleClientFrame(jDesktop, figTitle));
% ...the rest is exactly the same as above...

Either way, we now get a nice undecorated window containing our Matlab contents (see screenshot above).
Once the undecorated JFrame becomes visible, we should not hide or delete the original Matlab figure, because this will stop rendering of the contents.

Working with the undecorated frame

We can modify the Matlab figure and its contents normally, just as if they still appeared within the original Matlab figure. This can be used to display a dynamic application splash-screen, that displays information on various initialization/loading steps. Or alternately we could use it to display a system health-monitor (small panel with red/green indicators), or maybe a graph with streaming market data or live news alerts. The usages are endless, limited only by your imagination, not by Matlab.
For example, let’s modify our plot dynamically using a timer, and set the close button’s callback to dismiss the new JFrame and original figure:

% Set a timer to dynamically update the plot every 0.1 sec
start(timer('TimerFcn', {@timerCallback,hLine}, 'ExecutionMode','fixedRate', 'Period',0.1));
% Set the close button callback
set(hButton, 'Callback',{@closeCallback,jFrame});
% This is the close button's callback
function closeCallback(hButton, eventData, jFrame)
   delete(ancestor(hButton,'figure'));
   dispose(jFrame);
end
% This is the plot timer's callback
function timerCallback(hTimer, eventData, hLine)
   xdata = get(hLine,'XData') + 0.1;
   set(hLine, 'XData',xdata, 'YData',cos(xdata));
   xlim([min(xdata) max(xdata)]);
end

Note: if you don’t hide the toolbar/menubar in the original Matlab figure, some of their functions will not work properly in the new JFrame (e.g., zoom, pan etc.). But in most use-cases we do not want a toolbar/menubar in an undecorated window. The example above showed an undecorated window without the toolbar/menubar.
If we wish to avoid having the new JFrame appear in the Operating System’s taskbar, we can use the following command:

jFrame.setType(javaMethod('valueOf','java.awt.Window$Type','UTILITY'))

Note that this command must be executed before the JFrame is made visible. Also note that it only works with Java 7, in other words Matlab R2013b (8.2) or newer (or if you are very adventurous and happen to use an older Matlab with a custom Java 7 installation).
But now that there is no taskbar component, how can we transfer focus to our new undecorated window? In other words, if another windows hides our new undecorated frame, how can we get it back on top?
A simple solution is to set the Matlab figure frame’s FocusGainedCallback to requestFocus for the newly created jFrame. Then, when we click the Matlab figure’s button on the taskbar, the new jFrame will pop into focus. In effect, this provides the optical illusion that the taskbar button refers to the undecorated window (since the actual Matlab figure is positioned beyond the monitor’s area):

hjWindow = handle(jWindow, 'CallbackProperties');
set(hjWindow, 'FocusGainedCallback', @(h,e)jFrame.requestFocus);

Likewise, we should instrument our Matlab figure so that when it is closed/deleted, so too is our new jFrame:

set(hjWindow, 'WindowClosedCallback', @(h,e)jFrame_.dispose);

undecorateFig and redecorateFig

I have encapsulated all of the above in a couple of very easy-to-use utilities that I just posted on the Matlab File Exchange: undecorateFig, redecorateFig. Using them can’t get any simpler than this:

undecorateFig;        % undecorate the current figure (gcf)
undecorateFig(hFig);  % hFig is any GUI handle (needs to be visible)
redecorateFig;        % redecorate the current figure (gcf)
redecorateFig(hFig);  % hFig is any GUI handle

Any sufficiently advanced technology is indistinguishable from magic – Arthur C. Clarke 🙂

Have you made some interesting use of this nice feature in your application? If so, please share it in a comment below.
A suggested related mini project for anyone interested: add an image reflection of the current figure contents beneath the figure. You could use my ScreenCapture utility or directly use java.awt.Robot.createScreenCapture(mjc.getLocationOnScreen), process the resulting image (blur, apply transparency gradient, crop at 50% height etc.) and place the resulting image within an undecorated JFrame placed directly beneath the main figure. You can instrument the figure (hjWindow)’s ComponentMovedCallback and ComponentResizedCallback to move/resize the reflection JFrame whenever the parent figure moves or is resized. You could use a timer to periodically update the reflection image so that it remains synchronized with the parent. You’ll probably also want to add a nice toggle-button to the figure’s toolbar to turn the reflection on/off. Maybe I’ll hack this project someday when I have some spare time. Or maybe someone will beat me to it… Care to try?

12 Responses

David March 20, 2015 at 13:11 Reply

Hi Yair,

Great post and very useful to know but isn’t this type of figure modification in breach of MathWorks license agreement?

http://www.mathworks.com/matlabcentral/answers/91579-is-it-possible-to-control-the-appearance-of-the-title-bar-and-the-title-bar-icon-of-figure-windows-i

Yair Altman March 21, 2015 at 10:08 Reply

@David – I was (and am) not aware that this violates any license agreement. I am an engineer and not a lawyer. If anyone thinks that it violates the license then they should indeed not use this technique. I do NOT condone any action that violates the license.

I do not see, in my non-expert eyes, how this could violate any Matlab license, considering the fact that we’re not modifying the Matlab figure’s frame/border – we’re simply creating a new Java JFrame, which coexists alongside the original (decorated) Matlab figure. Doing this should be perfectly ok, I think. Note that this is not legal advise in any way – I am NOT a lawyer. Again – if you think that doing this is problematic, then you should not do it.

Ruben Faibish March 26, 2015 at 10:30 Reply
Hi Yair

The line:
jFrame = javaObjectEDT(javax.swing.JFrame(figTitle));
jFrame = javaObjectEDT(javax.swing.JFrame(figTitle));
gives me an Undefined variable "javax" or class "javax.swing.jFrame". message

By the way, about the violation of Matlab licence, I think that if the figure still appears in the taskbar with a Matlab icon, then you are not hiding the Matlab belonging of the figure.
But I am a physicist and not a lawyer so don’t use it as a legal advice.

Yair Altman March 26, 2015 at 10:52 Reply

@Ruben – you got the error because you spelled JFrame (in javax.swing.JFrame) with a lowercase j instead of an uppercase J

Cheung May 31, 2015 at 23:20 Reply

Now I meet a ticklish problem when I use your tool,’undecorateFig’. First I would like to describe my purpose. When we run a GUI we write, a corresponding figure always appear. now I want to full screen the figure, not just maximizing the figure, simultaneously, the most important is that the titlebar of the figure and taskbar should all be hidden or removed. The ‘undecorateFig’ tool can remove titlebar and taskbar of the figure, but the figure is not a full-screen figure, the area corresponding to the previous titlebar isn’t filled by the background of figure. I don’t know how to deal with it. Could you help me? Thanks. For example, I have the following codes:

% the function can display two images. when the 'OK' button is pressed, the second image would appear.  
function display_img 
   screen = get(0,'ScreenSize');
   H1=figure('menubar','none');
   set(H1,'Position',[0, 0, screen(3),screen(4)]);
   img1 = imread('peppers.png'); 
   subplot(1,2,1);
   subimage(img1);
   axis off;
   H2 = uicontrol('Style','pushbutton','String','OK','Position',[200,100,100,40],'Fontsize',12);
   set(H2,'callback','my_callbacks');
   jFrame = undecorateFig(H1);
 
function my_callbacks
   img2 = imread('peppers.png'); 
   subplot(1,2,2);
   subimage(img2);
   axis off;

However, after I use ‘undecorateFig’ tool, the ‘OK’ button doesn’t work .

Best regards!

Yair Altman May 31, 2015 at 23:57 Reply

@Cheung – you can increase the figure’s height by 20 pixels to take into account the titlebar (i.e., screen(4)+20).

As for your OK button, you should review how to specify Matlab callbacks.
Cheung June 1, 2015 at 02:37 Reply

@Yair – Thank you for your speedy response. I have tired your suggestion, but it doesn’t work,and remains the previous status, 20 pixels isn’t increased, I don’t why.

Bryan Moosman July 1, 2015 at 07:00 Reply

Hello Yair,

I’ve tried both the code above and the functions you submitted. I’ve got 2 areas of feedback:

1. The figure sizing isn’t quite correct. It was a bit large and I had to remove the “+mjr.getY” term to get it to fit properly.
2. There are focus traversal problems with the current function. When I use it, I’m unable to input any text or use any of the UI elements inside as the focus keeps transferring elsewhere before any text can be input.

On a side note, I’m using this to generate a popup menu inside of another GUI. It works pretty well, and I don’t think it would be too much work to clean it up. I think it would do well as a MATLAB file submission if labeled as a ‘popup’ menu template.

By the way, I’m using 2014a.
Iliya July 7, 2015 at 15:16 Reply
Hello Yair,

I started seeing the following warning when trying to access the JavaFrame property:
```
Warning: figure JavaFrame property will be obsoleted in a future release. For more information see the JavaFrame resource on the MathWorks web site.
```
I might be mistaken here, but I don’t think I saw this before R2015a. Should we be worried?

I mainly use it to maximize figures, as per your tip from long ago, and did not look into new methods since the introduction of HG2. Is there another way to maximize figures now without getting warnings?

Thanks!

Iliya July 7, 2015 at 15:20 Reply

I remembered that this issue was discussed in your blog before. I must’ve hidden the warning in the past…

David M October 4, 2015 at 12:32 Reply

Hello Yair,

Is it possible to grab and drag a ‘frameless’ figure without the title bar? I would like to click somewhere in the frameless figure area, and drag it around.

Kind regards

Yair Altman October 5, 2015 at 09:19 Reply

@David – you will need to do this programmatically: this is typically handled by the window frame but without the frame it doesn’t happen automatically. So trap a mouse click event and then move the figure as per subsequent mouse-movement events.

Jan Kl September 10, 2019 at 13:12 Reply

Hello Yair,
not sure if you’re still reading comments here but I will give it a shot. I love the functions you provided on the File Exchange. However, when trying to undecorate a GUI created with the App Designer I ran into some problems.

My idea was to include the undecorate.m file in the start up function but it produces the following error:

Cannot undecorate a docked figure.

Note that I am not too familiar with handling MATLAB figures so this might be easy to fix but I just don’t know how.

Regards, Jan

Yair Altman September 10, 2019 at 13:23 Reply

@Jan – undecorate only works with legacy (Java-based) figures, not the new App-designer-created uifigures (which use a completely different technology).

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.

Rolf (18 days 11 hours ago): Disclosure: This comes from the developer/vendor of the Code Checker for MATLAB. Have a look at the Code Checker for MATLAB by MonkeyProof Solutions which has many such (configurable)...
Yair Altman (26 days 4 hours ago): In theory you could use the data: URI scheme (e.g. .load('data:text/html,<html ><body>Hello world</body></html>')), but for some reason it doesn’t work well in...
Sebastian (26 days 10 hours ago): Thanks for your update to the now unsupported `HTMLBrowserPanel`. I tried to replace it with the `LightweightHelpPanel` but the application I am working on is showing generated...
Leuze (48 days 11 hours ago): Hello, I would like to add a new object into SLDD and display columns according to my object properties <>
Eric Delgado (77 days 13 hours ago): Hey Yair, I think your site is the right place to share that I wrote ccTools, a lib that allows a lot of customizations of Matlab built-in web components (such as uifigure,...
Eric Delgado (77 days 13 hours ago): Hey guys, first of all, thanks to @Yair, your site saved me a lot of times! 🙂 That’s why I am sharing that I wrote m2mlapp (*.m => *.mlapp) file conversion, that...
François (94 days 11 hours ago): more than 10 years later it helps me after struggling few hours, so thanks you very much !
Yair Altman (95 days 9 hours ago): I am not familiar with a universal catch-all tab-completion mechanism for all functions, and it also doesn’t make much sense to me, because different functions use...
Arye (96 days 3 hours ago): hi, is there a universal functionSignature.json file that will allow my to get the function hints when opening brackets of my funcs? something that automaticly recognize my function...
Sunham (98 days 21 hours ago): This is an old article, but the issue persists even in 2023. 2023a: z = mat2cell(1:1e6,1,repmat(1,1,1e 6)); f = @() cellfun(‘isempty’, z); g = @() cellfun(@isempty,z);...
Yair Altman (108 days 12 hours ago): Robot only runs when you tell it to run a command such as keyPress. If you don’t tell it to run a command, it uses no CPU, so there’s no need to remove the Robot...
Eric (108 days 23 hours ago): 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...
Elsa Smith (109 days 14 hours ago): I recently used java.awt.Robot to perform GUI testing on MATLAB and found it to be an extremely easy and useful way to control mouse movements.
Elsa Smith (109 days 14 hours ago): I’m suspecting that the slow performance of my GUI may be due to the use of java.awt.Robot. Is there a way to cancel/stop/remove the robot after it has been created, or is...
Michelle Kline (110 days 7 hours ago): *edit* tip about fopen(), not about fwrite(). ‘Wb’ vs. ‘wb’

Attempt #1 – direct invocation

Attempt #2 – reparenting: an optical illusion

Working with the undecorated frame

undecorateFig and redecorateFig

Related posts:

12 Responses

Leave a Reply