Lifecycle actions

Component: TPdf · Unit: PDFium

Control when PDF document and page lifecycle actions execute, including explicit save and print boundaries

Types

TPdfLifecycleActionPolicy = (lapDisabled, lapManual, lapAutomatic);

TPdfDocumentLifecycleAction = (dlaJavaScript, dlaOpen, dlaWillClose, dlaWillSave, dlaDidSave, dlaWillPrint, dlaDidPrint);

TPdfPageLifecycleAction = (plaOpen, plaClose);

Execution policy

property LifecycleActionPolicy: TPdfLifecycleActionPolicy; // default lapAutomatic

lapDisabled blocks both automatic and explicit lifecycle action execution

lapManual suppresses automatic actions while allowing the two explicit execution methods

lapAutomatic retains compatible automatic document JavaScript, document open and close, and page open and close behavior while still allowing explicit execution

Automatic mode does not wrap save or print operations because internal snapshots and conversion saves must not unexpectedly run document scripts; call the explicit document method at host-controlled workflow boundaries

Document actions

function ExecuteDocumentLifecycleAction(Action: TPdfDocumentLifecycleAction; out ErrorMessage: string): Boolean;

dlaJavaScript runs document-level JavaScript name-tree actions and dlaOpen runs the catalog open action

dlaWillClose, dlaWillSave, dlaDidSave, dlaWillPrint, and dlaDidPrint dispatch the corresponding document additional action

The method returns False with a non-empty ErrorMessage when policy blocks execution, the form fill environment is unavailable, or a callback raises an exception

Page actions

function ExecutePageLifecycleAction(PageNumber: Integer; Action: TPdfPageLifecycleAction; out ErrorMessage: string): Boolean;

PageNumber is one-based and must identify a page in the active document

The current page reuses its loaded native handle; another page is opened temporarily, registered with the form environment, dispatched, unregistered, and closed without changing TPdf.PageNumber

Load, registration, action, cleanup, and close failures are isolated into the return value and ErrorMessage

Save workflow example

var
  ErrorMessage: string;
begin
  Pdf.LifecycleActionPolicy := lapManual;
  if not Pdf.ExecuteDocumentLifecycleAction(dlaWillSave, ErrorMessage) then
    raise Exception.Create(ErrorMessage);
  try
    Pdf.SaveAs(TargetFileName);
  finally
    Pdf.ExecuteDocumentLifecycleAction(dlaDidSave, ErrorMessage);
  end;
end;

Security

Lifecycle actions can invoke document JavaScript, named actions, URI callbacks, and other host services configured on TPdf

Use lapDisabled for untrusted documents that must never execute actions, or lapManual when the application needs an explicit approval boundary