TdxCustomSpreadSheet.BeginUpdate(TcxLockedStateImageShowingMode) Method
Postpones all redraw operations and related notifications that reflect any document and setting changes until an EndUpdate procedure call.
Declaration
procedure BeginUpdate(AMode: TcxLockedStateImageShowingMode = lsimNever);Parameters
| Name | Type | Description |
|---|---|---|
| AMode | TcxLockedStateImageShowingMode | Optional. The active Locked State image display mode:
Note A subsequent EndUpdate call hides the Locked State image if the current |
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.
Locked State Image and Time-Consuming Operations
Spreadsheet and Report Designer controls automatically display a Locked State image during document import and export operations if they take a noticeable amount of time. The Locked State image displays the control’s state at the beginning of the operation with a dark or light visual effect and an optional message box to inform users that a time-consuming operation is underway and the application UI is non-interactive.
To display a Locked State image during a time-consuming batch operation between BeginUpdate and EndUpdate calls, you can pass lsimImmediate or lsimPending as the optional AMode parameter of the BeginUpdate procedure.
To configure the Locked State image, use settings accessible through the OptionsLockedStateImage property.
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
BeginUpdatecall - 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 procedures 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
BeginUpdateand 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:
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;
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.