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. The result looks like this: widgettest.pdf.

Note: not all PDF viewers behave exactly equal when displaying the PDF. For example, the checkbox may not be shown correctly with its tickmark in some cases.

• To change an existing widget, use code like so:

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
...
# again, use clean option when saving PDF
doc.save(..., clean = True, ...)