Can you guess which built-in Matlab function is the top search-term on UndocumentedMatlab.com and yet one of the least discussed topic on the CSSM forum?
The answer is uitree – Matlab’s built-in function for displaying data in a hierarchical (tree) GUI component. uitree has been included in all Matlab 7 releases, but has never been officially supported. Like most other uitools in the %matlabroot%/toolbox/matlab/uitools/ folder, uitree and its companion uitreenode are semi-documented, meaning that they have no support or doc-page, but do have readable help sections within their m-files. In our case, edit the uitree.m and uitreenode.m files to see their help section.
Note the following comment within %matlabroot%/toolbox/local/hgrc.m, which implies that uitree may soon become fully supported, although its interface might change somewhat (as was the case when uitable became supported in R2008a):
Temporarily turn off old uitree and uitreenode deprecated function warning… When we introduce the new documented uitree to replace the old undocumented uitree …
Like most other uitools (e.g. uitable and uitab), uitree is based on an underlying Java component, which ultimately extends Swing’s standard JTree. uitree sets up a scrollable JTree on-screen without the hassle of setting up a scrollable viewport and other similar nuts and bolts. In fact, you don’t need to know any Java to use uitree (although knowing JTree can greatly help you customize it) – uitrees can be manipulated using pure Matlab code, as shall be seen below.
uitree accepts an optional figure handle followed by P-V (property-value) pairs. Settable properties are Root, ExpandFcn, SelectionChangeFcn, Position (also Parent, but read on). As in uitab, a ‘v0′ input argument may be necessary to suppress a warning message. Note that uitrees are always created as a direct child of the containing figure, ignoring creation-time Parent values. However, the Parent property can be modified following the tree’s creation:
[mtree, container] = uitree('v0', 'Root','C:\', 'Parent',hPanel); % Parent is ignored set(container, 'Parent', hPanel); % fix the uitree Parent

A simple uitree
uitree returns two arguments: a handle to the created tree (a Java object wrapped within a Matlab handle) and an entirely-undocumented second optional argument holding a handle to the Matlab GUI container of the created tree. These two arguments are exactly the two arguments returned from the javacomponent function that I described last week.
uitreenode
uitree automatically understands Root objects of type Handle Graphics, Simulink model or char string (interpreted as a file-system folder name). Other Root types require setting dedicated ExpandFcn, SelectionChangeFcn Matlab callbacks (see uitree‘s help section or below for examples).
If we need to create a custom tree hierarchy (i.e., our root node is not an HG object, Simulink model or folder name), then we need to use the semi-documented uitreenode function as follows:
node = uitreenode('v0',handle(mtree),'my root','c:\root.gif',false); mtree.setRoot(node); set(mtree,'Root',node); % alternative to mtree.setRoot()
uitreenode accepts 4 arguments: a string or handle value (the node’s “internal” value), a string description (shown next to the node’s icon), an icon filename ([] will result in an icon assigned based on the node value), and a flag indicating whether the node is a leaf (no children) or not.
uitreenode returns a node object, which is little more than a Matlab handle wrapper for a Java Swing DefaultMutableTreeNode.
Node manipulation
Nodes can be added, moved or removed by node methods: node.add(anotherNode) adds anotherNode to the end of this node’s children list (possibly detaching it from its previous parent); node.insert(anotherNode,index) does the same but inserts anotherNode at a specific child index, rather than at the end; node.clone() makes a duplicate of this node that can then be added to another node; node.remove(index) and node.remove(node) remove a specific node whereas node.removeFromParent() removes this node; node.removeAllChildren() removes all children, if any, of this node.
Nodes can also be added and removed at the tree level: mtree.add(parent,nodes) allows adding a list of nodes to a parent node and mtree.remove(nodes) removes the specified nodes.
In order to programmatically collapse and expand nodes, use mtree.collapse(node) and mtree.expand(node).
Nodes can be programmatically selected using mtree.setSelectedNode(node). Multiple nodes may be selected using mtree.setSelectedNodes, if an earlier call to mtree.setMultipleSelectionEnabled(true) was made (default is multiple-selection disabled):
mtree.setSelectedNode(root); % root is a node mtree.setSelectedNodes([root,node1,node2]); % select 3 nodes

programmatically selecting multiple tree nodes
The currently-selected node(s) can be accessed using mtree.getSelectedNodes. Node selection callbacks often require knowledge of the currently selected rows:
% Tree set up mtree = uitree(..., 'SelectionChangeFcn',@mySelectFcn); set(mtree, 'SelectionChangeFcn',@mySelectFcn); % an alternative % The tree-node selection callback function nodes = mySelectFcn(tree, value) selectedNodes = tree.getSelectedNodes; if ~isempty(selectedNodes) % ... end end % mySelectFcn
Interested readers might also benefit from looking at the tree manipulations that I have programmed in my FindJObj utility.
Next week’s article will show how uitrees can be customized. There are numerous possible customizations, including icons, labels, appearance, and behavior. So if you have any special request, please post a comment below.
Related posts:
- Customizing uitree This article describes how to customize Matlab GUI tree controls created using the undocumented uitree function...
- Customizing uitree nodes – part 1 This article describes how to customize specific nodes of Matlab GUI tree controls created using the undocumented uitree function...
- Customizing uitree nodes – part 2 This article shows how Matlab GUI tree nodes can be customized with checkboxes and similar controls...
- An interesting uitree utility ExploreStruct is a utility that shows how custom uitrees can be integrated in Matlab GUI...
- 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....
- Tab panels – uitab and relatives This article describes several undocumented Matlab functions that support tab-panels...


Hello,
I’m trying to make a tree to store links to interesting m-files.
So I’d like to learn a bit more about using Uitree.
This is the code I have so far.
I have problems adding nodes in the tree : I don’t get my tree refreshed without restarting my gui.
Any feedback is welcome
Luc VDP –
Yair will correct me if I’m wrong but I think some of your problem might be related to the fact the ML tree is set up for lazy loading. The leafs aren’t actually created until you expand. So if you want a leaf to show up on a refresh (rather than a user actually clicking on it) you’ll actually have to expand to its location programmatically (I know there’s an .expandrow method but there are probably other ways to).
Scott
For Luc : maybe this is too late or you figure it out, but to refresh the display after altering nodes, you should use the reloadNode() method on the parent node.
Any idea on how to enable Drag and Drop on older versions of uitree? In Matlab 7.0.4 (Windows), uitree.m mentions a “DndEnabled” but it appears to have no affect. However, with ML 2007a DnD appears to be enabled by default.
What would be really useful is to have DnD available across a figure and or between panels but I’d imagine that’s pretty complicated.
Scott
Scott
Below are some generic solutions that I have taken out of some code I developed to simulate drag-and-drop between a JTree and a MATLAB figure using the WindowButtonMotion callback.
You may need to shake the mouse to initiate the callback on faster PCs- but that becomes second nature surprisingly quickly.
Error. The “@GUIWindowButtonMotionFcn” in the code above should be “fcn” for a generic solution. GUIWindowButtonMotionFcn is just the standard callback in my particular application.
Is there anyway to have the parent of a tree be a panel rather then a figure?
Thanks.
@Stephan – as explained in the article, you can set a tree’s parent to a uipanel using the Parent property, but only after the tree has been created:
I would like to say, I just discovered this blog, and am really blown away. I’m loving all the new stuff I’m learning.
I’ve been trying to implement a GUI with three tabs. Each tab has a child panel and in one of the tabs I’ve tried to place a uitree. However, regardless of how I set the uitree’s parent value, it always seems to be the figure, and not the panel on the tab. As a result, the uitree is always displayed regardless of which tab is selected.
I’ve included the code below. Is there something obvious I’m doing incorrectly?
@Drew – thanks for the compliment.
uitree is basically just a Java component, and Matlab’s implementation of uitab has a known bug that it does not hide Java or ActiveX objects when switching tabs.
The link I just gave provides some leads to solving this issue; you can try modifying the m-files in the folders %matlabroot%/toolbox/matlab/@uitools/@uitabgroup and /@uitools/@uitab, or you can use an actual JTabbedPanel (or one of several other Tab implementations mentioned in my uitab article) rather than Matlab’s built-in uitab.
No easy fix, I’m afraid…
- Yair
Hello,
I have a question regarding tree creation.
Typically, I would use node.setSelectedNodes() to mark a parent and then create a new child node below using treeModel.insertNodeInto().
The problem I am having is that Matlab seems not to wait for the setSelectedNodes-command to be finished before resuming its own code, and therefore, the order of the nodes gets mixed up (some times).
My first and rather unsatisfying solution to the problem was to use pause() after each selection, making the tree build up very slowly.
Is there any way to determine how long the java element exactly needs to finish the setSelectedNodes-command?
Or is this error maybe due to the old Matlab version I am using, 2006a?
Many thanks for any thoughts on this,
Tony
@Tony – You do not need to select the parent node.
As I said in the main article above, nodes can be added directly: node.add(anotherNode) adds anotherNode to the end of node‘s children list (possibly detaching it from its previous parent); node.insert(anotherNode,index) does the same but inserts anotherNode at a specific child index, rather than at the end of the children list.
I have created a tree inside a GUI, I do this in the figure create function. So the tree will be available to all the widgets, I put the tree into handles (handles.mtree=tree;). When I leave the create function a get(handles.mtree) returns a tree. But when I try to access it from other widgets, the command get(handles.mtree) returns the container that was created in the in my call to uitree. How do I get back to the actual tree?
@Teresa – I’m not exactly sure what you mean, but if I guess correctly, you may be missing a call to guidata(hObject,handles); after you modify the handles struct with the uitree handle. If you don’t use guidata(), then the handles struct is not updated outside the function.
-Yair
Thanks for your answer. I found another way to get back to the tree. But now I have another question.
% I am trying to store information into the node of the tree to be accessed
% later in my processing.
% I am:
% 1) creating the tree
% 2) createing a new node and putting data into it’s UserData area
% 3) inserting it into the tree
% 3) selecting that node and trying to get the data back.
% 1) Create the tree
objects = uitreenode(‘v0′, ‘Objects’, ‘Objects’, [], false);
root = uitreenode(‘v0′, ‘Scenario’, ‘Scenario’, [], false);
root.add(objects);
scTree = uitree(‘v0′, ‘Root’,root);
scTree.setSelectedNode(objects)
selNode=scTree.getSelectedNodes;
selNode=selNode(1);
% 2) Create the new node and put data into the userdata area
newNode=uitreenode(‘v0′,’selected’,struct.name,[],0);
% create a structure to put into the newNode userdata area
struct.name=’abc’;
struct.val=1;
newNode.UserData=struct;
% NOTE: The new node is a “javahandle.com.mathworks.hg.peer.UITreeNode”
% whereas newNode.java is a “com.mathworks.hg.peer.UITreeNode:abc”
% 3) Insert it into the tree
selNode.add(newNode)
% or scTree.Model.insertNodeInto(newNode,selNode,selNode.getChildCount());
scTree.setSelectedNode(newNode);
% 3) selecting that node and trying to get the data back.
selNode=scTree.getSelectedNodes;
selNode=selNode(1);
% NOTE: selNode is a “com.mathworks.hg.peer.UITreeNode:abc”, the same as
% newNode.java.
% My question is how do I get back to the userdata in the
% “javahandle.com.mathworks.hg.peer.UITreeNode” object create earlier??
@Teresa – Use the handle method ie: selNode.handle. This will return the javahandle.com.mathworks.hg.peer.UITreeNode you need. So for your example selNode.handle.UserData will return your struct. handle and java are complementary methods for converting to and from the javahandle package.
Thank You!
Thank You!
Thank You!
I’ve got a giant Excel file (~6000 entries) with values like this:
/CE_2/CE2_Normal_Telemetry/CCE_Amp_Temperature_Trip_Low
/CE_2/CE2_Normal_Telemetry/CCE_Amplifier_Temperature_Rate
/CE_2/CE2_Normal_Telemetry/CCE_Converter_Temp_Trip_High
/CE_2/CE2_Normal_Telemetry/CCE_Converter_Temp_Trip_Low
/CE_2/CE2_Normal_Telemetry/CCSDS_API
/CE_2/CE2_Normal_Telemetry/CCSDS_Sequence_Count
/CE_2/CE2_Normal_Telemetry/CCSDS_Size
/CE_2/CE2_Normal_Telemetry/CCSDS_Time
/CE_2/CE2_Normal_Telemetry/CRC
/CE_2/CE2_Normal_Telemetry/CSYNC
Writing gargantuan code to decimate and rebuild this list manually in a UITREE.
Anybody know of a shortcut?
Hi
Great post and discussion about “the tree”. Is there any way to make “Computer” or “Desktop” root, so the entire PC can be browsed?
Regards,
Henrik
Henrik,
You could do it yourself, or use uigetfile instead.
Regards,
Jason
All,
I’m having a lot of problems with uitree – specifically with the expand function. If I give the root node more than one child and It returns those two node’s in the roots expand handler, uitree chokes… This is topping off two days of frustration in using uitree.
All this frustration has got me thinking… What’s the advantage to uitree over simply implementing a JTree? What’s the advantage to all these ML wrapped java objects? I’ve put JTree’s in my ML apps before with little or no problems whatsoever. What am I getting for all the uitree frustration? Simplicity? Ease of use? I’m not seeing it.
@Joe – I tend to agree that if you know your way around Java’s JTree (or better still, JIDE’s JTree extensions) then you don’t gain much with uitree. However, keep in mind that many if not most Matlab users are not so comfortable using Java – a built-in Matlab wrapper would be something they would happily use, but not a Java JTree.
It was the same story with Matlab’s uitable. After many years in undocumented limbo, uitable (which was initially not much more than a JTable wrapper) finally became documented in 2008. Perhaps the same will happen to uitree some day…
Thanks for the reply Yair. I agree with you. I’m not a Java power coder but the online doc is very thorough. I can bump my way though. Java in ML is somewhat tedious although a lot less so now that I’m in ML 2010 and awtinvoke is no longer needed. If you write software for a living and have the time to learn, picking up Java is time well spent I think. I think I’ll go back to a JTree for now and maybe pick up uitree when it’s full grown. Thanks for all you Java support on this forum. I wouldn’t have gotten very far without it.
Hi,
I have problem using uitree and uicontrol together. I am using a tree and a edit box on a figure window. I am trying to read different data through edit boxes for each node.
Edit box’s callback function is not getting called when I immediately click on the tree’s node after entering data in edit box. After entering data in edit box, If I click enter or click on any other uiobject or on figure, then the callback is invoked. Edit box Callback is not working if I click immediately on tree’s node. Can someone suggest me how to fix this problem?
@Venkat – try to set your edit-box’s FocusLostCallback property, because the standard Matlab handles indeed do not update the edit-box’s value in such cases. You’ll need to gain access to the edit-box’s underlying Java handle for this, using the findjobj utility.
I have a problem with NodeSelectedCallback, in a GUIDE project when the function is called for some reason it doesn’t consider the calling figure as its current figure
I tested that using the below simple program that draws a a tree with one node, in the callback function I ask for the current figure using gcf, it creates a new one.
Any clue why this happens ?
@Johnson – gcf only returns the current figure if its HandleVisibility property is ‘on’. Otherwise, it skips this figure and if no other figure is open that has HandleVisibility=’on’, then gcf will simply create a new (empty) figure.
To solve this, you have several choices:
1. Set your figure’s HandleVisibility property to ‘on’
2. Run set(0,’ShowHiddenHandles’,'on’) – (the default is ‘off’)
3. Use gcbf instead of gcf