A Tint is a special kind of swatch that both encapsulates a base Color and a percentage of that color (tint value.) Skilled InDesign users know that adding custom Tints to the Swatches panel is safer and more consistent than arbitrarily applying tint values to some existing color(s), because you can then control and adjust the percentage globally.

Since a Tint object is a swatch per se, it is visible in the Swatches panel. But it cannot be renamed. Its name attribute is read-only and always based on the color name followed by the current tint value, e.g. “MyColor 60%”.

Note. - About parsing and processing tints from an InDesign script, see also “Increasing/reducing tints by constant steps”, and “Anonymous vs. unused swatches”.

You have now two ways to lighten the background (fillColor) of an object. Either by playing wildly with the Tint slider (wich preserves the assigned swatch and changes the tint value locally), or by applying the official Tint you've just created. In the 2×2 table below, the box 1b represents the wild case and the box 2a represents the official case. (We will discuss case 2b a little further down…)

From “tinted” Color (1b) to actual Tint (2a)…

If you click the image you can see in more detail that the actual Tint (2a), named “MyColor 60%”, has its value reflected in the Tint field (60), which is not locked. However, this doesn't mean that pushing the Tint slider would upgrade our Tint object. Instead, the base Color would be reapplied to the selected cell, using that particular tint value, and the connection between the background and the existing Tint would be lost.

In other words, you cannot apply a tint to a Tint! And the scripting subsystem has to deal with this special issue. Indeed, background (resp. stroke) colors are managed through a couple of properties: fillColor, fillTint (resp. strokeColor, strokeTint), where the ...Color part refers in fact to a Swatch, while the ...Tint part always expects a number.

So, how are we supposed to change the background of some object into an existing Tint? For now it's not too complicated:

myObj.fillColor = myTint;
myObj.fillTint = -1; // not needed

Sending a Tint instance to .fillColor is ok because this property supports any swatch object ([None], Color, Tint, Gradient, and MixedInk.) Also, when a Tint is involved, the associated .fillTint number is conventionally set to -1, which indicates that the actual value is inherited and controlled by an external component.

A common mistake would be to rewrite the fillTint property as follows: myObj.fillTint=myTint.tintValue. This simply invalidates the previous assignment, myObj.fillColor returns to the base Color object (as shown in the wild case) and myTint is lost!

Hence an important rule: never reassign fillTint (resp. strokeTint) with a positive number when fillColor (resp. strokeColor) has been set to a Tint object.

Special Issue with Cells

Tint and Cell objects have trouble understanding each other, and the box 2b should have intrigued you from the beginning.

How is (2b) possible? The Tint value is 100 for “MyColor 60%”!

In the above screenshot, the cell 2a is in its regular state, a Tint is applied to the background (fillColor) and the fillTint property is -1 as expected. But the cell 2b, although strictly equivalent to its neighbor, has its fillTint property returning 100! How is this possible?

The code I used is surprisingly stupid:

// Self-assignment of the fillColor prop (hosting a Tint.)
// ---
myCell.fillColor = myCell.fillColor;
alert( myCell.fillTint ); // => 100 (!)

So the Cell object is very capricious regarding color assignments. As soon as myCell.fillColor points out to a Tint (with myCell.fillTint normally equal to -1), the simple fact of setting fillColor to its already possessed value will change fillTint to 100!

This may have terrible cascading effects. On the one hand, the value (100) is definitely wrong if you interpret it as a tintValue. Make sure your script treats Tint objects throughout a special routine when you are in parsing table colors. On the other hand, the quality of being a Tint rather than a Color becomes highly instable while Cell, Row, Column, and Table objects are dynamically changed. For example, if your script needs to clone or move cells within a table, you may have to store and reassign different attributes from one cell to another. If not carefully processed, the ...Color and ...Tint properties could introduce inexplicable biases.