Minor improvements regarding annotations

py-pdf · Nov 15, 2024 · 421dca8 · 421dca8
1 parent 5763710
commit 421dca8
Show file tree

Hide file tree

Showing 40 changed files with 36 additions and 36 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,12 +21,12 @@ This can also be enabled programmatically with `warnings.simplefilter('default',
 * new optional parameter `border` for table cells [issue #1192](https://github.com/py-pdf/fpdf2/issues/1192) users can define specific borders (left, right, top, bottom) for individual cells
 * [`FPDF.write_html()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.write_html): now parses `<title>` tags to set the [document title](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_title). By default, it is added as PDF metadata, but not rendered in the document body. However, this can be enabled by passing `render_title_tag=True` to `FPDF.write_html()`.
 * support for LZWDecode compression [issue #1271](https://github.com/py-pdf/fpdf2/issues/1271)
-* [text_annotation()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.text_annotation) has a new optional `title` parameter
 ### Fixed
 * `FPDF.set_text_shaping(False)` was broken since version 2.7.8 and is now working properly - [issue #1287](https://github.com/py-pdf/fpdf2/issues/1287)
 * fixed bug where cells with `rowspan`, `colspan` > 1 and null text were not displayed properly - [issue #1293](https://github.com/py-pdf/fpdf2/issues/1293)
 ### Changed
 * improved logic for handling text substitution of the total number of pages, ensuring compatibility with text shaping - [issue #1090](https://github.com/py-pdf/fpdf2/issues/1090)
+* all [`AnnotationDict`](https://py-pdf.github.io/fpdf2/fpdf/annotations.html) properties can now be passed to `FPDF.text_annotation()`, `FPDF.free_text_annotation()`,  `FPDF.add_action()`, `FPDF.add_text_markup_annotation()` & `FPDF.ink_annotation()`. This includes `title`, `color`, `border_width`...
 ### Removed
 * reminder : since release `2.8.1`, `fpdf2` does not support Python 3.7, that reached [end-of-life](https://devguide.python.org/versions/#supported-versions) in 2023
 

diff --git a/fpdf/annotations.py b/fpdf/annotations.py
@@ -30,7 +30,7 @@ def __init__(
         y: int,
         width: int,
         height: int,
-        flags: Tuple[AnnotationFlag] = DEFAULT_ANNOT_FLAGS,
+        flags: Union[Tuple[AnnotationFlag], Tuple[str]] = DEFAULT_ANNOT_FLAGS,
         contents: str = None,
         dest: Destination = None,
         action: Action = None,
@@ -48,11 +48,11 @@ def __init__(
     ):
         self.type = Name("Annot")
         self.subtype = Name(subtype)
-        self.rect = f"[{x:.2f} {y:.2f} {x + width:.2f} {y - height:.2f}]"
+        self.rect = f"[{x:.2f} {y - height:.2f} {x + width:.2f} {y:.2f}]"
         self.border = f"[0 0 {border_width}]"
         self.f_t = Name(field_type) if field_type else None
         self.v = value
-        self.f = sum(flags)
+        self.f = sum(tuple(AnnotationFlag.coerce(flag) for flag in flags))
         self.contents = PDFString(contents, encrypt=True) if contents else None
         self.a = action
         self.dest = dest

diff --git a/fpdf/enums.py b/fpdf/enums.py
@@ -1012,19 +1012,19 @@ class TextDirection(CoerciveEnum):
 class Duplex(CoerciveEnum):
     "The paper handling option that shall be used when printing the file from the print dialog."
 
-    Simplex = Name("Simplex")
+    SIMPLEX = Name("Simplex")
     "Print single-sided"
 
-    DuplexFlipShortEdge = Name("DuplexFlipShortEdge")
+    DUPLEX_FLIP_SHORT_EDGE = Name("DuplexFlipShortEdge")
     "Duplex and flip on the short edge of the sheet"
 
-    DuplexFlipLongEdge = Name("DuplexFlipLongEdge")
+    DUPLEX_FLIP_LONG_EDGE = Name("DuplexFlipLongEdge")
     "Duplex and flip on the long edge of the sheet"
 
 
 class PageBoundaries(CoerciveEnum):
-    ArtBox = Name("ArtBox")
-    BleedBox = Name("BleedBox")
-    CropBox = Name("CropBox")
-    MediaBox = Name("MediaBox")
-    TrimBox = Name("TrimBox")
+    ART_BOX = Name("ArtBox")
+    BLEED_BOX = Name("BleedBox")
+    CROP_BOX = Name("CropBox")
+    MEDIA_BOX = Name("MediaBox")
+    TRIM_BOX = Name("TrimBox")
diff --git a/fpdf/fpdf.py b/fpdf/fpdf.py
@@ -2175,7 +2175,7 @@ def set_link(self, link, y=0, x=0, page=-1, zoom="null"):
         link.zoom = zoom
 
     @check_page
-    def link(self, x, y, w, h, link, alt_text=None, border_width=0):
+    def link(self, x, y, w, h, link, alt_text=None, **kwargs):
         """
         Puts a link annotation on a rectangular area of the page.
         Text or image links are generally put via `FPDF.cell`,
@@ -2213,7 +2213,7 @@ def link(self, x, y, w, h, link, alt_text=None, border_width=0):
             height=h * self.k,
             action=action,
             dest=dest,
-            border_width=border_width,
+            **kwargs,
         )
         self.pages[self.page].annots.append(link_annot)
         if alt_text is not None:
@@ -2313,15 +2313,13 @@ def file_attachment_annotation(
             h * self.k,
             file_spec=embedded_file.file_spec(),
             name=FileAttachmentAnnotationName.coerce(name) if name else None,
-            flags=tuple(AnnotationFlag.coerce(flag) for flag in flags),
+            flags=flags,
         )
         self.pages[self.page].annots.append(annotation)
         return annotation
 
     @check_page
-    def text_annotation(
-        self, x, y, text, w=1, h=1, name=None, flags=DEFAULT_ANNOT_FLAGS, title=""
-    ):
+    def text_annotation(self, x, y, text, w=1, h=1, name=None, **kwargs):
         """
         Puts a text annotation on a rectangular area of the page.
 
@@ -2344,8 +2342,7 @@ def text_annotation(
             h * self.k,
             contents=text,
             name=AnnotationName.coerce(name) if name else None,
-            flags=tuple(AnnotationFlag.coerce(flag) for flag in flags),
-            title=title,
+            **kwargs,
         )
         self.pages[self.page].annots.append(annotation)
         return annotation
@@ -2358,7 +2355,7 @@ def free_text_annotation(
         y=None,
         w=None,
         h=None,
-        flags=DEFAULT_ANNOT_FLAGS,
+        **kwargs,
     ):
         """
         Puts a free text annotation on a rectangular area of the page.
@@ -2373,6 +2370,8 @@ def free_text_annotation(
             h (float): optional height of the link rectangle. Default value: None, meaning an height equal
                 to the current font size
             flags (Tuple[fpdf.enums.AnnotationFlag], Tuple[str]): optional list of flags defining annotation properties
+            color (tuple): a tuple of numbers in the range 0.0 to 1.0, representing a colour used for the annotation background
+            border_width (float): width of the annotation border
         """
         if not self.font_family:
             raise FPDFException("No font set, you need to call set_font() beforehand")
@@ -2392,15 +2391,15 @@ def free_text_annotation(
             w * self.k,
             h * self.k,
             contents=text,
-            flags=tuple(AnnotationFlag.coerce(flag) for flag in flags),
             default_appearance=f"({self.draw_color.serialize()} /F{self.current_font.i} {self.font_size_pt:.2f} Tf)",
+            **kwargs,
         )
         self.fonts_used_per_page_number[self.page].add(self.current_font.i)
         self.pages[self.page].annots.append(annotation)
         return annotation
 
     @check_page
-    def add_action(self, action, x, y, w, h):
+    def add_action(self, action, x, y, w, h, **kwargs):
         """
         Puts an Action annotation on a rectangular area of the page.
 
@@ -2418,13 +2417,14 @@ def add_action(self, action, x, y, w, h):
             w * self.k,
             h * self.k,
             action=action,
+            **kwargs,
         )
         self.pages[self.page].annots.append(annotation)
         return annotation
 
     @contextmanager
     def highlight(
-        self, text, title="", type="Highlight", color=(1, 1, 0), modification_time=None
+        self, text, type="Highlight", color=(1, 1, 0), modification_time=None, **kwargs
     ):
         """
         Context manager that adds a single highlight annotation based on the text lines inserted
@@ -2448,10 +2448,10 @@ def highlight(
                 type,
                 text,
                 quad_points=quad_points,
-                title=title,
-                color=color,
                 modification_time=modification_time,
                 page=page,
+                color=color,
+                **kwargs,
             )
         self._text_quad_points = defaultdict(list)
         self._record_text_quad_points = False
@@ -2472,10 +2472,10 @@ def add_text_markup_annotation(
         type,
         text,
         quad_points,
-        title="",
         color=(1, 1, 0),
         modification_time=None,
         page=None,
+        **kwargs,
     ):
         """
         Adds a text markup annotation on some quadrilateral areas of the page.
@@ -2511,24 +2511,24 @@ def add_text_markup_annotation(
             y=y_max,
             width=x_max - x_min,
             height=y_max - y_min,
-            color=color,
             modification_time=modification_time,
-            title=title,
             quad_points=quad_points,
+            color=color,
+            **kwargs,
         )
         self.pages[page].annots.append(annotation)
         return annotation
 
     @check_page
     def ink_annotation(
-        self, coords, contents="", title="", color=(1, 1, 0), border_width=1
+        self, coords, text="", color=(1, 1, 0), border_width=1, **kwargs
     ):
         """
         Adds add an ink annotation on the page.
 
         Args:
             coords (tuple): an iterable of coordinates (pairs of numbers) defining a path
-            contents (str): textual description
+            text (str): textual description
             title (str): the text label that shall be displayed in the title bar of the annotation’s
                 pop-up window when open and active. This entry shall identify the user who added the annotation.
             color (tuple): a tuple of numbers in the range 0.0 to 1.0, representing a colour used for
@@ -2547,10 +2547,10 @@ def ink_annotation(
             width=x_max - x_min,
             height=y_max - y_min,
             ink_list=ink_list,
-            color=color,
+            contents=text,
             border_width=border_width,
-            contents=contents,
-            title=title,
+            color=color,
+            **kwargs,
         )
         self.pages[self.page].annots.append(annotation)
         return annotation

diff --git a/test/encryption/encryption_aes256.pdf b/test/encryption/encryption_aes256.pdf
diff --git a/test/encryption/encryption_with_hyperlink.pdf b/test/encryption/encryption_with_hyperlink.pdf
diff --git a/test/encryption/test_encryption.py b/test/encryption/test_encryption.py
@@ -220,7 +220,7 @@ def fixed_iv(size):
     pdf.ink_annotation(
         [(40, 50), (70, 25), (100, 50), (70, 75), (40, 50)],
         title="Lucas",
-        contents="Some encrypted annotation",
+        text="Some encrypted annotation",
     )
     pdf.set_encryption(
         owner_password="fpdf2",

diff --git a/test/file_attachment_annotation.pdf b/test/file_attachment_annotation.pdf
diff --git a/test/free_text_annotation_all_parameters.pdf b/test/free_text_annotation_all_parameters.pdf
diff --git a/test/free_text_annotation_text_parameter.pdf b/test/free_text_annotation_text_parameter.pdf
diff --git a/test/free_text_annotation_width_parameter.pdf b/test/free_text_annotation_width_parameter.pdf
diff --git a/test/goto_action.pdf b/test/goto_action.pdf
diff --git a/test/goto_remote_action.pdf b/test/goto_remote_action.pdf
diff --git a/test/highlighted.pdf b/test/highlighted.pdf
diff --git a/test/highlighted_over_page_break.pdf b/test/highlighted_over_page_break.pdf
diff --git a/test/html/html_features.pdf b/test/html/html_features.pdf
diff --git a/test/html/html_link_style.pdf b/test/html/html_link_style.pdf
diff --git a/test/hyperlinks.pdf b/test/hyperlinks.pdf
diff --git a/test/ink_annotation.pdf b/test/ink_annotation.pdf
diff --git a/test/inserting_same_page_link_twice.pdf b/test/inserting_same_page_link_twice.pdf
diff --git a/test/internal_links.pdf b/test/internal_links.pdf
diff --git a/test/later_call_to_set_link.pdf b/test/later_call_to_set_link.pdf
diff --git a/test/launch_action.pdf b/test/launch_action.pdf
diff --git a/test/link_alt_text.pdf b/test/link_alt_text.pdf
diff --git a/test/link_border.pdf b/test/link_border.pdf
diff --git a/test/link_to_other_document.pdf b/test/link_to_other_document.pdf
diff --git a/test/link_with_zoom_and_shift.pdf b/test/link_with_zoom_and_shift.pdf
diff --git a/test/named_actions.pdf b/test/named_actions.pdf
diff --git a/test/outline/2_pages_outline.pdf b/test/outline/2_pages_outline.pdf
diff --git a/test/outline/html_toc.pdf b/test/outline/html_toc.pdf
diff --git a/test/outline/html_toc_2_pages.pdf b/test/outline/html_toc_2_pages.pdf
diff --git a/test/outline/html_toc_with_h1_as_2nd_heading.pdf b/test/outline/html_toc_with_h1_as_2nd_heading.pdf
diff --git a/test/outline/simple_outline.pdf b/test/outline/simple_outline.pdf
diff --git a/test/outline/toc_with_right_aligned_page_numbers.pdf b/test/outline/toc_with_right_aligned_page_numbers.pdf
diff --git a/test/signing/sign_pkcs12_with_link.pdf b/test/signing/sign_pkcs12_with_link.pdf
diff --git a/test/table/table_with_images_and_links.pdf b/test/table/table_with_images_and_links.pdf
diff --git a/test/table/table_with_links.pdf b/test/table/table_with_links.pdf
diff --git a/test/test_annotations.py b/test/test_annotations.py
@@ -150,7 +150,7 @@ def test_ink_annotation(tmp_path):
     pdf.ink_annotation(
         [(40, 50), (70, 25), (100, 50), (70, 75), (40, 50)],
         title="Lucas",
-        contents="Hello world!",
+        text="Hello world!",
     )
     assert_pdf_equal(pdf, HERE / "ink_annotation.pdf", tmp_path)
 

diff --git a/test/text/multi_cell_markdown_link.pdf b/test/text/multi_cell_markdown_link.pdf
diff --git a/test/text_annotation.pdf b/test/text_annotation.pdf