Legend Items
- 5 minutes to read
This document describes how to display and customize default and custom legend items. Obtaining parameters of an individual legend item at runtime is possible. This document consists of the following sections:
- Default Legend Items
- Legend Markers
- Legend Check Boxes
- Custom Legend Items
- Legend Item Properties at Runtime
Default Legend Items
The default legend items represent series using a marker or check box and explanatory text for a series or series point.
Legend items are automatically generated based on a series view or a view’s SeriesViewColorEachSupportBase.ColorEach property. Legend items are generated for each series point if the property is set to true.
The legend controls the legend items’ appearance. For example, to change the item’s marker size, specify the LegendBase.MarkerSize property. At the same time, the series (constant line, strip or indicator) controls the item’s textual content and the SeriesBase.LegendTextPattern (ConstantLine.LegendText, Strip.LegendText or ChartElementNamed.Name of indicator) property customizes the item’s text pattern.
Note
Properties specifying the appearance influence default and custom legend items. At the same time, properties specifying content (that is, SeriesBase.LegendTextPattern) configure only default legend items.
Legend Markers
The appearance (shape and color) of the legend marker varies, depending on the item type it identifies. Thus, the marker’s image is different for a series of different view types, and for constant lines and strips as well. The color of the corresponding chart element determines the color that represents it.
For series and indicators, the description is based on their names (defined by the Series.Name and Indicator.Name properties, respectively). For constant lines and strips, the description is determined by their ConstantLine.LegendText and Strip.LegendText properties, respectively.
Note
To control whether a certain series should be represented in the legend, use the series SeriesBase.ShowInLegend property. Similarly, to show or hide strips, constant lines and indicators in the legend, use their Strip.ShowInLegend, ConstantLine.ShowInLegend and Indicator.ShowInLegend properties, respectively.
For series of the pie and doughnut view types, it is often necessary to choose the format in which their points should be represented in the legend (that is, whether their values should be reflected, or their arguments, or both). The SeriesBase.LegendTextPattern property can be used to display point values as percentages if necessary. A detailed tutorial can be found in the How to: Show Currency Values in the Legend of a Pie Chart tutorial.
The following section explains how to use legend checkboxes in your application:
Legend Check Boxes
Specify the appropriate Legend.MarkerMode property value to use check boxes or markers or both.
If you wish to show check boxes for each legend item individually, set the CheckableInLegend property to true (ConstantLine.CheckableInLegend, Indicator.CheckableInLegend, SeriesBase.CheckableInLegend and Strip.CheckableInLegend).
Note
The CheckableInLegend property is in effect for legend items when the Legend.MarkerMode property is set to MarkerAndCheckBox or CheckBoxAndMarker.
When the check box appears on a legend (the Legend.MarkerMode property is set to CheckBox, MarkerAndCheckBox or CheckBoxAndMarker and CheckableInLegend is set to true), you can control a chart element’s visibility in the legend using the CheckedInLegend property (ConstantLine.CheckedInLegend, Indicator.CheckedInLegend, SeriesBase.CheckedInLegend and Strip.CheckedInLegend).
Note
The indicator check boxes are automatically disabled when the SeriesBase.CheckedInLegend property is set to false for the series to which the indicators belong.
You can provide a custom legend check box by changing its default behavior in the ChartControl.LegendItemChecked event.
Custom Legend Items
In addition to default legend items, it is possible to add custom ones. A color or an image and text represent the custom legend item in a legend.
An instance of the CustomLegendItem class represents an individual custom legend item. Custom items are stored by a legend using the LegendBase.CustomItems property represented by the CustomLegendItemCollection collection. If the collection is empty, the legend displays default legend items.
To add custom labels to an axis at design time, do the following:
Select the required legend in the chart, and locate the LegendBase.CustomItems property in the Properties window. Click the ellipsis button opposite the property to invoke the Custom Legend Item Collection Editor.
In this dialog, click Add to create a custom legend item and customize its CustomLegendItem.Text and CustomLegendItem.MarkerImage properties.
- Finally, click Close to apply the changes and close the dialog.
Since most of the appearance settings of custom legend items are defined using the properties of a legend, custom legend items share their appearance settings with default legend items.
Note
By default, custom legend items defined for a legend cannot be displayed along with its default items. If the LegendBase.CustomItems collection does not store items, the legend displays the default labels. To show default and custom legend items, set the LegendBase.ItemVisibilityMode property to AutoGeneratedAndCustom.
To learn how to add custom legend items at runtime, refer to the How to: Add a Custom Legend Item example.
Legend Item Properties at Runtime
For default and custom axis labels, there is a capability to obtain individual legend item parameters at runtime in the specific ChartControl.CustomDrawSeries or ChartControl.CustomDrawSeriesPoint event. Properties whose names start with the Legend word store a legend item’s parameters, for example, the CustomDrawSeriesEventArgsBase.DXLegendMarkerImage property.
The following image demonstrates customized legend items using the ChartControl.CustomDrawSeries event:
Examples
- Create Custom Legend Radio Buttons to Control Visibility of a Chart Series
- Add a Custom Item to a Legend
- Draw a Custom Legend Marker for a Series Point