MATLAB Function Reference Previous page   Next Page
legend

Display a legend on graphs

Syntax

Description

legend places a legend on various types of graphs (line plots, bar graphs, pie charts, etc.). For each line plotted, the legend shows a sample of the line type, marker symbol, and color beside the text label you specify. When plotting filled areas (patch or surface objects), the legend contains a sample of the face color next to the text label.

The font size and font name for the legend strings match the Axes FontSize and FontName properties.

legend('string1','string2',...) displays a legend in the current axes using the specified strings to label each set of data.

legend(h,'string1','string2',...) displays a legend on the plot containing the objects identified by the handles in the vector h and using the specified strings to label the corresponding graphics object (line, barseries, etc.).

legend(string_matrix) adds a legend containing the rows of the matrix string_matrix as labels. This is the same as legend(string_matrix(1,:),string_matrix(2,:),...).

legend(h,string_matrix) associates each row of the matrix string_matrix with the corresponding graphics object in the vector h.

legend(axes_handle,...) displays the legend for the axes specified by axes_handle.

legend('off'), legend(axes_handle,'off') removes the legend in the current axes or the axes specified by axes_handle.

legend('toggle'), legend(axes_handle,'toggle') toggles the legend on or off. If no legend exists for the current axes, one is created using default strings.

The default string for an object is the value of the object's DisplayName property, if you have defined a value for DisplayName (which you can do using the Property Editor or calling set). Otherwise, legend constructs a sting of the form data1, data2, etc.

legend('hide'), legend(axes_handle,'hide') makes the legend in the current axes or the axes specified by axes_handle invisible.

legend('show'), legend(axes_handle,'show') makes the legend in the current axes or the axes specified by axes_handle visible.

legend('boxoff'), legend(axes_handle,'boxoff') removes the box from the legend in the current axes or the axes specified by axes_handle.

legend('boxon'), legend(axes_handle,'boxon') adds a box to the legend in the current axes or the axes specified by axes_handle.

legend_handle = legend returns the handle to the legend on the current axes or empty if no legend exists.

legend with no arguments refreshes all the legends in the current figure.

legend(legend_handle) refreshes the specified legend.

legend(...,'Location',location) uses location to determine where to place the legend. location can be either a 1-by-4 position vector ([left bottom width height]) or one of the following strings.

Specifier
Location in Axes
North
inside plot box near top
South
inside bottom
East
inside right
West
inside left
NorthEast
inside top right (default)
NorthWest
inside top left
SouthEast
inside bottom right
SouthWest
inside bottom left
NorthOutside
outside plot box near top
SouthOutside
outside bottom
EastOutside
outside right
WestOutside
outside left
NorthEastOutside
outside top right
NorthWestOutside
outside top left
SouthEastOutside
outside bottom right
SouthWestOutside
outside bottom left
Best
least conflict with data in plot
BestOutside
least unused space outside plot

The location string can be all lower case and can be abbreviated by sentinel letter (e.g., N, NE, NEO, etc.). Using one of the ...Outside values for location assure that the colorbar will not overlap the plot, whereas overlaps can occur when you specify any of the other cardinal values. The location property applies to colorbars and legends, but not to axes.

Obsolete Location Values

Obsolete Specifier
Location in Axes
-1
outside axes on right side
0
inside axes
1
upper right corner of axes
2
upper left corner of axes
3
lower left corner of axes
4
lower right corner of axes

legend(...,'Orientation','orientation') creates a legend with the legend items arranged in the specified orientation. orientation can be vertical (the default) or horizontal.

[legend_h,object_h,plot_h,text_strings] = legend(...) returns

These handles enable you to modify the properties of the respective objects.

legend(li_object,string1,string2,string3) creates a legend for legendinfo objects li_objects with strings string1, etc.

legend(li_object,M) creates a legend of legendinfo objects li_objects where M is a string matrix or cell array of strings corresponding to the legendinfo objects.

Remarks

legend associates strings with the objects in the axes in the same order that they are listed in the axes Children property. By default, the legend annotates the current axes.

MATLAB displays only one legend per axes. legend positions the legend based on a variety of factors, such as what objects the legend obscures.

The properties that legends do not share with axes are:

You can use a legend's handle to set text properties for all the strings in a legend at once, rather than looping through each of them. See the last line example below, which demonstrates setting a legend's Interpreter property See the documentation for Text Properties for additional details.

legend installs a figure ResizeFcn, if there is not already a user-defined ResizeFcn assigned to the figure. This ResizeFcn attempts to keep the legend the same size.

Moving the Legend

You can move the legend by pressing the left mouse button while the cursor is over the legend and dragging the legend to a new location. Double-clicking a label allows you to edit the label.

Examples

Add a legend to a graph showing a sine and cosine function:

In this example, the plot command specifies a solid, red line ('-r') for the cosine function and a dash-dot, blue line ('-.b') for the sine function.

See Also

LineSpec, plot

Adding a Legend to a Graph for more information on using legends

Annotating Plots for related functions


Previous page  le legendre Next page

© 1994-2005 The MathWorks, Inc.