TcxLockableComponent.BeginUpdate Method

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

Declaration

procedure BeginUpdate;

Remarks

Every time you modify the component’s settings or change displayed content, the component redraws itself 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 procedure 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
• Redraws the component.

Note

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

Example: VCL Charts – Add a Bar Series in Unbound Mode

A diagram is a pane designed to display and manage series in the Chart control. All diagram classes are descendants of TcxLockableComponent and, therefore, support batch operations.

The code example below adds a Bar series to an existing XY diagram in unbound data access mode. The added Bar series copies its settings from an existing series.

Delphi

var
  AXYDiagram: TdxChartXYDiagram;
  AXYSeries: TdxChartXYSeries;
begin
  // Obtains the only diagram in the Chart control and casts the diagram to the TdxChartXYDiagram class
  AXYDiagram := dxChartControl1.Diagrams[0] as TdxChartXYDiagram;
  AXYDiagram.BeginUpdate;  // Initiates the following batch change
  try
    AXYSeries := AXYDiagram.AddSeries;  // Creates a new series with the default settings
    AXYSeries.AssignFrom(AXYDiagram.Series[0]);  // Copies all settings from an existing series
    AXYSeries.Caption := '2019';  // Defines a different series caption
    // Populates the unbound XY series with data points
    AXYSeries.Points.Add('Asia', 4.7685);
    AXYSeries.Points.Add('Australia', 1.9576);
    AXYSeries.Points.Add('Europe', 3.3579);
    AXYSeries.Points.Add('North America', 3.7477);
    AXYSeries.Points.Add('South America', 1.8237);
  finally
    AXYDiagram.EndUpdate;  // Calls EndUpdate regardless of the batch operation's success
  end;
end;

C++

  TdxChartXYDiagram *AXYDiagram;
  TdxChartXYSeries *AXYSeries;
  // Obtains the only diagram in the Chart control and casts the diagram to the TdxChartXYDiagram class
  AXYDiagram = dynamic_cast<TdxChartXYDiagram*>(dxChartControl1->Diagrams[0]);
  AXYDiagram->BeginUpdate();  // Initiates the following batch change
  try
    AXYSeries = AXYDiagram->AddSeries();  // Creates a new XY series with the default settings
    AXYSeries->AssignFrom(AXYDiagram->Series[0]);  // Copies all settings from an existing series
    AXYSeries->Caption = "2019";  // Defines a different series caption
    // Populates the unbound XY series with data points
    AXYSeries->Points->Add("Asia", 4.7685);
    AXYSeries->Points->Add("Australia", 1.9576);
    AXYSeries->Points->Add("Europe", 3.3579);
    AXYSeries->Points->Add("North America", 3.7477);
    AXYSeries->Points->Add("South America", 1.8237);
  __finally
  {
    AXYDiagram->EndUpdate();  // Calls EndUpdate regardless of the batch operation's success
  }

CancelUpdate Usage Scenario – Preliminary Component 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 make multiple changes in a batch before your application displays the component to avoid an unnecessary freeze-up of the currently visible UI. The component redraws itself when the first content or setting change occurs after a CancelUpdate procedure call.