How to use Application.RecordRelative in the xlwings API way

The Application.RecordRelative property in Excel’s object model is a Boolean property that indicates whether the next macro recording will use relative references. In simpler terms, when RecordRelative is set to True, any actions you record (like selecting cells) will be stored relative to the initially selected cell. When set to False (the default), recordings use absolute references, meaning actions are tied to specific cell addresses (e.g., Range("A1")). This property is primarily useful when you are programmatically controlling the macro recorder via VBA or, in the context of automation, when you need to check or set the recorder’s state. However, it’s important to note that xlwings, as a Python library, does not have a direct, dedicated wrapper for every single property like RecordRelative. Instead, you access it through the generic api property, which exposes the underlying COM object (Excel’s Application object).

Syntax and Parameters in xlwings:
The xlwings syntax to get or set this property is:

app.api.RecordRelative

This is a read/write property. It accepts and returns a Boolean value.

• Get: current_state = app.api.RecordRelative retrieves the current setting (True for relative, False for absolute).
• Set: app.api.RecordRelative = True sets the macro recorder to use relative references for the next recording.

Important Considerations:

1. The RecordRelative property only affects the next macro recording session started via the Excel UI (e.g., Developer Tab > Record Macro) or via Application.StartRecorder. It does not affect existing macros or code.
2. This is a very low-level, recorder-specific property. Most xlwings scripts perform actions directly without involving the macro recorder, so its utility in typical xlwings automation is limited. It might be used in scenarios where you are building a tool that needs to programmatically prepare Excel’s environment for user-driven macro recording.

Code Examples:

Example 1: Checking the Current RecordRelative Setting

import xlwings as xw

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

# Get the current RecordRelative state
recording_mode = app.api.RecordRelative
print(f"Next macro will record with relative references: {recording_mode}")
# Output might be: Next macro will record with relative references: False

Example 2: Setting RecordRelative to True

import xlwings as xw

app = xw.apps.active

# Set the recorder to use relative references for the next macro
app.api.RecordRelative = True
print("Macro recorder is now set to relative reference mode.")
# If a user now starts recording a macro via the Excel UI, their cell selections will be recorded relatively.

Example 3: Toggling the Setting Based on a Condition

import xlwings as xw

app = xw.apps.active

# Toggle the current state
current_state = app.api.RecordRelative
app.api.RecordRelative = not current_state
print(f"Toggled RecordRelative from {current_state} to {app.api.RecordRelative}")