PdfFormScriptSession Class

Runs the scripts of an interactive form (ISO 32000-2, 12.6.4.17, 12.7.6) in a sandbox, when the host sets values: the keystroke and validation scripts of the field set, then the calculation scripts of the form in their order (PdfInteractiveForm.CalculationOrder), then the format scripts of the fields that changed.

public sealed class PdfFormScriptSession : IDisposable

Remarks

The scripts never run implicitly: opening a document and setting PdfFormField.Value run none. The document-level scripts (PdfDocument.JavaScripts) run once, when the session is created; the open action never runs.

The scripts run in a realm of their own, with the limits of the options. They see the event object, the fields (this.getField), the AF functions of the viewers (AFSimple_Calculate, AFNumber_Format...), util.printf, util.printd, util.scand and app.alert. The functions that reach outside of the form (submit, mail, print, open a URL or a document, menu items) do nothing, and are reported in the diagnostics. The numbers and the dates are formatted with fixed rules, not with the culture of the process.

Implements

Properties

NameDescription
InitializationDiagnosticsGets the diagnostics of the document-level scripts, run when the session was created.

InitializationDiagnostics

PdfFormScriptSession.cs

Gets the diagnostics of the document-level scripts, run when the session was created.

public IReadOnlyList<PdfFormScriptDiagnostic> InitializationDiagnostics { get; }

Methods

NameDescription
Dispose()Releases the engine of the scripts.
Recalculate()Runs the calculation scripts of the form in their order, then the format scripts of the fields that changed.
SetValue(string, string?)Sets the value of a field as a user would commit it: the keystroke and validation scripts of the field may reject it, then the calculation scripts of the form run, then the format scripts of the fields that changed.
SetValues(IEnumerable<KeyValuePair<string, string?>>)Sets the values of several fields: the keystroke and validation scripts of each, then the calculation scripts of the form once, at the end, then the format scripts of the fields that changed.

Releases the engine of the scripts.

public void Dispose()

Runs the calculation scripts of the form in their order, then the format scripts of the fields that changed.

public PdfFormScriptResult Recalculate()

Returns

PdfFormScriptResult The fields that changed, and the diagnostics of the scripts.

Exceptions

PdfFormScriptException
A script failed, and PdfFormScriptOptions.ThrowOnScriptError is set.

SetValue(string, string?)

PdfFormScriptSession.cs

Sets the value of a field as a user would commit it: the keystroke and validation scripts of the field may reject it, then the calculation scripts of the form run, then the format scripts of the fields that changed.

public PdfFormScriptResult SetValue(string fullName, string? value)

Parameters

fullName string
The fully qualified name of the field.
value string?
The value, or null to clear it.

Returns

PdfFormScriptResult Whether the value was accepted, the fields that changed, and the diagnostics of the scripts.

Exceptions

ArgumentException
The form has no field of this name.
PdfFormScriptException
A script failed, and PdfFormScriptOptions.ThrowOnScriptError is set.

SetValues(IEnumerable<KeyValuePair<string, string?>>)

PdfFormScriptSession.cs

Sets the values of several fields: the keystroke and validation scripts of each, then the calculation scripts of the form once, at the end, then the format scripts of the fields that changed.

Parameters

values IEnumerable<KeyValuePair<string, string?>>
The values, by fully qualified name of field.

Returns

PdfFormScriptResult Whether every value was accepted, the fields that changed, and the diagnostics of the scripts.

Exceptions

ArgumentException
The form has no field of one of the names.
PdfFormScriptException
A script failed, and PdfFormScriptOptions.ThrowOnScriptError is set.