Address 4254

For bug #4254, Ensure that multiple FreeText annotations are displayed as expected.

We also add the following new features:
1. Support for subtype FreeTextCallout
2. Support for rich text.

Author: JorjMcKie

docs/images/img-freetext.jpg docs/images/img-freetext1.jpgdocs/images/img-freetext.jpg renamed to docs/images/img-freetext1.jpg

@@ -180,44 +180,63 @@ In a nutshell, this is what you can do with PyMuPDF:
       :returns: the created annotation. Stroke color yellow = (1, 1, 0), no fill color support.
 
    .. index::
-      pair: color; add_freetext_annot
-      pair: fontname; add_freetext_annot
-      pair: fontsize; add_freetext_annot
       pair: rect; add_freetext_annot
-      pair: rotate; add_freetext_annot
-      pair: align; add_freetext_annot
+      pair: fontsize; add_freetext_annot
+      pair: fontname; add_freetext_annot
       pair: text_color; add_freetext_annot
-      pair: border_color; add_freetext_annot
       pair: fill_color; add_freetext_annot
+      pair: border_width; add_freetext_annot
+      pair: dashes; add_freetext_annot
+      pair: callout; add_freetext_annot
+      pair: line_end; add_freetext_annot
+      pair: opacity; add_freetext_annot
+      pair: align; add_freetext_annot
+      pair: rotate; add_freetext_annot
+      pair: richtext; add_freetext_annot
+      pair: style; add_freetext_annot
+
+   .. method:: add_freetext_annot(rect, text, *, fontsize=11, fontname="helv", text_color=0, fill_color=None, border_width=0, dashes=None, callout=None, line_end=PDF_ANNOT_LE_OPEN_ARROW, opacity=1, align=TEXT_ALIGN_LEFT, rotate=0, richtext=False, style=None)
 
-   .. method:: add_freetext_annot(rect, text, fontsize=12, fontname="helv", border_color=None, text_color=0, fill_color=1, rotate=0, align=TEXT_ALIGN_LEFT)
+      PDF only: Add text in a given rectangle. Optionally, the appearance of a "callout" shape can be requested by specifying two or three point-like objects -- see below.
 
-      PDF only: Add text in a given rectangle.
+      :arg rect_like rect: the rectangle into which the text should be inserted. Text is automatically wrapped to a new line at box width. Text portions not fitting into the rectangle will be invisible without warning.
 
-      :arg rect_like rect: the rectangle into which the text should be inserted. Text is automatically wrapped to a new line at box width. Lines not fitting into the box will be invisible.
+      :arg str text: the text. May contain any mixture of Latin, Greek, Cyrillic, Chinese, Japanese and Korean characters. If `richtext=True` (see below), the string is interpreted as HTML syntax. This adds a plethora of ways for attractive effects.
 
-      :arg str text: the text. May contain any mixture of Latin, Greek, Cyrillic, Chinese, Japanese and Korean characters. The respective required font is automatically determined. (New in v1.17.0)
-      :arg float fontsize: the :data:`fontsize`. Default is 12.
-      :arg str fontname: the font name. Default is "Helv".
-        Accepted alternatives are "Cour", "TiRo", "ZaDb" and "Symb".
-        The name may be abbreviated to the first two characters, like "Co" for "Cour".
-        Lower case is also accepted.
-        Bold or italic variants of the fonts are **not accepted** (changed in v1.16.0).
-        A user-contributed script provides a circumvention for this restriction -- see section *Using Buttons and JavaScript* in chapter :ref:`FAQ`.
-        The actual font to use is now determined on a by-character level, and all required fonts (or sub-fonts) are automatically included.
-        Therefore, you should rarely ever need to care about this parameter and let it default (except you insist on a serifed font for your non-CJK text parts). (New in v1.17.0)
+      :arg float fontsize: the :data:`fontsize`. Default is 11. Ignored if `richtext=True`.
+
+      :arg str fontname: The font name. Default is "Helv". Ignored if `richtext=True`, otherwise the following **restritions apply:**
 
-      :arg sequence,float text_color: the text color. Default is black. (New in v1.16.0)
+        * Accepted alternatives are "Helv" (Helvetica), "Cour" (Courier), "TiRo" (Timnes-Roman), "ZaDb" (ZapfDingBats) and "Symb" (Symbol). The name may be abbreviated to the first two characters, like "Co" for "Cour", lower case accepted.
 
-      :arg sequence,float fill_color: the fill color. Default is white. (New in v1.16.0)
-      :arg sequence,float text_color: the text color. Default is black.
-      :arg sequence,float border_color: the border color. Default is `None`. (New in v1.19.6)
-      :arg int align: text alignment, one of TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT - justify is **not supported**. (New in v1.17.0)
+        * Bold or italic variants of the fonts are **not supported.**
+        
+      :arg list,tuple,float text_color: the text color. Default is black. Ignored if `richtext=True`.
 
-      :arg int rotate: the text orientation. Accepted values are 0, 90, 270, invalid entries are set to zero.
+      :arg list,tuple,float fill_color: the fill color. This is used for ``rect`` and the end point of the callout lines when applicable. Default is ``None``.
+
+      :arg list,tuple,float border_color:  This parameter only has an effect if `richtext=True`. Otherwise, ``text_color`` is used.
+      
+      :arg float border_width: the width of border and ``callout`` lines. Default is 0 (no border), in which case callout lines may still appear with some hairline width, depending on the PDF viewer used.
+      
+      :arg list,tuple dashes: a list of floats specifying how border and callout lines should be dashed. Default is ``None``.
+      
+      :arg list,tuple callout: a list / tuple of two or three :data:`point_like` objects, which will be interpreted as end point [, knee point] and start point (in this sequence) of up to two line segments, converting this annotation into a call-out shape.
+      
+      :arg int line_end: the line end symbol of the call-out line. It is drawn at the first point specified in the `callout` list. Default is an open arrow. For possible values see :ref:`AnnotationLineEnds`.
+      
+      :arg float opacity: a float `0 <= opacity < 1` turning the annotation transparent. Default is no transparency.
+      
+      :arg int align: text alignment, one of TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT - justify is **not supported**. Ignored if `richtext=True`.
+      
+      :arg int rotate: the text orientation. Accepted values are integer multiples of 90°. Invalid entries receive a rotation of 0.
+      
+      :arg bool richtext: treat ``text`` as HTML syntax. This allows to achieve **bold**, *italic*, arbitrary text colors, font sizes, text alignment including justify and more - as far as HTML and styling instructions support this. This is similar to what happens in :meth:`Page.insert_htmlbox`. The base library will for example pull in required fonts if it encounters characters not contained in the standard ones. Some parameters are ignored if this option is set, as mentioned above. Default is ``False``.
+      
+      :arg str style: supply optional HTML styling information in CSS syntax. Ignored if `richtext=False`.
 
       :rtype: :ref:`Annot`
-      :returns: the created annotation. Color properties **can only be changed** using special parameters of :meth:`Annot.update`. There, you can also set a border color different from the text color.
+      :returns: the created annotation.
 
       |history_begin|
 

docs/images/img-freetext2.jpg

@@ -34,16 +34,25 @@ This script should lead to the following output:
 
 How to Use FreeText
 ~~~~~~~~~~~~~~~~~~~~~
-This script shows a couple of ways to deal with 'FreeText' annotations:
+This script shows a couple of basic ways to deal with 'FreeText' annotations:
 
-.. literalinclude:: samples/annotations-freetext.py
+.. literalinclude:: samples/annotations-freetext1.py
 
+The result looks like this:
+
+.. image:: images/img-freetext1.*
+   :scale: 80
+
+Here is an example for using rich text and call-out lines:
+
+.. literalinclude:: samples/annotations-freetext2.py
 
 The result looks like this:
 
-.. image:: images/img-freetext.*
+.. image:: images/img-freetext2.*
    :scale: 80
 
+
 ------------------------------
 
 

docs/page.rst

@@ -2,19 +2,19 @@
 import pymupdf
 
 # some colors
-blue  = (0,0,1)
-green = (0,1,0)
-red   = (1,0,0)
-gold  = (1,1,0)
+blue = (0, 0, 1)
+green = (0, 1, 0)
+red = (1, 0, 0)
+gold = (1, 1, 0)
 
 # a new PDF with 1 page
 doc = pymupdf.open()
 page = doc.new_page()
 
 # 3 rectangles, same size, above each other
-r1 = pymupdf.Rect(100,100,200,150)
-r2 = r1 + (0,75,0,75)
-r3 = r2 + (0,75,0,75)
+r1 = pymupdf.Rect(100, 100, 200, 150)
+r2 = r1 + (0, 75, 0, 75)
+r3 = r2 + (0, 75, 0, 75)
 
 # the text, Latin alphabet
 t = "¡Un pequeño texto para practicar!"

docs/recipes-annotations.rst

@@ -0,0 +1,50 @@
+import pymupdf
+
+"""Use rich text for FreeText annotations"""
+
+# define an overall styling
+ds = """font-size: 11pt; font-family: sans-serif;"""
+
+# some special characters
+bullet = chr(0x2610) + chr(0x2611) + chr(0x2612)
+
+# the annotation text with HTML and styling syntax
+text = f"""<p style="text-align:justify;margin-top:-25px;">
+PyMuPDF <span style="color: red;">འདི་ ཡིག་ཆ་བཀྲམ་སྤེལ་གྱི་དོན་ལུ་ པའི་ཐོན་ཐུམ་སྒྲིལ་དྲག་ཤོས་དང་མགྱོགས་ཤོས་ཅིག་ཨིན།</span>
+<span style="color:blue;">Here is some <b>bold</b> and <i>italic</i> text, followed by <b><i>bold-italic</i></b>. Text-based check boxes: {bullet}.</span>
+ </p>"""
+
+# here are some colors
+gold = (1, 1, 0)
+green = (0, 1, 0)
+
+# new/empty PDF
+doc = pymupdf.open()
+
+# make a page in ISO-A4 format
+page = doc.new_page()
+
+# text goes into this:
+rect = pymupdf.Rect(100, 100, 350, 200)
+
+# define some points for callout lines
+p2 = rect.tr + (50, 30)
+p3 = p2 + (0, 30)
+
+# define the annotation
+annot = page.add_freetext_annot(
+    rect,
+    text,
+    fill_color=gold,  # fill color
+    opacity=1,  # non-transparent
+    rotate=0,  # no rotation
+    border_width=1,  # border and callout line width
+    dashes=None,  # no dashing
+    richtext=True,  # this is rich text
+    style=ds,  # my styling default
+    callout=(p3, p2, rect.tr),  # define end, knee, start points
+    line_end=pymupdf.PDF_ANNOT_LE_OPEN_ARROW,  # symbol shown at p3
+    border_color=green,
+)
+
+doc.save(__file__.replace(".py", ".pdf"), pretty=True)