PdfInteractiveForm Class

Namespace: Meziantou.Framework.Pdf
Assembly: Meziantou.Framework.Pdf.dll
Package: Meziantou.Framework.Pdf 1.0.7
Source: PdfInteractiveForm.Create.cs
Available in package assets: net10.0net11.0

The interactive form of a document (ISO 32000-2, 12.7): the /AcroForm dictionary of the catalog and its field hierarchy. The fields are read from the objects each time: changes made through the object model are seen.

public sealed class PdfInteractiveForm

Remarks

Filling a field (PdfFormField.Value, PdfCheckBoxField.IsChecked, PdfChoiceField.SetSelectedValues) changes its value and the appearances of its widgets only: the other fields keep their values, and an incremental save keeps the signatures of the document valid. PdfInteractiveForm.Flatten draws the fields on their pages and removes them.

Properties

Name	Description
Dictionary	Gets the interactive form dictionary (`/AcroForm` of the catalog), or `null` when the document has no form.
Document	Gets the document of the form.
Exists	Gets a value indicating whether the document has an interactive form.
Fields	Gets the fields at the top of the hierarchy (`/Fields`).
NeedAppearances	Gets or sets a value indicating whether viewers must generate the appearances of the fields (`/NeedAppearances`, deprecated in PDF 2.0). The library writes the appearances of the fields it fills, so it is not needed for them.

Dictionary

PdfInteractiveForm.cs

Gets the interactive form dictionary (/AcroForm of the catalog), or null when the document has no form.

public PdfDictionary? Dictionary { get; }

Property value

PdfDictionary?

Document

PdfInteractiveForm.cs

Gets the document of the form.

public PdfDocument Document { get; }

Property value

PdfDocument

Exists

PdfInteractiveForm.cs

Gets a value indicating whether the document has an interactive form.

public bool Exists { get; }

Property value

bool

Fields

PdfInteractiveForm.cs

Gets the fields at the top of the hierarchy (/Fields).

public IReadOnlyList<PdfFormField> Fields { get; }

Property value

IReadOnlyList<PdfFormField>

NeedAppearances

PdfInteractiveForm.cs

Gets or sets a value indicating whether viewers must generate the appearances of the fields (/NeedAppearances, deprecated in PDF 2.0). The library writes the appearances of the fields it fills, so it is not needed for them.

public bool NeedAppearances { get; set; }

Property value

bool

Methods

Name	Description
AddCheckBox(PdfPage, string, PdfRectangle, PdfCheckBoxOptions?)	Adds a check box (12.7.5.2.3), with one widget and the appearances of its two states.
AddComboBox(PdfPage, string, PdfRectangle, IEnumerable<PdfChoiceOption>, PdfChoiceFieldOptions?)	Adds a combo box (12.7.5.4): a drop-down list of options, editable or not, with one widget, and writes its appearance.
AddFont(PdfFont)	Adds a font to the default resources of the form (`/DR`, 12.7.4.3), the fonts the default appearances of the fields (`/DA`) name, and returns its resource name. A font the resources already have keeps its name.
AddListBox(PdfPage, string, PdfRectangle, IEnumerable<PdfChoiceOption>, PdfChoiceFieldOptions?)	Adds a list box (12.7.5.4): a scrollable list of options, with one widget, and writes its appearance.
AddRadioButtons(string, IEnumerable<PdfRadioButton>, PdfRadioButtonOptions?)	Adds a group of radio buttons (12.7.5.2.4): a field with one widget per button, of which one at most is on.
AddSignatureField(PdfPage, string, PdfRectangle, PdfFormFieldOptions?)	Adds a signature field that is not signed (12.7.5.5), with one widget: `PdfSigner` signs it when `PdfSignatureOptions.FieldName` is its name. Its appearance shows the background and the border of the options.
AddTextField(PdfPage, string, PdfRectangle, PdfTextFieldOptions?)	Adds a single-line or multiline text field (12.7.5.3), with one widget, and writes its appearance.
FindField(string)	Finds a field by its fully qualified name, such as `address.city`.
Flatten()	Flattens the form: the normal appearance of each widget is drawn in the content of its page, and the fields and their widgets are removed, so that the values become content that cannot be changed. The signature fields that are signed are kept, with their widgets, so that the signatures stay.
GetFields()	Gets the terminal fields of the form, in the order of the hierarchy: the fields that have a value and widgets.

AddCheckBox(PdfPage, string, PdfRectangle, PdfCheckBoxOptions?)

PdfInteractiveForm.Create.cs

Adds a check box (12.7.5.2.3), with one widget and the appearances of its two states.

public PdfCheckBoxField AddCheckBox(PdfPage page, string name, PdfRectangle rectangle, PdfCheckBoxOptions? options = null)

Parameters

page PdfPage: The page of the widget.
name string: The fully qualified name of the field: see PdfInteractiveForm.AddTextField.
rectangle PdfRectangle: The rectangle of the widget, in default user space.
options PdfCheckBoxOptions?: The attributes of the field, or null for the defaults.

Returns

PdfCheckBoxField The field.

Exceptions

ArgumentException: The name is not valid or is the name of a field of the form, the page is a page of another document, or the on state is empty or Off.

AddComboBox(PdfPage, string, PdfRectangle, IEnumerable<PdfChoiceOption>, PdfChoiceFieldOptions?)

PdfInteractiveForm.Create.cs

Adds a combo box (12.7.5.4): a drop-down list of options, editable or not, with one widget, and writes its appearance.

public PdfChoiceField AddComboBox(PdfPage page, string name, PdfRectangle rectangle, IEnumerable<PdfChoiceOption> choices, PdfChoiceFieldOptions? options = null)

Parameters

page PdfPage: The page of the widget.
name string: The fully qualified name of the field: see PdfInteractiveForm.AddTextField.
rectangle PdfRectangle: The rectangle of the widget, in default user space.
choices IEnumerable<PdfChoiceOption>: The options: the export values and the texts the field shows.
options PdfChoiceFieldOptions?: The attributes of the field, or null for the defaults.

Returns

PdfChoiceField The field.

Exceptions

ArgumentException: The name is not valid or is the name of a field of the form, the page is a page of another document, the options are not consistent, or a chosen value is not an option.

AddFont(PdfFont)

PdfInteractiveForm.Create.cs

Adds a font to the default resources of the form (/DR, 12.7.4.3), the fonts the default appearances of the fields (/DA) name, and returns its resource name. A font the resources already have keeps its name.

public string AddFont(PdfFont font)

Parameters

font PdfFont: The font. An embedded font is embedded whole, so that viewers can show the text typed in the fields.

Returns

string The resource name of the font.

Remarks

The appearances of the fields whose default appearance names the font are written with it. The fonts of a file cannot show new text: to fill the fields of a document that was saved, whose default appearances name an embedded font, call this method with the same font first. The font of the file is found by its PostScript name, and keeps its resource name.

AddListBox(PdfPage, string, PdfRectangle, IEnumerable<PdfChoiceOption>, PdfChoiceFieldOptions?)

PdfInteractiveForm.Create.cs

Adds a list box (12.7.5.4): a scrollable list of options, with one widget, and writes its appearance.

public PdfChoiceField AddListBox(PdfPage page, string name, PdfRectangle rectangle, IEnumerable<PdfChoiceOption> choices, PdfChoiceFieldOptions? options = null)

Parameters

page PdfPage: The page of the widget.
name string: The fully qualified name of the field: see PdfInteractiveForm.AddTextField.
rectangle PdfRectangle: The rectangle of the widget, in default user space.
choices IEnumerable<PdfChoiceOption>: The options: the export values and the texts the field shows.
options PdfChoiceFieldOptions?: The attributes of the field, or null for the defaults.

Returns

PdfChoiceField The field.

Exceptions

ArgumentException: The name is not valid or is the name of a field of the form, the page is a page of another document, the options are not consistent, or a chosen value is not an option.

AddRadioButtons(string, IEnumerable<PdfRadioButton>, PdfRadioButtonOptions?)

PdfInteractiveForm.Create.cs

Adds a group of radio buttons (12.7.5.2.4): a field with one widget per button, of which one at most is on.

public PdfRadioButtonField AddRadioButtons(string name, IEnumerable<PdfRadioButton> buttons, PdfRadioButtonOptions? options = null)

Parameters

name string: The fully qualified name of the field: see PdfInteractiveForm.AddTextField.
buttons IEnumerable<PdfRadioButton>: The buttons: their pages, their rectangles and their options. Buttons that share an option are turned on and off together.
options PdfRadioButtonOptions?: The attributes of the field, or null for the defaults.

Returns

PdfRadioButtonField The field.

Exceptions

ArgumentException: The name is not valid or is the name of a field of the form, there is no button, a page is a page of another document, an option is empty or Off, or the value is not an option.

AddSignatureField(PdfPage, string, PdfRectangle, PdfFormFieldOptions?)

PdfInteractiveForm.Create.cs

Adds a signature field that is not signed (12.7.5.5), with one widget: PdfSigner signs it when PdfSignatureOptions.FieldName is its name. Its appearance shows the background and the border of the options.

public PdfSignatureField AddSignatureField(PdfPage page, string name, PdfRectangle rectangle, PdfFormFieldOptions? options = null)

Parameters

page PdfPage: The page of the widget.
name string: The fully qualified name of the field: see PdfInteractiveForm.AddTextField.
rectangle PdfRectangle: The rectangle of the widget, in default user space; an empty rectangle for an invisible signature.
options PdfFormFieldOptions?: The attributes of the field, or null for the defaults.

Returns

PdfSignatureField The field.

Exceptions

ArgumentException: The name is not valid or is the name of a field of the form, or the page is a page of another document.

AddTextField(PdfPage, string, PdfRectangle, PdfTextFieldOptions?)

PdfInteractiveForm.Create.cs

Adds a single-line or multiline text field (12.7.5.3), with one widget, and writes its appearance.

public PdfTextField AddTextField(PdfPage page, string name, PdfRectangle rectangle, PdfTextFieldOptions? options = null)

Parameters

page PdfPage: The page of the widget.
name string: The fully qualified name of the field, such as address.city: the fields named by the parts before the last period are created when the form has none.
rectangle PdfRectangle: The rectangle of the widget, in default user space.
options PdfTextFieldOptions?: The attributes of the field, or null for the defaults.

Returns

PdfTextField The field.

Exceptions

ArgumentException: The name is not valid or is the name of a field of the form, the page is a page of another document, the options are not consistent, or the value is longer than the maximum length.

FindField(string)

PdfInteractiveForm.cs

Finds a field by its fully qualified name, such as address.city.

public PdfFormField? FindField(string fullName)

Parameters

fullName string: The fully qualified name.

Returns

PdfFormField? The field, terminal or not, or null.

Flatten()

PdfInteractiveForm.cs

Flattens the form: the normal appearance of each widget is drawn in the content of its page, and the fields and their widgets are removed, so that the values become content that cannot be changed. The signature fields that are signed are kept, with their widgets, so that the signatures stay.

public void Flatten()

Remarks

The text fields and the choice fields whose widgets have no appearance, or all of them when PdfInteractiveForm.NeedAppearances is set, get the appearances of their values first. The hidden widgets are not drawn. The /AcroForm dictionary is removed when no field is kept.

GetFields()

PdfInteractiveForm.cs

Gets the terminal fields of the form, in the order of the hierarchy: the fields that have a value and widgets.

public IReadOnlyList<PdfFormField> GetFields()

Returns

IReadOnlyList<PdfFormField> The fields.