Interactive Dynamic XFA Widget Runtime

TXFAWidgetRuntime provides a host-neutral interaction model for dynamic XFA forms without converting them into AcroForm fields or flattening their content

The runtime exposes deterministic widget bounds and state so a desktop, service, or custom renderer can supply its own input, painting, accessibility, and event loop

Create a runtime

Create the runtime directly from XDP bytes or call THotPDF.CreateLoadedXFAWidgetRuntime after loading a PDF whose AcroForm contains a single-stream or packet-array /XFA entry

var
  Runtime: TXFAWidgetRuntime;
  State: TXFAWidgetState;
begin
  Runtime := PDF.CreateLoadedXFAWidgetRuntime;
  try
    if (Runtime <> nil) and (Runtime.WidgetCount > 0) then
    begin
      State := Runtime.Widgets[0];
      Runtime.FocusWidget(State.ID);
      Runtime.BeginEdit(State.ID);
      Runtime.ReplaceSelection(0, Length(State.Value), 'Updated value');
      if not Runtime.CommitEdit then
        raise Exception.Create(Runtime.LastDiagnostic);
    end;
  finally
    Runtime.Free;
  end;
end;

The loaded-document factory is read-only with respect to the PDF object graph and existing XFAFlattenWarnings; saving the document retains its original /XFA and /NeedsRendering entries

Interaction model

• FocusWidget and ClearFocus maintain one focused widget and publish ordered focus callbacks
• BeginEdit, ReplaceSelection, CancelEdit, and CommitEdit preserve Unicode text including leading and trailing spaces
• HitTest maps page coordinates to the topmost visible widget
• OnWidgetInvalidated, OnLayoutChanged, and OnFocusChanged let the host refresh only affected state

Atomic validation and calculation

A commit resolves explicit SOM bindings and the current repeated-row data context before running validate and calculate scripts

The edited value, calculated values, data nodes, widget model, focus and edit state, warnings, and pass counters publish together only after validation and layout stabilize

Rejected scripts, exhausted budgets, invalid UTF-16 selection boundaries, and layout or host-measurement exceptions restore the complete previous state and set LastDiagnostic

Budgets

TXFAWidgetRuntimeOptions limits widget count, edited value length, calculation passes, reflow passes, script operations, elapsed script time, and other FormCalc or JavaScript resources

The widget cap applies while layout items and pagination fragments are appended, while loaded XFA decompression and packet assembly stop at the XFA DOM input limit before parsing

Current boundaries

The runtime is a single-thread host object and does not provide a GUI, painter, or general XFA event-script engine

Focus entry and exit are supported directly, while event-driven instance or presence mutations fail with a stable diagnostic instead of partially changing the form

See Bounded XFA FormCalc and JavaScript, XFA Packet DOM, and Interactive Document Processing