chart: add chart title formatting options

Add border, fill, gradient and pattern formatting options for
chart titles.

Request #957

Author: jmcnamara

dev/docs/source/chart.rst

@@ -720,9 +720,21 @@ The properties that can be set are:
   with a sheetname, row and column such as ``['Sheet1', 0, 0]``. The name
   property is optional. The default is to have no chart title.
 
-* ``name_font``: Set the font properties for the chart title. See
+* ``font``: Set the font properties for the chart title. See
   :ref:`chart_fonts`.
 
+* ``border``: Set the border properties of the legend such as color and
+  style. See :ref:`chart_formatting_border`.
+
+* ``fill``: Set the solid fill properties of the legend such as color. See
+  :ref:`chart_formatting_fill`.
+
+* ``pattern``: Set the pattern fill properties of the legend. See
+  :ref:`chart_formatting_pattern`.
+
+* ``gradient``: Set the gradient fill properties of the legend. See
+  :ref:`chart_formatting_gradient`.
+
 * ``overlay``: Allow the title to be overlaid on the chart. Generally used
   with the layout property below.
 

xlsxwriter/chart.py

@@ -338,9 +338,22 @@ def set_title(self, options: Optional[Dict[str, Any]] = None) -> None:
         self.title.data_id = data_id
 
         # Set the font properties if present.
-        self.title.font = self._convert_font_args(options.get("name_font"))
+        if options.get("font"):
+            self.title.font = self._convert_font_args(options.get("font"))
+        else:
+            # For backward/axis compatibility.
+            self.title.font = self._convert_font_args(options.get("name_font"))
+
+        # Set the line properties.
+        self.title.line = Shape._get_line_properties(options)
+
+        # Set the fill properties.
+        self.title.fill = Shape._get_fill_properties(options.get("fill"))
 
-        # Set the axis name layout.
+        # Set the gradient properties.
+        self.title.gradient = Shape._get_gradient_properties(options.get("gradient"))
+
+        # Set the layout.
         self.title.layout = self._get_layout_properties(options.get("layout"), True)
 
         # Set the title overlay option.
@@ -2901,10 +2914,11 @@ def _write_title(self, title: ChartTitle, is_horizontal: bool = False) -> None:
             self._write_title_rich(title, is_horizontal)
         elif title.has_formula():
             self._write_title_formula(title, is_horizontal)
+        elif title.has_formatting():
+            self._write_title_format_only(title)
 
     def _write_title_rich(self, title: ChartTitle, is_horizontal: bool = False) -> None:
         # Write the <c:title> element for a rich string.
-
         self._xml_start_tag("c:title")
 
         # Write the c:tx element.
@@ -2917,13 +2931,15 @@ def _write_title_rich(self, title: ChartTitle, is_horizontal: bool = False) -> N
         if title.overlay:
             self._write_overlay()
 
+        # Write the c:spPr element.
+        self._write_sp_pr(title.get_formatting())
+
         self._xml_end_tag("c:title")
 
     def _write_title_formula(
         self, title: ChartTitle, is_horizontal: bool = False
     ) -> None:
         # Write the <c:title> element for a rich string.
-
         self._xml_start_tag("c:title")
 
         # Write the c:tx element.
@@ -2936,11 +2952,30 @@ def _write_title_formula(
         if title.overlay:
             self._write_overlay()
 
+        # Write the c:spPr element.
+        self._write_sp_pr(title.get_formatting())
+
         # Write the c:txPr element.
         self._write_tx_pr(title.font, is_horizontal)
 
         self._xml_end_tag("c:title")
 
+    def _write_title_format_only(self, title: ChartTitle) -> None:
+        # Write the <c:title> element title with formatting and default name.
+        self._xml_start_tag("c:title")
+
+        # Write the c:layout element.
+        self._write_layout(title.layout, "text")
+
+        # Write the c:overlay element.
+        if title.overlay:
+            self._write_overlay()
+
+        # Write the c:spPr element.
+        self._write_sp_pr(title.get_formatting())
+
+        self._xml_end_tag("c:title")
+
     def _write_tx_rich(self, title, is_horizontal, font) -> None:
         # Write the <c:tx> element.
 
@@ -3195,34 +3230,33 @@ def _write_symbol(self, val) -> None:
 
         self._xml_empty_tag("c:symbol", attributes)
 
-    def _write_sp_pr(self, series) -> None:
+    def _write_sp_pr(self, chart_format: dict) -> None:
         # Write the <c:spPr> element.
-
-        if not self._has_formatting(series):
+        if not self._has_formatting(chart_format):
             return
 
         self._xml_start_tag("c:spPr")
 
         # Write the fill elements for solid charts such as pie and bar.
-        if series.get("fill") and series["fill"]["defined"]:
-            if "none" in series["fill"]:
+        if chart_format.get("fill") and chart_format["fill"]["defined"]:
+            if "none" in chart_format["fill"]:
                 # Write the a:noFill element.
                 self._write_a_no_fill()
             else:
                 # Write the a:solidFill element.
-                self._write_a_solid_fill(series["fill"])
+                self._write_a_solid_fill(chart_format["fill"])
 
-        if series.get("pattern"):
+        if chart_format.get("pattern"):
             # Write the a:gradFill element.
-            self._write_a_patt_fill(series["pattern"])
+            self._write_a_patt_fill(chart_format["pattern"])
 
-        if series.get("gradient"):
+        if chart_format.get("gradient"):
             # Write the a:gradFill element.
-            self._write_a_grad_fill(series["gradient"])
+            self._write_a_grad_fill(chart_format["gradient"])
 
         # Write the a:ln element.
-        if series.get("line") and series["line"]["defined"]:
-            self._write_a_ln(series["line"])
+        if chart_format.get("line") and chart_format["line"]["defined"]:
+            self._write_a_ln(chart_format["line"])
 
         self._xml_end_tag("c:spPr")
 

xlsxwriter/chart_title.py

@@ -29,6 +29,7 @@ def __init__(self) -> None:
         self.layout: Optional[Dict[str, Any]] = None
         self.overlay: Optional[bool] = None
         self.hidden: bool = False
+        self.line: Optional[Dict[str, Any]] = None
         self.fill: Optional[Dict[str, Any]] = None
         self.pattern: Optional[Dict[str, Any]] = None
         self.gradient: Optional[Dict[str, Any]] = None
@@ -56,14 +57,28 @@ def has_formatting(self) -> bool:
         Check if the title has any formatting properties set.
 
         Returns:
-            True if the title has font, fill, pattern, or gradient formatting.
+            True if the title has line, fill, pattern, or gradient formatting.
         """
-        has_font = self.font is not None
+        has_line = self.line is not None and self.line.get("defined", False)
         has_fill = self.fill is not None and self.fill.get("defined", False)
         has_pattern = self.pattern is not None
         has_gradient = self.gradient is not None
 
-        return has_font or has_fill or has_pattern or has_gradient
+        return has_line or has_fill or has_pattern or has_gradient
+
+    def get_formatting(self) -> Dict[str, Any]:
+        """
+        Get a dictionary containing the formatting properties.
+
+        Returns:
+            A dictionary with line, fill, pattern, and gradient properties.
+        """
+        return {
+            "line": self.line,
+            "fill": self.fill,
+            "pattern": self.pattern,
+            "gradient": self.gradient,
+        }
 
     def is_hidden(self) -> bool:
         """
@@ -82,9 +97,14 @@ def __repr__(self) -> str:
             f"ChartTitle(\n"
             f"    name = {self.name!r},\n"
             f"    formula = {self.formula!r},\n"
-            f"    hidden = {self.hidden!r})\n,"
+            f"    hidden = {self.hidden!r},\n"
             f"    font = {self.font!r},\n"
+            f"    line = {self.line!r},\n"
+            f"    fill = {self.fill!r},\n"
+            f"    pattern = {self.pattern!r},\n"
+            f"    gradient = {self.gradient!r},\n"
             f"    layout = {self.layout!r},\n"
             f"    overlay = {self.overlay!r},\n"
-            f")"
+            f"    has_formatting = {self.has_formatting()!r},\n"
+            f")\n"
         )

xlsxwriter/shape.py

@@ -378,13 +378,13 @@ def _get_font_latin_attributes(font):
         if not font:
             return attributes
 
-        if font["name"] is not None:
+        if font.get("name") is not None:
             attributes.append(("typeface", font["name"]))
 
-        if font["pitch_family"] is not None:
+        if font.get("pitch_family") is not None:
             attributes.append(("pitchFamily", font["pitch_family"]))
 
-        if font["charset"] is not None:
+        if font.get("charset") is not None:
             attributes.append(("charset", font["charset"]))
 
         return attributes

xlsxwriter/test/comparison/test_bootstrap62.py

@@ -0,0 +1,58 @@
+###############################################################################
+#
+# Tests for XlsxWriter.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+# Copyright (c), 2013-2025, John McNamara, jmcnamara@cpan.org
+#
+
+from ...workbook import Workbook
+from ..excel_comparison_test import ExcelComparisonTest
+
+
+class TestCompareXLSXFiles(ExcelComparisonTest):
+    """
+    Test file created by XlsxWriter against a file created by Excel.
+
+    """
+
+    def setUp(self):
+
+        self.set_filename("bootstrap62.xlsx")
+
+    def test_create_file(self):
+        """Test the creation of an XlsxWriter file with default title."""
+
+        workbook = Workbook(self.got_filename)
+
+        worksheet = workbook.add_worksheet()
+        chart = workbook.add_chart({"type": "column"})
+
+        chart.axis_ids = [67991424, 68001152]
+
+        data = [
+            [1, 2, 3, 4, 5],
+            [2, 4, 6, 8, 10],
+            [3, 6, 9, 12, 15],
+        ]
+        worksheet.write_column("A1", data[0])
+        worksheet.write_column("B1", data[1])
+        worksheet.write_column("C1", data[2])
+
+        chart.add_series({"values": "=Sheet1!$A$1:$A$5"})
+        chart.add_series({"values": "=Sheet1!$B$1:$B$5"})
+        chart.add_series({"values": "=Sheet1!$C$1:$C$5"})
+
+        chart.set_title(
+            {
+                "border": {"color": "yellow"},
+                "fill": {"color": "red"},
+            }
+        )
+
+        worksheet.insert_chart("E9", chart)
+
+        workbook.close()
+
+        self.assertExcelEqual()

xlsxwriter/test/comparison/test_bootstrap63.py

@@ -0,0 +1,59 @@
+###############################################################################
+#
+# Tests for XlsxWriter.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+# Copyright (c), 2013-2025, John McNamara, jmcnamara@cpan.org
+#
+
+from ...workbook import Workbook
+from ..excel_comparison_test import ExcelComparisonTest
+
+
+class TestCompareXLSXFiles(ExcelComparisonTest):
+    """
+    Test file created by XlsxWriter against a file created by Excel.
+
+    """
+
+    def setUp(self):
+
+        self.set_filename("bootstrap63.xlsx")
+
+    def test_create_file(self):
+        """Test the creation of an XlsxWriter file with default title."""
+
+        workbook = Workbook(self.got_filename)
+
+        worksheet = workbook.add_worksheet()
+        chart = workbook.add_chart({"type": "column"})
+
+        chart.axis_ids = [67991424, 68001152]
+
+        data = [
+            [1, 2, 3, 4, 5],
+            [2, 4, 6, 8, 10],
+            [3, 6, 9, 12, 15],
+        ]
+        worksheet.write_column("A1", data[0])
+        worksheet.write_column("B1", data[1])
+        worksheet.write_column("C1", data[2])
+
+        chart.add_series({"values": "=Sheet1!$A$1:$A$5"})
+        chart.add_series({"values": "=Sheet1!$B$1:$B$5"})
+        chart.add_series({"values": "=Sheet1!$C$1:$C$5"})
+
+        chart.set_title(
+            {
+                "name": "Title",
+                "border": {"color": "yellow"},
+                "fill": {"color": "red"},
+            }
+        )
+
+        worksheet.insert_chart("E9", chart)
+
+        workbook.close()
+
+        self.assertExcelEqual()