- Undocumented Matlab - https://undocumentedmatlab.com/blog_old -
Figure window customizations
Posted By Yair Altman On June 1, 2016 | No Comments
A friend recently asked me, in light of my guesstimate [3] that Java-based Matlab figures will be replaced by web-based figures sometime around 2018-2020, whether there are any “killer features” that make it worthwhile to use undocumented Java-based tricks today, despite the fact that they will probably break in 2-5 years. In my opinion, there are many such features; today I will focus on just a subset of them – those features that relate to the entire figure window.
Over the years I wrote many articles here about figure-level customizations [4], as well as an entire chapter in my Matlab-Java programming book [5]. So today’s post will be a high-level overview, and users who are interested in any specific topic can visit the referenced links for the implementation details.
JavaFrame [6] is an undocumented hidden property of the figure handle that provides access to the underlying Java window (JFrame
) peer object’s reference. Since R2008a, a warning is issued whenever we retrieve this property:
>> jFrame = get(gcf,'JavaFrame'); 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.)
Until HG2 (R2014b+) we could suppress the warning by simply wrapping the figure handle within a handle() call, as explained here [6]. Since R2014b we need to use the warning function to do this:
warning('off', 'MATLAB:HandleGraphics:ObsoletedProperty:JavaFrame');
We can do several things directly with the JavaFrame‘s properties and methods, including:
JFrame
(Java window), as discussed belowMathWorks have set up a dedicated webpage where you can specify how you are using JavaFrame and why it is important for you: http://www.mathworks.com/javaframe [9]. I encourage you to use this webpage to tell MathWorks which features are important for you. This will help them to decide which functionality should be added to the new web-based figures.
The JavaFrame handle enables direct retrieval of the containing Java JFrame
[10] (window) reference, using several alternatives. Here are two of these alternatives (there are others):
% Alternative #1 >> jWindow = jFrame.getFigurePanelContainer.getTopLevelAncestor jWindow = com.mathworks.hg.peer.FigureFrameProxy$FigureFrame[fClientProxyFrame,72,62,576x507,...] % Alternative #2 try jClient = jFrame.fFigureClient; % This works up to R2011a catch try jClient = jFrame.fHG1Client; % This works from R2008b-R2014a catch jClient = jFrame.fHG2Client; % This works from R2014b and up end end jWindow = jClient.getWindow;
jWindow
reference, we can do several additional interesting things:As you can see, there are numerous very interesting customizations that can be done to Matlab figures which rely on the undocumented implementation. Here are a couple of usage examples that you can easily adapt (follow the links above for additional details and usage examples):
jWindow.setEnabled(false); % disable entire figure [true/false] jWindow.setMinimized(true); % minimize window [true/false] jWindow.setMaximized(true); % maximize window [true/false] jWindow.setAlwaysOnTop(true); % set to be always on top [true/false] % Set a Matlab callback function to a window focus-gain event hjWindow = handle(jWindow, 'CallbackProperties'); hjWindow.FocusGainedCallback = @myCallbackFunc;
In addition to the Java-based features above, some functionalities can also be achieved via direct OS manipulations, for example using Jan Simon’s great WindowAPI utility [23] (Windows-only), although I typically prefer using the Java approach since it is cross-platform compatible.
Using all these features is super-easy, so there is not really a question of code complexity or technical risk – the main question is whether to accept the risk that the associated code will stop working when Matlab figures will eventually become web-based.
This is an excellent question. I contend that the answer depends on the specific use-case. In one project you may decide that it is indeed worth-while to use these undocumented features today, whereas in another GUI you may decide that it is not.
It might make sense to use the features above in any of the following circumstances:
Here’s another twist to consider: do not take it for granted that when web-based uifigures replace Java-based figures all the documented functionality will work as-is on the new uifigures just as they have on the old figures. In fact, I personally believe that we will need to extensively modify our GUI code to make it compatible with the new uifigures. In other words, avoiding the undocumented hacks above will probably not save us from the need to recode (or at least adapt) our GUI, it will just reduce the necessary work somewhat. We encountered a similar situation with the graphics hacks that I exposed over the years: many people avoided them in the fear that they might someday break; then when R2014b came and HG2 graphics replaced HG1, it turned out that many of these supposedly risky hacks continued working in HG2 (examples: LooseInset [24], YLimInclude [25]) whereas quite a bit of standard fully-documented Matlab functionality was broken and required some recoding. I believe that the lessons from the HG2 migration were well studied and assimilated by MathWorks, but realistically speaking we should not expect a 100% full-proof transition to uifigures.
Still, accepting the risk does not mean that we should bury our head in the sand. Whenever using any undocumented feature in your code, I strongly suggest to use defensive coding practices, such as wrapping your code within try-catch blocks. This way, even if the feature is removed in R2020a (or whenever), the program will still run, albeit with somewhat diminished functionality, or in other words, graceful degradation. For example:
try jFrame = get(hFig, 'JavaFrame'); jFrame.setMaximized(true); catch oldUnits = get(hFig, 'Units'); set(hFig, 'Units','norm', 'Pos',[0,0,1,1]); set(hFig, 'Units',oldUnits); end
Once again, I urge you to visit http://www.mathworks.com/javaframe [9] and tell MathWorks which of the above features are important for you. The more users tell MathWorks that they depend on a specific feature, the more would MathWorks be likely to invest R&D efforts in enabling it in the future web-based figures.
Categories: Figure window, GUI, Hidden property, High risk of breaking in future versions, Java, Undocumented feature
Article printed from Undocumented Matlab: https://undocumentedmatlab.com/blog_old
URL to article: https://undocumentedmatlab.com/blog_old/figure-window-customizations
URLs in this post:
[1] Image: https://undocumentedmatlab.com/feed/
[2] email feed: https://undocumentedmatlab.com/subscribe_email.html
[3] my guesstimate: https://undocumentedmatlab.com/blog/adding-a-search-box-to-figure-toolbar#uifigure
[4] figure-level customizations: https://undocumentedmatlab.com/blog/tag/javaframe
[5] Matlab-Java programming book: https://undocumentedmatlab.com/books/matlab-java
[6] JavaFrame: https://undocumentedmatlab.com/blog/minimize-maximize-figure-window/#JavaFrame
[7] details: https://undocumentedmatlab.com/blog/minimize-maximize-figure-window
[8] setFigDockGroup utility: http://www.mathworks.com/matlabcentral/fileexchange/16650-setfigdockgroup
[9] http://www.mathworks.com/javaframe: http://www.mathworks.com/javaframe
[10] JFrame
: https://docs.oracle.com/javase/7/docs/api/javax/swing/JFrame.html
[11] details: https://undocumentedmatlab.com/blog/disable-entire-figure-window
[12] details: https://undocumentedmatlab.com/blog/frameless-undecorated-figure-windows
[13] details: https://undocumentedmatlab.com/blog/transparent-matlab-figure-window
[14] details: https://undocumentedmatlab.com/blog/blurred-matlab-figure-window
[15] details: https://undocumentedmatlab.com/blog/detecting-window-focus-events
[16] details: https://undocumentedmatlab.com/blog/matlab-callbacks-for-java-events-in-r2014a
[17] details1: https://undocumentedmatlab.com/blog/customizing-menu-items-part-2
[18] details2: https://undocumentedmatlab.com/blog/customizing-menu-items-part-3
[19] details1: https://undocumentedmatlab.com/blog/docking-figures-in-compiled-applications
[20] details2: https://undocumentedmatlab.com/blog/disabling-menu-entries-in-deployed-docked-figures
[21] details1: https://undocumentedmatlab.com/blog/setting-status-bar-text
[22] details2: https://undocumentedmatlab.com/blog/setting-status-bar-components
[23] WindowAPI utility: http://www.mathworks.com/matlabcentral/fileexchange/31437-windowapi
[24] LooseInset: https://undocumentedmatlab.com/blog/axes-looseinset-property
[25] YLimInclude: https://undocumentedmatlab.com/blog/plot-liminclude-properties
[26] Minimize/maximize figure window : https://undocumentedmatlab.com/blog_old/minimize-maximize-figure-window
[27] FindJObj – find a Matlab component’s underlying Java object : https://undocumentedmatlab.com/blog_old/findjobj-find-underlying-java-object
[28] Uitable sorting : https://undocumentedmatlab.com/blog_old/uitable-sorting
[29] Frameless (undecorated) figure windows : https://undocumentedmatlab.com/blog_old/frameless-undecorated-figure-windows
[30] Builtin PopupPanel widget : https://undocumentedmatlab.com/blog_old/builtin-popuppanel-widget
[31] Matlab toolstrip – part 2 (ToolGroup App) : https://undocumentedmatlab.com/blog_old/matlab-toolstrip-part-2-toolgroup-app
Click here to print.
Copyright © Yair Altman - Undocumented Matlab. All rights reserved.