One of my many File Exchange submissions, UISplitPane, was chosen yesterday as Matlab Central’s Pick of the Week (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, and Matlab provided a very innovative solution for this (the semi-documented uitabgroup function), which shall be described in a separate post. Unfortunately, uitabgroup’s solution cannot be applied to the split-pane problem since in JSplitPane’s case, the container overlaps the axes-containing panes.
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 addDivider() function which does this, setting mouse cursor and other interesting properties.
The Java divider’s reference is then converted into a Matlab handle, so that some extra properties can be added using schema.prop (which [you guessed it] will be described in a later post) and will become visible when using regular get.
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:
Two levels of UISplitPane, with customized dividers
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); setptr is used to set the mouse pointer (cursor).
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 uitogglesplittool in the javacomponent.m and %matlabroot%/bin/registry/hg.xml files. These are not valid functions (built-in or otherwise) and I could not figure out how this functionality can actually be used. At the very least it is certain that it is deeply undocumented and (of course) unsupported, leaving an open mystery for future investigation…
Related posts:
- Continuous slider callback Matlab slider uicontrols do not enable a continuous-motion callback by default. This article explains how this can be achieved using undocumented features....
- Setting listbox mouse actions Matlab listbox uicontrol can be modified to detect mouse events for right-click context menus, dynamic tooltips etc....
- Customizing listbox & editbox scrollbars Matlab listbox and multi-line editbox uicontrols have pre-configured scrollbars. This article shows how they can be customized....
- Setting line position in an edit-box uicontrol Matlab uicontrols have many useful features that are only available via Java. Here's how to access them....
- Uicontrol callbacks This post details undocumented callbacks exposed by the underlying Java object of Matlab uicontrols, that can be used to modify the control's behavior in a multitude of different events...
- Adding a context-menu to a uitree uitree is an undocumented Matlab function, which does not easily enable setting a context-menu. Here's how to do it....
 (No Ratings Yet) Loading ... |
 |
 Print
|
Dear 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…
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.
Yair, This is nice. How easy to implement a round slider, like a meter?
Wei - 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 http://swing-components.safe-install.com/
This will solve the problems people have with R2008b and latter (exceptions…)
This also solve the exceptions with your brilliant Systray software.
Regards
t=java.awt.Toolkit.getDefaultToolkit() ev=t.getAWTEventListeners() for i=1:length(ev) str=ev(i).getListener().getClass.toString if str.indexOf('com.mathworks.mwswing.desk.DTSelectionManager')>=0 || ... str.indexOf('javax.swing.plaf.basic.BasicLookAndFeel')>=0 t.removeAWTEventListener(ev(i)) end endThanks J
Please replace with this condition:
str.indexOf('com.mathworks.mwswing.desk.DTSelectionManager')>=0 || ... str.indexOf('javax.swing.plaf.basic.BasicLookAndFeel')>=0 || ... str.indexOf('com.mathworks.widgets.text.mcode.MLintDecorator')>=0With these 3 event listeners removed, it seems no more exeptions occurs (hopefully).
[...] (May 15, 2009): A kind reader today left a comment on another post of this blog with a solution for some reported Java exceptions when using systray in Matlab R2008b onward. [...]