TdxCustomChartControl.BeginUpdate Method

Postpones all control redraw operations that reflect content and appearance setting changes until an EndUpdate or CancelUpdate procedure call.

Declaration

procedure BeginUpdate;

Remarks

Every time you add or modify a diagram, title, or legend, or customize an appearance setting, the Chart control redraws its content to reflect the change. Enclose multiple content and appearance changes between BeginUpdate and EndUpdate procedure calls to avoid UI flickering due to excessive redraw operations and improve performance.

BeginUpdate/EndUpdate and Batch Changes

A BeginUpdate procedure call disables notifications and postpones all changes until an EndUpdate call. A subsequent EndUpdate call does the following:

• Re-enables change notifications and the corresponding redraw operations
• Applies all changes made after a BeginUpdate call
• Sends the corresponding notifications in a batch
• Raises the OnChange event
• Redraws the Chart control

Note

Ensure that every BeginUpdate procedure call is followed by an EndUpdate or CancelUpdate procedure call, even if an exception occurs. Otherwise, the Chart control’s UI remains frozen and unresponsive.

Example

The following code example creates an XY diagram with two bar chart series, configures diagram and axis titles, and loads data previously saved by the SaveToStream procedure:

Delphi

uses cxDataStorage;  // This unit declares the TcxStringValueType class
// ...
var
  AFileStream: TFileStream;
  AXYDiagram: TdxChartXYDiagram;
  AXYSeries: TdxChartXYSeries;
  ADataBinding: TdxChartXYSeriesUnboundDataBinding;
begin
  dxChartControl1.BeginUpdate;  // Initiates the following batch change
  try
    AFileStream := TFileStream.Create('DevAVSales.dat', fmOpenRead);
    try
      AXYDiagram := dxChartControl1.AddDiagram<TdxChartXYDiagram>('DevAV Sales by Region');
      AXYDiagram.Title.Appearance.FontOptions.Size := 20;
      AXYDiagram.Axes.AxisY.Title.Text := 'Millions of Dollars';
      AXYSeries := AXYDiagram.AddSeries('2018');
      // Selects the unbound data access mode
      AXYSeries.DataBindingClass := TdxChartXYSeriesUnboundDataBinding;
      AXYSeries.ViewClass := TdxChartXYSeriesBarView;  // Selects the Bar series View
      ADataBinding := AXYSeries.DataBinding as TdxChartXYSeriesUnboundDataBinding;
      ADataBinding.ArgumentField.ValueTypeClass := TcxStringValueType;  // Selects the string data type
      AXYSeries.View.ValueLabels.Visible := True;  // Displays value labels on bars
      AXYSeries := AXYDiagram.AddSeries('2019');
      // Selects the unbound data access mode
      AXYSeries.DataBindingClass := TdxChartXYSeriesUnboundDataBinding;
      AXYSeries.ViewClass := TdxChartXYSeriesBarView;  // Selects the Bar series View
      ADataBinding := AXYSeries.DataBinding as TdxChartXYSeriesUnboundDataBinding;
      ADataBinding.ArgumentField.ValueTypeClass := TcxStringValueType;  // Selects the string data type
      AXYSeries.View.ValueLabels.Visible := True;  // Displays value labels on bars
      dxChartControl1.LoadFromStream(AFileStream);
    finally
      AFileStream.Free;  // Releases the file stream regardless of the data load operation's success
    end;
  finally
    dxChartControl1.EndUpdate; // Calls EndUpdate regardless of the batch change's success
  end;
end;

C++

#include "cxDataStorage.hpp"  // This header declares the TcxStringValueType class
// ...
  TFileStream *AStream;
  TdxChartXYDiagram *AXYDiagram;
  TdxChartXYSeries *AXYSeries;
  TdxChartXYSeriesUnboundDataBinding *ADataBinding;
  // ...
  dxChartControl1->BeginUpdate();  // Initiates the following batch change
  try
  {
    AFileStream = new TFileStream("DevAVSales.dat", fmOpenRead);
    try
    {
      AXYDiagram = new TdxChartXYDiagram(dxChartControl1->Owner);
      AXYDiagram->SetParentComponent(dxChartControl1);
      AXYDiagram->Title-Text = "DevAV Sales by Region";
      AXYDiagram->Title->Appearance->FontOptions->Size = 20;
      AXYDiagram->Axes->AxisY->Title->Text = "Millions of Dollars";
      AXYSeries = AXYDiagram->AddSeries("2018");
      // Selects the unbound data access mode
      AXYSeries->DataBindingClass = __classid(TdxChartXYSeriesUnboundDataBinding);
      AXYSeries->ViewClass = __classid(TdxChartXYSeriesBarView);  // Selects the Bar series View
      ADataBinding = dynamic_cast<TdxChartXYSeriesUnboundDataBinding*>(AXYSeries->DataBinding);
      // Selects the string data type for arguments
      ADataBinding->ArgumentField->ValueTypeClass = __classid(TcxStringValueType);
      AXYSeries->View->ValueLabels->Visible = true;  // Displays value labels on bars
      AXYSeries = AXYDiagram->AddSeries("2019");
      // Selects the unbound data access mode
      AXYSeries->DataBindingClass = __classid(TdxChartXYSeriesUnboundDataBinding);
      AXYSeries->ViewClass = __classid(TdxChartXYSeriesBarView);  // Selects the Bar series View
      ADataBinding = dynamic_cast<TdxChartXYSeriesUnboundDataBinding*>(AXYSeries->DataBinding);
      // Selects the string data type for arguments
      ADataBinding->ArgumentField->ValueTypeClass = __classid(TcxStringValueType);
      AXYSeries->View->ValueLabels->Visible = true;  // Displays value labels on bars
      dxChartControl1->LoadFromStream(AFileStream);
    }
    __finally
    {
      delete AFileStream;  // Releases the file stream regardless of the data load operation's success
    }
  }
  __finally
  {
    dxChartControl1->EndUpdate(); // Calls EndUpdate regardless of the batch operation's success
  }
  // ...

CancelUpdate Usage Scenario – Preliminary Chart Configuration

The EndUpdate procedure invokes the apply changes operation in the UI thread. Depending on the number of changes and available system resources, this operation may take a noticeable amount of time and render the application UI temporarily unresponsive. You can call CancelUpdate instead of the EndUpdate procedure when you need to do multiple chart changes in a batch before your application displays the Chart control to avoid an unnecessary freeze-up of the currently visible UI. The Chart control redraws its content when the first data or setting change occurs after a CancelUpdate procedure call.