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

Multi-line uitable column headers

Posted By Yair Altman On June 27, 2012 | 21 Comments

I often need to present data in tabular format in Matlab GUI, and this data often has relatively long column headers such as “Maximal draw/gain” or “Coefficient of elasticity”. When the table has many columns, these long column headers do not fit in the small space that is available:

uitable('data',magic(2),'ColumnName',{'Maximal draw/gain','Coefficient of elasticity'})

Default uitable behavior with long headers
Default uitable behavior with long headers

Creating multi-line headers

It makes sense to split such long column headers into a multi-line string. In the new (R2008a+) uitable, this can easily be done by adding the | character wherever we wish the line to be split; in both the new and the old uitable, we can also use the built-in HTML support [1] by adding a simple <br/>. The following code snippet demonstrates both of these alternatives:

uitable('data',magic(2), 'ColumnName',{'Maximal|draw/gain', '
Coefficient
of elasticity'});

Multi-line uitable headers
Multi-line uitable headers

Much more readable and useful, I think. Note that HTML code is left-aligned by default, so to center the header I added the <center> tag in the snippet.
If the text appears too crowded in the header cells, we can slightly reduce the header font, to make it appear more spaced-out. The following snippet illustrates this for the old uitable (available since Matlab 7.0 all the way until today), which can only use the HTML alternative since it does not support |:

headers = {'Maximal
draw/gain', ... '
Coefficient
of elasticity
'}; uitable('v0','data',magic(2),'ColumnNames',headers);

Multi-line headers in the old uitable
Multi-line headers in the old uitable

Dynamic multi-line headers

While adding | or <br/> solves the problem for the majority of cases, it is sometimes difficult to know in advance where to place the line-split. This often happens when the column headers are dynamically generated by the program. If we omit the <br/> from our header strings, we get sub-optimal rendering: The new uitable simply hides all overflow terms, and the old uitable pushes them to the bottom:

headers = {'Maximal draw/gain', ...
           '
Coefficient of elasticity'}; uitable('v0','data',magic(2),'ColumnNames',headers);

Default dynamic HTML multi-line (old uitable)
Default dynamic HTML multi-line (old uitable)

I’ve tried numerous things, including CSS wrapping directives etc. None seem to work (I’ll be happy to hear a new idea that does work), except for the following weird-sounding trick: add a “<br/>&nbsp;” at the end of the HTML header string. If the column is wide enough, then this will be disregarded; otherwise, it will automatically split the string nicely:

headers = {'Maximal draw/gain
 ', ... '
Coefficient of elasticity
 
'}; uitable('v0','data',magic(2),'ColumnNames',headers);

Nicely-behaved dynamic HTML multi-lines
Nicely-behaved dynamic HTML multi-lines

Note: the &nbsp; part is important – the trick will NOT work without it!

Controlling the headers

HTML provides some degree of control over the table header row. Some additional aspects can be configured by accessing the underlying Java’s TableHeader sub-component. But here’s another trick that I found handy: I hide the table header row altogether, and use the top table data row for my headers. I can control this row’s height using JTable’s standard setRowHeight() method. Using some fancy cell background colors [2] I can make this row stand out, and I can easily control other aspects as well.
The same trick can also be used for the row-header column: I can dispense with the standard one and use the table’s first column as a row-header column.
For more information on uitable customization, refer to section 4.1 of my Matlab-Java book [3], or to my uitable customization report [4].
Do you have a favorite trick with multi-line strings in Matlab GUI? If so, please share it in a comment below [5].

Categories: GUI, Low risk of breaking in future versions, Stock Matlab function, UI controls, Undocumented feature


21 Comments (Open | Close)

21 Comments To "Multi-line uitable column headers"

#1 Comment By OrO On June 27, 2012 @ 19:33

Thank you, great tips !

#2 Comment By Luc Le Blanc On October 3, 2014 @ 08:30

Can you have a two-level header, where items in the top line cover more than one column?

Like in this example where I have 3 autocorrelation columns:

Autocorrelations
1 2 3

#3 Comment By Yair Altman On October 4, 2014 @ 10:16

@Luc – yes, this is indeed possible. Contact me by email for a short consulting proposal.

#4 Comment By Christopher On November 20, 2014 @ 14:16

In the:
Creating multi-line headers

section, you have two examples, the first having the flat default matlab tan color on the headers,.. the other has a ’rounded’ silver looking header section…

How was this done?

Thank you

#5 Comment By Yair Altman On November 21, 2014 @ 04:13

@Christopher – this is because the flat header is used by the new (R2008a+) uitable, whereas the gradient-colored header is used by the “old” uitable (R14-today), accessible via uitable(‘v0’,…). A detailed description of the two uitable variants can be found in my [12] (section 4.1), or in my [13].

#6 Comment By Jette On February 12, 2016 @ 16:17

Thank you very much for all your great tips.

Do you know if it is possible to rotate an entry in the header of an uitable to keep columns small (e.g. for checkbox-columns)?

#7 Comment By Yair Altman On February 12, 2016 @ 16:22

@Jette – I am not aware of a way to do this

#8 Comment By Pooja Narayan On February 18, 2016 @ 13:52

Is it possible to the do the same for data as well? I mean the table ‘Data’ and not just the headers.

#9 Comment By Yair Altman On February 18, 2016 @ 13:58

@Pooja – yes of course:

data = {pi, 'multi
line', true} uitable('data',data)

But you will need to reduce the font-size or to use the underlying Java object (jtable) to fix the row-heights, so that the multi-line contents appear properly.

#10 Comment By Pooja Narayan On February 18, 2016 @ 14:25

Thanks Mr Altman. I’m using the newest version of MATLAB (2015b). I can’t access the java handles. Did this,

data = {pi, 'multiline', true}
mtable = uitable('data',data)
jscroll = findobj(mtable);
jtable = jscroll.getViewport.getComponent(0);

Line 4 throws an error -> ‘No appropriate method, property, or field ‘getViewport’ for class ‘matlab.ui.control.Table’.

Tried using ‘ColumnNames’ property to use the old uitable version but MATLAB moans saying it’s an obsolete version and errors out.

So guess I can’t change the row height.

Any thoughts on this?

Thanks much.

#11 Comment By Yair Altman On February 18, 2016 @ 14:36

Use [14], not findobj

#12 Comment By Pooja Narayan On February 18, 2016 @ 15:24

Hi Mr Altman,

No I’m unable to use that. It says ‘Undefined function or variable ‘findjobj”.

Is there a work-around?

Best regards,
Pooja

#13 Comment By Yair Altman On February 18, 2016 @ 19:22

@Pooja – did you read the [14] article that I linked in my answer?! findjobj is not part of the core Matlab, you need to download and install it

#14 Comment By Amit Madahar On March 16, 2016 @ 15:46

Hi Yair – Can we control Old uitable Table Header height using Java’s TableHeader sub-component? If so then how? If it is mentioned in any of your published texts please let me know where, I must be overlooking.

Thanks,
Amit

#15 Comment By Yair Altman On March 16, 2016 @ 16:08

Amit – I concentrated in my book and report on the interface with Matlab, and this is purely an internal Java thing, part of the underlying JTable. So, you will need to search Java resources for the answer.

#16 Comment By Amit Madahar On March 16, 2016 @ 19:00

Interestingly I have managed to get the dimensions of the header of jtable using:

mTable=uitable('v0','data',X...
jtable=mTable.getTable
% get the table header
tHeader=jtable.getTableHeader
% returns dimensions of the header
d=tHeader.getPreferredSize()

Now, d.height returns the height of the header and d.width returns the width of the header. The only problem is whilst setting this property.

It returns no error when I do this: d.height = 50 and I see the new property is set to 50 but it does not update the uitable. Any help on how can I make it to set this property so that it is updated in uitable too will be appreciated?

#17 Comment By Amit On March 17, 2016 @ 19:00

Hi Yair – I have a managed to set the height using theader.getParent.setPreferredSize(d) and it works. However it does not apply it on uitable until I resize it. How can I make it to update dynamically i.e. as soon as I update the property it should be updated in uitable.

Also running theader.getParent.setPreferredSize(d) in m-file throws an error ‘Attempt to reference field of non-structure array’ which I have also raised (in addition to above) at Matlab forums.

If you know the answer from top of your head it would be appreciated. If not then I understand you don’t use your time on this.

#18 Comment By Yair Altman On March 24, 2016 @ 22:01

@Amit – try jtable.revalidate(); jtable.repaint();

#19 Comment By Shi On February 17, 2017 @ 14:56

Hi,Yair
Thanks you createTable.m and it is really work using uicontextmenu in uitree.while I find a bug, I really can set uicontextmenu in old uitable through createTable.m. In container it really have a uicontextmenu defined by program. but in the uitable, it shows also the default uicontextmenu. How can show the Custom menu?

#20 Comment By Santiago On July 14, 2021 @ 00:57

Hi , Yair.

¿Do the HTML options still work in the uitables created with the app designer?

#21 Comment By Yair Altman On July 14, 2021 @ 01:06

No. In the new web-based uifigures you need to use uihtml and uistyle to update the table appearance.


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

URL to article: https://undocumentedmatlab.com/articles/multi-line-uitable-column-headers

URLs in this post:

[1] built-in HTML support: http://undocumentedmatlab.com/blog/multi-line-tooltips/#HTML

[2] cell background colors: http://undocumentedmatlab.com/blog/uitable-cell-colors/

[3] Matlab-Java book: http://undocumentedmatlab.com/matlab-java-book/

[4] uitable customization report: http://undocumentedmatlab.com/blog/uitable-customization-report/

[5] below: http://undocumentedmatlab.com/blog/multi-line-uitable-column-headers#respond

[6] Multi-column (grid) legend : https://undocumentedmatlab.com/articles/multi-column-grid-legend

[7] Multi-line tooltips : https://undocumentedmatlab.com/articles/multi-line-tooltips

[8] Uitable sorting : https://undocumentedmatlab.com/articles/uitable-sorting

[9] Uitable customization report : https://undocumentedmatlab.com/articles/uitable-customization-report

[10] Uitable cell colors : https://undocumentedmatlab.com/articles/uitable-cell-colors

[11] Explicit multi-threading in Matlab part 2 : https://undocumentedmatlab.com/articles/explicit-multi-threading-in-matlab-part2

[12] : https://undocumentedmatlab.com/matlab-java-book/

[13] : https://undocumentedmatlab.com/blog/uitable-customization-report

[14] : https://undocumentedmatlab.com/blog/findjobj-find-underlying-java-object

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