5. Forms & interactivity

Interactive form fields and document interactivity.

A PDF is not always a static page. It can carry links you can click, anchors you can jump to, and AcroForm fields a reader can fill in. This chapter covers the interactive features Rivoli PDF writes today, and is clear about where the edges are.

Hyperlinks

A hyperlink is an inline: it lives inside a paragraph and wraps link text. The convenience method is Paragraph.AddLink(target, text):

using Rivoli.Pdf;
using Rivoli.Pdf.Model;

var section = doc.AddSection();

section.Add(new Paragraph()
    .Add("Read the ")
    .AddLink("https://github.com/rivoli-ai/rivoli-pdf", "source on GitHub")
    .Add(" for details."));

AddLink constructs a Hyperlink (namespace Rivoli.Pdf.Model) and appends it to the paragraph’s Inlines. The Target string decides the link kind:

Target form	Result
https://…, mailto:…, any non-# string	External link: emitted as a URI action
#anchor	Internal link: emitted as a named-destination jump

The renderer collects each hyperlink’s rendered rectangle and writes it as a /Link annotation on the page: external targets become a URI action, and #anchor targets become a /Dest referencing the anchor name (the part after the #).

Internal anchors

External links are fully wired. Internal #anchor links emit a named-destination annotation, but the model has no first-class API for declaring the destination a name points to. Treat in-document jumps as partially supported, and prefer external links where reliability matters.

Bookmarks and the document outline

Outline authoring is not implemented

Rivoli PDF can parse an existing document’s outline on the import path, but there is no authoring API to add bookmarks / outline entries to a document you are building. If you need a navigation outline today, it is not yet available on the writing path. This is a known gap, not a documented feature.

Form fields (AcroForm)

Form fields are a document-level, cross-cutting collection rather than body content. The Document owns them through FormFields, and you add them with AddFormField:

using Rivoli.Pdf;
using Rivoli.Pdf.Forms;

var doc = Document.Create("Application Form");
doc.AddSection().AddHeading("Membership application");

doc.AddFormField(new TextField("full_name")
{
    Rect = new Rectangle(72, 700, 320, 720),   // left, bottom, right, top (points)
    PageIndex = 0,
    Tooltip = "Your full legal name",
    Required = true,
});

Every field derives from the abstract FormField (namespace Rivoli.Pdf.Forms), which carries the properties common to all of them:

Member	Purpose
Name	Field name (must be unique within the document)
Rect	Placement rectangle, in PDF points (Rectangle(left, bottom, right, top))
PageIndex	Zero-based page the widget appears on
ReadOnly, Required	Standard AcroForm flags
Tooltip	Hover / accessibility text
DefaultValue	Reset value

AddFormField enforces unique names and throws if you add two fields with the same Name. Companion methods round out management: GetFormField(name), RemoveFormField(field) / RemoveFormField(name), and ClearFormFields().

The field types

All seven AcroForm field types are present as authoring models:

Type	Key members
TextField	Value, MaxLength, IsMultiLine, IsPassword, Alignment, FontSize
CheckBoxField	IsChecked, ExportValue, Style
RadioButtonField	GroupName, ExportValue, IsSelected, Style
ComboBoxField	Options, SelectedValue, IsEditable, SortOptions
ListBoxField	Options, SelectedValues, AllowMultipleSelection, VisibleItems
PushButtonField	Caption, Action, SubmitUrl, JavaScript, Appearance
SignatureField	SignReason, SignLocation, SignerName, IsSigned

A small interactive form:

// A required text field
doc.AddFormField(new TextField("email")
{
    Rect = new Rectangle(72, 660, 320, 680),
    PageIndex = 0,
    IsMultiLine = false,
});

// A checkbox
doc.AddFormField(new CheckBoxField("subscribe", isChecked: true)
{
    Rect = new Rectangle(72, 630, 90, 648),
    PageIndex = 0,
    ExportValue = "yes",
});

// A drop-down with options
var plan = new ComboBoxField("plan");
plan.Rect = new Rectangle(72, 600, 320, 618);
plan.PageIndex = 0;
plan.AddOption("Standard");
plan.AddOption("Premium", "PREM");
doc.AddFormField(plan);

Radio buttons share a group through their Name / GroupName: add one RadioButtonField per option, all with the same group name and distinct ExportValues.

When you save, the renderer writes the AcroForm dictionary, the field tree, and a widget annotation per field with a generated default appearance. Choice fields (ComboBoxField, ListBoxField) carry their Options through.

Filling and flattening are not authoring concerns here

These APIs author the field definitions and their initial values. Rivoli PDF is not a forms runtime: there is no fill-and-flatten or interactive round-trip beyond setting the initial Value / IsChecked / SelectedValue you write into the model.

Signature fields vs. signing

SignatureField defines the placeholder for a signature: its rectangle, reason, location, and signer metadata. Actually applying a cryptographic signature is a separate operation covered in the next chapter.

Next

• 6. Security: encryption & signatures: passwords, permissions, and digitally signing a document.
• The document model: where form fields sit relative to body content.