How to Add Form Fields

Starting with version v1.13.11, form field annotations (also called "widgets") can be added to a new or existing PDF. Since v1.13.12, existing widgets can also be updated.

If necessary, the first added widget will turn the PDF into a "Form PDF".

Widgets represent an annotation type with many special features and disparate subtypes. To present a manageable programmer API, covering a broad range of functions, we have introduced a new class, called Widget, which serves as a "communication vehicle" in the following way:

To access complete widget information of a widget annotation annot on a page, consult its property annot.widget which is a Widget object (or None for other annotation types). Among its attributes are field name and field value. Demo script list-fields.py prints all information of all widgets of a PDF.
To add a widget on a page, use the following sequence of instructions:

widget = fitz.Widget()                 # create a new empty widget object
widget.rect = fitz.Rect(...)           # where to locate the field
widget.field_type = fitz.ANNOT_WG_TEXT # set other properties
widget.field_name = "some text field"  # ... like field name, field value, etc
widget.field_value = "carpe diem!"
...
annot = page.addWidget(widget)         # add the widget
# now the PDF has eventually become a Form PDF
# and further widgets can be added to this or other pages
...
doc.save(..., clean = True)            # use the clean option!

Demo script widgettest.py creates a new PDF page with 5 different form fields. After using a suitable viewer software to fill out this form, the result looks like this: widgettest.pdf

To change an existing widget, use code like so:

´´´python

annot = ... # widget annotation widget = annot.widget # get widget properties if not widget: raise ValueError("not a widget") # that is no pdf field! widget.field_value = "updated value" # change field value annot.updateWidget(widget) # write changes back to field ...