TdxSpreadSheetCustomView.BeginUpdate Method

Postpones all worksheet redraw operations and related notifications that reflect any content change until an EndUpdate procedure call.

Declaration

procedure BeginUpdate;

Remarks

Every time you change worksheet content (for example, manage cells, floating containers, or cell styles), the parent Spreadsheet control redraws its UI and content to reflect the change. Enclose multiple worksheet content 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 call, even if an exception occurs. Otherwise, the spreadsheet control remains frozen and unresponsive.

Batch Operations in Individual Document Model Parts

The in-memory document model in Spreadsheet and Report Designer controls consists of multiple associated objects (the base document structure stored in a TdxCustomSpreadSheet class descendant instance, worksheet content stored in a TdxSpreadSheetCustomView descendant instance, etc.) These objects notify each other of their changes to keep the entire document model up to date.

A BeginUpdate call in any part of the document model stops all notifications to other document model parts. Therefore, any unexpected change made in another document model part between BeginUpdate and EndUpdate calls may result in access violations and logical errors.

Important

If you perform a batch change between BeginUpdate and EndUpdate procedure calls in a worksheet, do not change any settings in other parts of the document model between these calls. For example, do not attempt to load a spreadsheet file during a batch operation in a worksheet.

Any changes in different parts of the document model must precede or follow the batch operation in the current document model part as demonstrated in the code example below. Alternatively, you can perform all required operations in a batch only at the control level.

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

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;

C++

  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
  }