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

UISplitPane

Posted By Yair Altman On March 28, 2009 | __18 Comments__

One of my many File Exchange submissions, UISplitPane ^{[3]}, was chosen yesterday as Matlab Central’s Pick of the Week ^{[4]} (thanks Jiro!). UISplitPane was probably my most challenging submission to date. I thought it would be a good point in time to share some of the undocumented features that I used in UISplitPane. Readers are encouraged to download UISplitPane.m and look at its code.

The basic problem which UISplitPane solves is the inability in Matlab to construct a dual pane separated by an interactive divider. Such split-panes are very common in modern GUIs, including Matlab tools, but were never available for Matlab GUIs. Java Swing has the JSplitPane control, but Matlab axes cannot (as yet) be added to Java containers. A similar problem exists for tabbed-panes ^{[5]}, and Matlab provided a very innovative solution for this (the semi-documented ** uitabgroup** function), which is described in a separate post

To make a long story short, the solution was to create an off-screen (invisible) JSplitPane, extract only its narrow central divider sub-component, and place that onscreen using * javacomponent*. I encourage readers to look at the

The Java divider’s reference is then converted into a Matlab * handle*, so that some extra properties can be added using

Pure-Matlab code then attaches standard Matlab uipanels as sub-panes on either side of the divider. Property linkages (this will be detailed in later posts about schema.prop’s getter/setter functions and * handle.listener*) ensure that whenever the divider is dragged or programmatically modified, the two sub-panes on its sides will be resized accordingly, together with all their content (axes and controls). Since the two split panes are simple uipanels, they can contain not only axes and controls but also other uisplitpanes, creating a hierarchy of split-panes:

[hDown,hUp,hDiv1] = uisplitpane(gcf, 'Orientation','ver', 'dividercolor',[0,1,0]); [hLeft,hRight,hDiv2] = uisplitpane(hDown, 'dividercolor','r', 'dividerwidth',3); t=0:.1:10; hax1=axes('Parent',hUp); plot(t,sin(t)); hax2=axes('parent',hLeft); plot(t,cos(t)); hax3=axes('parent',hRight); plot(t,tan(t)); hDiv1.DividerLocation = 0.75; % one way to modify divider properties... set(hDiv2,'DividerColor','red'); % ...and this is another way...

UISplitPane makes use of some semi-documented internal helper functions: * hgfeval* is used in the mouse callbacks, in order to chain the original WindowButton callback (if available);

UISplitPane behaves nicely in the presence of Mode Managers (zoom, pan, …) by using the figure’s undocumented ‘ModeManager’ property and setting its ‘ButtonDownFilter’ to bypass mode.

Finally, the figure’s undocumented ‘JavaFrame’ property is used to get a reference to the figure’s AxisComponent container, which is needed for setting mouse callbacks that behave better than similar callbacks at the figure level.

All-in-all, UISplitPane is perhaps a good example of combining a variety of unrelated undocumented Matlab features in order to achieve a coherent application.

An interesting side-note: Matlab 7.6 (R2008a) and onward contain a reference to * uisplittool* and

__ Addendum Jan 14, 2015__: For an alternative implementation of split-panes, see here

Categories: GUI, Java, Listeners, Medium risk of breaking in future versions, UI controls

18 Comments (Open | Close)

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

URL to article: **https://undocumentedmatlab.com/blog/uisplitpane**

URLs in this post:

[1] Image: **http://undocumentedmatlab.com/feed/**

[2] **email feed**: **http://undocumentedmatlab.com/subscribe_email.html**

[3] UISplitPane: **http://www.mathworks.com/matlabcentral/fileexchange/23073**

[4] Matlab Central’s Pick of the Week: **http://blogs.mathworks.com/pick/2009/03/27/gui-layout-part-6/**

[5] tabbed-panes: **https://undocumentedmatlab.com/blog/tab-panels-uitab-and-relatives/**

[6] here: **https://undocumentedmatlab.com/blog/unorthodox-checkbox-usage**

[7] Continuous slider callback : **https://undocumentedmatlab.com/blog/continuous-slider-callback**

[8] Inactive Control Tooltips & Event Chaining : **https://undocumentedmatlab.com/blog/inactive-control-tooltips-event-chaining**

[9] Setting line position in an edit-box uicontrol : **https://undocumentedmatlab.com/blog/setting-line-position-in-edit-box-uicontrol**

[10] Additional uicontrol tooltip hacks : **https://undocumentedmatlab.com/blog/additional-uicontrol-tooltip-hacks**

[11] The javacomponent function : **https://undocumentedmatlab.com/blog/javacomponent**

[12] Customizing combobox popups : **https://undocumentedmatlab.com/blog/customizing-combobox-popups**

[13] : **http://swing-components.safe-install.com/**

Click here to print.

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

18 Comments To "UISplitPane"

#1 CommentByMikhailOn April 1, 2009 @ 2:22 pmDear Yair,

Thank you very much for starting blogging and investing so much effort in gaining and sharing you knowledge!

About split pane: I think that this component is great for axes and possibly few uicontrols, but would be much more powerfull when embedded into a consistent Layout Manager. What do you think about it?

It is really valuable to see all undocumented features, but apart from this point why have you opted for such complex implementation? I naively think it could be possible in pure matlab…

#2 CommentByYair AltmanOn April 2, 2009 @ 3:29 am@Mikhail – uisplitpane (or the split-panes concept, same as the tab-panes concept) is a component that can be embedded into any Matlab container or Layout Manager (Matlab itself has several layout managers – see the File Exchange), just like any other Matlab component/container. That was an important design point of uisplitpane. I agree that my sample screenshot would be more powerful if I showed the split-panes embedded in some Matlab uipanel – If I have some spare time I’ll do this.

Using the Java divider (as opposed to pure-Matlab button) enabled me to use its internal one-click flush hotspots (the arrows near the top/left end of the dividers that enable to flush the divider all the way to the side in one click) with a special mouse hover cursor. The property listeners were required to ensure that whenever the divider was modified, the split-panes did as well – this cannot be done in pure Matlab. The other undocumented functions had their own special reasons too.

#3 CommentByweiOn April 2, 2009 @ 6:41 amYair, This is nice. How easy to implement a round slider, like a meter?

#4 CommentByYair AltmanOn April 2, 2009 @ 7:02 amWei – the standard javax.swing.JSlider doesn’t have this out-of-the-box, but you can easily integrate 3rd-party components that do this. Google is your best friend, or search one of numerous Swing component repositories, like

^{[13]}#5 CommentByAnonymousOn May 15, 2009 @ 4:17 amThis will solve the problems people have with R2008b and latter (exceptions…)

This also solve the exceptions with your brilliant Systray software.

Regards

#6 CommentByYair AltmanOn May 15, 2009 @ 4:21 amThanks J

#7 CommentByAlexanderOn May 4, 2012 @ 1:09 amDear Yair, dear Anonymus,

while trying to implement my own code to use a systray icon (Yair, your

function is great but throws many warnings about “depreciated use of set/get” in more recent Matlab versions), I stumbled over another error message using the java code.systrayThough above code resolves the issue in Matlab 2010b, in 2011b, the issued event is

`com.mathworks.widgets.desk.DTDocumentBar.wantsToHandle`

So you should add this to your list.

By the way: Which events are triggered by these four (to be removed) event_listeners and why could they easily be removed without changing other stuff?

The code I used is basically:

Thanks for your great work,

Alexander

#8 CommentByAlexanderOn May 4, 2012 @ 2:56 amAddendum:

After turning off

`com.mathworks.widgets.desk.DTDocumentBar.wantsToHandle`

, also`com.mathworks.widgets.tooltip.ToolTipAndComponentAWTListener.mouseInTipComponent`

throws an error. But this is not part of the event_listener list.

#9 CommentByAnonymousOn May 15, 2009 @ 4:37 amPlease replace with this condition:

With these 3 event listeners removed, it seems no more exeptions occurs (hopefully).

#10 CommentByZachOn March 15, 2010 @ 2:37 pmThis works great – one question I have though, I’m not able to get a uitree to resize when placed in one of the panes this creates:

When the sliders are moved, the uitree doesn’t change size with the pane.

#11 CommentByZachOn May 5, 2010 @ 8:53 amUpdate, here’s an ugly hack I’ve inserted into

so that auisplitpanecorrectly resizes if it’s in one of the panes.uitreeIn the updateSubPaneSizes, line 800, I’ve inserted:

Seems to work well enough.

Thanks,

Zach

#12 CommentByYogeshOn November 23, 2010 @ 1:18 pmYair/Anonymous,

Where do I insert the following lines to remove the bug with R2008+?

#13 CommentByYair AltmanOn November 30, 2010 @ 4:12 pm@Yogesh – You can do this anywhere in your Matlab session, or at the beginning of the function. Note that the relevant condition was modified by Anonymous (see the comments above) to:

#14 PingbackByuiinspect | Undocumented MatlabOn January 24, 2013 @ 7:07 am[…] In a general case where we might wish to embed Matlab graphs in one of the side panels, we would need to employ a more sophisticated solution (see my UISplitPane utility). […]

#15 PingbackByRich-contents log panel | Undocumented MatlabOn September 18, 2013 @ 7:01 am[…] Draggable (resizable) panel borders (note that this feature does not work in the new HG2 – I hope it will be fixed by the time that HG2 is released) […]

#16 CommentByBenOn January 3, 2014 @ 11:58 amI know this is an old topic but I had a question/problem I hope someone can help me with.

Using the example from the file exchange I noticed that the mouse pointer no longer updates. Example, select the “zoom in” button, mouse over an axes and the pointer does not change. However, it still functions correctly. Is there a way to fix this so the Pan/Zoom/Etc. positioning controls retain the correct mouse pointer.

#17 CommentBySebasOn October 14, 2014 @ 1:16 amCiao Yair!

It seems that the suggestions to remove all those Java exception (even with the conditions update) do not work with Matlab 2013b onward. It is a shame as the power of what you are sharing is amazing! Is there any chance to provide us some working code so we can take advantage of your very great job? 😉

Many thanks!

Seb

#18 CommentByMollieOn September 28, 2015 @ 6:18 pmHi Yair,

I recently updated to Matlab 2015a and thus updated my UISplitPane method in my program. I was using your previous UISplitPane method on Matlab 2012a and referenced a property called ‘offsetPosition,’ it was stored within plotDivider; is there a reason why this is not written into the Matlab 2015a version?

Also, in the old UISplitPane method, there was a line “G.Z.updateSubPaneSIzes = @updateSubPaneSizes” so that I could call updateSubPaneSizes elsewhere in the program, do you have a suggestion for how I could call updateSubPaneSizes outside of UISplitPane?