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.
Legends, like many other Chart elements, support a wide variety of appearances including the following:
Gradient colors, with numerous styles available (see the figure below). These are applicable to both legends and legend items. Hatching, with numerous patterns available. Background images. Transparency, set using a color's alpha value.
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).
As an alternative, they can be explicitly positioned using position-related properties, such as X, Y, Width and Height.
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.
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.
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.
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.
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".
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
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.