checkbox: initial checkbox support

Feature request #1092

Author: jmcnamara

Changes

@@ -1,3 +1,9 @@
+Release 3.2.2 - January XX 2025
+--------------------------------
+
+* Added support for checkboxes xxx
+
+
 Release 3.2.1 - January 22 2025
 --------------------------------
 

dev/docs/source/_images/checkbox.png

@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: BSD-2-Clause
+   Copyright (c) 2013-2025, John McNamara, jmcnamara@cpan.org
+
+.. _ex_checkbox:
+
+Example: Inserting a checkbox in a Worksheet
+============================================
+
+An example of adding checkbox boolean values to a worksheet.
+
+.. image:: _images/checkbox.png
+
+.. literalinclude:: ../../../examples/checkbox.py

dev/docs/source/_images/checkbox_boolean.png

@@ -38,6 +38,7 @@ directory of the XlsxWriter distribution.
    example_headers_footers.rst
    example_panes.rst
    example_tables.rst
+   example_checkbox.rst
    example_user_types1.rst
    example_user_types2.rst
    example_user_types3.rst

dev/docs/source/_images/excel_checkbox.png

@@ -278,6 +278,11 @@ properties that can be applied and the equivalent object method:
 +------------+------------------+----------------------+------------------------------+
 |            | Right color      | ``'right_color'``    | :func:`set_right_color()`    |
 +------------+------------------+----------------------+------------------------------+
+| Misc.      | Cell border      | ``'quote_prefix'``   | :func:`set_quote_prefix()`   |
++------------+------------------+----------------------+------------------------------+
+|            | Checkbox format  | ``'checkbox'``       | :func:`set_checkbox()`       |
++------------+------------------+----------------------+------------------------------+
+
 
 The format properties and methods are explained in the following sections.
 
@@ -1211,3 +1216,15 @@ Set the quote prefix property of a format to ensure a string is treated as a
 string after editing. This is the same as prefixing the string with a single
 quote in Excel. You don't need to add the quote to the string but you do need
 to add the format.
+
+
+format.set_checkbox()
+---------------------
+
+.. py:function:: set_checkbox()
+
+   Turn on the checkbox property for the format.
+
+This format property can be used with a cell that contains a boolean value to
+display it as a checkbox. This property isn't required very often and it is
+generally easier to create a checkbox using the :func:`insert_checkbox` method.

dev/docs/source/example_checkbox.rst

@@ -1724,6 +1724,61 @@ See :ref:`object_position` for more detailed information about the positioning
 and scaling of images within a worksheet.
 
 
+worksheet.insert_checkbox()
+---------------------------
+
+.. py:function:: insert_checkbox(row, col, boolean[, cell_format])
+
+   Insert a boolean checkbox in a worksheet cell.
+
+   :param row:         The cell row (zero indexed).
+   :param col:         The cell column (zero indexed).
+   :param boolean:     The boolean value to display as a checkbox.
+   :param cell_format: Optional Format object.
+   :type  row:         int
+   :type  col:         int
+   :type  boolean:     bool
+   :type  cell_format: :ref:`Format <format>`
+
+   :returns:  0: Success.
+   :returns: -1: Row or column is out of worksheet bounds.
+
+Checkboxes are a new feature added to `Excel in 2024`_. They are a way of
+displaying a boolean value as a checkbox in a cell. The underlying value is
+still an Excel ``TRUE/FALSE`` boolean value and can be used in formulas and in
+references.
+
+.. image:: _images/excel_checkbox.png
+
+.. _Excel in 2024: https://techcommunity.microsoft.com/blog/excelblog/introducing-checkboxes-in-excel/4173561
+
+The ``insert_checkbox()`` method can be used to replicate this behavior:
+
+.. literalinclude:: ../../../examples/checkbox.py
+   :lines: 18-36
+
+.. image:: _images/checkbox.png
+
+See :ref:`ex_checkbox` for the complete example.
+
+The checkbox feature is only available in Excel versions from 2024 and later. In
+older versions the value will be displayed as a standard Excel ``TRUE`` or
+``FALSE`` boolean. In fact Excel stores a checkbox as a normal boolean but with
+a special format. If required you can make use of this property to create a
+checkbox with :func:`write_boolean` and a cell format that has the
+:func:`set_checkbox` property set::
+
+    cell_format = workbook.add_format({"checkbox": True})
+
+    worksheet.write(2, 2, False, cell_format)
+    worksheet.write(3, 2, True, cell_format)
+
+.. image:: _images/checkbox_boolean.png
+
+This latter method isn't required very often but it can be occasionally useful
+if you are dealing with boolean values in a dataframe.
+
+
 worksheet.insert_button()
 -------------------------
 

dev/docs/source/examples.rst

@@ -0,0 +1,39 @@
+##############################################################################
+#
+# An example of adding checkbox boolean values to a worksheet using the the
+# XlsxWriter Python module.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+# Copyright (c) 2013-2025, John McNamara, jmcnamara@cpan.org
+#
+import xlsxwriter
+
+# Create a new Excel file object.
+workbook = xlsxwriter.Workbook("checkbox.xlsx")
+
+# Add a worksheet to the workbook.
+worksheet = workbook.add_worksheet()
+
+# Create some formats to use in the worksheet.
+bold = workbook.add_format({"bold": True})
+light_red = workbook.add_format({"bg_color": "#FFC7CE"})
+light_green = workbook.add_format({"bg_color": "#C6EFCE"})
+
+# Set the column width for clarity.
+worksheet.set_column(0, 0, 30)
+
+# Write some descriptions.
+worksheet.write(1, 0, "Some simple checkboxes:", bold)
+worksheet.write(4, 0, "Some checkboxes with cell formats:", bold)
+
+# Insert some boolean checkboxes to the worksheet.
+worksheet.insert_checkbox(1, 1, False)
+worksheet.insert_checkbox(2, 1, True)
+
+# Insert some checkboxes with cell formats.
+worksheet.insert_checkbox(4, 1, False, light_red)
+worksheet.insert_checkbox(5, 1, True, light_green)
+
+# Close the workbook.
+workbook.close()

dev/docs/source/format.rst

@@ -181,6 +181,15 @@ def _add_metadata(self):
             ("/xl/metadata.xml", APP_DOCUMENT + "spreadsheetml.sheetMetadata+xml")
         )
 
+    def _add_feature_bag_property(self):
+        # Add the featurePropertyBag file to the ContentTypes overrides.
+        self._add_override(
+            (
+                "/xl/featurePropertyBag/featurePropertyBag.xml",
+                "application/vnd.ms-excel.featurepropertybag+xml",
+            )
+        )
+
     def _add_rich_value(self):
         # Add the richValue files to the ContentTypes overrides.
         self._add_override(