Legends (Chart Controls)

Legends enable people to distinguish between the series and data points in the chart picture. They are stored as Legend objects in the Chart.Legends collection property.

By default, a legend is not docked to a chart area and is displayed out side of all chart areas. You can dock a legend to a chart area using the Legend object's DockedToChartArea property. Each series is individually assigned to a legend using the Series object's Legend property.

In most chart types, each legend item represents a plotted series. In a pie, doughnut, funnel, or pyramid chart, each legend item represents a data point in the series.

By default, the Chart control automatically creates two columns in a legend, one to indicate the colors of the plotted data and one that shows the legend text. You can specify the legend text in the Series.LegendText property or DataPoint.LegendText property.

Adding Legends at Run Time

To add a legend to a chart at run time, make sure that it is docked to the correct chart area, assigned to a data series, and that the data series' IsVisibleInLegend property is set to true. The following code demonstrates this.

// Create a new legend called "Legend2".
Chart1.Legends.Add(new Legend("Legend2"));

// Set Docking of the Legend chart to the Default Chart Area.
chart1.Legends["Legend2"].DockToChartArea = "Default"; 

// Assign the legend to Series1.
Chart1.Series["Series1"].Legend = "Legend2";
Chart1.Series["Series1"].IsVisibleInLegend = true;

Use properties in a Legend object to customize the appearance of the legend, such as Docking, Alignment, IsDockedInsideChartArea, Position, TableStyle, LegendStyle, MaximumAutoSize, Font, and InterlacedRows.

Using Titles, Headers, and Columns

The following diagram shows the various legend features and the corresponding properties in the Legend object.

Picture showing legend features

You cannot adjust the individual legend items and cells in the Chart.Legends collection. To adjust them, use custom legend items.

When using the Legend.Title property to specify a legend title, use \n to indicate a new line. You can also use keywords so that the text can change according to the data series. For more information, see Keywords.

To customize the number of columns in the legend, use the Legend.CellColumns collection property. The columns in this property apply to each legend item that is automatically generated.

The following code demonstrates both the Legend.CellColumns property and the use of keywords. It adds three columns: one for the series names, one for the series symbol, and one for the average of data in each series.

Chart1.Legends["Legend2"].CellColumns.Add(new LegendCellColumn("Name", LegendCellColumnType.Text, "#LEGENDTEXT"));
Chart1.Legends["Legend2"].CellColumns.Add(new LegendCellColumn("Sym", LegendCellColumnType.SeriesSymbol,""));
Chart1.Legends["Legend2"].CellColumns.Add(new LegendCellColumn("Avg", LegendCellColumnType.Text, "#AVG{N2}"));

You can adjust each column's look and feel using the LegendCellColumn object's properties, such as MinimumWidth, MaximumWidth, Alignmnent, Margins, HeaderText, and ItemColumnsSeparator.

See Also