Legend Class

Definition

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

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)

Applies to