How to use Application.MeasurementUnit in the xlwings API way

The MeasurementUnit property of the Application object in Excel is a relatively niche but useful feature when dealing with international or regional document settings. This property allows you to retrieve or set the default measurement unit used in the Excel application for various interface elements, such as ruler units, column widths, row heights, and dialog box measurements. The primary utility lies in ensuring consistency when macros or automated processes depend on specific unit systems, especially when sharing workbooks across different regional versions of Excel. For instance, a macro designed assuming inches for column widths might behave unexpectedly if the application is set to centimeters. By programmatically controlling the MeasurementUnit property, you can standardize the environment, enhancing the reliability of your xlwings automation scripts.

Syntax and Parameters

In xlwings, you access this property through the Application object. The property is both readable and writable, accepting integer values that correspond to specific measurement units.

• xlwings API Call Format:

# To get the current measurement unit
current_unit = xw.apps.active.api.MeasurementUnit

# To set the measurement unit
xw.apps.active.api.MeasurementUnit = new_unit_value

Note: The .api attribute provides direct access to the underlying Excel VBA object model.

• Parameter Values:
  The new_unit_value is an integer from the XlMeasurementUnit enumeration. The common values are:

Constant Name (VBA)	Value	Description
xlInches	0	Measurement is in inches.
xlCentimeters	1	Measurement is in centimeters.
xlMillimeters	2	Measurement is in millimeters.

You can use either the integer values directly or, for better code readability, define the constants in your Python script (e.g., xlInches = 0).

Code Examples

Here are practical examples demonstrating how to use the MeasurementUnit property with xlwings.

1. Retrieving the Current Measurement Unit:
   This script checks the current setting and prints a descriptive message.

import xlwings as xw

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

# Get the current measurement unit
unit_constant = app.api.MeasurementUnit

# Interpret the value
unit_map = {0: "Inches", 1: "Centimeters", 2: "Millimeters"}
unit_name = unit_map.get(unit_constant, "Unknown Unit")

print(f"The current application measurement unit is: {unit_name} (Value: {unit_constant})")

2. Setting the Measurement Unit and Applying a Change:
   This example changes the global measurement unit to centimeters and then adjusts the width of the first column accordingly. This showcases how the property affects subsequent actions.

import xlwings as xw

# Define constants for clarity (these are not built into xlwings)
xlInches = 0
xlCentimeters = 1
xlMillimeters = 2

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

# Set the application's measurement unit to Centimeters
app.api.MeasurementUnit = xlCentimeters
print("Measurement unit set to Centimeters.")

# Now, set the width of column A to 5 centimeters.
# The .column_width property in xlwings uses the application's current MeasurementUnit.
ws.range('A:A').column_width = 5
print("Column A width set to 5 centimeters.")

# Optional: Switch back to Inches and read the column width
app.api.MeasurementUnit = xlInches
width_in_inches = ws.range('A:A').column_width
print(f"Column A width in inches is approximately: {width_in_inches:.2f}")