How to use Application.HighQualityModeForGraphics in the xlwings API way

The Application.HighQualityModeForGraphics property in Excel, when accessed through the xlwings library, provides control over a performance optimization setting specifically for graphics rendering. This feature is particularly relevant when dealing with workbooks that contain a large number of charts, shapes, or other graphic elements. Enabling high-quality mode can improve the visual fidelity of graphics during screen updates and printing, but it may come at the cost of increased memory usage and potentially slower performance, especially on complex documents. The property allows developers to programmatically balance visual quality against application responsiveness based on the specific needs of their automation script or add-in.

Syntax and Parameters

In xlwings, you interact with this property through the Application object. The property is a read/write Boolean.

# Getting the current setting
current_setting = xw.apps[0].api.HighQualityModeForGraphics

# Setting a new value
xw.apps[0].api.HighQualityModeForGraphics = True # or False

• Member Access: The property is accessed via the .api attribute of the xw.apps object. This .api gateway provides direct access to the underlying Excel object model, allowing you to use the native property names as defined in the VBA documentation.
• Property Type: Boolean (bool).
• Values:
• True: Enables high-quality mode for graphics. Excel uses more memory to cache graphic elements, aiming for better rendering quality.
• False (Default): Disables high-quality mode, favoring performance and lower memory consumption. Graphics might be rendered with lower detail during rapid screen changes.

Code Examples

Here are practical examples demonstrating how to use this property with xlwings:

1. Checking the Current Status:
   This is useful for diagnostics or for conditionally adjusting other settings.

import xlwings as xw

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

# Get the current HighQualityModeForGraphics setting
hq_setting = app.api.HighQualityModeForGraphics
print(f"High Quality Mode for Graphics is currently: {hq_setting}")

2. Enabling High-Quality Mode for a Printing Routine:
   Temporarily enable high-quality graphics before a print job to ensure the best output, then restore the original setting.

import xlwings as xw

app = xw.apps.active
wb = app.books.active

# Store the original setting
original_setting = app.api.HighQualityModeForGraphics

try:
    # Enable high-quality mode for printing
    app.api.HighQualityModeForGraphics = True
    print("High-quality mode enabled for printing.")

    # Perform the print action (e.g., print the active sheet)
    wb.api.ActiveSheet.PrintOut()

finally:
    # Restore the original setting reliably, even if an error occurs during printing
    app.api.HighQualityModeForGraphics = original_setting
    print(f"High-quality mode restored to: {original_setting}")

3. Optimizing Performance for a Data Processing Macro:
   If your script is primarily manipulating data and doesn’t require perfect graphic rendering during the process, disabling this mode can improve speed.

import xlwings as xw

app = xw.apps.active
original_setting = app.api.HighQualityModeForGraphics

# Disable high-quality mode for faster processing
app.api.HighQualityModeForGraphics = False

# ... Perform intensive data operations, chart updates, or shape manipulations ...

# Restore the setting after operations are complete
app.api.HighQualityModeForGraphics = original_setting