ENH: PdfWriter: Scale and wrap text in text annotations

This patch scales and/or wrap text that does not
fit into a text field unaltered, under the condition
that font size was set to 0 in the default
appearance stream.

We only wrap text if the multiline bit was set in
the corresponding annotation's field flags, otherwise
we just scale the font until it fits.

We move the escaping of parentheses below, so that it
does not interfere with calculating the width of a
text string.

Author: PJBrs

pypdf/_writer.py

@@ -51,6 +51,7 @@
 from ._cmap import _default_fonts_space_width, build_char_map_from_dict
 from ._doc_common import DocumentInformation, PdfDocCommon
 from ._encryption import EncryptAlgorithm, Encryption
+from ._font import FontDescriptor
 from ._page import PageObject, Transformation
 from ._page_labels import nums_clear_range, nums_insert, nums_next
 from ._reader import PdfReader
@@ -929,23 +930,35 @@ def _update_field_annotation(
             da = da.get_object()
         font_properties = da.replace("\n", " ").replace("\r", " ").split(" ")
         font_properties = [x for x in font_properties if x != ""]
+        # If font name was given when calling this method, then add it to
+        # the font properties, otherwise read it from the default appearance
         if font_name:
             font_properties[font_properties.index("Tf") - 2] = font_name
         else:
             font_name = font_properties[font_properties.index("Tf") - 2]
+        # If font size was given when calling this method, then add it to
+        # the font properties, otherwise read it from the default appearance
         font_height = (
             font_size
             if font_size >= 0
             else float(font_properties[font_properties.index("Tf") - 1])
         )
+        formatting = {
+            "wrap" : False,
+            "scale" : False,
+        }
+        # Only when font height is 0 in the default appearance (or when there is no default
+        # appearance, but this should not be the case for a text annotation) set the text
+        # wrapping and/or font scaling options for generating the appearance stream.
         if font_height == 0:
             if field.get(FA.Ff, 0) & FA.FfBits.Multiline:
                 font_height = DEFAULT_FONT_HEIGHT_IN_MULTILINE
+                formatting["wrap"] = True
+                formatting["scale"] = True
             else:
                 font_height = rct.height - 2
+                formatting["scale"] = True
         font_properties[font_properties.index("Tf") - 1] = str(font_height)
-        da = " ".join(font_properties)
-        y_offset = rct.height - 1 - font_height
 
         # Retrieve font information from local DR ...
         dr: Any = cast(
@@ -977,6 +990,7 @@ def _update_field_annotation(
             _font_subtype, _, font_encoding, font_map = build_char_map_from_dict(
                 200, font_res
             )
+            font_descriptor = FontDescriptor.from_font_resource(font_res)
             try:  # remove width stored in -1 key
                 del font_map[-1]
             except KeyError:
@@ -994,6 +1008,7 @@ def _update_field_annotation(
         else:
             logger_warning(f"Font dictionary for {font_name} not found.", __name__)
             font_full_rev = {}
+            font_descriptor = FontDescriptor()
 
         # Retrieve field text and selected values
         field_flags = field.get(FA.Ff, 0)
@@ -1005,11 +1020,9 @@ def _update_field_annotation(
         else:  # /Tx
             txt = field.get("/V", "")
             sel = []
-        # Escape parentheses (PDF 1.7 reference, table 3.2, Literal Strings)
-        txt = txt.replace("\\", "\\\\").replace("(", r"\(").replace(")", r"\)")
         # Generate appearance stream
         ap_stream = generate_appearance_stream(
-            txt, sel, da, font_full_rev, rct, font_height, y_offset
+            txt, sel, font_properties, font_full_rev, font_descriptor, rct, font_height, formatting
         )
 
         # Create appearance dictionary
@@ -3536,14 +3549,36 @@ def scale_text(
 def generate_appearance_stream(
     txt: str,
     sel: list[str],
-    da: str,
+    font_properties: list[str],
     font_full_rev: dict[str, bytes],
+    font_descriptor: FontDescriptor,
     rct: RectangleObject,
     font_height: float,
-    y_offset: float,
+    formatting: dict[str, bool],
 ) -> bytes:
+    # Only wrap text for non-choice fields, otherwise we break matching sel and line later on.
+    if sel:
+        formatting["wrap"] = False
+    if formatting["scale"]:
+        lines, font_height = scale_text(
+            font_descriptor,
+            font_height,
+            rct.width - 3,  # One point margin left and right, and an additional point because the first offset
+                            # takes one extra point (see below, under "line_number == 0:")
+            rct.height - 3,  # One point margin for top and bottom, one point extra for the first line (see y_offset)
+            txt,
+            formatting["wrap"],
+        )
+        font_properties[1] = str(font_height)
+    else:
+        lines = txt.replace("\n", "\r").split("\r")
+
+    y_offset = rct.height - 1 - font_height
+    da = " ".join(font_properties)
     ap_stream = f"q\n/Tx BMC \nq\n1 1 {rct.width - 1} {rct.height - 1} re\nW\nBT\n{da}\n".encode()
-    for line_number, line in enumerate(txt.replace("\n", "\r").split("\r")):
+    for line_number, line in enumerate(lines):
+        # Escape parentheses (PDF 1.7 reference, table 3.2, Literal Strings)
+        line = line.replace("\\", "\\\\").replace("(", r"\(").replace(")", r"\)")
         if line in sel:
             # may be improved but cannot find how to get fill working => replaced with lined box
             ap_stream += (