How to use Application.RollZoom in the xlwings API way

The Application.RollZoom property in Excel is a read-write Boolean property that controls whether scrolling with the IntelliMouse (or similar wheel mouse) zooms the worksheet instead of scrolling through it. When set to True, rolling the mouse wheel changes the zoom level of the active window. When set to False (the default), rolling the mouse wheel scrolls the worksheet up or down. This property is part of the Excel Application object, which represents the entire Excel application. In xlwings, you can access and manipulate this property through the app object, which corresponds to the Excel Application.

Functionality:
The primary function of RollZoom is to toggle the mouse wheel behavior between zooming and scrolling. This can enhance user experience when navigating large or detailed worksheets, as zooming can provide a better view of data without changing the visible range through scrolling.

Syntax in xlwings:
In xlwings, you access the Application object via the app property of a Book or directly through xw.apps. The RollZoom property is exposed as an attribute. The syntax is straightforward:

import xlwings as xw

# Get the current Excel application instance
app = xw.apps.active # or xw.App() for a new instance

# Get the current RollZoom setting
current_setting = app.api.RollZoom

# Set the RollZoom property
app.api.RollZoom = True # Enable zoom with mouse wheel
app.api.RollZoom = False # Enable scrolling with mouse wheel (default)

Note: app.api provides direct access to the underlying Excel object model. The RollZoom property is a Boolean, so it accepts True or False values.

Parameters:
This property does not have parameters in the traditional sense; it is a simple Boolean property. However, it affects the entire Excel application session, meaning the setting applies to all open workbooks and windows until changed. There is no direct method to specify a particular window or sheet; the property is global for the application instance.

Code Examples:

1. Check and Toggle RollZoom Setting:
   This example checks the current RollZoom setting and toggles it, then prints a message to confirm the change.

import xlwings as xw

# Connect to the active Excel application
app = xw.apps.active

# Check current setting
if app.api.RollZoom:
    print("RollZoom is currently enabled (mouse wheel zooms).")
else:
    print("RollZoom is currently disabled (mouse wheel scrolls).")

# Toggle the setting
app.api.RollZoom = not app.api.RollZoom

# Verify the change
new_setting = "enabled" if app.api.RollZoom else "disabled"
print(f"RollZoom is now {new_setting}.")

2. Temporarily Enable Zoom for Data Review:
   In this example, RollZoom is temporarily set to True to allow zooming during a data review process, then restored to its original state afterward.

import xlwings as xw

app = xw.apps.active
original_setting = app.api.RollZoom # Save the original setting

try:
    # Enable zoom for detailed data inspection
    app.api.RollZoom = True
    print("Zoom with mouse wheel is now active. Review your data.")

    # Simulate a pause or user interaction (e.g., input prompt)
    input("Press Enter after reviewing data to revert to original setting...")

finally:
    # Restore the original setting
    app.api.RollZoom = original_setting
    status = "enabled" if original_setting else "disabled"
    print(f"RollZoom has been restored to {status}.")

3. Integrate with Workbook Operations:
   This example demonstrates setting RollZoom when opening a new workbook for a specific task, such as creating a chart, where zooming might be beneficial.

import xlwings as xw

# Start a new Excel instance (or use an existing one)
app = xw.App(visible=True)
app.api.RollZoom = True # Enable zoom for this session

# Add a new workbook and perform operations
wb = app.books.add()
sheet = wb.sheets[0]
sheet.range("A1").value = [[1, 2], [3, 4]] # Sample data

# Create a chart (zooming can help view chart details)
chart = sheet.charts.add()
chart.set_source_data(sheet.range("A1").expand())

print("Workbook created with RollZoom enabled. Use mouse wheel to zoom.")

# Keep the workbook open for user interaction
input("Press Enter to close and exit...")
wb.close()
app.quit()