How to use Worksheet.EnableSelection in the xlwings API way

The Worksheet.EnableSelection property in the xlwings API provides control over the types of selections a user can make within a worksheet via the user interface. This property is particularly useful when you want to protect a worksheet but still allow users to interact with specific cells, such as unlocked cells in a form or template. By setting EnableSelection, you can restrict users from selecting locked cells, unlocked cells, or any cells at all, even when sheet protection is enabled. This enhances data integrity and user experience in shared or sensitive workbooks by preventing accidental modifications to critical data.

In xlwings, you access this property through the api property of a Worksheet object, which exposes the underlying Excel object model. The syntax for using EnableSelection is:
worksheet.api.EnableSelection = value
Here, worksheet is an xlwings Worksheet object, and value is an integer that specifies the selection type. The possible values for value are defined in the Excel enumeration xlEnableSelection, which includes:

• xlNoSelection (value: -4142): Prevents any selection in the worksheet.
• xlNoRestrictions (value: 0): Allows selection of all cells (default behavior when protection is off).
• xlUnlockedCells (value: 1): Permits selection only of unlocked cells.

To use these values in xlwings, you can import the constants from the win32com.client module if you are on Windows, or use their numeric equivalents directly for cross-platform compatibility. For example, xlUnlockedCells corresponds to the integer 1. This property is often set in conjunction with the Protect method to customize protection settings.

Below are code examples demonstrating the usage of Worksheet.EnableSelection with xlwings. Ensure you have an active workbook and worksheet object before running these snippets.

Example 1: Allow selection only of unlocked cells after protecting the worksheet. This is common in forms where users should only edit specific input fields.

import xlwings as xw
# Open an existing workbook or create a new one
wb = xw.Book('example.xlsx')
ws = wb.sheets['Sheet1']
# First, unlock some cells that users are allowed to edit (e.g., range A1:B2)
ws.range('A1:B2').api.Locked = False
# Protect the worksheet with a password (optional) and set EnableSelection
ws.api.Protect(Password='yourpassword', DrawingObjects=True, Contents=True, Scenarios=True)
ws.api.EnableSelection = 1 # xlUnlockedCells
# Now, users can only select and edit the unlocked cells A1:B2

Example 2: Disable all selections in a protected worksheet to make it completely read-only, preventing users from even clicking on cells.

import xlwings as xw
wb = xw.Book('example.xlsx')
ws = wb.sheets['Sheet1']
# Protect the worksheet without allowing any selections
ws.api.Protect(Password='secure123')
ws.api.EnableSelection = -4142 # xlNoSelection
# Users cannot select any cells, ensuring no accidental interactions

Example 3: Remove restrictions and allow full selection, which might be useful when temporarily disabling protection for editing.

import xlwings as xw
wb = xw.Book('example.xlsx')
ws = wb.sheets['Sheet1']
# If the worksheet is protected, unprotect it first
if ws.api.ProtectContents:
    ws.api.Unprotect(Password='yourpassword')
    # Set EnableSelection to allow all selections
    ws.api.EnableSelection = 0 # xlNoRestrictions
    # Users can now select any cell freely