How to use Application.UserControl in the xlwings API way

The Application.UserControl property in Excel’s object model is a read-only Boolean value that indicates whether the Excel application was started by a user (True) or programmatically by another application (False). In xlwings, this property is accessed through the api property of the App object, which provides direct access to the underlying Excel object model. This can be useful for determining the context in which Excel is running, allowing for conditional logic in automation scripts—for example, to avoid closing an instance that a user is actively interacting with.

Functionality:
The primary function is to check the startup origin of the Excel instance. If UserControl returns True, Excel was launched directly by a user (e.g., via desktop shortcut or file double-click). If False, it was started programmatically, often through automation tools like xlwings, COM, or other scripting methods. This property helps in managing application lifecycle and user experience in automated processes.

Syntax:
In xlwings, you access this property via the api attribute of an App instance. The syntax is:

app.api.UserControl

• app: An instance of the xlwings App class representing the Excel application.
• The property returns a Boolean: True for user-controlled, False for programmatically controlled.
  No parameters are required, as it is a property, not a method.

Code Example:
Here is a practical example using xlwings to check the UserControl property and perform actions based on its value:

import xlwings as xw

# Connect to the active Excel instance or create a new one
app = xw.apps.active

# Check if Excel was started by the user
if app.api.UserControl:
    print("Excel was started by the user. Avoid automated shutdown.")
    # Perform user-friendly operations, like leaving Excel open
else:
    print("Excel was started programmatically. Safe to close after tasks.")
    # Perform automated tasks and close Excel
app.quit()

In this example, the script prints a message and decides whether to quit Excel based on the UserControl value. This prevents accidentally closing an Excel window that a user might be working in.

Another use case involves launching Excel conditionally:

import xlwings as xw

# Start a new instance of Excel programmatically
app = xw.App(visible=True)
print(f"UserControl status: {app.api.UserControl}") # Likely outputs False

# If you need to ensure user control for interaction, you might check and alert
if not app.api.UserControl:
    # Add a workbook for user input, but keep automation running
    wb = app.books.add()
    wb.sheets[0].range("A1").value = "Please enter data here."
    # Keep app open without quitting automatically