TcxGridChartDiagram.OnCustomDrawLegendItem Event

Allows you to override or complement built-in legend item draw operations.

Declaration

property OnCustomDrawLegendItem: TcxGridChartDiagramLegendItemCustomDrawEvent read; write;

Remarks

You can handle the OnCustomDrawLegendItem event to change the appearance of individual legend items depending on specific conditions in your application.

Event Occurrence

The OnCustomDrawLegendItem event occurs every time the grid View is about to draw a legend item; immediately before the GridView.OnCustomDrawLegendItem event.

Note

The GridView.OnCustomDrawLegendItem event handler (at the parent Chart View level) may override the handler associated with the OnCustomDrawLegendItem event. We recommend that you handle only one of these events.

Performance-Related Recommendations

Since the OnCustomDrawLegendItem event may occur often, the assigned handler must not include time-consuming calculations. Otherwise, the resource-intensive custom draw routine may render the application UI slow and unresponsive.

Important

If you need to rely on data-dependent conditions in an OnCustomDrawLegendItem event handler, we strongly recommend that you use only cached or pre-calculated values instead of complex calculations at the data controller or dataset level.

Event Parameters

The following parameters are available within an OnCustomDrawLegendItem event handler:

Sender

Provides access to the grid Chart diagram that raised the legend item draw event.

ACanvas

Provides access to the processed legend item’s canvas. You can call canvas draw routines accessible through this parameter to display custom content.

ViewInfo

Returns information required to draw the processed legend item.

ADone

Specifies if built-in legend item draw routines are disabled. Assign True to this parameter within an OnCustomDrawLegendItem event handler to implement the draw routine for the processed legend item from scratch.

Refer to the TcxGridChartDiagramLegendItemCustomDrawEvent procedural type description for detailed information on all available options.

Code Example: Highlight Legend Items

The following code example fills background with two colors for legend items with different names:

Delphi

uses
  cxGrid,  // Declares the TcxGrid control
  cxGridDBChartView,  // Declares the TcxGridDBChartView class
  StrUtils;  // Declares the ContainsText function
// ...

procedure TMyForm.cxGrid1ChartViewDiagramStackedColumnCustomDrawLegendItem(
  Sender: TcxGridChartDiagram; ACanvas: TcxCanvas;
  AViewInfo: TcxGridChartLegendItemViewInfo; var ADone: Boolean);
begin
  if ContainsText((AViewInfo.Series as TcxGridDBChartSeries).DataBinding.FieldName, 'Female')  then
    ACanvas.FillRect(AViewInfo.Bounds, clWebLightGreen)
  else
    ACanvas.FillRect(AViewInfo.Bounds, clWebLightCoral);
end;

C++

#include "cxGrid.hpp"  // Declares the TcxGrid control
#include "cxGridDBChartView.hpp"  // Declares the TcxGridDBChartView class
#include "StrUtils.hpp"  // Declares the ContainsText function

// Add the following linker directives to the corresponding CPP source file:
#pragma link "cxGrid"  // Required to use cxGrid.hpp declarations
#pragma link "cxGridDBChartView"  // Required to use cxGridDBChartView.hpp declarations

void __fastcall TMyForm::cxGrid1ChartViewDiagramStackedColumnCustomDrawLegendItem(
  TcxGridChartDiagram *Sender, TcxCanvas *ACanvas,
  TcxGridChartLegendItemViewInfo *AViewInfo, bool &ADone)
{
  if(ContainsText(dynamic_cast<TcxGridDBChartSeries*>(AViewInfo->Series)->DataBinding->FieldName, "Female"))
    ACanvas->FillRect(AViewInfo->Bounds, clWebLightGreen);
  else
    ACanvas->FillRect(AViewInfo->Bounds, clWebLightCoral);
}