windowsforms-401517-controls-and-libraries-chart-control-data-representation-format-text-chart-elements.md
This topic describes how to format and customize chart elements’ text.
This article consists of the following sections:
You can apply format strings to customize the text of chart elements with the ~Pattern property. Patterns can contain regular text (displayed as is) and value placeholders in braces. You can use placeholders listed in the Available Placeholders section. To format numeric and date/time values, you can apply Format Specifiers. Use a colon to separate a placeholder and its format specifier.
See the Examples section for code samples that show how to create patterns.
This section describes placeholders for all diagram types.
|
Placeholder
|
Description
|
Use in Properties
| | --- | --- | --- | |
{S}
|
Displays the series name. This value is obtained from Series.Name.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.LegendTextPattern
SeriesBase.ToolTipPointPattern
SeriesBase.ToolTipSeriesPattern
SeriesLabelBase.TextPattern
TotalLabel.TextPattern
| |
{A}
|
Displays a series point argument.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.LegendTextPattern (if a legend displays series points)
SeriesBase.ToolTipPointPattern
SeriesLabelBase.TextPattern
TotalLabel.TextPattern (for stacked bar series)
AxisLabel.TextPattern (for x-axes)
| |
{V}
|
Displays a series point value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.LegendTextPattern (if a legend displays series points)
SeriesBase.ToolTipPointPattern
SeriesLabelBase.TextPattern
AxisLabel.TextPattern (for y-axes)
|
This section describes placeholders specific to Pie, Donut, and Nested Donut series.
|
Placeholder
|
Description
|
Use in Properties
| | --- | --- | --- | |
{VP}
|
Displays series point values as percentages.
|
SeriesLabelBase.TextPattern
SeriesBase.LegendTextPattern
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{TV}
|
Displays a total group value.
|
TotalLabel.TextPattern
Title.Text (for pie series titles)
|
This section describes placeholders specific to stacked series (Side-by-Side Stacked Bar, Full-Stacked Area, and so on).
|
Placeholder
|
Description
|
Use in Properties
| | --- | --- | --- | |
{VP}
|
Displays series point values as percentages.
|
SeriesBase.LegendTextPattern (if a legend displays series points)
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
SeriesLabelBase.TextPattern (for y-axes)
| |
{G}
|
Displays a stacked series point group name.
|
CrosshairOptions.GroupHeaderPattern
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{TV}
|
Displays a total group value.
|
TotalLabel.TextPattern (for stacked bar series)
|
This section describes placeholders specific to Bubble series.
|
Placeholder
|
Description
|
Use in Properties
| | --- | --- | --- | |
{W}
|
Displays the series point weight.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.LegendTextPattern (if a legend displays series points)
SeriesBase.ToolTipPointPattern
|
This section describes placeholders specific to Side-by-Side Gantt and Overlapped Gantt series.
|
Placeholder
|
Description
|
Use in Properties
| | --- | --- | --- | |
{V1}
|
Displays the first point value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{V2}
|
Displays the second point value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{VD}
|
Displays the duration between the first and second data point values
formatted using a common time format
(e.g. HH:MM:SS for date time values and #.## for numeric values).
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{VDTD}
|
Displays the duration between the first and second date-time data point values in days.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{VDTH}
|
Displays the duration between the first and second date-time data point values in hours.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{VDTM}
|
Displays the duration between the first and second date-time data point values in minutes.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{VDTS}
|
Displays the duration between the first and second date-time data point values in seconds.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{VDTMS}
|
Displays the duration between the first and second date-time data point values in milliseconds.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
|
This section describes placeholders specific to Stock and Candle Stick series.
|
Placeholder
|
Description
|
Use in Properties
| | --- | --- | --- | |
{OV}
|
Displays a series point’s open value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{HV}
|
Displays a series point’s high value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{LV}
|
Displays a series point’s low value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{CV}
|
Displays a series point’s close value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
|
This section describes placeholders specific to Box Plot series.
|
Placeholder
|
Description
|
Use in Properties
| | --- | --- | --- | |
{BP_MIN}
|
Displays the Box Plot point’s Minimum value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{BP_Q1}
|
Displays the Box Plot point’s First Quartile value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{BP_MDN}
|
Displays the Box Plot point’s Median value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{BP_AVG}
|
Displays the Box Plot point’s Mean value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{BP_Q3}
|
Displays the Box Plot point’s Third Quartile value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{BP_MAX}
|
Displays the Box Plot point’s Maximum value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
|
This section describes placeholders specific to Waterfall series.
|
Placeholder
|
Description
|
Use in Properties
| | --- | --- | --- | |
{V}
|
Displays a value change for a rising and falling bar in relation to the previous bar value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
| |
{VABS}
|
Displays an absolute point value.
|
SeriesBase.CrosshairLabelPattern
SeriesBase.ToolTipPointPattern
|
This section describes placeholders you can use for indicators.
|
Placeholder
|
Description
|
Use in Properties
| | --- | --- | --- | |
{I}
|
Displays the indicator name.
|
Indicator.CrosshairLabelPattern
| |
{S}
|
Displays the series name to which the indicator belongs.
|
Indicator.CrosshairLabelPattern
| |
{A}
|
Displays an indicator point’s argument.
|
Indicator.CrosshairLabelPattern
| |
{V}
|
Displays an indicator point’s value.
|
Indicator.CrosshairLabelPattern
| |
{AV}
|
Displays the Moving Average indicator average line’s point value.
The MovingAverage.Kind property value should be MovingAverage or MovingAverageAndEnvelope ;
otherwise this placeholder returns 0.
You can also use the {AV} placeholder to display a middle line’s point value for a BollingerBands indicator.
|
Indicator.CrosshairLabelPattern
| |
{UV}
|
Displays the Moving Average upper envelope line’s point value.
The MovingAverage.Kind property value should be Envelope or MovingAverageAndEnvelope ;
otherwise this placeholder returns 0.
You can also use the {UV} placeholder to display an upper line’s point value for a BollingerBands indicator.
|
Indicator.CrosshairLabelPattern
| |
{LV}
|
Displays the Moving Average lower envelope line’s value.
The MovingAverage.Kind property value should be Envelope or MovingAverageAndEnvelope ;
otherwise this placeholder returns 0.
You can also use the {LV} placeholder to display a lower line’s point value for a BollingerBands indicator.
|
Indicator.CrosshairLabelPattern
| |
{T}
|
Displays an Error Bar point’s highest value.
|
Indicator.CrosshairLabelPattern
| |
{B}
|
Displays an Error Bar point’s lowest value.
|
Indicator.CrosshairLabelPattern
| |
{SV}
|
Displays the MovingAverageConvergenceDivergence indicator signal line’s point value.
|
Indicator.CrosshairLabelPattern
|
This section describes placeholders you can use to format a histogram chart’s x-axis labels.
|
Placeholder
|
Description
|
Use in Properties
| | --- | --- | --- | |
{OB}
|
Displays an opening bracket.
|
IntervalOptionsBase.OverflowValuePattern
IntervalOptionsBase.UnderflowValuePattern
| |
{CB}
|
Displays a closing bracket.
|
IntervalOptionsBase.OverflowValuePattern
IntervalOptionsBase.UnderflowValuePattern
| |
{A1}
|
Displays the interval start value.
|
IntervalOptionsBase.OverflowValuePattern
IntervalOptionsBase.UnderflowValuePattern
| |
{A2}
|
Displays the interval end value.
|
IntervalOptionsBase.OverflowValuePattern
IntervalOptionsBase.UnderflowValuePattern
| |
{OS}
|
Displays the greater than sign.
|
IntervalOptionsBase.OverflowValuePattern
IntervalOptionsBase.UnderflowValuePattern
| |
{US}
|
Displays the less than or less than or equal to sign.
|
IntervalOptionsBase.OverflowValuePattern
IntervalOptionsBase.UnderflowValuePattern
|
Placeholders in this group are used to format legend items for range colorizers. Refer to Point Range Colorizer and Segment Range Colorizer for more information.
|
Placeholder
|
Description
|
Use in Properties
| | --- | --- | --- | |
{V1}
|
Displays the first value that defines a color range boundary.
|
RangeColorizer.LegendItemPattern
RangeSegmentColorizer.LegendItemPattern
| |
{V2}
|
Displays the second value that defines a color range boundary.
|
RangeColorizer.LegendItemPattern
RangeSegmentColorizer.LegendItemPattern
|
The following examples show how to form patterns for axis labels and legend items. You can use the same syntax to create patterns for other chart elements.
The following images show charts with formatted axis labels:
axisXLabel.TextPattern = “{A:dd-MM HH:mm}”, axisYLabel.TextPattern = “{V} °F”
axisYLabel.TextPattern = “{VP:P0}”
axisXLabel.TextPattern = “{A:0.0#}”, axisYLabel.TextPattern = “{V}°C”
axisXLabel.TextPattern = “{A:dd-MMM-yy}”, axisYLabel.TextPattern = “${V}”
axisXLabel.TextPattern = “{A:MMM}”, axisYLabel.TextPattern = “{V}°C”
The charts above use the AxisLabel.TextPattern property to format auto-generated axis labels.
AxisLabel axisXLabel = ((XYDiagram)chartControl.Diagram).AxisX.Label;
AxisLabel axisYLabel = ((XYDiagram)chartControl.Diagram).AxisY.Label;
axisXLabel.TextPattern = "{A:dd-MM HH:mm}";
axisYLabel.TextPattern = "{V} °F";
Dim axisXLabel As AxisLabel = CType(chartControl.Diagram,XYDiagram).AxisX.Label
Dim axisYLabel As AxisLabel = CType(chartControl.Diagram,XYDiagram).AxisY.Label
axisXLabel.TextPattern = "{A:dd-MM HH:mm}"
axisYLabel.TextPattern = "{V} °F"
The following images show charts with formatted legend items:
LegendTextPattern = “{S} - {A}: {V:F1}”
LegendTextPattern = “{A}: {VP:P2} ({V:F1}M km²)”
LegendTextPattern = “{V1:c1} .. {V2:c1}”
LegendTextPattern = “Function: {S}”
The charts above use the SeriesBase.LegendTextPattern property to format legend items.
private void OnFormLoad(object sender, EventArgs e) {
((SideBySideBarSeriesView)chartControl1.Series[0].View).ColorEach = true;
chartControl1.Series[0].LegendTextPattern = "{S} - {A}: {V:F1}";
}
Private Sub OnFormLoad(ByVal sender As Object, ByVal e As EventArgs)
(CType(chartControl1.Series(0).View, SideBySideBarSeriesView)).ColorEach = True
chartControl1.Series(0).LegendTextPattern = "{S} - {A}: {V:F1}"
End Sub
Tip
Alternatively, you can use the Pattern Editor to form patterns for series labels, axis labels, and legend items at design time.
When the Chart Control or a series is bound to data, the text pattern may contain data field values in addition to default placeholders. For example, the data source contains the Discount field and the text pattern may look like: {S}: {V:F2} (Discount: {Discount:P0}).
series1.CrosshairLabelPattern = "{S}: {V:F2} (Discount: {Discount:P0})";
series1.CrosshairLabelPattern = "{S}: {V:F2} (Discount: {Discount:P0})"
When the chart control is unbound, you can initialize a series point’s Tag property with an object that stores information associated with a point. Then, use the object’s property names as placeholders in patterns ({Info} in the example below).
series1.Points.Add(new SeriesPoint(new DateTime(2019, 11, 10), 20) { Tag = new { Info = "Accepted" }});
// ...
series1.CrosshairLabelPattern = "Status: {Info}";
series1.Points.Add(New SeriesPoint(New DateTime(2019, 11, 10), 20) With {
.Tag = New With {
.Info = "Accepted"
}
})
'...
series1.CrosshairLabelPattern = "Status: {Info}"
You can use HTML tags to specify text for the following elements:
Chart titles, series titles, pane titles, axis titles, legend titles, and constant line titles. Use the title Text property.
Text annotations. Use the TextAnnotation.Text and TextAnnotation.Lines properties.
Crosshair labels. Use the SeriesBase.CrosshairLabelPattern and Indicator.CrosshairLabelPattern properties.
// Adds a title and formats its text with HTML tags.
chartControl1.Titles.Add(new ChartTitle { Text = "<i>Point Chart</i>" });
// Formats croshair label content.
series1.CrosshairLabelPattern = "Value:
<color=#FF7200><b>{V}</b></color>";
' Adds a title and formats its text with HTML tags.
chartControl1.Titles.Add(New ChartTitle With {
.Text = "<i>Point Chart</i>"
})
' Formats croshair label content.
series1.CrosshairLabelPattern = "Value:
<color=#FF7200><b>{V}</b></color>"
The following image shows the results:
See the HTML-inspired Text Formatting document for a list of supported tags.
Use the ChartControl.CustomDrawCrosshair event to customize the crosshair label’s text. You can define any condition that allows you to specify the text’s format and appearance. If you customize the crosshair elements’ text in the event handler, patterns specified for these elements are not in effect.
chartControl1.CustomDrawCrosshair += OnCustomDrawCrosshair;
//...
private void OnCustomDrawCrosshair(object sender, CustomDrawCrosshairEventArgs e) {
foreach (CrosshairElementGroup group in e.CrosshairElementGroups) {
foreach (CrosshairElement element in group.CrosshairElements) {
element.LabelElement.Text = (element.SeriesPoint.Values[0] > 20)
? $"<b>{element.SeriesPoint.DateTimeArgument:MMMM dd}: </b><color=green><i>{element.SeriesPoint.Values[0]}</i></color>"
: $"<b>{element.SeriesPoint.DateTimeArgument:MMMM dd}: </b><color=red><i>{element.SeriesPoint.Values[0]}</i></color>";
}
}
}
chartControl1.CustomDrawCrosshair += OnCustomDrawCrosshair
'...
Private Sub OnCustomDrawCrosshair(ByVal sender As Object, ByVal e As CustomDrawCrosshairEventArgs)
For Each group As CrosshairElementGroup In e.CrosshairElementGroups
For Each element As CrosshairElement In group.CrosshairElements
element.LabelElement.Text = If(element.SeriesPoint.Values(0) > 20, $"<b>{element.SeriesPoint.DateTimeArgument:MMMM dd}: </b><color=green><i>{element.SeriesPoint.Values(0)}</i></color>", $"<b>{element.SeriesPoint.DateTimeArgument:MMMM dd}: </b><color=red><i>{element.SeriesPoint.Values(0)}</i></color>")
Next
Next
End Sub
Use the ChartControl.CustomDrawAxisLabel event to customize axis labels. For example, you can apply a specific color to labels if they display values greater than a specified threshold.
You can also use the AxisLabel.Formatter property to pass a custom format provider for axis labels.
The Chart Control provides the CustomizeStackedBarTotalLabel and ChartControl.CustomizePieTotalLabel events that allow you to configure a total label‘s text format and appearance.