Undocumented Matlab

FindJObj – find a Matlab component’s underlying Java object

Wednesday, January 6th, 2010

In a previous post, I explained that all Matlab GUI (except the axes plotting engine) is based on Java components, and showed how we can use this information to display HTML contents in Matlab uicontrols. In other posts, I have shown how a utility called findjobj can be used to access the underlying Java components to enable customizations that are unavailable in standard Matlab: setting the line location in an edit-box, customizing button appearance, setting uicontrol callbacks, or setting list-box mouse actions. I have also shown how findjobj can be used to display the component hierarchy of complex Matlab containers such as the figure window, GUIDE or the Editor.

The time is therefore well overdue for a formal introduction of findjobj, explaining its uses and internal mechanism. Of course, readers are welcome to continue using findjobj as a black-box utility, but I think important insight can be gained from understanding its inner details. Findjobj’s code is available for free download on the MathWorks File Exchange. It is one of my favorite submissions and is apparently well-liked by users, being highly reviewed and highly downloaded.

Findjobj has two main purposes:

1. Find the underlying Java object reference of a given Matlab handle – Historically this was the original purpose, hence the utility’s name. Findjobj was meant to extend Matlab’s standard findobj function, which does not expose Java components.
2. Display a container’s internal components hierarchy in a graphical user interface, to facilitate visualization of complex containers. This was later extended to also display and allow modification of the sub-components’ properties and callbacks.

Today I will focus on the first (programmatic) aspect; next week I will describe the second (GUI) aspect.

Findjobj’s heart is finding a control’s underlying Java handle. Unfortunately, this is not exposed by Matlab except in very rare cases. As hard as I tried, I could not find a way to directly access the underlying Java-peer handle. I therefore resorted to getting the control’s enclosing Java frame (window) reference, and then working down its sub-components hierarchy until finding the Java object(s) which satisfy the position and/or class criteria. To get the enclosing Java frame (aka TopLevelAncestor), I use the Matlab figure’s undocumented JavaFrame property. Using this property issues a standard warning (since Matlab release R2008a) of becoming obsolete in some future Matlab release. Since it worked so far, I have turned off this warning in findjobj’s code, but note that this code may well fail in some future Matlab version. If and when JavaFrame does become obsolete, be sure to look in this blog for workarounds…

Traversing the frame’s hierarchy presents several challenges: Main-menu items are accessed using different functions than other Swing components or sub-containers, and are not automatically accessible until first displayed. I have overcome this latter challenge by simulating a menu-open action in case menus should be searched (this is off by default since it takes several seconds and also changes the GUI focus). For “regular” sub-containers, sometimes we need to loop over getComponent(…) and in some other cases over getChildAt(…).

Another challenge was presented by the fact that Java positions start at (0,0) in the top left corner increasing rightward and downward, rather than starting at (1,1) in the bottom left and increasing upward as in Matlab. Moreover, Java positions are always pixel-based and relative to their parent container, which is different from Matlab (if the Matlab units is ‘pixels’ then the value is absolute; if ‘normalized’ then it returns a non-pixel value). To further complicate matters, some Matlab controls have a different size than their Java counterparts: some controls have a 5-pixel margins while others not, some controls are shifted by a pixel or two from their container’s border (for a total offset of up to 7 pixels), while some controls (such as popup-menus) have an entirely different reported size. In theory, we could use the Matlab component’s undocumented PixelBounds property (much faster than getpixelposition), but unfortunately PixelBounds turns out to be unreliable and returns erroneous values in many cases. Finally, different Java containers/components have different ways of returning their position: for some it is a getLocation() method, for others it is getX()/getY() and for others it is the X and Y properties (that sometimes have no corresponding getX()/getY() accessor methods!).

Having finally overcome all these challenges (and quite a few smaller ones, documented within the source code), I have wrapped the algorithm in a function interface that tries to emulate findobj’s. Using findjobj can now be as easy as:

% Modify the mouse cursor when over the button
hButton = uicontrol('string','click me!');
jButton = findjobj(hButton);
jButton.setCursor(java.awt.Cursor(java.awt.Cursor.HAND_CURSOR))

Modified uicontrol cursor - a Java property

…or as complex as:

% Find all non-button controls with the specified label
jControls = findjobj('property',{'text','click me!'}, 'not','class','button');

Space here is limited and findjobj is over 2500 lines long, so I have obviously not covered everything. I encourage you to download the utility and explore the code, and I gladly welcome your feedback.

Related posts:

1. FindJObj GUI – display container hierarchy The FindJObj utility can be used to present a GUI that displays a Matlab container's internal Java components, properties and callbacks....
2. JMI – Java-to-Matlab Interface JMI enables calling Matlab functions from within Java. This article explains JMI's core functionality....
3. Matlab and the Event Dispatch Thread (EDT) The Java Swing Event Dispatch Thread (EDT) is very important for Matlab GUI timings. This article explains the potential pitfalls and their avoidance using undocumented Matlab functionality....
4. Customizing Matlab labels Matlab's text uicontrol is not very customizable, and does not support HTML or Tex formatting. This article shows how to display HTML labels in Matlab and some undocumented customizations...
5. Rich Matlab editbox contents The Matlab editbox uicontrol does not handle HTML contents as do other uicontrols. In this article I show how this limitation can be removed....
6. Matlab layout managers: uicontainer and relatives Matlab contains a few undocumented GUI layout managers, which greatly facilitate handling GUI components in dynamically-changing figures....

Tags: FindJObj, GUI, Handle graphics, Java, JavaFrame, PixelBounds, Undocumented feature

Categories: Figure window, GUI, Handle graphics, High risk of breaking in future versions, Java, UI controls, Undocumented feature

This entry was posted on Wednesday, January 6th, 2010 at 2:06 pm PST
You can follow any responses to this entry through the RSS 2.0 feed.
You can leave a response, or trackback from your own site.

(No Ratings Yet)  Loading ...

Print

14 Responses to “FindJObj – find a Matlab component’s underlying Java object”

1. Peter says:

   January 7, 2010 at 3:44 am

   Dear Yair

   Thank you very much for your great, great website. One really gets a feel for what is going on behind the scens in matlab.

   I have a few question related to the findobj application:

   You say that everything except the Java plotting engine is based on Java. I would like though to use the panelling from findobj in an application with for insatnce a matlab plot in one of the panels. Does your comment mean that I will be unsuccesful with that? If not, can you please give me a quick hint on how to get this?

   Second, when you publish fíndobj in “High risk of breaking…” what is the risk then? Does it include the panels feature that I am after or do you rather think of the more programmatic part of it?

   Thank you very much in advance!

   Peter
2. Yair Altman says:

   January 7, 2010 at 6:20 am

   Thanks Peter.

   Unfortunately, you cannot embed a Matlab plot axis in a Java container (only Java components in a Matlab container). However, to solve this problem I have created the UISplitPane utility that behaves exactly like a Java JSplitPane, and enables interactively-resizable panels with Matlab plots:

   

   Two levels of UISplitPane, with customized dividers

   As for your second question, I indicated “High risk of breaking in a future version” because FindJObj is highly dependent on internal Matlab implementation, which may break without warning between Matlab releases. For example, the very next release (R2010a) might remove the JavaFrame property, on which findjobj relies. Of course, since I maintain this utility I will try to bypass the problem and upload a new version (and findjobj has an automated mechanism to detect and suggest this new version), but I cannot promise anything concrete. Some other undocumented features I believe to be less prone to breaking in future releases, and so they get a less severe warning. Note that I base the severity on gut instinct and calculated guesses – I have no official access to Matlab’s development roadmap.
3. Peter says:

   January 11, 2010 at 6:15 am

   Thank you very much Yair

   I will have a look at the UIsplitpane utility. It seems more appropiate for my use.

   Thanks again. It is a real cool site you have!

   Peter
4. Daniel says:

   January 13, 2010 at 8:24 pm

   Yair
   Your program is great, but I found some trouble using it. It seems like it only works with controls created by code. I tried to find underlying java object for controls created with GUIDE, and findjobj always returned empty handles arrays. it’s that posible? is there another way to find a JTextbox behind a uicontrol created with GUIDE?

   Thanks,
   Daniel
5. Yair Altman says:

   January 14, 2010 at 10:23 am

   @Daniel – It works for me…
   Perhaps you’re calling findjobj in your _OpeningFcn() instead of in your _OutputFcn() or in callbacks? This would explain the problem, since the GUI has not yet rendered onscreen in _OpeningFcn() (the figure is still invisible), so findjobj cannot find the Java handle.
6. Daniel says:

   January 14, 2010 at 2:28 pm

   Yair, you’re right. I was calling it in my OpenFcn() method. My purpose was set a InputVerifier to an edit control. Is there another callback in wich i can do that?

   Thank you very much!
7. Yair Altman says:

   January 15, 2010 at 12:35 am

   @Daniel – as I said, simply attach your InputVerifier in the _OutputFcn() instead of in the _OpeningFcn(). Both of these functions are automatically created by GUIDE: _OpeningFcn() is invoked before the figure is made visible and the Java peers are created; _OutputFcn() is invoked immediately after it’s made visible, when the peers are in place.

   I would be happy if you added a comment with your InputVerifier code, for the benefit of other readers. If the code is long, email me (altmany at gmail) and I’ll add a separate post about it.
8. Daniel says:

   January 15, 2010 at 4:55 pm

   Yair, i moved my code to the _OutputFcn, but findjobj still returns empty arrays. I couldn’t find out what is my error.
   i’ve written a simple code which replaces uicontrols with javax.swing.JTextFields:

   function [ output_args ] = ReemplazarControles(hObject)
   %UNTITLED2 Summary of this function goes here
   %   Detailed explanation goes here
    
       children = get(hObject,'Children');
       nSize = size(children);
       for i=1:nSize
           hControl = children(i);
           if isa(handle(hControl),'uicontrol') 
               cStyle = get(hControl,'Style');
               if strcmp(cStyle,'edit')==1
                   sPosition = get(hControl,'Position');
                   sUnits = get(hControl,'Units');
                   sParent = get(hControl,'Parent');
                   [text textcontainer] = javacomponent('javax.swing.JTextField',[0 0 100 100], hObject);
                   set(textcontainer,'Units','characters','Position',sPosition);
                   delete(hControl);
               end
           end
           if isa(handle(hControl),'uipanel')
               ReemplazarControles(hControl);
           end
       end
   end

   it works fine, but JTextFields not response Tab key strokes.
   I could use both methods. I don’t know wich is better.
   I deeply appreciate your help
9. Peter says:

   January 29, 2010 at 3:17 am

   Dear Yair

   I am sorry for this kind of java newbie question, but I am back using the panes from the findobj. Now, instead of including a figure (as I asked about above) in one of the panes I would like to put a uitable or preferably your createtable from the FEX. I have tried many approaches, but none of them successful. I would be very happy if you have any directions on how to do it or have an example.

   Thank you very much in advance!

   Best regards, Peter
10. Yair Altman says:

    January 29, 2010 at 4:00 am

    @Peter – look at the way I added the callbacks-table in the FindJObj and UIInspect utilities. The source code is available on the File Exchange.

    Yair
11. Peter says:

    January 29, 2010 at 4:31 am

    Thanks Yair! I will try to figure it out from there… As long as I know it should be possible, it puts a little more power behind the effort.

    Peter
12. Continuous slider callback | Undocumented Matlab says:

    February 8, 2010 at 7:08 am

    [...] AdjustmentValueChangedCallback property that is useful for our purposes and is accessible using the FindJObj utility. Simply download FindJObj from the File Exchange, and then: hSlider = [...]
13. Tabbed panes – uitab and relatives | Undocumented Matlab says:

    June 23, 2010 at 11:47 am

    [...] This object is not directly exposed by uitabgroup, but can be found using the FindJObj utility [...]
14. GUI integrated HTML panel | Undocumented Matlab says:

    June 30, 2010 at 12:19 pm

    [...] for undocumented features we need the editbox’s underlying JTextPane handle. This is done using the FindJObj utility [...]

   <pre lang="matlab">
   a = magic(3);
   sum(a)
   </pre>