TdxCustomSpreadSheet.EndUpdate Method

Applies all pending changes and redraws the control after a BeginUpdate procedure call.

Declaration

delphi

procedure EndUpdate;

Remarks

Every time you change the current spreadsheet document or any control settings, the control redraws its UI and content to reflect the change. Enclose multiple content and setting changes between BeginUpdate and EndUpdate procedure calls to avoid UI flickering due to excessive redraw operations and improve performance.

BeginUpdate/EndUpdate Calls 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 corresponding redraw operations
Applies all changes made after a BeginUpdate call
Sends corresponding notifications in a batch
Redraws the control

Note

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

Batch Operations in Individual Document Model Parts

TdxCustomSpreadSheet class descendants implement the full spreadsheet document model stored in memory. Many other classes that implement its dependent objects (document model parts), such as TdxSpreadSheetTableView, implement their own sets of BeginUpdate/EndUpdate procedure to support more granular batch operations.

A BeginUpdate call for any object stops notifications to all related objects that comprise the document model. Therefore, an unexpected change in another document model part during the batch change may result in access violations and logical errors.

If you execute a batch operation in an individual document model part, make sure that you do not change another part of the document model in the current batch change. For example, do not modify a floating container while deleting columns in a batch operation in the same worksheet. Otherwise, the control may attempt to access unavailable resources due to document model inconsistency.

Tip

To ensure document model consistency during batch operations, you can do one of the following:

Perform all required operations in a batch only at the control level (between BeginUpdate and EndUpdate calls)
Execute multiple individual batch operations subsequently as demonstrated in the code example below

Code Example: Batch Operations

The following code example performs two batch operations at control and worksheet levels to change the default (document-wide) cell style, populate cells in the active worksheet, and apply a different style to the populated cells:

Delphi
C++

delphi

var
  ATableView: TdxSpreadSheetTableView;
  ACell: TdxSpreadSheetCell;
  I, J: Integer;
begin
  ATableView := dxSpreadSheet1.ActiveSheetAsTable; // Accesses the active worksheet

  // Change the spreadsheet document-wide cell style (the first batch operation)
  dxSpreadSheet1.BeginUpdate; // Initiates the following batch change at the control level
  try
    dxSpreadSheet1.DefaultCellStyle.Brush.BackgroundColor := clWebLightBlue;
    dxSpreadSheet1.DefaultCellStyle.Brush.ForegroundColor := clWebLightGreen;
    dxSpreadSheet1.DefaultCellStyle.Brush.Style := sscfsDiagonalStrip;
    dxSpreadSheet1.DefaultCellStyle.Borders[bRight].Color := clLtGray;
    dxSpreadSheet1.DefaultCellStyle.Borders[bRight].Style := sscbsThin;
    dxSpreadSheet1.DefaultCellStyle.Borders[bBottom].Color := clLtGray;
    dxSpreadSheet1.DefaultCellStyle.Borders[bBottom].Style := sscbsThin;
  finally
    dxSpreadSheet1.EndUpdate; // Calls EndUpdate regardless of the batch operation's success
  end;

  // Create and populate 75 cells with random integer values (the second batch operation)
  Randomize; // Initializes the random number generator
  ATableView.BeginUpdate; // Initiates the following batch change at the worksheet level
  try
    for I := 0 to 14 do // Iterates through 15 rows
      for J := 0 to 4 do // Iterates through 5 columns
      begin
        ACell := ATableView.CreateCell(I, J); // Creates a cell object
        ACell.AsInteger := Random(1000); // Populates the created cell object with a random integer value
        // Customize cell style settings
        ACell.Style.Borders[bLeft].Color := clWhite;
        ACell.Style.Borders[bLeft].Style := sscbsDotted;
        ACell.Style.Borders[bBottom].Color := clWhite;
        ACell.Style.Borders[bBottom].Style := sscbsDotted;
        ACell.Style.Font.Style := [fsBold, fsItalic];
        ACell.Style.Font.Color := clWhite;
        ACell.Style.Brush.Style := sscfsRevDiagonalStrip;
        ACell.Style.Brush.BackgroundColor := clLime;
        ACell.Style.Brush.ForegroundColor := clGreen;
      end;
  finally
    ATableView.EndUpdate; // Calls EndUpdate regardless of the batch operation's success
  end;
end;

cpp

TdxSpreadSheetTableView *ATableView;
  TdxSpreadSheetCell *ACell;
  // ...
  ATableView = dxSpreadSheet1->ActiveSheetAsTable; // Accesses the active worksheet

  // Change the spreadsheet document-wise cell style (the first batch operation)
  dxSpreadSheet1->BeginUpdate(); // Initiates the following batch change at the control level
  try
  {
    dxSpreadSheet1->DefaultCellStyle->Brush->BackgroundColor = clWebLightBlue;
    dxSpreadSheet1->DefaultCellStyle->Brush->ForegroundColor = clWebLightGreen;
    dxSpreadSheet1->DefaultCellStyle->Brush->Style = sscfsDiagonalStrip;
    dxSpreadSheet1->DefaultCellStyle->Borders[bRight]->Color = clLtGray;
    dxSpreadSheet1->DefaultCellStyle->Borders[bRight]->Style = sscbsThin;
    dxSpreadSheet1->DefaultCellStyle->Borders[bBottom]->Color = clLtGray;
    dxSpreadSheet1->DefaultCellStyle->Borders[bBottom]->Style = sscbsThin;
  }
  __finally
  {
    dxSpreadSheet1->EndUpdate(); // Calls EndUpdate regardless of the batch operation's success
  }

  // Create and populate 75 cells with random integer values (the second batch operation)
  Randomize(); // Initializes the random number generator
  ATableView->BeginUpdate();
  try
  {
    for(int i = 0; i < 15; i++) // Iterates through 15 rows
      for(int j = 0; j < 5; j++) // Iterates through 5 columns
      {
        ACell = ATableView->CreateCell(i, j); // Creates a cell object
        ACell->AsInteger = Random(1000); // Populates the created cell object with a random integer value
        // Customize cell style settings
        ACell->Style->Borders[bLeft]->Color = clWhite;
        ACell->Style->Borders[bLeft]->Style = sscbsDotted;
        ACell->Style->Borders[bBottom]->Color = clWhite;
        ACell->Style->Borders[bBottom]->Style = sscbsDotted;
        ACell->Style->Font->Style = TFontStyles() << fsBold << fsItalic;
        ACell->Style->Font->Color = clWhite;
        ACell->Style->Brush->Style = sscfsRevDiagonalStrip;
        ACell->Style->Brush->BackgroundColor = clLime;
        ACell->Style->Brush->ForegroundColor = clGreen;
      }
  }
  __finally
  {
    ATableView->EndUpdate(); // Calls EndUpdate regardless of the batch operation's success
  }

CancelUpdate Usage Scenario – Preliminary Spreadsheet 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 apply mass content and setting changes in a batch before your application displays the Spreadsheet or Report Designer control to avoid an unnecessary freeze-up of the currently visible UI. The control redraws its content when the first data or setting change occurs after a CancelUpdate procedure call.