Add QPDFAcroFormDocumentHelper::addFormField

ChangeLog

@@ -1,5 +1,8 @@
 2021-02-18  Jay Berkenbilt  <ejb@ql.org>
 
+	* Add QPDFAcroFormDocumentHelper::addFormField, which adds a new
+	form field, initializing the AcroForm dictionary if needed.
+
 	* Add QPDFPageObjectHelper::getMatrixForFormXObjectPlacement,
 	which returns the transformation matrix required to map from a
 	form field's coordinate system into a specific rectangle within

include/qpdf/QPDFAcroFormDocumentHelper.hh

@@ -106,6 +106,13 @@ class QPDFAcroFormDocumentHelper: public QPDFDocumentHelper
     bool
     hasAcroForm();
 
+    // Add a form field, initializing the document's AcroForm
+    // dictionary if needed. Calling this method invalidates the
+    // cache, which makes it possible to add a field that is not yet
+    // associated with an annotation or page.
+    QPDF_DLL
+    void addFormField(QPDFFormFieldObjectHelper);
+
     // Return a vector of all terminal fields in a document. Terminal
     // fields are fields that have no children that are also fields.
     // Terminal fields may still have children that are annotations.

libqpdf/QPDFAcroFormDocumentHelper.cc

@@ -32,6 +32,26 @@ QPDFAcroFormDocumentHelper::hasAcroForm()
     return this->qpdf.getRoot().hasKey("/AcroForm");
 }
 
+void
+QPDFAcroFormDocumentHelper::addFormField(QPDFFormFieldObjectHelper ff)
+{
+    invalidateCache();
+    auto acroform = this->qpdf.getRoot().getKey("/AcroForm");
+    if (! acroform.isDictionary())
+    {
+        acroform = this->qpdf.makeIndirectObject(
+            QPDFObjectHandle::newDictionary());
+        this->qpdf.getRoot().replaceKey("/AcroForm", acroform);
+    }
+    auto fields = acroform.getKey("/Fields");
+    if (! fields.isArray())
+    {
+        fields = QPDFObjectHandle::newArray();
+        acroform.replaceKey("/Fields", fields);
+    }
+    fields.appendItem(ff.getObjectHandle());
+}
+
 std::vector<QPDFFormFieldObjectHelper>
 QPDFAcroFormDocumentHelper::getFormFields()
 {

manual/qpdf-manual.xml

@@ -5286,12 +5286,20 @@ print "\n";
         <listitem>
          <para>
 	  Add
-	  <function>QPDFPageObjectHelper::getMatrixForFormXObjectPlacement</function>
+	  <function>QPDFPageObjectHelper::getMatrixForFormXObjectPlacement</function>,
 	  which returns the transformation matrix required to map from
 	  a form field's coordinate system into a specific rectangle
 	  within the page.
          </para>
         </listitem>
+        <listitem>
+         <para>
+          Add method
+          <function>QPDFAcroFormDocumentHelper::addFormField</function>,
+          which adds a new form field, initializing the AcroForm
+          dictionary if needed.
+         </para>
+        </listitem>
         <listitem>
          <para>
           Add <function>QUtil::path_basename</function> to return the