NAME

PDF::Make::Form - PDF interactive forms (AcroForms) for PDF::Make

SYNOPSIS

use PDF::Make;

my $pdf = PDF::Make->new();
my $page = $pdf->add_page(width => 612, height => 792);

# Create a form
my $form = $pdf->create_form();

# Add a text field
my $name_field = $form->add_text_field(
    name   => 'name',
    x      => 100,
    y      => 700,
    width  => 200,
    height => 20,
);
$name_field->set_value('John Doe');
$name_field->add_to_page($page);

# Add a checkbox
my $checkbox = $form->add_checkbox(
    name     => 'agree',
    x        => 100,
    y        => 650,
    width    => 15,
    height   => 15,
    on_value => 'Yes',
);
$checkbox->set_value('Yes');  # Check it
$checkbox->add_to_page($page);

# Finalize and render
$form->finalize();
my $bytes = $pdf->render();

DESCRIPTION

This module provides PDF interactive forms (AcroForms) support per ISO 32000-2:2020 §12.7. It supports:

• Text fields (single-line, multiline, password)

• Checkboxes and radio button groups

• Dropdown (combo) and list boxes

• Push buttons

• Signature fields (placeholder)

• FDF/XFDF export and import

• Form flattening

METHODS

new

my $form = PDF::Make::Form->new($document);

Create a new form for the given document. Usually called via $pdf->create_form() rather than directly.

add_text_field

my $field = $form->add_text_field(
    name   => 'field_name',
    x      => 100,
    y      => 500,
    width  => 200,
    height => 20,
);

Create a text field at the specified location.

Options:

• name - Field name (required)

• x, y - Lower-left corner coordinates

• width, height - Field dimensions

• value - Initial value

• default_value - Default value for reset

• max_len - Maximum characters allowed

• multiline - Enable multiline input

• password - Mask input as password

• readonly - Make field read-only

• required - Mark as required

• quadding - Text alignment (0=left, 1=center, 2=right)

• da - Default appearance string

add_checkbox

my $field = $form->add_checkbox(
    name     => 'agree',
    x        => 100,
    y        => 500,
    width    => 15,
    height   => 15,
    on_value => 'Yes',
);

Create a checkbox field.

add_radio_group

my $group = $form->add_radio_group(name => 'choice');
$group->add_option(x => 100, y => 500, width => 15, height => 15, value => 'A');
$group->add_option(x => 100, y => 480, width => 15, height => 15, value => 'B');
$group->add_option(x => 100, y => 460, width => 15, height => 15, value => 'C');

Create a radio button group.

add_choice

my $field = $form->add_choice(
    name    => 'country',
    x       => 100,
    y       => 500,
    width   => 150,
    height  => 20,
    combo   => 1,          # 1 for dropdown, 0 for listbox
    options => [
        { display => 'United States', export => 'US' },
        { display => 'Canada', export => 'CA' },
        { display => 'Mexico', export => 'MX' },
    ],
);

Create a choice field (dropdown or listbox).

add_combo

my $field = $form->add_combo(name => 'country', ...);

Shorthand for add_choice(combo = 1, ...)>.

add_listbox

my $field = $form->add_listbox(name => 'items', ...);

Shorthand for add_choice(combo = 0, ...)>.

add_button

my $field = $form->add_button(
    name    => 'submit',
    x       => 100,
    y       => 100,
    width   => 80,
    height  => 25,
    caption => 'Submit',
);

Create a push button.

add_signature

my $field = $form->add_signature(
    name   => 'sig',
    x      => 100,
    y      => 100,
    width  => 200,
    height => 50,
);

Create a signature field (placeholder for digital signature).

field_count

my $count = $form->field_count();

Return the number of top-level fields.

field_at

my $field = $form->field_at($index);

Get field at the given index.

field_by_name

my $field = $form->field_by_name('person.name.first');

Find a field by its full name.

fields

my @fields = $form->fields();

Get all top-level fields.

finalize

$form->finalize();

Finalize the form: create AcroForm dictionary, field dictionaries, widget annotations, and appearance streams. Call this before rendering.

flatten

$form->flatten();

Flatten all form fields: render values into page content and remove interactive elements. After flattening, the PDF is no longer editable.

export_fdf

my $fdf_data = $form->export_fdf();

Export form data in FDF format.

export_xfdf

my $xfdf_data = $form->export_xfdf();

Export form data in XFDF (XML) format.

import_fdf

$form->import_fdf($fdf_data);

Import form data from FDF format.

import_xfdf

$form->import_xfdf($xfdf_data);

Import form data from XFDF format.

set_need_appearances

$form->set_need_appearances(1);

Set the NeedAppearances flag. If true, the PDF viewer will generate field appearances. If false (default), appearances are generated during finalization.

SEE ALSO

PDF::Make, PDF::Make::Field

AUTHOR

LNATION <email@lnation.org>

COPYRIGHT AND LICENSE

Copyright (C) 2024 by LNATION

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm PDF::Make

perl -MCPAN -e shell
install PDF::Make