How to use Worksheet.EnableOutlining in the xlwings API way

EnableOutlining Property in xlwings

In Excel’s object model, the EnableOutlining property of a Worksheet object controls whether outlining (grouping and ungrouping of rows or columns) is allowed on the worksheet. When set to True, users can manually create and manipulate outlines via the Excel interface, such as grouping rows to collapse detail data and show summary rows. When set to False, outlining is disabled, preventing users from creating new groups or modifying existing ones. This property is useful for protecting the structure of a worksheet when distributing workbooks, ensuring that predefined outline levels remain intact.

Syntax in xlwings

In xlwings, the EnableOutlining property is accessed through the api property of a Sheet object (which corresponds to a Worksheet in Excel’s object model). The property is a boolean value.

sheet.api.EnableOutlining = True # Enable outlining
sheet.api.EnableOutlining = False # Disable outlining

• sheet: An xlwings Sheet object representing the worksheet.
• .api: Provides direct access to the underlying Excel object model (via pywin32 on Windows or appscript on macOS).
• EnableOutlining: The property name as defined in the Excel object model. It can be set to True or False.

Parameters and Usage
The property does not take additional parameters. It simply gets or sets a boolean value. Note that enabling or disabling outlining does not affect existing outlines; it only controls whether new outlines can be created or existing ones modified by the user. In Excel, this setting is often used in combination with worksheet protection (Protect method) to lock the outline structure.

Code Examples

1. Enabling Outlining on a Worksheet
   This example opens an Excel workbook, enables outlining on the first sheet, and saves the file. Users will then be able to group rows or columns manually in Excel.

import xlwings as xw

# Open an existing workbook or create a new one
app = xw.App(visible=False)
workbook = app.books.open('example.xlsx')
sheet = workbook.sheets[0]

# Enable outlining
sheet.api.EnableOutlining = True

# Save and close
workbook.save()
workbook.close()
app.quit()

2. Disabling Outlining and Protecting the Worksheet
   Here, outlining is disabled, and the worksheet is protected to prevent any changes to the outline structure. This is common in finalized reports.

import xlwings as xw

app = xw.App(visible=False)
workbook = app.books.open('report.xlsx')
sheet = workbook.sheets['Summary']

# Disable outlining to lock grouping features
sheet.api.EnableOutlining = False

# Protect the worksheet (optional: add a password)
sheet.api.Protect(Password="your_password", AllowFormattingCells=True)

workbook.save('report_locked.xlsx')
workbook.close()
app.quit()

3. Checking the Current Outlining Status
   You can also retrieve the current value of EnableOutlining to conditionally modify the worksheet.

import xlwings as xw

app = xw.App(visible=False)
workbook = app.books.open('data.xlsx')
sheet = workbook.sheets[0]

# Get the current outlining status
is_outlining_enabled = sheet.api.EnableOutlining
print(f"Outlining is enabled: {is_outlining_enabled}")

# If disabled, enable it
if not is_outlining_enabled:
    sheet.api.EnableOutlining = True
    workbook.save()

workbook.close()
app.quit()