Customize Series Data Labels with DevExpress Presentation API
- 7 minutes to read
Data labels display additional information about chart data points, such as values, category names, and percentages. The DevExpress Presentation API allows you to show and configure data labels at the view level for all series in a view or at the series level for an individual series. You can customize data labels in both Chart and ChartEx.
Show Data Labels
Initialize the series or view
DataLabelsproperty with a~DataLabelsobject that corresponds to the chart type. For example, use BarDataLabels for bar charts and PieDataLabels for pie charts. Note that ChartEx allows you to specify data labels only at the series level.Use
Show~properties to specify what information the labels should display. For example, setShowValuetotrueto show data point values.
Note: Series-level settings override view-level settings.
The following code snippet enables data labels for a Bar series:
using DevExpress.Docs.Office;
using DevExpress.Docs.Presentation;
Chart chart1 = new Chart();
chart1.Width = presentation.SlideSize.Width;
chart1.Height = presentation.SlideSize.Height;
slide1.Shapes.Add(chart1);
// Populate chart data
chart1.ChartData[0, "A1"].NumericValue = 120;
chart1.ChartData[0, "A2"].NumericValue = 95;
chart1.ChartData[0, "A3"].NumericValue = 140;
chart1.ChartData[0, "B1"].TextValue = "Q1";
chart1.ChartData[0, "B2"].TextValue = "Q2";
chart1.ChartData[0, "B3"].TextValue = "Q3";
// Create a bar series
BarSeries barSeries = new BarSeries();
barSeries.Values = new ChartDataReference(sheetIndex: 0, fromCellReference: "A1", toCellReference: "A3");
barSeries.Arguments = new ChartDataReference(sheetIndex: 0, fromCellReference: "B1", toCellReference: "B3");
chart1.Series.Add(barSeries);
// Show labels for an individual series.
barSeries.DataLabels = new BarDataLabels { ShowValue = true };
// If you have multiple bar series,
// you can apply settings across all series at view level.
// Enable data labels for all bar series in the view.
BarChartView barView = (BarChartView)chart1.Views[0];
barView.DataLabels = new BarDataLabels {
ShowValue = true
};
Specify Data Label Content
The DataLabelBase class exposes the following properties to manage label content:
- ShowValue
- Displays the data point value.
- ShowCategoryName
- Displays the category (argument) name.
- ShowSeriesName
- Displays the series name.
- ShowPercent
- Displays the percentage of the total. Available for pie and doughnut charts.
- ShowLegendKey
- Displays the legend key (color swatch) next to the label.
- ShowBubbleSize
- Displays the bubble size. Available for bubble charts.
- ShowDataLabelRange
- Displays values from a custom data range.
- Separator
- Specifies the separator string between multiple label fields.
The following code snippet shows the value and category name in a pie chart label:
pieSeries.DataLabels = new PieDataLabels {
ShowValue = true,
ShowCategoryName = true,
ShowPercent = true,
Separator = "\n"
};
Set Data Label Position
Use the LabelPosition property on the chart-type-specific ~DataLabels class to position labels relative to data points. The available positions depend on the chart type.
The following code snippet positions data labels at the end of each bar:
BarChartView barView = (BarChartView)chart.Views[0];
barView.DataLabels = new BarDataLabels {
ShowValue = true,
LabelPosition = BarDataLabelPosition.OutsideEnd
};
Format Label Numbers
Use the NumberFormat property to apply a number format to data label values. Assign a NumberFormatOptions instance and set FormatCode to the format string. Set IsSourceLinked to false to apply the custom format. If IsSourceLinked is true, the label value format is obtained from the source cell format (CellValue.NumberFormat).
The following code snippet formats label values with a thousands separator and two decimal places:
chart.ChartData["A1"].TextValue = "Q1";
chart.ChartData["A2"].TextValue = "Q2";
chart.ChartData["A3"].TextValue = "Q3";
chart.ChartData["A4"].TextValue = "Q4";
chart.ChartData["C1"].NumericValue = 2346.6646;
chart.ChartData["C2"].NumericValue = 3450.12344;
chart.ChartData["C3"].NumericValue = 3652.45546;
chart.ChartData["C4"].NumericValue = 3347.12;
BarSeries barSeries = new BarSeries();
chart.Series.Add(barSeries);
barSeries.Arguments = new ChartDataReference("A1", "A4");
barSeries.Values = new ChartDataReference("C1", "C4");
BarChartView barView = (BarChartView)chart.Views[0];
barView.DataLabels = new BarDataLabels {
ShowValue = true,
NumberFormat = new NumberFormatOptions {
FormatCode = "#,##0.00",
IsSourceLinked = false
}
};
Customize Data Label Appearance
Use the TextProperties property to change data label font settings. Use the Properties property to change the label background fill and border.
The following code snippet customizes the font and background color for data labels:
using DevExpress.Docs.Office;
using DevExpress.Docs.Presentation;
using System.Drawing;
BarChartView barView = (BarChartView)chart.Views[0];
barView.DataLabels = new BarDataLabels {
ShowValue = true,
ShowLegendKey = true,
Properties = new ChartElement { Fill = new SolidFill(Color.MistyRose) },
TextProperties = new TextProperties {
FontSize = 24,
Bold = true,
Italic = true,
Fill = new SolidFill(Color.DarkMagenta)
}
};
Customize Individual Data Point Labels
The DataLabels class implements IDictionary<int, DataLabel>. You can add a chart-type-specific DataLabel entry to override the display settings for a specific data point. Use the zero-based data point index as the key.
The following code snippet applies custom settings to the second data point label in a bar series:
barSeries.DataLabels = new BarDataLabels {
ShowValue = true,
LabelPosition = BarDataLabelPosition.OutsideEnd,
TextProperties = new TextProperties { FontSize = 24 }
};
// Override label for the second data point (zero-based index 1).
barSeries.DataLabels[1] = new BarDataLabel {
ShowValue = false,
ShowCategoryName = true,
LabelPosition = BarDataLabelPosition.InsideEnd,
TextProperties = new TextProperties { FontSize = 24, Fill = new SolidFill (Color.White) }
};
Hide a Specific Data Label
Set the Hidden property to true to hide the label for a specific data point. Hidden has a higher priority than other display settings (such as ShowValue or ShowCategoryName).
The following code snippet hides the label for the second data point: