====== std.pdf.forms ======

PDF AcroForms (WP-PDF-18): Interaktive Formularfelder — Textfelder, Checkboxen, Radio-Buttons und Dropdown-Listen (ComboBox). Alle Felder werden als Widget-Annotations mit Appearance-Streams in das AcroForm-Dictionary eingebettet. Optional können alle Felder mit ''PdfFlattenForms'' in statischen Seiteninhalt umgewandelt werden.

→ [[lyx_-_programmiersprache:units:pdf:annot|std.pdf.annot]] · [[lyx_-_programmiersprache:units:pdf:builder|std.pdf.builder]] · [[lyx_-_programmiersprache:units|Standard Library]]

----

===== Koordinaten-Packing =====

Position und Größe werden als gepackte ''int64''-Werte übergeben (gleiche Konvention wie ''[[lyx_-_programmiersprache:units:pdf:shading|std.pdf.shading]]''):

  * ''pos = PdfPackCoords(x100, y100)'' — linke untere Ecke
  * ''size = PdfPackCoords(w100, h100)'' — Breite × Höhe
  * ''size100'' — bei quadratischen Feldern (Checkbox, Radio) ein einzelner Seitenlängenwert ×100

Alle Werte sind in **×100-Einheiten** (100 = 1 PDF-Punkt).

----

===== Funktionen =====

==== Felder hinzufügen ====

^ Signatur ^ Rückgabe ^ Beschreibung ^
| ''PdfAddTextField(doc, page, pos, size, name: pchar, defaultValue: pchar): int64'' | ''fieldId'' / −1 | Einzeiliges bearbeitbares Textfeld. ''name'': Feldname (/T). ''defaultValue'': Initialwert (/V), ''0'' für leer. |
| ''PdfAddCheckbox(doc, page, pos, size100, name: pchar, checked: int64): int64'' | ''fieldId'' / −1 | Quadratische Checkbox. ''size100'': Seitenlänge ×100. ''checked'': 1 = anfangs aktiviert, 0 = deaktiviert. |
| ''PdfAddRadioButton(doc, page, pos, size100, groupName: pchar, value: pchar): int64'' | ''fieldId'' / −1 | Radio-Button in einer benannten Gruppe. Gruppen werden bei erstmaliger Nennung automatisch angelegt. ''value'': Wert-String dieses Buttons (z. B. ''„Option1"''). |
| ''PdfAddComboBox(doc, page, pos, size, name: pchar): int64'' | ''fieldId'' / −1 | Dropdown-Liste. Items separat mit ''PdfComboAddItem'' hinzufügen. |

==== Items und Aktionen ====

^ Signatur ^ Beschreibung ^
| ''PdfComboAddItem(doc: int64, fieldId: int64, item: pchar): void'' | Hängt einen Eintrag an die Option-Liste einer ComboBox. Mehrfachaufruf für mehrere Einträge. |
| ''PdfFlattenForms(doc: int64): void'' | Wandelt alle Formularfelder in statischen Seiteninhalt um. Das PDF wird danach nicht mehr interaktiv — Viewer zeigen die Felder als gezeichnetes Bild. Nützlich für Archivierung oder Druck. |

----

===== Vollständige Signaturen =====

<code lyx>
pub fn PdfAddTextField(doc: int64, page: int64, pos: int64, size: int64,
                        name: pchar, defaultValue: pchar): int64

pub fn PdfAddCheckbox(doc: int64, page: int64, pos: int64, size100: int64,
                       name: pchar, checked: int64): int64

pub fn PdfAddRadioButton(doc: int64, page: int64, pos: int64, size100: int64,
                          groupName: pchar, value: pchar): int64

pub fn PdfAddComboBox(doc: int64, page: int64, pos: int64, size: int64,
                       name: pchar): int64

pub fn PdfComboAddItem(doc: int64, fieldId: int64, item: pchar): void

pub fn PdfFlattenForms(doc: int64): void
</code>

----

===== Verwendung =====

==== Einfaches Formular ====

<code lyx>
import std.pdf.forms;
import std.pdf.shading;   // für PdfPackCoords

fn AddContactForm(doc: int64, page: int64): void {
    // Textfeld "Name" — Position (50, 700), Größe 200×20 (×100: 5000×2000)
    var nameField := PdfAddTextField(doc, page,
        PdfPackCoords(5000, 70000),
        PdfPackCoords(20000, 2000),
        "name", "Ihr Name");

    // Textfeld "E-Mail"
    var mailField := PdfAddTextField(doc, page,
        PdfPackCoords(5000, 67000),
        PdfPackCoords(20000, 2000),
        "email", "");

    // Checkbox "Newsletter"
    var cbNews := PdfAddCheckbox(doc, page,
        PdfPackCoords(5000, 64000),
        1500,          // 15 × 15 Punkte
        "newsletter", 1);   // anfangs aktiviert
}
</code>

==== Radio-Gruppe ====

<code lyx>
import std.pdf.forms;
import std.pdf.shading;

fn AddRadioGroup(doc: int64, page: int64): void {
    // Drei Radio-Buttons in Gruppe "priority"
    PdfAddRadioButton(doc, page,
        PdfPackCoords(5000, 70000), 1500, "priority", "high");

    PdfAddRadioButton(doc, page,
        PdfPackCoords(5000, 67500), 1500, "priority", "medium");

    PdfAddRadioButton(doc, page,
        PdfPackCoords(5000, 65000), 1500, "priority", "low");
}
</code>

==== ComboBox mit Einträgen ====

<code lyx>
import std.pdf.forms;
import std.pdf.shading;

fn AddCountryDropdown(doc: int64, page: int64): void {
    var combo := PdfAddComboBox(doc, page,
        PdfPackCoords(5000, 70000),
        PdfPackCoords(15000, 2000),
        "country");

    PdfComboAddItem(doc, combo, "Deutschland");
    PdfComboAddItem(doc, combo, "Österreich");
    PdfComboAddItem(doc, combo, "Schweiz");
    PdfComboAddItem(doc, combo, "Liechtenstein");
}
</code>

==== Formular flattening für Archivierung ====

<code lyx>
import std.pdf.forms;

fn SaveFlattened(doc: int64, path: pchar): void {
    // Alle Felder zeichnen und AcroForm entfernen
    PdfFlattenForms(doc);
    PdfSave(doc, path);
}
</code>

----

===== Hinweise =====

  * ''fieldId'' ist der nullbasierte Index des Feldes im internen Feld-Array — stabil für ''PdfComboAddItem''.
  * ''PdfAddRadioButton'': Gruppen werden automatisch bei erstmaliger Nennung von ''groupName'' angelegt. Alle Buttons derselben Gruppe teilen sich einen übergeordneten /Btn-Parent-Widget.
  * ''PdfFlattenForms'' setzt intern das ''FORMFLAT''-Flag: ''PdfSave'' überspringt dann das ''/AcroForm''-Dictionary und die Widget-Annotations.
  * Das AcroForm-Objekt-ID wird beim ersten ''PdfAddTextField''/''PdfAddCheckbox''-Aufruf lazy angelegt — kein Overhead wenn keine Felder verwendet werden.
  * Koordinatensystem: Ursprung (0, 0) unten links, Y wächst nach oben (PDF-Standard). A4: 595 × 842 Punkte, also ×100: 59 500 × 84 200.

----

===== Verwandte Units =====

  * ''[[lyx_-_programmiersprache:units:pdf:annot|std.pdf.annot]]'' — Hyperlink- und sonstige Annotations
  * ''[[lyx_-_programmiersprache:units:pdf:shading|std.pdf.shading]]'' — ''PdfPackCoords'' / ''PdfPackColor''
  * ''[[lyx_-_programmiersprache:units:pdf:builder|std.pdf.builder]]'' — Dokumenterstellung (PdfCreate, PdfSave)

Letzte Aktualisierung: 2026-06-05