TXFAFormStructure

HPDFXFAFormStructure provides native preparation and identity mapping for template-backed form instances

The class borrows its TXFADocument, owns its structural graph and detached candidates, and never frees the borrowed document

constructor Create(Document: TXFADocument;
  const Limits: TXFADataStructureLimits;
  const OnTick: TXFADataStructureTick);
procedure BeginOperation(const OnTick: TXFADataStructureTick);
procedure EndOperation;
function PrepareUnboundModel: TXFANode;
function EnsureInstance(Definition, DataNode: TXFANode): TXFANode;
function PrepareMaterialization(Definition, Instance: TXFANode;
  out Aliases: TXFAFormStructureAliases): TXFANode;
function ReplaceInstance(Instance, Prepared: TXFANode): TXFANode;
procedure DiscardPrepared(Node: TXFANode);
property Graph: TXFADataStructure;

Operation scope

Call BeginOperation before structural work and EndOperation in a finally block

The supplied callback is called throughout bounded traversal, copying and graph preflight, and may raise an exception to cancel the operation

Graph.DetachedRoots exposes the graph's owning collection for observation and coordinated snapshot restoration, and callers must not independently free nodes still owned by that collection

Preparation and adoption

PrepareMaterialization composes a detached form candidate from a template definition and an optional existing instance, returning source-to-candidate pairs in TXFAFormStructureAliases

TXFAFormStructureAlias.Source and Target are borrowed node references for remapping external identities before releasing the previous instance

ReplaceInstance adopts the prepared candidate and returns the previous instance as a detached graph-owned node

Retarget dependent references before calling DiscardPrepared on the returned previous instance

DiscardPrepared releases a detached candidate owned by the same graph and does not remove an attached live instance

Initial and sparse instances

PrepareUnboundModel returns a detached form model for an empty merge, preserving authored template content and expanding supported subform occurrences into independent native nodes

EnsureInstance returns an existing live form node or constructs the required sparse instance path for a template definition and its live data context

EnsureInstance can mutate several live nodes, so compound-operation rollback belongs to the caller's surrounding document transaction

TXFAWidgetRuntime provides that transaction for public script events, including native document and detached identity restoration

Helper functions

Function	Purpose
`HPDFXFAEmptyMergeCount`	Validates an occurrence declaration and returns its empty-merge count, using explicit initial or the minimum
`HPDFXFAIsMaterializedFormNode`	Checks the namespace-qualified materialization marker under an explicit traversal budget
`HPDFXFAResolveMaterializedDefinition`	Resolves the effective form node for a definition and data context, reporting whether the materialized model is authoritative
`HPDFXFAResolveActualFormScope`	Resolves the live data scope of an actual repeated form instance without repeating its template declaration again

The saved marker uses urn:hotpdf:xfa:form-structure:1 with a collision-safe prefix, whilst native form nodes use the XFA form namespace

Standalone native callers must retain the document for the class lifetime and provide rollback around compound graph operations when cancellation or another failure must restore earlier successful steps