How to use Application.SmartArtColors in the xlwings API way

The SmartArtColors member of the Application object in Excel provides programmatic access to the collection of color styles available for SmartArt graphics. This collection is essentially the set of color themes you see in the “Change Colors” gallery when working with a SmartArt graphic in the Excel interface. Through xlwings, you can retrieve this collection to apply predefined, coordinated color schemes to SmartArt objects, enhancing visual consistency and appeal without manually setting individual colors. This is particularly useful for automating report generation or ensuring corporate branding across multiple charts.

Syntax and Parameters

In xlwings, you access this property via the Application object. The property returns a SmartArtColors object, which is a collection of SmartArtColor objects. Each SmartArtColor object represents a specific color style (e.g., “Colorful – Accent Colors”, “Gradient Loop – Accent 1”).

The basic xlwings API call format is:

app.smart_art_colors

• Return Value: An xlwings object representing the SmartArtColors collection. There are no parameters for this property call.

To work with individual color styles, you typically iterate through the collection or access items by their index (which corresponds to the order in the Excel gallery, usually starting at 1). A common subsequent step is to apply a color style to a specific SmartArt graphic by setting the SmartArt graphic’s ColorStyle property to the desired SmartArtColor object.

Code Example

The following xlwings code demonstrates how to list available SmartArt color styles and apply one to an existing SmartArt graphic on the active worksheet.

import xlwings as xw

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

# Access the SmartArtColors collection
color_collection = app.smart_art_colors

# Example 1: List the names of available color styles
print("Available SmartArt Color Styles:")
# The collection is 1-indexed. We use .count to get the number of items.
for i in range(1, color_collection.count + 1):
    color_style = color_collection(i) # Access by index
    print(f" {i}: {color_style.name}")

# Example 2: Apply a specific color style to a SmartArt graphic
# Assuming the first shape on the active sheet is a SmartArt graphic
wb = app.books.active
sheet = wb.sheets.active

# Target the first shape
target_shape = sheet.shapes[0]

# Check if the shape is a SmartArt graphic (requires platform-specific API caution)
# In practice, you might ensure this shape is SmartArt via its properties.
# Apply the third color style in the collection (e.g., "Gradient Range - Accent 1")
# First, get the desired SmartArtColor object
desired_color_style = color_collection(3)

# Apply it by setting the SmartArt graphic's ColorStyle property.
# Note: Direct property access might require using the .api property for full OM features.
target_shape.api.ColorStyle = desired_color_style

print(f"Applied '{desired_color_style.name}' to the SmartArt graphic.")