How to use Application.CutCopyMode in the xlwings API way

The Application.CutCopyMode property in Excel VBA is a property of the Application object that returns or sets the status of the Cut or Copy mode. This property is useful for programmatically determining if a cut or copy operation is currently active, or to cancel such an operation. In xlwings, this property is accessed through the api property of the App object, which provides direct access to the underlying Excel object model. Understanding this property is essential for automating tasks that involve clipboard operations, ensuring that your macros run without interference from pending cut/copy actions.

Functionality:
The primary function of the CutCopyMode property is to manage the state of cut and copy operations within Excel. It can have three possible values:

• False (or 0): Indicates that no cut or copy operation is currently in progress.
• True (or 1): Indicates that a copy operation is active. The source range is highlighted with a moving border.
• xlCut (or 2): Indicates that a cut operation is active. The source range is also highlighted.

By reading this property, your script can check for an active operation before performing actions that might conflict, such as pasting or clearing the clipboard. Setting this property to False is the programmatic equivalent of pressing the ESC key, which cancels the moving border and clears the clipboard state.

Syntax in xlwings:
In xlwings, you interact with this property via the Excel Application object’s COM interface.

• To Get the current mode:
  current_mode = xw.apps[<app_index>].api.CutCopyMode
  This returns an integer corresponding to the current state.
• To Set the mode (typically to cancel):
  xw.apps[<app_index>].api.CutCopyMode = False

Parameter & Return Values:
The property is read/write. Its value can be set or returned as a Long integer or a Boolean. The standard values are:

Value	Constant (VBA)	Description
0	False	No cut or copy mode is active.
1	True	Copy mode is active.
2	xlCut	Cut mode is active.

When setting the property, only False (0) is typically used to cancel the mode. Attempting to set it to True or xlCut does not initiate a new cut/copy operation.

Code Examples:

1. Checking and Reporting the Current Mode:
   This example checks the status and prints a descriptive message.

import xlwings as xw

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

# Get the current CutCopyMode
mode = app.api.CutCopyMode

if mode == 0:
    print("No cut or copy operation is active.")
elif mode == 1:
    print("A copy operation is in progress.")
elif mode == 2:
    print("A cut operation is in progress.")
else:
    print(f"Unknown mode value: {mode}")

2. Cancelling an Active Cut/Copy Operation:
   This is a common practice to ensure a clean state before executing other operations.

import xlwings as xw

app = xw.apps.active

# Check if a cut/copy mode is active
if app.api.CutCopyMode:
    print("Cancelling the active cut/copy mode.")
    app.api.CutCopyMode = False # Equivalent to pressing ESC

# Now it's safe to proceed, e.g., with a paste operation
# app.api.Selection.PasteSpecial() # Example follow-up action

3. Integrating into a Larger Workflow:
   This example copies a range, performs a check, and then cancels the mode.

import xlwings as xw

app = xw.apps.active
wb = app.books.active
sheet = wb.sheets[0]

# Perform a copy operation (this activates Copy mode)
sheet.range("A1:B2").copy()

# Verify the mode was activated
if app.api.CutCopyMode == 1:
    print("Range copied successfully. Copy mode is active.")

# ... Perform other tasks ...

# Cancel the copy mode explicitly when done
app.api.CutCopyMode = False
print("Copy mode cleared.")