Technical Article

PDFium Component Dynamic XFA: Page Count Is a Delta

When a dynamic XFA form in a Delphi viewer adds or removes pages, PDFium Component reports the new total through TPdf.PageCount and TPdf.OnXfaPageCountChanged, reading it from the completed layout because the native page event carries an added/removed delta rather than a total. The Windows V8 libraries also move input hit areas with relocated fields, and TPdfView reloads page handles after the layout callback returns. Picture an expense claim form: click Add Row twice and the form grows to two pages. A viewer that trusts the event argument proudly reads 1 of 1, and one that keeps pre-layout widget geometry sends keystrokes for a field that moved to page 2 somewhere invisible. None of it shows up with the fixed-length sample forms everyone tests with first, and the reasons why are worth knowing if you embed a form viewer

What happens when a dynamic XFA form repaginates?

A dynamic XFA form has no fixed page list, so its page count is an output of layout and can change every time the user edits data. XFA 3.3 describes the form as a tree of subforms; a repeating subform is controlled by an instanceManager, and a script such as _Row.addInstance() clones one more row. The layout processor then flows the content into the page areas again, which may add a page, drop a page or push existing fields onto another page. ISO 32000-1 §12.7.8 only defines how the XFA packets ride inside the PDF; everything that happens after that belongs to the XFA engine, which in PDFium Component is PDFium's own XFA layout running in the host process. A Delphi viewer therefore deals with a document whose page count, page sizes and widget positions are all live state. Three things go wrong when the host assumes otherwise:

  • The page count the host caches for navigation, scroll ranges and page spinners goes stale, or worse, gets updated with the wrong number
  • Fields that relocate show their border in the new position while the editor and mouse hit area stay at the old coordinates
  • The viewer keeps a page handle that the layout has replaced, so clicks and paints go to a page that no longer exists in that form

Persisting row edits across save and reopen is a separate problem with its own rules; this article stays with what happens at runtime inside the viewer

Which PDFium runtime does dynamic XFA need?

Dynamic XFA in PDFium Component requires the V8/XFA build of the native library, selected by the global EnableV8Engine variable in the PDFium unit before the first document loads. The process commits to one DLL the first time any TPdf loads the library, and a plain PDFium build cannot run the XFA engine at all. When a document opens, TPdf does peek at the file for XFA markers and switches to the V8 build automatically, but only if no plain library has been loaded yet in that process. When the commitment has already gone the wrong way, TPdf.OnXfaRuntimeMissing fires once so the host can tell the user to restart. Setting the flag explicitly at startup removes the guesswork. The FPDF_FORMFILLINFO callback structure that carries the XFA events must also match the DLL; the background is in FPDF_FORMFILLINFO version 2 and the XFA callback ABI, and detecting XFA forms and reading their packets covers telling the form types apart before you open a viewer

uses
  PDFium;

procedure TClaimForm.FormCreate(Sender: TObject);
begin
  // Decide before the first TPdf loads the native library:
  // the process cannot switch from pdfium.dll to pdfium.v8.dll later
  EnableV8Engine := True;

  FPdf := TPdf.Create(nil);
  FPdf.OnXfaRuntimeMissing := PdfXfaRuntimeMissing;
  FPdf.OnXfaPageCountChanged := PdfXfaPageCountChanged;
  FPdf.FileName := 'C:\Forms\expense-claim.pdf';
  FPdf.Active := True;

  PdfView1.Pdf := FPdf;
  PdfView1.OnPageChange := PdfViewPageChange;
  PdfView1.Active := True;

  UpdatePageRange(FPdf.PageCount);
end;

procedure TClaimForm.PdfXfaRuntimeMissing(Sender: TObject);
begin
  StatusBar1.SimpleText :=
    'This XFA form needs the V8 runtime; restart the application to enable it';
end;

Why would PageCount report 1 for a two-page form?

A wrapper that stores the page_count argument of the native page event as the document total gets it wrong, because that argument is actually the absolute difference between the new and old page counts. PDFium raises FFI_PageEvent after a layout pass finishes with an event type of page added or page removed; internally it updates its stored page count first and then passes abs(new - old). On the initial layout the old count is zero, so the delta equals the total, and a three-page static sample reports three pages as expected. That is exactly why fixed-length test forms never expose the mistake. The first time a dynamic form grows from one page to two, the delta is 1, and such a wrapper reports a page count of 1. Removing a row from a three-page form produces the same kind of nonsense in the other direction

Accumulating the delta onto the previous value is not a safe repair either. The order of initialization and layout callbacks means the wrapper cannot always trust its earlier count as a baseline, so a running sum can drift. PDFium Component's callback therefore ignores the argument as a count and calls FPDF_GetPageCount on the document, which reads the total from the layout that has just completed. It then clears the cached page scenes, stores that total as the XFA page-count override behind TPdf.PageCount, and only after that raises OnXfaPageCountChanged. By the time your handler runs, NewCount and FPdf.PageCount agree

PDFium Component dynamic XFA diagram where adding a row repaginates a one-page form to two pages and FFI_PageEvent passes abs(new minus old) as a delta, so treating it as a total would report a page count of 1, while PDFium Component reads FPDF_GetPageCount and reports the correct total
The native page event reports an added-or-removed delta, not a total, so PDFium Component ignores the argument and reads the completed layout before raising OnXfaPageCountChanged
procedure TClaimForm.PdfXfaPageCountChanged(Sender: TObject; NewCount: Integer);
begin
  // NewCount is the completed layout's total, never a delta.
  // This runs inside PDFium's layout callback: update host UI state only,
  // do not close the document or reload pages from here
  UpdatePageRange(NewCount);
end;

procedure TClaimForm.PdfViewPageChange(Sender: TObject);
begin
  // Fires after every page reload, including the deferred XFA refresh
  PageSpin.Value := PdfView1.PageNumber;
end;

procedure TClaimForm.UpdatePageRange(Count: Integer);
begin
  PageSpin.MinValue := 1;
  PageSpin.MaxValue := Count;
  PageLabel.Caption := Format('of %d', [Count]);
end;

The event only fires for Full XFA forms whose layout changes at runtime. Static XFA and AcroForm documents never raise it, so a viewer that handles both can leave the same handler assigned. Leaving it unassigned is safe as well; the override behind TPdf.PageCount is applied regardless, and the event exists so the host can refresh whatever it cached

Why does the input box stay on the old page when a field moves?

The border moves and the editor does not when the native XFA notifier compares a rectangle with itself. When layout changes the geometry of a widget that is already loaded, PDFium is supposed to notice the new rectangle and call PerformLayout on the widget, which repositions the text editor and its hit area. A check that compares GetWidgetRect() against RecacheWidgetRect() can never fire: both functions return a const reference to the same member, and the recache overwrites that member in place, so the comparison always sees two identical values and loaded widgets skip their relayout

The symptom appears when a subform height changes so that existing fields cross onto the next page: the field border is drawn at its new position while the typed text and the mouse hit area stay at the previous Y coordinate. An explicit relayout does not help, and neither does reloading the page, because the widget still believes its geometry is current. The Windows V8 libraries that ship with PDFium Component copy the old rectangle by value before recaching and compare that copy, so moved widgets relayout and the edited value appears exactly where the border is. The check lives in native code and travels with the DLLs, so deploy pdfium.v8.dll together with the Pascal units. To test it yourself, edit a surviving row to a nondefault value first and then look for that value at the field's new location, because a row rebuilt with default values would otherwise look like a pass

PDFium Component widget relayout diagram contrasting a self-comparison where GetWidgetRect and RecacheWidgetRect return one shared member so moved widgets skip PerformLayout, with the Windows V8 copy-by-value check that repositions the editor and mouse hit area onto the redrawn border
Comparing a rectangle with itself never detects a change, so the border moves while typed text and clicks stay behind unless the check saves a copy by value first

How does TPdfView reload pages without pulling a handle from under PDFium?

TPdfView defers the page reload that follows an XFA layout change until the native call stack has unwound. The page event usually fires while PDFium is still processing input: the user clicked an Add Row button, the click ran a script, the script changed the instance count, and layout finished inside that same native call. Closing and reopening the page handle at that moment would free an object the caller is still using. A viewer that only invalidates itself at that point keeps a page handle that points at pre-layout state, and if the user was on the last page when it disappeared, the selected page number is out of range

The deferred refresh works in a few small steps, and they explain the behavior you see from the host:

  1. The page-event callback marks the view as having a pending XFA layout refresh and posts a private window message; repeated events before the message arrives merge into one refresh
  2. A view without a window handle yet keeps the pending flag and posts the message from CreateWnd, while changing documents, deactivating the view or destroying it clears the flag
  3. When the message arrives, the view clears the text selection, search highlight and focused-field index, because all three referred to the old layout
  4. The selected page is clamped to the new PageCount; a changed page number goes through the normal page switch, otherwise the current page is reloaded, and the fit mode is applied again
  5. If the layout leaves no pages at all, the view unloads its old page handle instead of painting a page that no longer exists
PDFium Component TPdfView deferred XFA refresh diagram where a page event inside the native layout call stack only marks a pending refresh and posts a window message, which later clears stale selection state, clamps the page to the new PageCount and reloads or unloads the page handle
The reload waits until the native call stack unwinds: a posted message merges repeated events, then the view clamps the page, reloads it and raises OnPageChange

The same constraint applies to your own code. OnXfaPageCountChanged runs inside that native layout callback, so treat it like a notification: update labels, spinner ranges and toolbar state there, and queue anything heavier, such as closing the document or opening another one, with a posted message so it runs after the callback returns. TPdfView.OnPageChange then tells you when the view has actually reloaded the page, and reading PdfView1.PageNumber at that point gives you the clamped value. Tab-key traversal and the FormType checks a form viewer runs on open are covered in PDF form field navigation with PDFium Component

How does the viewer treat Full XFA pages that have no text layer?

Full XFA pages have no PDF text page, so anything that asks for one on such a page fails with a Cannot open text page error. A viewer's default text selection and link detection both consult that layer: with TPdfView.AllowUserTextSelection at its default of True, hovering asks the text layer for a character under the mouse, and a mouse-up click runs an automatic URL probe over the page text. In TPdfView both internal paths return no result when TPdf.FormType is ftXfaFull and the XFA runtime is available, so the default settings work and field input stays available

Turning off AllowUserTextSelection for Full XFA documents is a reasonable UI choice, because there is no page text to select and drag gestures should not start a selection mode

procedure TClaimForm.ConfigureViewerForForm;
begin
  // FormType reads the open document, so call this after FPdf.Active := True
  if FPdf.XFA and (FPdf.FormType = ftXfaFull) and FPdf.XfaRuntimeAvailable then
  begin
    // No PDF text layer exists on Full XFA pages; fields stay editable
    PdfView1.AllowUserTextSelection := False;
    StatusBar1.SimpleText := Format('Dynamic XFA form, %d page(s)',
      [FPdf.PageCount]);
  end
  else
    PdfView1.AllowUserTextSelection := True;
end;

Typing over a selection needs its own handling. The native XFA text editor does not replace a selection when it receives a character: FORM_OnChar inserts at the caret, and Backspace deletes a single character, so passing keystrokes straight through would put old and new text side by side. PDFium Component remembers that the click landed on an XFA text field and routes typed characters, Backspace and Delete through FORM_ReplaceSelection whenever a selection exists and the document grants fill-forms or modify permission. Whether a read-only XFA field may change is decided by the native editor, so a field marked read-only in the form keeps its value even in a document that otherwise allows filling. Setting TPdfView.AllowFormEvents to False also stops this keyboard routing, which keeps a read-only viewer read-only

Quick reference: dynamic XFA in a Delphi viewer

SymptomCauseHandled by
Page count shows 1 after the form grows to two pagesNative page event passes an added/removed delta, not a totalTPdf.PageCount reads the completed layout
Field border moves, typed text and hit area stay behindLoaded widget skips relayout after a self-comparisonCopy-by-value check in the Windows V8 libraries
Viewer paints or routes input to pre-layout page statePage handle not reloaded after repaginationDeferred refresh in TPdfView
Click into a field asks for a text page that does not existText selection and URL probe on pages without a text layerText paths return no result on ftXfaFull pages
Typing over a selected value appends instead of replacingNative XFA editor inserts at the caretKeystrokes routed through FORM_ReplaceSelection
  • Set EnableV8Engine to True before any document loads, and handle OnXfaRuntimeMissing for the case where the plain library was loaded first
  • Read the total from TPdf.PageCount or the NewCount parameter of OnXfaPageCountChanged; never add or subtract page counts yourself
  • Keep the OnXfaPageCountChanged handler light, because it runs inside the native layout callback
  • Sync the current page indicator in TPdfView.OnPageChange, which fires after the deferred reload clamps the page number
  • Deploy the Windows V8 DLLs together with the units; the widget relayout check lives in native code
  • Test with a form that actually changes its page count and moves an edited field across a page break, because fixed-length samples hide every problem on this list

Dynamic XFA turns page count and field geometry into live values, and a viewer stays correct only when it takes them from the completed layout and reloads pages at a safe moment. PDFium Component handles both inside TPdf and TPdfView, so the host only has to listen. Details and downloads are on the PDFium Component for Delphi product page