Controlling measurementUnits

From pixels to points to ciceros, InDesign allows users to pick from 15 different measurement units to use in various places of their documents. Thanks to this versatility, it can sometimes be hard to predict how a script will act in a measurement unit environment even slightly different from yours.

Where are these measurement units?

There are three major places where measurement units could vary depending on the user environment:

1. document.viewPreferences

Here you will find five important measurementUnit settings that may totally mess up your script if not accounted for.

The measurementUnit settings are:

  • horizontalMeasurementUnits
  • verticalMeasurementUnits
  • strokeMeasurementUnits
  • textSizeMeasurementUnits
  • typographicMeasurementUnits

Although some documentation lists all 15 MeasurementUnit enums as possible values for these properties, the truth is that the stroke, textSize, and typographic properties only accept values from a specific subset of these enums. They are:

Stroke measurement units

  • MeasurementUnits.POINTS
  • MeasurementUnits.MILLIMETERS
  • MeasurementUnits.PIXELS

Text size measurement units

  • MeasurementUnits.POINTS
  • MeasurementUnits.PIXELS
  • MeasurementUnits.Q
  • MeasurementUnits.AMERICAN_POINTS

Typographic measurement units

  • MeasurementUnits.POINTS
  • MeasurementUnits.PIXELS
  • MeasurementUnits.HA
  • MeasurementUnits.AMERICAN_POINTS
  • MeasurementUnits.U
  • MeasurementUnits.BAI
  • MeasurementUnits.MILS

2. application.viewPreferences

Same as document.viewPreferences, but like a default setting for new documents. The document.viewPreferences for each individual document will take precedence over these.

3. application.scriptPreferences.measurementUnit

This single property here affects some — but confusingly, not all — ways in which scripts handle units. In addition to all 15 MeasurementUnit enums, there is also a special context-dependent AutoEnum.AUTO_VALUE that uses whatever MeasurementUnit enum is assigned to a relevant property in the viewPreferences. AutoEnum.AUTO_VALUE is the default setting.

I consider this, the scriptPreferences.measurementUnit, to be the most dangerous measurementUnit pitfall. Why? Unlike the viewPreferences, there is no way a casual user of your script will be able to find or change this setting through the standard InDesign GUI. Thus, a reckless script that changes this setting and fails to revert it may alter the behavior of all other scripts in that user’s environment.

There are two things you should do to prevent this disaster. One is to be extremely serious about reverting any changes you make to this property. It’s a good idea to call the reverting routine in the finally of a try clause, so that an unexpected error will not abort the script without reverting.

The second is to script defensively, and make sure your script works regardless of the user’s scriptPreferences.measurementUnit. Do not assume it will always be set to AutoEnum.AUTO_VALUE. If the setting is going to affect any functionality in your script, alter it temporarily to something that is guaranteed to work as intended, and then revert to the original setting.

Test your script

Check to see how your script will work in random measurement unit environments.