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

Matlab layout managers: uicontainer and relatives

Posted By __Yair Altman__ On June 9, 2010 @ 3:03 pm In __GUI,Handle graphics,Low risk of breaking in future versions,Semi-documented function__ | __14 Comments__

When designing Matlab applications, we can either use Matlab’s designer (**guide**^{[3]}), or manually position each GUI component programmatically, using its **Position** property. Matlab lacks the layout managers so common in Java, that enable easy relative component positioning, taking into account dynamic container size, components spacing weights etc. Of course, we can always trap the container’s **ResizeFcn** callback to update our layout, but doing so is one royal pain in the so-and-so…

Luckily, there is (of course) an undocumented solution to this problem, and at the public’s demand ^{[4]} I will detail it below. It doesn’t solve all layout-management needs, but it goes a long way. Most importantly, it uses **pure Matlab** – no Java knowledge whatsoever is needed.

Matlab’s uicontainer family (* uicontainer*,

The basic * uicontainer* object appears to be little more than a transparent container for contained objects. It can be used interchangeably with

The UICONTAINER function is undocumented, and is not intended for direct use. The UIPANEL function should be used instead, as it provides more functionality.

In some cases, Matlab itself uses * uicontainer* instead of

>> [hActivex,hContainer] = actxcontrol('OWC11.Spreadsheet.11'); >> get(hContainer,'Type') ans = uicontainer

* uicontainer* objects are not very customizable. For example, unlike

Relatives of * uicontainer* are more useful in general:

* uiflowcontainer* is a

By default, objects are added from the top-left corner, depending on the * uiflowcontainer*‘s available space and dimensions: if width > height then rightward, otherwise downward. If the container’s dimensions change, for example by resizing the figure window, then the container’s components will automatically be resized accordingly:

hc = uiflowcontainer('Units','norm','Position',[.1,.1,.8,.8]); h1 = uicontrol('string','1','parent',hc); h2 = uicontrol('string','2','parent',hc); h3 = uicontrol('string','3','parent',hc);

The components flow direction within the container may be modified by setting the * uiflowcontainer*‘s

set(hc,'FlowDirection','BottomUp') set(hc,'FlowDirection','RightToLeft')

Spacing between the components and the container’s border, and between themselves, may be controlled via the **Margin** property. By default, **Margin** is set to 2 (pixels):

The advantage of using * uiflowcontainer* is its automatic resizing and positioning of components. Notice how we simply specified the

If we need to use fixed-dimensions components, we can use * uicontrol*‘s undocumented properties

set(h1, 'HeightLimits',[10,20], 'WidthLimits',[30,30]) set(h2, 'HeightLimits',[50,50]) set(h3, 'HeightLimits',[2,inf]) % =default value

Sometimes, however, no amount of component resizing is enough to fully contain all components within the * uiflowcontainer*:

set(h2, 'WidthLimits',[150,150]) set(h3, 'HeightLimits',[50,50]) % resize figure to see effect

Note: uiflowcontainer normally ignores the specified limits if they would cause the component to stretch beyond the container boundaries. This happens unless the limits are identical (as in the preceding example), which informs * uiflowcontainer* that it has no judgment in the component’s dimensions.

In more complex cases, consider coding your own customized class deriving from * uiflowcontainer*. An example for such a customization can be seen in %matlabroot%/toolbox/matlab/uitools/@uitools/@uitabgroup/schema.m, which derives

Components within a * uiflowcontainer* are ordered according to the order they were added to the container. This order can be modified by rearranging the handles in the container’s

* uigridcontainer* is similar to

hc = uigridcontainer('Units','norm','Position',[.1,.1,.8,.8]); set(hc, 'GridSize',[2,3]); % default GridSize is [1,1] h1 = uicontrol('string','1','parent',hc); h2 = uicontrol('string','2','parent',hc); h3 = uicontrol('string','3','parent',hc); h4 = axes('parent',hc); x = -4:.1:4; plot(h4,x,sin(x)); set(h4,'YTickLabel',[],'XTickLabel',[]);

The grid cells relative size can be controlled via the **HorizontalWeight** and **VerticalWeight** properties (set to NaN by default). These properties should be a numeric vector the same size as the corresponding number of cells. The property values are not important – only their relative values are used to control the relative cell dimensions. The **EliminateEmptySpace** property (default=’off’) controls whether empty grid rows/columns are eliminated from the container or displayed. As in * uiflowcontainer*s, the

set(hc, 'HorizontalWeight',[6,3,1], 'VerticalWeight',[0.2,0.5]) delete([h2,h3]); % only h1,h4 remain set(hc,'EliminateEmptySpace','on')

Brad Phelan of XTargets has created ^{[8]} Matlab equivalents of Java’s BorderLayout ^{[9]} and SpringLayout ^{[10]}. The advantage of using Brad’s layout managers is that they appear to have full Matlab interoperability, including the ability to add Matlab components, unlike Java’s layout managers.

A File Exchange contributor named Jason has added a GridBagLayout implementation ^{[11]}, mimicking Java’s well-known GridBagLayout ^{[12]}.

Additional and more flexible layout managers are available in Java (one of my favorites is JGoodies Forms ^{[13]}, which is pre-bundled with Matlab). Just remember the limitation that no Matlab component (such as GUI controls or plot axes) can be added to Java containers. Therefore, feel free to use these Java containers as long as their contained GUI is limited to Java components (JButton, JComboBox etc.).

Today’s article about * uicontainer* and its relatives was the first of several posts that will describe undocumented functions that reside in the %matlabroot%/toolbox/matlab/uitools folder. Feel free to look within this folder for other interesting undocumented functions. Most of these functions are semi-documented, meaning that they have a usable help-section hidden within the m-file (type “edit uicontainer.m” for example). Many have existed more-or-less unchanged for many releases. Note that there is no guarantee that they will remain in future releases. When using unsupported functionality, always code defensively.

Related posts:

- Tab panels – uitab and relatives
^{[14]}This article describes several undocumented Matlab functions that support tab-panels... - Setting the Matlab desktop layout programmatically
^{[15]}The Matlab desktop enables saving and switching layouts using the main menu. This post shows how to do so programmatically.... - Matlab and the Event Dispatch Thread (EDT)
^{[16]}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.... - handle2struct, struct2handle & Matlab 8.0
^{[17]}This article explains how we can use a couple of undocumented functions in Matlab GUI, and what we can learn from this about Matlab's future.... - Customizing Matlab labels
^{[18]}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... - uitree
^{[19]}This article describes the undocumented Matlab uitree function, which displays data in a GUI tree component...

14 Comments (Open | Close)

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

URL to article: **http://undocumentedmatlab.com/blog/matlab-layout-managers-uicontainer-and-relatives**

URLs in this post:

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

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

[3] * guide*:

[4] the public’s demand: **http://www.mathworks.com/matlabcentral/newsreader/view_thread/279442#736318**

[5] notes: **http://www.mathworks.com/support/solutions/en/data/1-OQBBH/**

[6] FlowLayout: **http://java.sun.com/docs/books/tutorial/uiswing/layout/flow.html**

[7] GridLayout: **http://java.sun.com/docs/books/tutorial/uiswing/layout/grid.html**

[8] created: **http://web.archive.org/web/20071015004151/http://xtargets.com/cms/Tutorials/Matlab-Programming/Advanced-Layout-Management-With-Handle-Graphics.html**

[9] BorderLayout: **http://java.sun.com/docs/books/tutorial/uiswing/layout/border.html**

[10] SpringLayout: **http://java.sun.com/docs/books/tutorial/uiswing/layout/spring.html**

[11] GridBagLayout implementation: **http://www.mathworks.com/matlabcentral/fileexchange/22968**

[12] GridBagLayout: **http://java.sun.com/docs/books/tutorial/uiswing/layout/gridbag.html**

[13] JGoodies Forms: **http://www.jgoodies.com/freeware/forms/**

[14] Tab panels – uitab and relatives: **http://undocumentedmatlab.com/blog/tab-panels-uitab-and-relatives**

[15] Setting the Matlab desktop layout programmatically: **http://undocumentedmatlab.com/blog/setting-the-matlab-desktop-layout-programmatically**

[16] Matlab and the Event Dispatch Thread (EDT): **http://undocumentedmatlab.com/blog/matlab-and-the-event-dispatch-thread-edt**

[17] handle2struct, struct2handle & Matlab 8.0: **http://undocumentedmatlab.com/blog/handle2struct-struct2handle-and-matlab-8**

[18] Customizing Matlab labels: **http://undocumentedmatlab.com/blog/customizing-matlab-labels**

[19] uitree: **http://undocumentedmatlab.com/blog/uitree**

[20] : **http://www.mathworks.com/matlabcentral/fileexchange/27758-gui-layout-toolbox**

[21] : **http://www.mathworks.com/access/helpdesk/help/techdoc/ref/uitable.html**

[22] : **http://www.mathworks.com/access/helpdesk/help/techdoc/ref/openvar.html**

Click here to print.

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

14 Comments To "Matlab layout managers: uicontainer and relatives"

#1 CommentByper isaksonOn June 10, 2010 @ 9:33 amThank you Yair for this blog and this post. I really appreciate the insight.

You don’t mention the

^{[20]}that appeared on the File Exchange last month. It seems to share ancestors with Brad Phelan’s layout managers. Brad, who once worked for The Mathworks, is acknowledged.GUI Layout Toolbox

by Ben Tordoff

(The Mathworks)

/ per

#2 CommentByYair AltmanOn June 11, 2010 @ 8:34 am@per – my bad for the oversight – thanks for pointing it out. The GUI Layout Toolbox is indeed an excellent utility. Funny it was published only two weeks ago and I missed it…

#3 CommentByChaitanyaOn June 22, 2010 @ 7:32 pmHi Sir,

I am a beginner in Matlab. I have saved data from the workspace into a mat file. It consists of vectors of sizes 82×3 , 32×1 … Now I intend to print it out in the form of a table. Should I convert it to excel? How should I create tables from workspace data(in the form of mat files)? Awaiting your reply.

#4 CommentByYair AltmanOn June 23, 2010 @ 12:37 am@Chaitanya – you can use the

^{[21]}function to display and print data in table format in Matlab.was undocumented (but available) until R2008a.uitableAlternately, you can display your data in the Variable (Array) Editor, using the

^{[22]}function:#5 PingbackByTabbed panes – uitab and relatives | Undocumented MatlabOn June 23, 2010 @ 11:45 am[...] the returned

object hTabGroup is actually a Matlab container (deriving fromuitabgroup) that always displays two elements: the Java tab-group, and the active Matlabuiflowcontainer[...]uicontainer#6 CommentBySimonOn July 9, 2010 @ 6:48 amYair, thank you for your blog. It’s very useful!

When did the

Height/WidthLimitsproperty appeared? It doesn’t seem to work in R2007b. What I get is:`??? Error using ==> set`

There is no 'HeightLimits ' property in the 'uicontrol' class.

`Thank you`

Sim

#7 CommentBySimonOn July 9, 2010 @ 8:22 amNever mind, I just noticed that the container needed to be a

.uiflowcontainerdoes not enable the ‘uigridcontainerHeightLimits‘ hidden property.Sim

#8 CommentBySimonOn July 9, 2010 @ 8:27 amWell, disregard again, the error disappeared because I commented my line of code. So I still have the problem. Anyways, here’s what uiflowcontainer.m tells about these hidden properties

Which is what I’m doing, but without success with R2007b.

#9 CommentByYair AltmanOn July 11, 2010 @ 10:15 am@Simon – I’m not sure why it’s not working for you. It does work fine on my Matlab R2007b on a Windows XP platform:

From your quoted error message above, I see that you called the property ‘HeightLimits ‘ (with an extra space) – perhaps this is the problem?

#10 CommentBySimonOn July 12, 2010 @ 9:09 amMy error was to set the

HeightLimitsproperty at uicontrol creation, instead of using a separate set(‘HeightLimits’).Thanks!

Simon

#11 CommentByKeshOn August 18, 2010 @ 7:01 amA little heads-up for using the uiflowcontainer object.

When the container is copied using copyobj, the WidthLimits and HeightLimits properties of its children are not copied.

And MathWorks, why oh why do you not have these limits properties implemented for uigridcontainer children??? I hope they have it on the to-do list…

#12 CommentBysebboOn January 8, 2013 @ 2:23 amHi,

these containers are great.

One issue I’m having though is that patch objects (as e.g. used by a bar-plot) seem to have problems, when drawn in an axes which has a flow/gridcontainer as parent.

After zooming the axis, the patch-graphics which is not in the zoomed axis-range any more keeps being drawn outside the axis-area.

Surface-plots on the other hand seem to be ok…

This is in R2011b.

Has anybody else come across this problem?

It would be great if there’s a workaround…

ps:

Here’s a minimalistic example demonstrating the problem:

#13 CommentByBenjamin CharltonOn November 6, 2013 @ 2:27 pmHello, quick question on uipanels/button groups, how can i make one item (a radio button) with in the uipanel visible/not visible…

the code “set(handles.uibatspanel,’visible’,'off’)” makes the panel itself visible or not, but i want the radio button “raido2bats” within this panel to be visiable/not visiable

Many Thanks

Ben

#14 CommentByYair AltmanOn November 6, 2013 @ 2:47 pm