VCL Charts Tips and Tricks — Value Label Customization

As you may already know, we just updated our VCL component library (v23.1) with the following new features/capabilities:

• Enhanced High DPI Resolution Support
• "Light" Style Rendering
• Windows 11 Theme
• VCL Chart Control

We'd like to thank everyone who participated in v23.1 EAP/BETA testing and for your feedback via online surveys. If you've not yet had a chance to review our What's New VCL webpage, please take a moment to do so and tell us your thoughts about this release at your convenience (v23.1 Survey).

In this post, I'll highlight a prominent feature we implemented in our Chart Control for this release cycle (v23.1) — the ability to customize axis, series, and total labels display text. This new capability will be useful for multiple usage scenarios, including the need to apply a formatting pattern to all value labels, emphasize certain axis/series values, display different measurement units for different orders of magnitude, etc.

As always, should you have any questions about the DevExpress VCL product line, feel free to submit a support ticket via the DevExpress Support Center.

How to Apply a Formatting Pattern to Value Labels

The DevExpress VCL Chart control now supports advanced formatting patterns similar to those found in our WinForms Chart control. A formatting pattern can consist of static text and one or more supported placeholder field markers enclosed in curly brackets.

All placeholder markers that display numeric values also support numeric formatting patterns. For example, the following formatting pattern displays a floating-point series value with two decimal places: {V:0.00}. Text outside curly brackets defines common value labels for the same formatting pattern.

You can assign the same/different formatting patterns to all series value labels in a diagram, argument axis, value axis, or the total label of a simple series.

Series Value Label Customization

Series value labels without a formatting pattern display values as is. Simple series also add corresponding arguments to labels.

To apply a formatting pattern to all value labels (for a series) at design time, you must:

1. Double-click the Chart control to invoke the Chart Designer dialog.
   
2. Select the target series.
3. Expand View and ValueLabels nodes in the Object Inspector.
4. Assign a formatting pattern to the TextFormat property (such as {V:0.00}M km²).
   

In this particular instance, value labels display series values with two decimal places followed by a measurement unit.

Total Label Customization

To customize the Total label displayed at the center of a Doughnut series, you must:

1. Make certain that the target series is selected.
2. Expand View and TotalLabel nodes in the Object Inspector.
3. Assign the same formatting pattern to the TextFormat property.

Once complete, the Total label will use the same formatting as value labels:

Refer to the Doughnut View Tutorial for a complete example and detailed information on our VCL Doughnut series.

How to Customize Individual Value Labels

In addition to formatting patterns (used to customize display text in value labels), you can customize individual labels based on specific conditions — for example, you can hide value labels for intermediate points or display different measurement units for different orders of magnitude. Our diagram classes include the following value label customization events that occur each time the Chart control is about to determine how to draw an individual label:

• OnGetValueLabelDrawParameters and OnGetAxisValueLabelDrawParameters events are available in an XY diagram and allow you to customize series and axis value labels, respectively.
• OnGetValueLabelDrawParameters and OnGetTotalLabelDrawParameters events are available in a simple diagram and allow you to customize series value and total labels, respectively.
  

You can handle these events to identify the currently processed label and define how the Chart control draws it on-screen. For example, you can display different measurement units in labels that mark axis and series values with different orders of magnitude in the following manner:

• If a series value exceeds one million, the corresponding value label displays the million digit followed by the M character.
• If a series value exceeds one thousand but is less than one million, the corresponding value label displays the thousands digits followed by the k character.
  

To achieve this, you need to handle the OnGetValueLabelDrawParameters event:

procedure TMyForm.cdAreaGetValueLabelDrawParameters(Sender: TdxChartCustomDiagram;
  AArgs: TdxChartGetValueLabelDrawParametersEventArgs);
begin
  if AArgs.SeriesPoint.Value >= 1000 * 1000 then // Millions
    AArgs.Text := Format('%.1fM', [AArgs.SeriesPoint.Value / (1000 * 1000)])
  else if AArgs.SeriesPoint.Value >= 1000 then // Thousands
    AArgs.Text := Format('%.0fk', [AArgs.SeriesPoint.Value / 1000])
  else
    AArgs.Text := Format('%0f', [AArgs.SeriesPoint.Value]);
end;

Then, handle the OnGetAxisValueLabelDrawParameters event:

procedure TMyForm.cdAreaGetAxisValueLabelDrawParameters(Sender: TdxChartCustomDiagram;
  AArgs: TdxChartGetAxisValueLabelDrawParametersEventArgs);
begin
  if AArgs.Axis.ClassName <> 'TdxChartAxisY' then Exit;
  if AArgs.Value >= 1000 * 1000 then // Millions
    AArgs.Text := Format('%.1fM', [AArgs.Value / (1000 * 1000)])
  else if AArgs.Value >= 1000 then // Thousands
    AArgs.Text := Format('%.0fk', [AArgs.Value / 1000])
  else
    AArgs.Text := Format('%0f', [AArgs.Value]);
end;

As a result, series and axis value labels display different measurement units for different orders of magnitude:

Your Feedback Matters

Free DevExpress Products - Get Your Copy Today