Clarify FreeText annotation color options

Author: JorjMcKie

docs/annot.rst

@@ -170,8 +170,7 @@ There is a parent-child relationship between an annotation and its page. If the
 
       .. note::
 
-         * While 'FreeText', 'Line', 'PolyLine', and 'Polygon' annotations can have these properties, (Py-) MuPDF does not support line ends for 'FreeText', because the call-out variant of it is not supported.
-         * *(Changed in v1.16.16)* Some symbols have an interior area (diamonds, circles, squares, etc.). By default, these areas are filled with the fill color of the annotation. If this is *None*, then white is chosen. The *fill_color* argument of :meth:`Annot.update` can now be used to override this and give line end symbols their own fill color.
+         * Some symbols have an interior area (diamonds, circles, squares, etc.). These areas are filled with the fill color or the stroke color, depending on the annotation type.
 
       :arg int start: The symbol number for the first point.
       :arg int end: The symbol number for the last point.
@@ -305,15 +304,13 @@ There is a parent-child relationship between an annotation and its page. If the
 
    .. method:: set_colors(colors=None, stroke=None, fill=None)
 
-      * Changed in version 1.16.9: Allow colors to be directly set. These parameters are used if *colors* is not a dictionary.
-
-      Changes the "stroke" and "fill" colors for supported annotation types -- not all annotations accept both.
+      Changes the "stroke" and "fill" colors for supported annotation types -- not all annotation types accept both. **Do not use this method at all for FreeText annotations** because it has its special conventions to deal with up to three colors (border, fill, text).
 
       :arg dict colors: a dictionary containing color specifications. For accepted dictionary keys and values see below. The most practical way should be to first make a copy of the *colors* property and then modify this dictionary as required.
       :arg sequence stroke: see above.
       :arg sequence fill: see above.
 
-      *Changed in v1.18.5:* To completely remove a color specification, use an empty sequence like `[]`. If you specify `None`, an existing specification will not be changed.
+      To completely remove a color specification, use an empty sequence like `[]`. If you specify `None`, an existing specification will not be changed.
 
 
    .. method:: delete_responses()
@@ -349,20 +346,26 @@ There is a parent-child relationship between an annotation and its page. If the
       Color specifications may be made in the usual format used in PuMuPDF as sequences of floats ranging from 0.0 to 1.0 (including both). The sequence length must be 1, 3 or 4 (supporting GRAY, RGB and CMYK colorspaces respectively). For GRAY, just a float is also acceptable.
 
       :arg float opacity: *(new in v1.16.14)* **valid for all annotation types:** change or set the annotation's transparency. Valid values are *0 <= opacity < 1*.
+
       :arg str blend_mode: *(new in v1.16.14)* **valid for all annotation types:** change or set the annotation's blend mode. For valid values see :ref:`BlendModes`.
+
       :arg float fontsize: change :data:`fontsize` of the text. 'FreeText' annotations only.
-      :arg sequence,float text_color: change the text color. 'FreeText' annotations only.
-      :arg sequence,float border_color: change the border color. 'FreeText' annotations only.
-      :arg sequence,float fill_color: the fill color.
 
-          * 'Line', 'Polyline', 'Polygon' annotations: use it to give applicable line end symbols a fill color other than that of the annotation *(changed in v1.16.16)*.
+      :arg sequence,float text_color: change the text color. 'FreeText' annotations only. This has the same effect as ``border_color``. Note that the text color of rich-text annotations cannot be changed at all because it is set by HTML / CSS syntax and part of the text itself.
+
+      :arg sequence,float border_color: change the border color. 'FreeText' annotations only. This has the same effect as ``text_color``.
+
+      :arg sequence,float fill_color: the fill color.
 
       :arg bool cross_out: *(new in v1.17.2)* add two diagonal lines to the annotation rectangle. 'Redact' annotations only. If not desired, *False* must be specified even if the annotation was created with *False*.
+
       :arg int rotate: new rotation value. Default (-1) means no change. Supports 'FreeText' and several other annotation types (see :meth:`Annot.set_rotation`), [#f1]_. Only choose 0, 90, 180, or 270 degrees for 'FreeText'. Otherwise any integer is acceptable.
 
       :rtype: bool
 
-      .. note:: Using this method inside a :meth:`Page.annots` loop is **not recommended!** This is because most annotation updates require the owning page to be reloaded -- which cannot be done inside this loop. Please use the example coding pattern given in the documentation of this generator.
+      This method is the only way to change the colors of a FreeText annotation. You cannot use `:meth:Annot.set_colors` for this purpose. But be aware that for rich-text annotations, the text color is never changed. The text color is set by the *text_color* entry of the *info* dictionary. This is a limitation of MuPDF and not a bug.
+
+      .. caution:: Using this method inside a :meth:`Page.annots` loop is **not recommended!** This is because most annotation updates require the owning page to be reloaded -- which cannot be done inside this loop. Please use the example coding pattern given in the documentation of this generator.
 
 
    .. attribute:: file_info
@@ -500,7 +503,10 @@ There is a parent-child relationship between an annotation and its page. If the
 
    .. attribute:: colors
 
-      dictionary of two lists of floats in range *0 <= float <= 1* specifying the "stroke" and the interior ("fill") colors. The stroke color is used for borders and everything that is actively painted or written ("stroked"). The fill color is used for the interior of objects like line ends, circles and squares. The lengths of these lists implicitly determine the colorspaces used: 1 = GRAY, 3 = RGB, 4 = CMYK. So "[1.0, 0.0, 0.0]" stands for RGB color red. Both lists can be empty if no color is specified.
+      dictionary of two lists of floats in range *0 <= float <= 1* specifying the "stroke" and the interior ("fill") colors. The stroke color is used for borders and everything that is actively painted or written ("stroked"). The fill color is used for the interior of objects like line ends, circles and squares. The lengths of these lists implicitly determine the colorspaces used: 1 = GRAY, 3 = RGB, 4 = CMYK. So "[1.0, 0.0, 0.0]" stands for RGB color red. Both lists can be empty if no color is specified. Be aware about some potentially unexpected cases:
+
+      * The color of Highlight annotations is a **stroke** color, contrary to intuition.
+      * The color if FreeText annotations is a **stroke** color, but appears as the color that fills the rectangle and any applicable line end symbols. Text color and border color cannot be accessed at all.
 
       :rtype: dict
 

docs/page.rst

@@ -216,9 +216,9 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       :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 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 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. In any case, this value must be positive to see a border line.
 
       :arg list,tuple dashes: a list of floats specifying how border and callout lines should be dashed. Default is ``None``.
 
@@ -232,7 +232,7 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       :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 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 the PDF subset of HTML and styling instructions supports 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`.
 

src/__init__.py

@@ -1326,14 +1326,19 @@ def set_colors(self, colors=None, stroke=None, fill=None):
 
         Use either a dict or the direct arguments.
         """
+        if self.type[0] == mupdf.PDF_ANNOT_FREE_TEXT:
+            raise ValueError("cannot be used for FreeText annotations")
+
         CheckParent(self)
         doc = self.get_parent().parent
         if type(colors) is not dict:
             colors = {"fill": fill, "stroke": stroke}
         fill = colors.get("fill")
         stroke = colors.get("stroke")
+
         fill_annots = (mupdf.PDF_ANNOT_CIRCLE, mupdf.PDF_ANNOT_SQUARE, mupdf.PDF_ANNOT_LINE, mupdf.PDF_ANNOT_POLY_LINE, mupdf.PDF_ANNOT_POLYGON,
                        mupdf.PDF_ANNOT_REDACT,)
+
         if stroke in ([], ()):
             doc.xref_set_key(self.xref, "C", "[]")
         elif stroke is not None: