MATLAB®

Controlling Legends

Legend Control Options

Graphics objects that are used to represent data, such as lines, surfaces, patches, etc. can be represented in figure legends (see legend for information on creating legends). By setting object properties, you can:

• Include a particular graphics object in the legend (the default)

• Exclude a particular graphics object from the legend

• Group graphics object together by parenting them to an hggroup or hgtransform object and represent the group as a single item in the legend (Group Objects)

• Display only the children of an object and not the parent in the legend. This is useful when the graph contains plot objects (Plot Objects)

• You can specify the text label used in the legend for any object

Back to Top

Properties for Controlling Legend Content

Graphics objects have two properties that control the options described above:

• Annotation — controls whether the graphics object appears in the legend and determines if the object or its children appear in the legend.

• DisplayName — specifies the text label used by the legend for the object. However, specifying a string with the legend commands resets the value of DisplayName property.

Accessing the Annotation Control Objects

Querying the Annotation property returns the handle of an hg.Annotation object. The hg.Annotation object has a property called LegendInformation, which contains an hg.LegendEntry object. The hg.LegendEntry object has a property called IconDisplayStyle that you can set to one of three values.

For example, if object_handle is the handle of a graphics object, you can use the following statements to set the object's IconDisplayStyle. In this case, the graphics object, object_handle, is not included in the legend because its IconDisplayStyle property is set to off.

hAnnotation = get(object_handle,'Annotation');
hLegendEntry = get(hAnnotation','LegendInformation');
set(hLegendEntry,'IconDisplayStyle','off')

Back to Top

Updating a Legend

If a legend exist and you change its IconDisplayStyle setting, you must call legend to update the display. See the legend command for the options available.

Back to Top

Example — Excluding a Particular Object From a Legend

This example creates a graph (using random data in this case) and also draws a line that indicates the mean value of the data. The legend displays a key for the mean data line only because the blue data line object has its.IconDisplayStyle property of the associated LegendEntry object set to off.

function annotation_property_line
dat = rand(50,1);
hLine = plot(dat);
plotMean % Nested function draws a line at mean value
set(get(get(hLine,'Annotation'),'LegendInformation'),...
    'IconDisplayStyle','off'); % Exclude line from legend
legend('mean')
    function plotMean
    xlimits = get(gca,'XLim');
    meanValue = mean(dat);
    meanLine = line([xlimits(1) xlimits(2)],[meanValue meanValue],...
        'Color','k','LineStyle','-.');
    end
end

Here is the graph:

Back to Top

Example — One Legend Entry for a Group of Objects

You can group graphics objects in an hggroup or hgtransform object and represent the whole group as one item in a legend. This example creates two series of graphs (sines and cosines of the same data).

• The lines drawn to represent the sine are parented to one hggroup object

• The lines drawn to represent the cosine are parented to another hggroup object

• Both hggroup objects need their associated IconDisplayStyle property set to on

• The legend then displays entries for both hggroup objects, but not their children (the plotted lines)

t = 0:.1:2*pi;
for k=1:5
    offset = k/7;
    m(:,k) = t+offset';
end
hSLines = plot(t,sin(m),'Color','b');hold on
hCLines = plot(t,cos(m),'Color','g');
hSGroup = hggroup;
hCGroup = hggroup;
set(hSLines,'Parent',hSGroup)
set(hCLines,'Parent',hCGroup)
set(get(get(hSGroup,'Annotation'),'LegendInformation'),...
    'IconDisplayStyle','on'); % Include this hggroup in the legend
set(get(get(hCGroup,'Annotation'),'LegendInformation'),...
    'IconDisplayStyle','on'); % Include this hggroup in the legend
legend('Sine','Cosine')

Back to Top

Example — Showing Children of Group Objects in Legend

You can include the children of a group in the legend by setting the group object's IconDisplayStyle to children. This is useful when graphs contain plot objects, which are groups of core graphics objects. For example, consider the following contour graph.

[X,Y] = meshgrid(-2:.1:2);
Z = X.*exp(-X.^2-Y.^2);
[mC hC] = contour(X,Y,Z);
set(get(get(hC,'Annotation'),'LegendInformation'),...
    'IconDisplayStyle','Children');
%{
Assigns each line object's DisplayName property a string 
based on the value of the contour interval it represents
%}
k =1; ind = 1; hLines = get(hC,'Children');
while k < size(mC,2),
   set(hLines(ind),'DisplayName',num2str(mC(1,k)))
   k = k+mC(2,k)+1; ind = ind+1;
end 
% Display the legend using DisplayName labels
legend('show')

Back to Top

Example — Grouping Objects to Reduce the Legend Entries

Some functions that visualize large data sets create many objects to render graphs. For example, contourslice uses patch objects to generate contour slices of volume data. This example groups the 1829 patch objects into hggroup objects according to which plane the objects represent and sets corresponding values for the DisplayName property, resulting in a legend with only three items.

load mri
D = squeeze(D);
phandles = contourslice(D,[],[],[1,15,27],8);view(3)
gh(1) = hggroup; gh(2) = hggroup; gh(3) = hggroup;
%set(gh,'Parent',gca)
for k=1:length(phandles)
   zd = get(phandles(k),'ZData');
   plane = num2str(zd(1));
   switch plane
      case '1'
         set(phandles(k),'Parent',gh(1),'EdgeColor','r')
      case '15'
         set(phandles(k),'Parent',gh(2),'EdgeColor','g')
      case '27'
         set(phandles(k),'Parent',gh(3),'EdgeColor','b')
      otherwise
         disp('Don''t know what to do with it')
   end
end
hA = get(gh,'Annotation');
hLL = get([hA{:}],'LegendInformation');
set([hLL{:}],{'IconDisplayStyle'},...
   {'on','on','on'}')
set(gh,{'DisplayName'},{'Level=1','Level=15','Level=27'}')
legend show

Back to Top

Grouping Objects Within Axes — hgtransform

Callback Properties for Graphics Objects