Legend Class

.NET Framework (current version)

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Represents the legend for the chart image.

Namespace:   System.Windows.Forms.DataVisualization.Charting
Assembly:  System.Windows.Forms.DataVisualization (in System.Windows.Forms.DataVisualization.dll)

public class Legend : ChartNamedElement


Initializes a new instance of the Legend class.


Initializes a new instance of the AnnotationPathPoint class with the specified legend name.


Gets or sets the alignment of the legend.


Gets or sets the minimum font size that can be used by the autofitting algorithm for the legend text.


Gets or sets the background color of a legend.


Gets or sets the orientation for the background gradient of a legend. Also determines whether a gradient is used.


Gets or sets the hatching style of a legend.


Gets or sets the background image of a legend.


Gets or sets the background image alignment used for the Unscaled drawing mode.


Gets or sets a color that will be replaced with a transparent color when the background image is drawn.


Gets or sets the legend background image drawing mode.


Gets or sets the secondary color of a legend background.


Gets or sets the border color of a legend.


Gets or sets the border style of a legend.


Gets or sets the border width of a legend.


Gets the LegendCellColumnCollection object that contains the collection of cell columns for a legend.


Gets a T:System.Windows.Forms.DataVisualization.Charting.LegendItemsCollection object used for custom legend items.


Gets or sets the name of the ChartArea where the legend will be docked.


Gets or sets a value that determines whether the legend is docked.


Gets or sets a value that indicates whether the legend is enabled.


Gets or sets a Font object, which is used to set font properties of the legend.


Gets or sets the color of the legend text.


Gets or sets the visual separator type for the legend header.


Gets or sets the color of the separator for the legend header.


Gets or sets the name of the chart area in which the legend is drawn.


Gets or sets a flag that indicates whether legend rows will be drawn with interlaced background color.


Gets or sets the background color of the legend's interlaced rows.


Gets or sets a flag that indicates whether the legend is docked inside or outside the chart area.


Gets or sets a flag that indicates whether all legend items are equally spaced.


Gets or sets a flag that indicates whether the legend text is automatically sized.


Gets or sets the visual separator type for the legend table columns.


Gets or sets the color of the legend table column separator.


Gets or sets the legend table column spacing.


Gets or sets a value that specifies the order in which legend items are displayed. This property only affects legend items automatically added for the chart series; it has no effect on custom legend items.


Gets or sets the style of the legend.


Gets or sets the maximum size of the legend, measured as a percentage of the chart area. This value is used by the automatic layout algorithm.


Gets or sets the name of the legend.(Overrides ChartNamedElement.Name.)


Gets or sets an ElementPosition object, which can be used to get or set the position of the legend.


Gets or sets the shadow color of the legend.


Gets or sets the shadow offset, in pixels, of the legend.


Gets or sets the legend table style.


Gets or sets an object associated with this chart element.(Inherited from ChartElement.)


Gets or sets the number of characters that can be sequentially displayed in the legend before the text is wrapped.


Gets or sets the text of the legend title.


Gets or sets the alignment of the legend title.


Gets or sets the background color of the legend title.


Gets or sets the font for the legend title.


Gets or sets the text color of the legend title.


Gets or sets the visual separator type for the legend title.


Gets or sets the color of the legend title separator.


Releases the resources used by the ChartElement.(Inherited from ChartElement.)


Releases the unmanaged resources used by the Legend and optionally releases the managed resources.(Overrides ChartElement.Dispose(Boolean).)


Determines whether the specified Object is equal to the current ChartElement.(Inherited from ChartElement.)


Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)


Returns a hash function for a particular type.(Inherited from ChartElement.)


Gets the Type of the current instance.(Inherited from Object.)


Creates a shallow copy of the current Object.(Inherited from Object.)


Returns a string that represents the current Object.(Inherited from ChartElement.)

The Legend class encapsulates all the functionality of the Chart control's legend, and is exposed using the Legends collection property of the root Chart object.

There can be any number of legends for a chart image.

Legends can:

  • Be docked and aligned.

  • Be displayed inside or outside the plotted chart areas.

  • Automatically fit their contents.

  • Use a predefined style, such as row, column or table.

  • Use hatching, gradient colors and background images.

  • Be sized and positioned anywhere within the chart image.

Legend items are represented by the P:System.Windows.Forms.DataVisualization.Charting.LegendItem object, and are either default or custom items. Custom items are not associated with data, and can be added, deleted and modified using the CustomItems property.

Default items are by default automatically added to the legend, and are the names of the plotted data points for doughnut and pie charts.

For all other chart types, the default items are the names of the plotted data series. Each series has a Legend property that defines the name of the legend that will be used. A legend item will not be created for a series if the IsVisibleInLegend property is set to false. The text for these default items can be changed using the LegendText property. This property will allow you to specify predefined keywords that will be replaced by their appropriate values at run-time.

If you have a pie chart and you set the Label property, it will also set the legend text to the value you set for the labels. If you want to set the text to a different value, you can set the LegendText property. In most cases, you would want to set the LegendText property to "#AXISLABEL" or "#VALX".

Legend series symbols are rectangles, dots or lines. The symbol type is set automatically by the chart and depends on the plotted chart type.

Legend text by default is automatically sized. You can disable automatic sizing of legend text by disabling the IsTextAutoFit property. When this property is set to false, the size of the legend text is determined by the Size property of the legend Font. If the IsTextAutoFit property is enabled, the AutoFitMinFontSize property determines the minimum font size that a legend item can have when resizing.

The TextWrapThreshold property defines a limit on the number of characters that can be shown on one line before text is wrapped to another line. If you do not wish to wrap text in the legend, set the value of the TextWrapThreshold property to zero. By default, when the entire legend text does not fit in the legend, the text will be truncated. You can set the TextWrapThreshold on the legend to get the text to wrap instead of being truncated.

If the contents of the legend cannot fit into the given space, legend entries are truncated. An ellipsis will be shown to indicate that there are more entries than the legend has space for. To prevent the legend items from being truncated,, set the position and size of the legend using the Position and P:System.Windows.Forms.DataVisualization.Charting.Legend.Size properties, respectively. When setting the legend position or size, the chart can no longer automatically position the elements in the chart. In some cases, you many need to manually position other chart elements to achieve the desired appearance.

Another option would be to define your own cell columns instead of using the default legend settings.

The Legend object has a CellColumn Collection; each CellColumn object represents a column in the Legend. A cell column has MaximumWidth and MinimumWidth properties that can be used to adjust the size of the columns.

When the legend contains many entries, InterlacedRows can be used to improve readability. When this property is set to True, it will display a back color that you can set using the InterlacedRowsColor property.

By default, the legend is positioned in the top-right corner of the chart. This position can be modified by using the Docking and Alignment properties of the legend. The legend can also be associated with a chart area by use of the DockedToChartArea property. This property specifies the name of the chart area for which the legend should be docked. In addition, the IsDockedInsideChartArea property can be used to display the legend inside a chart area.

When IsDockedInsideChartArea is set to False, the MaximumAutoSize property defines the maximum size, in percent, of the legend within the available chart when the legend is automatically positioned. This property should be set if you wish to adjust the width or height of the legend after the docking properties have been set.

The legend can be modified using the CustomizeLegend event.

.NET Framework
Available since 4.0

Any public static ( Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top