How to use Worksheet.ProtectDrawingObjects in the xlwings API way

The ProtectDrawingObjects property of a Worksheet object in Excel is a Boolean value that indicates whether the shapes (drawing objects) on the worksheet are protected. When a worksheet is protected using the Protect method, this property can be set to True to prevent users from modifying, moving, or deleting shapes such as charts, text boxes, and other drawing objects. It is particularly useful when you want to lock down the visual elements of a worksheet while still allowing data entry in cells, depending on the overall protection settings.

In xlwings, you can access this property through the api property of a Worksheet object, which provides direct access to the underlying Excel object model. The property is read/write, meaning you can both retrieve its current value and set it to a new value.

Syntax in xlwings:

worksheet.api.ProtectDrawingObjects

• worksheet: An xlwings Worksheet object representing the target worksheet.
• ProtectDrawingObjects: Returns or sets a Boolean value (True or False).
• True: Drawing objects are protected (locked) when the worksheet is protected.
• False: Drawing objects are not protected, even if the worksheet is protected.

Note that this property only takes effect when the worksheet is protected. If the worksheet is not protected, drawing objects remain editable regardless of this setting. To protect the worksheet, use the Protect method, such as worksheet.api.Protect().

Example Code:
Here is a practical example demonstrating how to use the ProtectDrawingObjects property with xlwings. This example assumes you have an Excel workbook open and a worksheet named “Sheet1”. It checks the current protection status for drawing objects, sets it to True, protects the worksheet, and then verifies the changes.

import xlwings as xw

# Connect to the active Excel application and workbook
app = xw.apps.active
wb = app.books.active
ws = wb.sheets['Sheet1']

# Check the current ProtectDrawingObjects setting
current_setting = ws.api.ProtectDrawingObjects
print(f"Current ProtectDrawingObjects setting: {current_setting}")

# Set ProtectDrawingObjects to True to protect shapes when the sheet is protected
ws.api.ProtectDrawingObjects = True

# Protect the worksheet to activate the drawing object protection
# You can specify a password and other options; here, we use default settings
ws.api.Protect(Password=None, DrawingObjects=True, Contents=True, Scenarios=True)
# Note: The 'DrawingObjects' parameter in the Protect method corresponds to ProtectDrawingObjects.

# Verify the protection status
if ws.api.ProtectDrawingObjects:
    print("Drawing objects are now protected on this worksheet.")
else:
    print("Drawing objects are not protected.")

# Optionally, unprotect the worksheet to make changes
ws.api.Unprotect()
ws.api.ProtectDrawingObjects = False
print("Worksheet unprotected and ProtectDrawingObjects set to False.")