Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Collapse]Chart Control
   [Expand]Getting Started
   [Collapse]Fundamentals
    [Expand]Charting Basics
    [Expand]Professional Charting
    [Expand]Series Views
    [Collapse]Chart Elements
     [Expand]Series
     [Expand]Diagram
      Chart Titles
     [Collapse]Legends
       Adding Legends
       Legends Alignment and Layout
       Legends Appearance
       Legend Title
       Legend Items
     [Expand]Annotations
   [Expand]Providing Data
   [Expand]Appearance Customization
   [Expand]End-User Features
   [Expand]Design-Time Features
   [Expand]Visual Elements
   [Expand]Examples
   [Expand]Additional Resources
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Legend Items

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:

Expanded 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 controlls the legend items' appearance. For example, to change the item's marker size, specify the Legend.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.

Expanded 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:

Expanded 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.

Expanded 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 Legend.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 Legend.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 Legend.CustomItems collection does not store items, the legend displays the default labels. To show default and custom legend items, set the Legend.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.

Expanded 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.LegendMarkerImage property.

The following image demonstrates customized legend items using the ChartControl.CustomDrawSeries event:

A code example detailing how to achieve this can be found at How to: Custom Draw Series.

Expanded See Also

How would you rate this topic?​​​​​​​