TdxPDFDocument.BeginUpdate Method

Disables all document change notifications until an EndUpdate procedure call.

Declaration

procedure BeginUpdate;

Remarks

Every time you load, unload, or modify a document in the TdxPDFDocument container, it applies the document model change and sends corresponding change notifications to the parent TdxPDFViewer control to redraw content. Enclose multiple document changes between BeginUpdate and EndUpdate procedure calls to improve performance (and avoid UI flickering in the parent TdxPDFViewer control if you do not use a standalone TdxPDFDocument class instance).

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 corresponding redraw operations in the parent TdxPDFViewer control if the document container is not standalone).
• Applies all changes made after a BeginUpdate call.
• Sends corresponding notifications in a batch.

• Raises the following events once for the batch change:

  OnChanged

  Allows you to track all document changes except for load and unload operations.

  OnLoaded

  Notifies the application or the parent TdxPDFViewer control of a successful document load operation.

  This event occurs once if the current batch change includes a successful document load operation (a LoadFromFile or LoadFromStream procedure call).

  OnUnloaded

  Notifies the application or the parent TdxPDFViewer of a document unload (close) operation.

  This event occurs once if the current batch change includes a document unload operation (a Clear procedure call).

Note

Ensure that every BeginUpdate procedure call is followed by an EndUpdate procedure call, even if an exception occurs. Otherwise, the TdxPDFDocument container is unable to apply pending changes to the stored document (and notify the parent TdxPDFViewer control of the changes if the document container is not standalone).

Code Example: Delete the First Two Document Pages

The following code example loads a PDF document from the Demo.pdf file, deletes the first two pages of the loaded document, and saves the resulting document to a different file (Result.pdf):

Delphi

uses
  dxPDFDocument;  // This unit declares the TdxPDFDocument class
// ...
var
  ADocument: TdxPDFDocument;
begin
  ADocument := TdxPDFDocument.Create;
  try
    ADocument.LoadFromFile('Data\Demo.pdf');
    ADocument.BeginUpdate;  // Initiates the following batch change
    try
      ADocument.Pages.Delete(0);
      ADocument.Pages.Delete(0);
    finally
      ADocument.EndUpdate;  // Calls EndUpdate regardless of the batch operation's success
    end;
    ADocument.SaveToFile('Data\Result.pdf');
  finally
    ADocument.Free;  // Releases the created document container to avoid memory leaks
  end;

C++

#include "dxPDFDocument.hpp"  // This header declares the TdxPDFDocument class
// ...
  TdxPDFDocument *ADocument = new TdxPDFDocument();
  try
  {
    ADocument->LoadFromFile("Data\\Demo.pdf");
    ADocument->BeginUpdate();  // Initiates the following batch change
    try
    {
      ADocument->Pages->Delete(0);
      ADocument->Pages->Delete(0);
    }
    __finally
    {
      ADocument->EndUpdate();  // Calls EndUpdate regardless of the batch operation's success
    }
    ADocument->SaveToFile("Data\\Result.pdf");
  }
  __finally
  {
    delete ADocument;  // Releases the created document container to avoid memory leaks
  }