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

Multi-column (grid) legend

Posted By Yair Altman On February 7, 2011 | 5 Comments

I would like to welcome guest blogger Adrian Cherry. Adrian will describe a very handy utility that shows how basic built-in Matlab functions can be improved and customized by just a bit of fiddling under Matlab’s hood.

Legend Plotting

Whilst I enjoy using the many time saving features of Matlab, one area where I feel it suffers is the technical plotting and annotation. This tale relates the development of a legend plotting routine, gridLegend [1], in an effort to improve the presentation.
In my day job we have a requirement to condense a large quantity of data onto summary charts. However, there is only so much data consolidation possible before you start losing the information required. We often need to plot 40 or 50 lines of test data to visualize trends or outliers, using the legend to identify the number of test hours against each test specimen.
Using the standard Matlab legend function resulted in a long legend over twice the size of the associated plot:

Standard Matlab legend
Standard Matlab legend

I wanted some way of generating a more compact legend format.
Fortunately earlier in the year, an entry on Matlab Central allowing a multi-column legend to be generated was posted, columnlegend [2]. Although lacking some features, columnlegend gave me a good start on developing what I wanted for a multi column legend, culminating in gridLegend [1]:
Multi-column legend
Multi-column legend

Delving into the Undocumented Matlab

So where is the link with undocumented Matlab?
As mentioned in the original columnlegend entry, it was relatively simple to redraw the legend as required on the screen. However, as soon as the figure was printed or exported to an image file, internal Matlab workings would redraw the figure, including the legend, thereby undoing my careful legend crafting, squeezing it back into one column (Yuck!):

Matlab-reverted multi-column legend
Matlab-reverted multi-column legend

As we wanted to automatically output images files, I had to delve into the hidden areas of Matlab to try to solve this problem.
My initial thought was to find out where the figure got redrawn for printing or export and override the standard legend call with a call to my new function. I couldn’t find the obvious culprit, stepping as far as I could through the print function there didn’t appear to be any call to the legend function.
In my search for information on how the legend worked I found the undocumented Matlab article about generating dynamic legends [3]. This dynamic-legend post covered details about attaching a listener to a child of the legend axes, in Matlab the legend function creates its own set of axes on the figure to display the legend.
Armed with the information that legend axes objects could have listeners attached, I considered that these might be the source of redrawing the legend for printing. So with the legend I had generated I took a look at what listeners were attached, using the undocumented hidden axes property ScribeLegendListeners:

>> legendListener = get(gca,'ScribeLegendListeners')
legendListener =
        fontname: [1x1 handle.listener]
        fontsize: [1x1 handle.listener]
      fontweight: [1x1 handle.listener]
       fontangle: [1x1 handle.listener]
       linewidth: [1x1 handle.listener]
         deleted: [1x1 handle.listener]
    proxydeleted: [1x1 handle.listener]

The font size and line positioning were all being redrawn for printing so this was potentially the source of my problem. However I’d not looked at a handle.listener before, so a little further digging was required:

K>> get(legendListener.fontname)
      SourceObject: [1x1 schema.prop]
         Container: [1x1 axes]
         EventType: 'PropertyPostSet'
          Callback: {2x1 cell}
    CallbackTarget: []
           Enabled: 'on'

The option Enabled immediately drew my attention, and so the following lines were added to my gridLegend function to switch off these listeners and apply it back to the legend:

LL = get(gca,'ScribeLegendListeners');

Finally allowing me to output the image files with a multi-column legend:

Printed multi-column legend
Printed multi-column legend

So my thanks to the contributors on Matlab Central who enabled me to get started on gridLegend and to Yair for collating the many nuggets of information on Undocumented Matlab which allowed me to complete the function and get it posted on Matlab Central.
Multi-column legend in action
Multi-column legend in action

Categories: Guest bloggers, Handle graphics, Hidden property, Listeners, Medium risk of breaking in future versions, Stock Matlab function, Undocumented feature

5 Comments (Open | Close)

5 Comments To "Multi-column (grid) legend"

#1 Comment By toto On March 13, 2011 @ 20:26

thank you about this. Now I can create legend modified with Matlab. Nice tutorial.

#2 Comment By Michelle On May 17, 2012 @ 14:29

Thank you!!

#3 Comment By Dora On December 25, 2014 @ 18:56

That’s exactly what I’m looking for, thanks so much!

#4 Comment By Dan On March 28, 2016 @ 21:50

I’m working with a bit of code that works on my boss’ computer but doesn’t work on mine. I have 2015b, I believe he has a 2013 version. When I try

LL = get(gca,'ScribeLegendListeners');

I get an error saying “There is no ScribeLegendListeners property on the Axes class.” Is this because something changed in the 2015 release?

#5 Comment By Yair Altman On March 29, 2016 @ 03:33

@Dan – In R2014b Matlab’s graphics engine has been completely revamped (a.k.a. “HG2”, for “Handle Graphics version 2”). This is one of the many fallouts. If you dig inside the utility’s code, you may find a way to modify it to work on HG2. Or you can contact Adrian to ask him to do this.

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

URL to article: https://undocumentedmatlab.com/articles/multi-column-grid-legend

URLs in this post:

[1] gridLegend: http://www.mathworks.com/matlabcentral/fileexchange/29248-gridlegend-a-multi-column-format-for-legends

[2] columnlegend: http://www.mathworks.com/matlabcentral/fileexchange/27389-columnlegend

[3] dynamic legends: http://undocumentedmatlab.com/blog/legend-semi-documented-feature/

[4] Multi-line uitable column headers : https://undocumentedmatlab.com/articles/multi-line-uitable-column-headers

[5] Transparent legend : https://undocumentedmatlab.com/articles/transparent-legend

[6] Plot legend customization : https://undocumentedmatlab.com/articles/plot-legend-customization

[7] Plot legend title : https://undocumentedmatlab.com/articles/plot-legend-title

[8] Legend '-DynamicLegend' semi-documented feature : https://undocumentedmatlab.com/articles/legend-semi-documented-feature

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

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