Microsoft Chart Control for .NET Framework supports an unlimited number of legends, which can automatically be positioned and aligned inside or outside of chart areas.

Legend Features

Appearance Properties

Legends, like many other Chart elements, support a wide variety of appearances including the following:

Gradient Color

Positioning, Docking and Alignment

Legends can be docked and aligned either inside of outside of chart areas, making them easy to position on a form (see the figure below).

Docking and Alignment of Legends

As an alternative, they can be explicitly positioned using position-related properties, such as  X, Y, Width and Height.

Default and Custom Legend Items

The Chart by default automatically creates one or more legend entries for all chart types. The entries that are used for pie and doughnut charts are the names of the plotted data points, while entries for all other chart types are the names of the plotted series.

These items are referred to as the default legend items, and their text can be changed using the LegendText property of series and data points. Note that legend items are not created for series or data points if their IsVisibleInLegend property is set to False.

A custom legend item is is not associated with data, and can be inserted into a legend via the CustomItems collection property of the Legend object. Custom items are always appended to any existing default legend items. The Name property defines the legend item's text, and three styles can be used: Rectangle, Marker, and Line.

Docking and Alignment of Legends

Extending Default Legend Items

By default, the legend has two cell columns: a series symbol cell column, which corresponds to the series indicator color, and a text cell column, which corresponds to the series name. You can use the CellColumn collection to extend the functionality of the default legend.

Note that you can use a line break for multi-line legend text. At design time, use a '\n' character sequence. At run time, use your respective programming language's line break or carriage return expression. For example, vbCrLf for Visual Basic.

Headers

You can use a header, positioned at the top of each cell column, to appropriately name each cell column. Depending on the size of the table, the header may be repeated at the top of each legend item column.

To add a header to a cell column, use the HeaderText property. After setting the HeaderText property, you can also specify the HeaderBackColor and HeaderSeparator properties.

Legend Item Columns

When using multiple legend item columns, you have the option of defining the ItemColumnSeparator type, as well as the spacing between columns using the ItemColumnSpacing property.

Keyword Support

Text assigned to the DataPoint.Label property can contain special keywords, which are used to insert data point values into the point's label. The figure below shows a legend item with its LegenText property set to "Value = #VAL".

Using Keywords in Legend Items

Keywords are case-sensitive, and are specific to the chart element to which they are applied. For example, #VAL is used for series and data points. Refer to the following table for a listing of all available keywords:

Keyword Replaced By
#VALX X value of the data point
#VAL, #VALY, #VALY2, #VALY3, ... Y values of the data point
#SER Series name
#LABEL: Data point label
#INDEX Data point index
#PERCENT Percentage of the data point Y value
#TOTAL Total of all Y values in the series
#LEGENDTEXT Legend text

Custom Cells

The Cells collection gives you the ability to modify each individual cell of a custom legend item. Each cell can have its own spacing by setting the Alignment and Margins properties. All values appliable to margins and cell spans are calculated as a percentage of the legend font size. 

Three cell types are available: Text, SeriesSymbol, and Image. These styles determine how each individual cell is displayed, and are determined by the CellType property.

Text

When Cell.CellType is set to Text, the text defined by the Cell.Text property is displayed in the cell.

SeriesSymbol

When Cell.CellType is set to SeriesSymbol, the series symbol defined by the LegendItem.Style property is displayed for the cell. When Style is set to Marker, all marker attributes of the custom item apply to the cell. To specify the size of the marker in a custom cell, use the Cell.SeriesSymbolSize property to define the width and height of the series symbol. All values appliable to series symbol size are calculated as a percentage of the legend font size. The following figure shows the available types of series symbols.

Image

When Cell.CellType is set to Image, the image defined by the Cell.Image property is displayed in the cell. Additionally, you can set the size of the image via the ImageSize property. All values applicable to image size are calculated as a percentage of the legend font size.