Using colors in Acrobat JavaScript

By Thom Parker – November 5, 2006

Scope: All Acrobat versions 
Skill Level: Beginner
Prerequisites: Familiarity with Acrobat

In Acrobat JavaScript, color is primarily used for setting annotation and form field visual properties, such as the border, fill, and text. Color is a slightly complex topic and many methods have been developed for specifying color. In fact, inside the PDF, color specifications can be very complex. But JavaScript, of course, needs to be as simple as possible, so the Acrobat JavaScript model uses a compromise solution. Colors are stored as an array of simple values. The array provides some flexibility, but does not go overboard. 

The color array

The elements of the color array are the color space name followed by a numerical value for each color channel in the color space. The color spaces are RGB (3 channels- Red, Green, and Blue), CMYK (4 channels- Cyan, Magenta, Yellow, and Black), gray scale (1 channel), and transparent (no channels). The following code specifies colors in each of the different color spaces.  

var colDkYellow = ["RGB", 0.7 , 0.7, 0 ];  // Dark Yellow
var colLtYellow = ["CMYK", 0 , 0, 0.7, 0 ];  // Light Yellow
var colDkGray = ["G", 0.7]; // Dark Gray
var colClear = ["T"];  // Transparent

JavaScript must be cross-platform and able to deal with a variety of display hardware. So to make the color specification as generic as possible, values are specified as a floating-point number between 0 and 1, where a 0 value means no color on that channel, and 1 means full color. 

Converting from other color specifications

Color specifications in most other environments, such as HTML, use an integer value between 0 and 255 for the color channel value. This range allows the color value to be easily specified in hexadecimal, where each channel has a color resolution of 8 bits (1 byte). Use the following code if you need to convert an 8 bit color depth to a JavaScript color.

var jsColorChannel = eightBitColorChannel / 255;

The color object

To help simplify specifying and using colors, Acrobat JavaScript provides a color object with some predefined colors and color operators. Unfortunately, only the simple colors are predefined, as shown in Table 1.

Predefined Color	Color Value
color.red	["RGB",0,0,1 ]
color.green	["RGB",0,0,1 ]
color.blue	["RGB",0,0,1 ]
color.cyan	["CMYK",0,0,1,0 ]
color.magenta	["CMYK",0,0,1,0 ]
color.yellow	["CMYK",0,0,1,0 ]
color.white	["G",0 ]
color.black	["G",1 ]
color.transparent	["T"]

Adding your own predefined colors to the color object is simple, as shown below.

color.purple= ["RGB", 0.5, 0, 0.5];

Comparing colors

Since there are three color spaces and the color values are arrays, there is no simple method for determining if two colors are equal. Fortunately, the color object provides a function for comparing colors, the color.equal() function.

color.equal(color.blue, ["CMYK",1,1,0,0]);

The equal() function takes two inputs, which are the colors that will be compared. It automatically converts the colors to the same color space. In the code above the first input is RGB and the second input is CMYK, but the function returns true, since they are both blue.

Converting color spaces

Sometimes it is important to convert color values into a particular color space. Again, the color object comes to the rescue with a function, the color.convert() function.

var cmykBlue = color.convert(color.blue,"CMYK");

The first input to the function is the color that will be converted. The second input is the name of the color space it will be converted into. 

Using color

As stated earlier, colors can be applied to border, fill or text. The following code changes the colors used on a text field.

var fld = this.getField("Text1");
fld.strokeColor = ["RGB",0.5,0.5,1]; //Change border to dark blue
fld.Color = ["RGB",0,0,0.7]; //Change fill to light blue
fld.textColor = ["RGB",0.5,0.5,0]; //Change text to light yellow

Another way to use color is for hiding or highlighting a value in a text field.  For example, an error value or a calculation that results in a nonsensical value. 

In the following form field validation script, the field value is displayed in red if the input is not a valid telephone number. This technique allows the user to correct a bad input as opposed to re-entering the entire number, which is what would happen if event.rc was set to false.

var rgexTele = /^\s*(\(\d{3}\))\d{3}\-\d{4}\s*$/;
if(rgexTele.test(event.value))
	event.target.textColor = ["G",1]; //Change text to black
else
{
	event.target.textColor = ["RGB",1,0,0]; //Change text to red
	app.alert("Invalid Telephone Number");
}

In the next example, a form field calculation script sets the text color to white if the result is negative. This effectively hides the value, without affecting how calculations may be handled elsewhere in the form.

// Do the actual calculation first
event.value = . . . ;
// Now test the result
if(event.value < 0)
	event.target.textColor = ["G", 1]; //Change text to white
else
	event.target.textColor = ["G", 0]; //Change text to black

It would be nice if we could use the transparent color to hide text, but unfortunately, this particular color cannot be applied to text. It can only be used for stroke and fill colors.

Colors are simple to use once you understand how to use a Color Array specification. The ColorCalculator.pdf example file demonstrates how the different color spaces are specified in Acrobat JavaScript.