Using Colors in Acrobat JavaScript

What’s a PDF without color? (Answer: monotone, ha ha. Sorry, that was a nerd joke). Color is used in JavaScript for the borders, fill, and text of annotations and form fields. It can be specified in RGB, CMYK, or gray scale and there is even a transparent color. 

The Color Array

There are a few different ways to specify colors. In Acrobat JavaScript, colors are specified with an array containing the color space name and an entry for the value of 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.  

// Dark Yellow
var colDkYellow = ["RGB", 0.7 , 0.7, 0 ];

// Light Yellow
var colLtYellow = ["CMYK", 0 , 0, 0.7, 0 ];

// Dark Gray
var colDkGray = ["G", 0.7];

// Transparent
var colClear = ["T"];

JavaScript must be cross platform and able to deal with a variety of display hardware. To accommodate a variety of color depths, values are specified as a floating point number between 0 and 1. Many other color specifications use an integer between 0 and 255. For historical reasons, this is a traditional way of representing colors in image files. It corresponds to color resolution of 8 bits (1 byte) per channel. 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 a color, Acrobat JavaScript provides a few colors. These predefined colors are accessed via the color object. Unfortunately, only the simple colors are predefined, as shown in Table 1.

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

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

This code is best placed in a Folder Level script so it is always automatically available for use.

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");

//Change border to dark blue
fld.strokeColor = ["RGB",0.5,0.5,1];

//Change fill to light blue
fld.Color = ["RGB",0,0,0.7];

//Change text to light yellow
fld.textColor = ["RGB",0.5,0.5,0];

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 reentering 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 (below) demonstrates how the different color spaces are specified in Acrobat JavaScript.