Skip to content

Commit 8c66333

Browse files
committed
checkbox: initial checkbox support
Feature request #1092
1 parent 3524002 commit 8c66333

28 files changed

+809
-11
lines changed

Changes

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
Release 3.2.2 - January XX 2025
2+
--------------------------------
3+
4+
* Added support for checkboxes xxx
5+
6+
17
Release 3.2.1 - January 22 2025
28
--------------------------------
39

dev/docs/source/_images/checkbox.png

82.6 KB
Loading
78 KB
Loading
84.6 KB
Loading

dev/docs/source/example_checkbox.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
.. SPDX-License-Identifier: BSD-2-Clause
2+
Copyright (c) 2013-2025, John McNamara, [email protected]
3+
4+
.. _ex_checkbox:
5+
6+
Example: Inserting a checkbox in a Worksheet
7+
============================================
8+
9+
An example of adding checkbox boolean values to a worksheet.
10+
11+
.. image:: _images/checkbox.png
12+
13+
.. literalinclude:: ../../../examples/checkbox.py

dev/docs/source/examples.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ directory of the XlsxWriter distribution.
3838
example_headers_footers.rst
3939
example_panes.rst
4040
example_tables.rst
41+
example_checkbox.rst
4142
example_user_types1.rst
4243
example_user_types2.rst
4344
example_user_types3.rst

dev/docs/source/format.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -278,6 +278,11 @@ properties that can be applied and the equivalent object method:
278278
+------------+------------------+----------------------+------------------------------+
279279
| | Right color | ``'right_color'`` | :func:`set_right_color()` |
280280
+------------+------------------+----------------------+------------------------------+
281+
| Misc. | Cell border | ``'quote_prefix'`` | :func:`set_quote_prefix()` |
282+
+------------+------------------+----------------------+------------------------------+
283+
| | Checkbox format | ``'checkbox'`` | :func:`set_checkbox()` |
284+
+------------+------------------+----------------------+------------------------------+
285+
281286

282287
The format properties and methods are explained in the following sections.
283288

@@ -1211,3 +1216,15 @@ Set the quote prefix property of a format to ensure a string is treated as a
12111216
string after editing. This is the same as prefixing the string with a single
12121217
quote in Excel. You don't need to add the quote to the string but you do need
12131218
to add the format.
1219+
1220+
1221+
format.set_checkbox()
1222+
---------------------
1223+
1224+
.. py:function:: set_checkbox()
1225+
1226+
Turn on the checkbox property for the format.
1227+
1228+
This format property can be used with a cell that contains a boolean value to
1229+
display it as a checkbox. This property isn't required very often and it is
1230+
generally easier to create a checkbox using the :func:`insert_checkbox` method.

dev/docs/source/worksheet.rst

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1724,6 +1724,61 @@ See :ref:`object_position` for more detailed information about the positioning
17241724
and scaling of images within a worksheet.
17251725

17261726

1727+
worksheet.insert_checkbox()
1728+
---------------------------
1729+
1730+
.. py:function:: insert_checkbox(row, col, boolean[, cell_format])
1731+
1732+
Insert a boolean checkbox in a worksheet cell.
1733+
1734+
:param row: The cell row (zero indexed).
1735+
:param col: The cell column (zero indexed).
1736+
:param boolean: The boolean value to display as a checkbox.
1737+
:param cell_format: Optional Format object.
1738+
:type row: int
1739+
:type col: int
1740+
:type boolean: bool
1741+
:type cell_format: :ref:`Format <format>`
1742+
1743+
:returns: 0: Success.
1744+
:returns: -1: Row or column is out of worksheet bounds.
1745+
1746+
Checkboxes are a new feature added to `Excel in 2024`_. They are a way of
1747+
displaying a boolean value as a checkbox in a cell. The underlying value is
1748+
still an Excel ``TRUE/FALSE`` boolean value and can be used in formulas and in
1749+
references.
1750+
1751+
.. image:: _images/excel_checkbox.png
1752+
1753+
.. _Excel in 2024: https://techcommunity.microsoft.com/blog/excelblog/introducing-checkboxes-in-excel/4173561
1754+
1755+
The ``insert_checkbox()`` method can be used to replicate this behavior:
1756+
1757+
.. literalinclude:: ../../../examples/checkbox.py
1758+
:lines: 18-36
1759+
1760+
.. image:: _images/checkbox.png
1761+
1762+
See :ref:`ex_checkbox` for the complete example.
1763+
1764+
The checkbox feature is only available in Excel versions from 2024 and later. In
1765+
older versions the value will be displayed as a standard Excel ``TRUE`` or
1766+
``FALSE`` boolean. In fact Excel stores a checkbox as a normal boolean but with
1767+
a special format. If required you can make use of this property to create a
1768+
checkbox with :func:`write_boolean` and a cell format that has the
1769+
:func:`set_checkbox` property set::
1770+
1771+
cell_format = workbook.add_format({"checkbox": True})
1772+
1773+
worksheet.write(2, 2, False, cell_format)
1774+
worksheet.write(3, 2, True, cell_format)
1775+
1776+
.. image:: _images/checkbox_boolean.png
1777+
1778+
This latter method isn't required very often but it can be occasionally useful
1779+
if you are dealing with boolean values in a dataframe.
1780+
1781+
17271782
worksheet.insert_button()
17281783
-------------------------
17291784

examples/checkbox.py

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
##############################################################################
2+
#
3+
# An example of adding checkbox boolean values to a worksheet using the the
4+
# XlsxWriter Python module.
5+
#
6+
# SPDX-License-Identifier: BSD-2-Clause
7+
#
8+
# Copyright (c) 2013-2025, John McNamara, [email protected]
9+
#
10+
import xlsxwriter
11+
12+
# Create a new Excel file object.
13+
workbook = xlsxwriter.Workbook("checkbox.xlsx")
14+
15+
# Add a worksheet to the workbook.
16+
worksheet = workbook.add_worksheet()
17+
18+
# Create some formats to use in the worksheet.
19+
bold = workbook.add_format({"bold": True})
20+
light_red = workbook.add_format({"bg_color": "#FFC7CE"})
21+
light_green = workbook.add_format({"bg_color": "#C6EFCE"})
22+
23+
# Set the column width for clarity.
24+
worksheet.set_column(0, 0, 30)
25+
26+
# Write some descriptions.
27+
worksheet.write(1, 0, "Some simple checkboxes:", bold)
28+
worksheet.write(4, 0, "Some checkboxes with cell formats:", bold)
29+
30+
# Insert some boolean checkboxes to the worksheet.
31+
worksheet.insert_checkbox(1, 1, False)
32+
worksheet.insert_checkbox(2, 1, True)
33+
34+
# Insert some checkboxes with cell formats.
35+
worksheet.insert_checkbox(4, 1, False, light_red)
36+
worksheet.insert_checkbox(5, 1, True, light_green)
37+
38+
# Close the workbook.
39+
workbook.close()

xlsxwriter/contenttypes.py

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,15 @@ def _add_metadata(self):
181181
("/xl/metadata.xml", APP_DOCUMENT + "spreadsheetml.sheetMetadata+xml")
182182
)
183183

184+
def _add_feature_bag_property(self):
185+
# Add the featurePropertyBag file to the ContentTypes overrides.
186+
self._add_override(
187+
(
188+
"/xl/featurePropertyBag/featurePropertyBag.xml",
189+
"application/vnd.ms-excel.featurepropertybag+xml",
190+
)
191+
)
192+
184193
def _add_rich_value(self):
185194
# Add the richValue files to the ContentTypes overrides.
186195
self._add_override(

0 commit comments

Comments
 (0)