How to use Worksheet.ScrollArea in the xlwings API way

The ScrollArea property in the Worksheet object of the Excel object model defines the range of cells that users are allowed to scroll within a specific worksheet. When set, scrolling is restricted to this defined area, preventing users from accessing cells outside of it. This is particularly useful for protecting certain parts of a worksheet, such as headers, footers, or sensitive data, while allowing interaction within a designated data entry or view area. In xlwings, this property can be accessed and modified through the api property, which provides direct access to the underlying Excel object model.

The syntax for using the ScrollArea property in xlwings involves the api property of a Worksheet object. The property is a string that represents the range address in A1-style notation. To get the current scroll area, read the property; to set it, assign a string specifying the range. If the scroll area is cleared, set the property to an empty string. The parameter is a string that can be:

• A range address, such as “A1:D10”.
• An empty string (“”) to clear the restriction.
• None to check if no area is set.

For example, setting the scroll area to “B2:F20” limits scrolling to cells within that rectangle. It’s important to note that this property only affects scrolling via the user interface; programmatic access through xlwings or other methods remains unrestricted. Additionally, if the worksheet is protected, the scroll area might interact with other protection settings, so testing in the target environment is advisable.

Here are xlwings API code examples demonstrating the use of the ScrollArea property:

1. Setting a scroll area: Restrict scrolling to the range A1 to E15 in the active worksheet.

import xlwings as xw
wb = xw.Book.active
ws = wb.sheets.active
ws.api.ScrollArea = "A1:E15"

2. Getting the current scroll area: Retrieve and print the currently set scroll area.

import xlwings as xw
wb = xw.Book.active
ws = wb.sheets.active
scroll_area = ws.api.ScrollArea
print(f"Current scroll area: {scroll_area}")

3. Clearing the scroll area: Remove any scrolling restrictions by setting the property to an empty string.

import xlwings as xw
wb = xw.Book.active
ws = wb.sheets.active
ws.api.ScrollArea = ""

4. Checking if no scroll area is set: Determine whether scrolling is unrestricted by comparing the property to an empty string or using a conditional check.

import xlwings as xw
wb = xw.Book.active
ws = wb.sheets.active
if not ws.api.ScrollArea:
    print("No scroll area is set; scrolling is unrestricted.")
else:
    print(f"Scroll area is set to: {ws.api.ScrollArea}")