HPDFXFAExecuteJavaScriptEvent

Unit: HPDFXFAEventScript

Declaration

function HPDFXFAExecuteJavaScriptEvent(const Script: AnsiString;
  const Bindings: TXFAEventBindings; SelfIndex: Integer;
  const Options: TXFAFormScriptOptions; out Actions: TXFAEventActions;
  out Operations: Integer; out Diagnostic: string;
  Session: TXFAJavaScriptSession= nil;
  HostTransaction: TXFAHostTransaction= nil;
  LocaleProvider: TXFALocaleDataProvider= nil;
  HostModel: PXFAHostModelState= nil): Boolean;

Behavior

Executes an event against a live virtual form DOM and returns validated mutation records without modifying the caller document

Bindings supply the host context and SelfIndex selects this; Options.EnableJavaScript must be True

Script and raw binding text are UTF-8 bytes, decoded explicitly for the JavaScript source and quoted context instead of being interpreted using the operating-system ANSI code page; literal Greek, supplementary scalars and Unicode line separators retain their exact value

Uses the shipped bounded QuickJS engine or Options.JavaScriptEvaluator, with script, context, memory, stack, interrupt, time, operation and output budgets

Returns True only when engine execution and output validation succeed; failed execution clears Actions and reports Diagnostic

TXFAWidgetRuntime validates and replays actions within its own snapshot transaction; direct callers must provide equivalent transactional handling

The native engine compiles reusable event support code once per session engine, while every call supplies its current binding vector, event body, limits and recorded host, locale, calculation and XML responses; separate sessions and repeated script objects retain independent state

Support initialization, event execution, suspension retries and rollback reconstruction share the original elapsed-time deadline; custom JavaScriptEvaluator callbacks receive a complete standalone wrapper

Pass an owned TXFAJavaScriptSession to retain script objects and lexical state across calls; a nil session creates an isolated engine for that call

Pass an owned TXFAHostTransaction for explicit application effects; suspension retries restore the session checkpoint and consume recorded responses without invoking completed requests again

Lower-level callers must finalize the host transaction with their document outcome; host effects require the shipped engine and cannot use JavaScriptEvaluator

LocaleProvider supplies read-only locale metadata; nil uses Windows locale data, while TXFAWidgetRuntime supplies the current document localeSet with system fallback

The nearest nonempty Locale binding supplies the ambient locale; an empty inherited locale selects the current user locale

Computed locale names suspend native execution, restore the session checkpoint and retry with the recorded metadata; committed replay consumes that metadata without invoking the provider again

Each call permits at most 64 named locale requests, 256 UTF-16 code units per identifier and 2 MiB of locale metadata, sharing the elapsed script deadline; custom JavaScriptEvaluator callbacks must consume the supplied locale data without requesting native lookups

HostModel supplies a read-only snapshot of application metadata, pages, flags, title and focus; nil uses TXFAHostModelState.Default, and returned host/focus/reset actions require native transactional application by the caller

Dynamic FormCalc Eval suspends for native compilation and retries with recorded compiled responses inside the same deadline; custom JavaScriptEvaluator callbacks cannot service these requests

The pointer is read synchronously and never retained or written; TXFAWidgetRuntime passes its current state and applies mutations within its document snapshot transaction

The executing binding's EventActivity supplies xfa.event.name, with event as the lower-level fallback

Live SOM resolution uses binding hierarchy and current occurrence order, supports class and descendant selectors and candidate predicates, and selects one inferred or default occurrence when an index is omitted

Data DOM bindings build the datasets tree, connect form values through DataIdentity and support data writes and retained native data handles; direct callers apply both domains and virtual identity actions transactionally

Property DOM bindings expose declared property children and Attributes/DefaultAttributes; direct callers apply property raw-value and attribute actions to the matching native form occurrence

Named field aliases are visible through the outer event scope; local const, let, class, function and var declarations follow normal JavaScript lexical rules inside the event body

The event body preserves an initial use strict directive, its form-node this context and explicit return values; lexical or strict-mode failures reject the same native transaction

See JavaScript Event Scope for shadowing and persistence behavior

Related APIs

Interactive Dynamic XFA Widget Runtime, FormCalc Functions and XFA Packet DOM