Legend Class

Definition

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

Properties

Methods

Applies to