BeginPageUpdate

Page layout

Description

Starts a batched-drawing transaction on the currently selected page. Subsequent drawing calls (text, paths, images, annotations) are buffered into a single batch and flushed to the page's content stream when a matching EndPageUpdate call is made.

Use this when assembling a complex page out of many small drawing primitives, especially when re-opening a previously saved page for editing. Batching avoids the per-call content-stream serialisation overhead and keeps the resulting page content stream compact and well-formed.

Syntax

Delphi

function TPDFlib.BeginPageUpdate: Integer;

ActiveX

Function PDFlib::BeginPageUpdate As Long

DLL

int DLBeginPageUpdate(int InstanceID);

Return values

0	Failed — no document is open or no page is currently selected.
1	The batched-drawing transaction has been started.

Remarks

Every BeginPageUpdate call must be paired with one EndPageUpdate call on the same page. The pair is not strictly required when adding content to a brand-new page that has just been created by NewPage; in that case the page is already in "open for writing" state. The pair is required when re-opening a previously closed page (after EndPage or after loading the document) and modifying its content.

Nested calls are not supported — call EndPageUpdate before opening a different page for editing.

Example

// Add a stamp on an existing page of a loaded document
PDF.LoadFromFile('contract.pdf', '');
PDF.SelectPage(1);
PDF.BeginPageUpdate;
  PDF.SetTextColor(0.8, 0, 0);
  PDF.SetFontSize(48);
  PDF.PrintText(150, 400, 'DRAFT');
PDF.EndPageUpdate;
PDF.SaveToFile('contract-stamped.pdf');