This documentation is archived and is not being maintained.

Legend Class

Represents the legend for the chart image.

Namespace:  System.Web.UI.DataVisualization.Charting
Assembly:  System.Web.DataVisualization (in System.Web.DataVisualization.dll)

public class Legend : ChartNamedElement

The Legend type exposes the following members.

Public methodLegend()Initializes a new instance of the Legend class.
Public methodLegend(String)Initializes a new instance of the AnnotationPathPoint class with the specified legend name.

Public propertyAlignmentGets or sets the alignment of the legend.
Public propertyAutoFitMinFontSizeGets or sets the minimum font size that can be used by the autofitting algorithm for the legend text.
Public propertyBackColorGets or sets the background color of a legend.
Public propertyBackGradientStyleGets or sets the orientation for the background gradient of a legend. Also determines whether a gradient is used.
Public propertyBackHatchStyleGets or sets the hatching style of a legend.
Public propertyBackImageGets or sets the background image of a legend.
Public propertyBackImageAlignmentGets or sets the background image alignment used for the Unscaled drawing mode.
Public propertyBackImageTransparentColorGets or sets a color that will be replaced with a transparent color when the background image is drawn.
Public propertyBackImageWrapModeGets or sets the drawing mode of a legend background image.
Public propertyBackSecondaryColorGets or sets the secondary color of a legend background.
Public propertyBorderColorGets or sets the border color of a legend.
Public propertyBorderDashStyleGets or sets the border style of a legend.
Public propertyBorderWidthGets or sets the border width of a legend.
Public propertyCellColumnsGets the LegendCellColumnCollection for a legend.
Public propertyCustomItemsGets a T[:System.Web.UI.DataVisualization.Charting.LegendItemsCollection] object used for custom legend items.
Public propertyDockedToChartAreaGets or sets the name of the ChartArea where the legend will be docked.
Public propertyDockingGets or sets a value that determines where the legend is docked.
Public propertyEnabledGets or sets a value that determines if the legend is enabled.
Public propertyFontGets or sets a Font object, which is used to set font properties of the legend.
Public propertyForeColorGets or sets the color of the legend text.
Public propertyHeaderSeparatorGets or sets the visual separator type for the legend header.
Public propertyHeaderSeparatorColorGets or sets the color of the separator for the legend header.
Public propertyInsideChartAreaGets or sets the name of the chart area in which the legend is drawn.
Public propertyInterlacedRowsGets or sets a flag that indicates if legend rows will be drawn with interlaced background color.
Public propertyInterlacedRowsColorGets or sets the background color of the legend's interlaced rows.
Public propertyIsDockedInsideChartAreaGets or sets a flag that indicates whether the legend is docked inside or outside the chart area.
Public propertyIsEquallySpacedItemsGets or sets a flag that indicates whether all legend items are equally spaced.
Public propertyIsTextAutoFitGets or sets a flag that indicates if the legend text is automatically sized.
Public propertyItemColumnSeparatorGets or sets the visual separator type for the legend table columns.
Public propertyItemColumnSeparatorColorGets or sets the color of the legend table column separator.
Public propertyItemColumnSpacingGets or sets the legend table column spacing.
Public propertyLegendItemOrderGets or sets a flag 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.
Public propertyLegendStyleGets or sets the style of the legend.
Public propertyMaximumAutoSizeGets 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.
Public propertyNameGets or sets the name of the legend. (Overrides ChartNamedElement.Name.)
Public propertyPositionGets or sets an ElementPosition object, which can be used to get or set the position of the legend.
Public propertyShadowColorGets or sets the shadow color of the legend.
Public propertyShadowOffsetGets or sets the shadow offset, in pixels, of the legend.
Public propertyTableStyleGets or sets the legend table style.
Public propertyTagGets or sets an object associated with this chart element. (Inherited from ChartElement.)
Public propertyTextWrapThresholdGets or sets the number of characters that can be sequentially displayed in the legend before the text is wrapped.
Public propertyTitleGets or sets the text of the legend title.
Public propertyTitleAlignmentGets or sets the alignment of the legend title.
Public propertyTitleBackColorGets or sets the background color of the legend title.
Public propertyTitleFontGets or sets the font for the legend title.
Public propertyTitleForeColorGets or sets the text color of the legend title.
Public propertyTitleSeparatorGets or sets the visual separator type for the legend title.
Public propertyTitleSeparatorColorGets or sets the color of the legend title separator.

Public methodDispose()Releases the resources used by the ChartElement. (Inherited from ChartElement.)
Protected methodDispose(Boolean)Releases the unmanaged resources used by the Legend and optionally releases the managed resources. (Overrides ChartElement.Dispose(Boolean).)
Public methodEqualsDetermines whether the specified Object is equal to the current ChartElement. (Inherited from ChartElement.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeReturns a hash function for a particular type. (Inherited from ChartElement.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodToStringReturns 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 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 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

Supported in: 4

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

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