Legend Class

Definition

Namespace:

System.Windows.Forms.DataVisualization.Charting

Assembly:

System.Windows.Forms.DataVisualization.dll

Represents the legend for the chart image.

public ref class Legend : System::Windows::Forms::DataVisualization::Charting::ChartNamedElement

public class Legend : System.Windows.Forms.DataVisualization.Charting.ChartNamedElement

type Legend = class
    inherit ChartNamedElement

Public Class Legend
Inherits ChartNamedElement

Inheritance

Object

ChartElement

ChartNamedElement

Legend

Remarks

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 is 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 property. 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.

Constructors

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

Properties

Alignment	Gets or sets the alignment of the legend.
AutoFitMinFontSize	Gets or sets the minimum font size that can be used by the autofitting algorithm for the legend text.
BackColor	Gets or sets the background color of a legend.
BackGradientStyle	Gets or sets the orientation for the background gradient of a legend. Also determines whether a gradient is used.
BackHatchStyle	Gets or sets the hatching style of a legend.
BackImage	Gets or sets the background image of a legend.
BackImageAlignment	Gets or sets the background image alignment used for the Unscaled drawing mode.
BackImageTransparentColor	Gets or sets a color that will be replaced with a transparent color when the background image is drawn.
BackImageWrapMode	Gets or sets the legend background image drawing mode.
BackSecondaryColor	Gets or sets the secondary color of a legend background.
BorderColor	Gets or sets the border color of a legend.
BorderDashStyle	Gets or sets the border style of a legend.
BorderWidth	Gets or sets the border width of a legend.
CellColumns	Gets the LegendCellColumnCollection object that contains the collection of cell columns for a legend.
CustomItems	Gets a LegendItemsCollection object used for custom legend items.
DockedToChartArea	Gets or sets the name of the ChartArea where the legend will be docked.
Docking	Gets or sets a value that determines whether the legend is docked.
Enabled	Gets or sets a value that indicates whether the legend is enabled.
Font	Gets or sets a Font object, which is used to set font properties of the legend.
ForeColor	Gets or sets the color of the legend text.
HeaderSeparator	Gets or sets the visual separator type for the legend header.
HeaderSeparatorColor	Gets or sets the color of the separator for the legend header.
InsideChartArea	Gets or sets the name of the chart area in which the legend is drawn.
InterlacedRows	Gets or sets a flag that indicates whether legend rows will be drawn with interlaced background color.
InterlacedRowsColor	Gets or sets the background color of the legend's interlaced rows.
IsDockedInsideChartArea	Gets or sets a flag that indicates whether the legend is docked inside or outside the chart area.
IsEquallySpacedItems	Gets or sets a flag that indicates whether all legend items are equally spaced.
IsTextAutoFit	Gets or sets a flag that indicates whether the legend text is automatically sized.
ItemColumnSeparator	Gets or sets the visual separator type for the legend table columns.
ItemColumnSeparatorColor	Gets or sets the color of the legend table column separator.
ItemColumnSpacing	Gets or sets the legend table column spacing.
LegendItemOrder	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.
LegendStyle	Gets or sets the style of the legend.
MaximumAutoSize	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.
Name	Gets or sets the name of the legend.
Position	Gets or sets an ElementPosition object, which can be used to get or set the position of the legend.
ShadowColor	Gets or sets the shadow color of the legend.
ShadowOffset	Gets or sets the shadow offset, in pixels, of the legend.
TableStyle	Gets or sets the legend table style.
Tag	Gets or sets an object associated with this chart element. (Inherited from ChartElement)
TextWrapThreshold	Gets or sets the number of characters that can be sequentially displayed in the legend before the text is wrapped.
Title	Gets or sets the text of the legend title.
TitleAlignment	Gets or sets the alignment of the legend title.
TitleBackColor	Gets or sets the background color of the legend title.
TitleFont	Gets or sets the font for the legend title.
TitleForeColor	Gets or sets the text color of the legend title.
TitleSeparator	Gets or sets the visual separator type for the legend title.
TitleSeparatorColor	Gets or sets the color of the legend title separator.

Methods

Dispose()	Releases the resources used by the ChartElement. (Inherited from ChartElement)
Dispose(Boolean)	Releases the unmanaged resources used by the Legend and optionally releases the managed resources.
Equals(Object)	Determines whether the specified Object is equal to the current ChartElement. (Inherited from ChartElement)
GetHashCode()	Returns a hash function for a particular type. (Inherited from ChartElement)
GetType()	Gets the Type of the current instance. (Inherited from Object)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToString()	Returns a string that represents the current Object. (Inherited from ChartElement)