quads 5.0 Type: Array Annots: Highlight, StrikeOut,Underline, Squiggly Access: R/W
An array of 8 x n numbers specifying the coordinates of n quadrilaterals in Default User Space. Each quadrilateral encompasses a word or group of contiguous words in the text underlying the annotation. See Table 7.19, page 414 of the PDF Reference for more details. The quads for a word can be obtained through calls to the getNthTemplate. See getNthTemplate for an example.
rect 5.0 Type: Array Annots: all Access: R/W
The Array consists of four numbers [x ll , y ll , x ur , y ur ] specifying the lower-left x, lower-left y, upper-right x and upper-right y coordinates in Default User Space of the rectangle defining the location of the annotation on the page. See also popupRect.
readOnly 5.0 Annots: all Access: R/W
When readOnly is set to true, this indicates that the annotation should display, but not interact with the user.
rotate 5.0 Annots: FreeText Access: R/W
The property rotate is the number of degrees (0, 90, 180, 270) the annotation is rotated counter-clockwise relative to the page. The Icon based annotations do not rotate, this property is only significant for FreeText annotations.
strokeColor 5.0 Type: color Annots: all Access: R/W
This property sets the appearance color of the annotation. Values are defined by using transparent, gray, RGB or CMYK color. In the case of a FreeText annotation, strokeColor sets the border and text colors. Refer to the Color Arrays section for information on defining color arrays and how values are used with this property. Example:
// Make a text note red var annot = this.addAnnot({type: "Text"}); annot.strokeColor = color.red;
textFont 5.0 Type: String Annots: FreeText Access: R/W
The textFont property determines the font that is used when laying out text in a FreeText annotation. Valid fonts are defined as properties of the "font" object, as listed in the textFont property of the Field object:
An arbitrary font can be used when laying out a FreeText annotation by setting the value of textFont equal to a string that represents the PostScript name of the font. The following example illustrates the use of this property and the font object.

hideToolbarButton 4.0 Parameters: cName Returns: Nothing
This method allows a forms integrator to customize the look of the Acrobat viewer by removing the toolbar button specified by cName. Menu item names can be discovered via the listToolbarButtons method. Language independent names for toolbar buttons can be obtained from the Acrobat Viewer Plug-In API On-line Reference (Technical Note #5191). See Useful Documents. Example: A file named, myConfig.js, containing the script
app.hideToolbarButton("Hand");
is placed in one of the Folder Level JavaScripts folders. When the Acrobat viewer is started, the "Hand" icon does not appear.
listMenuItems 5.0 Parameters: None Returns: Nothing Lists all menu item names in the application to the console. Useful for writing scripts and debugging. Language independent names for menu items can also be obtained from the Acrobat Viewer plug-in API On-Line Reference (Technical Note #5191). See Useful Documents. Example: List all menu item names to the console.
console.show(); app.listMenuItems();
See also the addMenuItem, addSubMenu, execMenuItem, and hideMenuItem methods.
listToolbarButtons 5.0 Parameters: None Returns: Nothing
Lists all toolbar button names in the application to the console. Useful for writing scripts and debugging. Language independent names for menu items can also be obtained from the Acrobat Viewer plug-in API On-Line Reference(Technical Note #5191). See Useful Documents. See also the hideToolbarButton method.

mailMsg 4.0

Parameters: bUI, cTo, [cCc], [cBcc], [cSubject], [cMsg] Returns: Nothing This method sends out an e-mail message with or without user interaction depending on the value of bUI. If it is set to true then the rest parameters are used to seed the compose new message window that is displayed to the user. If bUI is set to false, the cTo parameter is required and others are optional. You must use a semicolon ";" to separate multiple recipients in cTo, cCc, cBcc parameters. The length limit for cSubject and cMsg is 64k bytes. Example:
/* This will pop up the compose new message window */ app.mailMsg(true); /* This will send out the mail to fun1@fun.com and fun2@fun.com */ app.mailMsg(false, "fun1@fun.com; fun2@fun.com", "", "", "This is the subject", "This is the body of the mail."); /* Or the same message can be sent as follows: app.mailMsg( {bUI: false, cTo: "fun1@fun.com; fun2@fun.com", cSubject: "This is the subject", cMsg: "This is the body of the mail."} );

numFields 4.0 Type: Integer Access: R
This property returns the total number of fields in the document. See also the getNthFieldName method.
numPages Type: Integer This property contains the number of pages in the document. Access: R
numTemplates Type: Integer Access: R
This property returns the number of templates in the document (see also getNthTemplate and spawnPageFromTemplate methods). See also the document templates property which supersedes this property in later versions.
path Type: String Access: R
This property defines the device independent path of the document, for example /c/Program Files/Adobe/Acrobat 5.0/Help/AcroHelp.pdf. See Section 3.10.1, File Specification Strings , page 108, in the PDF Reference for exact syntax of the path.
pageNum Type: Integer Access: R/W
Use this property to get or set a page of the document. When setting the pageNum to a specific page, remember that the values are "0" based.
// This example will go to the first page of the document. this.pageNum = 0 ; // This example will advance the document to the next page this.pageNum++;

producer

This property contains producer of the document (e.g. "Acrobat Distiller", "PDFWriter", etc.). See also the document info property which supersedes this property in later versions.
securityHandler 5.0 Type: String | null Access: R
This property returns the name of the security handler used to encrypt the document and returns null if there is no security handler (i.e. the document is not encrypted). For example,
console.println(this.securityHandler != null ? "This document is encrypted with " + this.securityHandler + " security." : "This document is unencrypted.");

could print out

Encrypted with Standard security.
if the document was encrypted with the standard security handler.
selectedAnnots 5.0 Type: Array Access: R
This property returns an array of Annot Objects corresponding to every markup annotation the user currently has selected. Example:
// show all the comments of selected annots in console var aAnnots = this.selectedAnnots; for (var i=0; i < aAnnots.length; i++) console.println(aAnnots[i].contents);
See also, getAnnot and getAnnots.
sounds 5.0 Type: Array Returns an array comprised of all of the named Sound Objects in the document. Example:
var s = this.sounds; for (i = 0; i < s.length; i++) console.println("Sound[" + i + "]=" + s[i].name);
See also the getSound, importSound, and deleteSound methods, and the Sound Object.
spellDictionaryOrder 5.0 Type: Array Access: R/W
This property can be used to access or specify the dictionary array search order for this document. The Spelling plug-in will search for words first in this array and then it will search the dictionaries the user has selected on the Spelling Preference panel. The user s preferred order is available from the spell.dictionaryOrder property. An array of the currently installed dictionaries can be obtained using the spell.dictionaryNames property. For example, if a user is filling out a Medical Form the form designer may want to specify a Medical dictionary to be searched first before searching the user s preferred order.

: If the cDIPath parameter is specified, then this method can only be executed during batch, console or menu events, or through an external call (e.g. OLE). See the Event Object for a discussion of Acrobat JavaScript events.
importIcon 5.0 Parameters: cName, [cDIPath], [nPage] Returns: Integer This method imports an icon into the document and associates it with the specified name. cDIPath is optional and specifies a device independent path to a PDF file on the user s hard drive. This path may be absolute or relative to the current document. cDIPath may only be specified in a batch environment or from the console. See Section 3.10.1, File Specification Strings in the PDF Reference for the exact syntax of the path. If cDIPath is not specified then the nPage parameter is ignored and the user will be prompted to locate a PDF file and browse to a particular page. nPage is the zero-based index of the page in the PDF file to import as an icon. Default is 0.
This method returns a code indicating whether it was successful or not.
Return Codes Code -1 -2 Description No error The user cancelled the dialog The selected file couldn t be opened The selected page was invalid
This function is useful to populate a document with a series of named icons for later retrieval. For example, if a user of a document selects a particular state in a listbox, the author may want the picture of the state to appear next to the listbox. In prior versions of the application, this could be done using a number of fields that could be hidden and shown. This is difficult to author, however; instead, the appropriate script might be something like this:
var f = this.getField("StateListBox"); var b = this.getField("StateButton"); b.buttonSetIcon(this.getIcon(f.value));
This uses a single field to perform the same effect. A simple user interface can be constructed to add named icons to a document. Assume the existence of two fields: a field called IconName which will contain the icon name and a field called IconAdd which will add the icon to the document. The mouse up script for IconAdd would be:
var t = this.getField("IconName"); this.importIcon(t.value);
The same kind of script can be applied in a batch setting to populate a document with every selected icon file in a folder. See also the icons property and the addIcon, getIcon and removeIcon methods of the Doc Object, the buttonGetIcon, buttonImportIcon, and buttonSetIcon methods of the Field Object, and the Icon Object.

: If cDIPath is specified, this method can only be executed during batch, console or menu events. See the Event Object for a discussion of Acrobat JavaScript events.
importSound 5.0 Parameters: cName, [cDIPath] Returns: Nothing This method imports a sound into the document and associates the specified name with the sound. cName is the name to associate with the sound object. cPath is optional and specifies a device independent path to a sound file on the user s hard drive. This path may be absolute or relative to the current document. If cPath is not specified then the user will be prompted to locate a sound file. See Section 3.10.1, File Specification Strings , in the PDF Reference for the exact syntax of the path. Example:
this.importSound("Moo"); this.getSound("Moo").play(); this.importSound("Moof", "./moof.wav"); this.getSound("Moof").play();
See also the sounds property, the getSound, and deleteSound methods, and the Sound Object.
: If cDIPath is specified, this method can only be executed during batch, console, or menu events. See the Event Object for a discussion of Acrobat JavaScript events.
importTextData 5.0 Parameters: [cPath], [nRow] Returns: Nothing This method imports a row of data from a text file. Each row must be tab delimited. The entries in the first row of the text file are the column names of the tab delimited data. These names are also field names for text fields present in the PDF file. The data row numbers are 0based; i.e., the first row of data is row zero (this does not include the column name row). When a row of data is imported, each column datum becomes the field value of the field that corresponds to the column to which the data belongs. cPath is a relative device independent path to the text file. If not specified, the user is prompted to locate the text data file.
nRow is the zero-based index of the row of the data to import not counting the header row. If not specified, the user is prompted to select the row to import. Example: Suppose there are text fields named "First", "Middle" and "Last", and there is also a data file, the first row of which consists of the three strings, First, Middle and Last, separated by tabs. Suppose there are four additional rows of name data, again separated by tabs.

The file select flag is mutually exclusive with the multiline, charLimit, password, and defaultValue properties. Also, on the Macintosh platform, when setting the file select flag, the field gets treated as read-only; hence, the user must browse for the file to enter into the field. (See the browseForFileToSubmit method.)
: This property can only be set during batch, menu, or console events. See the Event Object for a discussion of Acrobat JavaScript events.

fillColor

Type: Array
This property specifies the background color for a field. The background color is used to fill the rectangle of the field. Values are defined by using transparent, gray, RGB or CMYK color. Refer to the Color Arrays section for information on defining color arrays and how values are used with this property.
var f = this.getField("myField"); if (color.equal(f.fillColor, color.red)) f.fillColor = color.blue; else f.fillColor = color.yellow;
In older versions of this specification, this property was named bgColor. The use of bgColor is now discouraged but for backwards compatibility is still valid.

hidden

This property controls whether the field is hidden or visible to the user. If the value is false the field is visible, true the field is invisible. The default value for hidden is false.
// Set the field to hidden var f = this.getField("myField"); f.hidden = true;
See also the display property which supersedes this property in later versions.

highlight

Fields: button
This property defines how a button reacts when a user clicks it. The four highlight modes supported are none, invert, push, and outline. The none highlight does not indicate visually that the button has been clicked. The invert highlight causes the region encompassing the button s rectangle to invert momentarily. The push highlight displays the down face for the button (if any) momentarily. The outline highlight causes the border of the rectangle to invert momentarily.
The convenience highlight object defines all the characteristics that a button can have. The following chart shows the highlight object and its associated keywords:
Type none invert push outline Keyword highlight.n highlight.i highlight.p highlight.o
The following example sets the highlight property of a button to "invert".

required

Fields: all but button
This property sets or gets the required characteristic of a field. If a field is required its value must be non-null when the user clicks a submit button that causes the value of the field to be posted. If the field value is null, the user receives a warning message and the submit does not occur. Example:
var f = this.getField("myField"); f.required = true;

strokeColor

This property specifies the stroke color for a field which is used to stroke the rectangle of the field with a line as large as the line width. Values are defined by using transparent, gray, RGB or CMYK color. Refer to the Color Arrays section for information on defining color arrays and how values are used with this property. In older versions of this specification, this property was borderColor. The use of borderColor is now discouraged but for backwards compatibility is still valid.
Fields: checkbox, radiobutton
This property allows the user to set the style of a check box or a radio button, that is, sets the glyph used to indicate that the check box or radio button has been selected. Valid styles include "check", "cross", "diamond", "circle", "star", and "square". The following table lists the style properties and the associated keywords:
Style check cross diamond circle star square Keyword style.ch style.cr style.di style.ci style.st style.sq
The following example illustrates the use of this property and the style object:
var f = this.getField("myCheckbox"); f.style = style.ci;
submitName 5.0 Type: String Fields: all Access: R/W
If nonempty, this property is used during form submission instead of the field name. Only applicable if submitting in HTML format (i.e. urlencoded).

textColor

This property determines the foreground color of a field. It represents the text color for text, button, or listbox fields and the check color for check box or radio button fields. Values are defined the same as the fillColor property. Refer to the Color Arrays section for information on defining color arrays and how values are set and used with this property.

validateSignaturesOnOpen 5.0
Type: boolean Access: R/W
Gets or sets the user level preference that validates signatures when a document is opened.

Security Object Methods

getHandler Parameters: cName, [bUIEngine] Returns: Sig Object Returns the signature handler object specified by cName. If the signature handler is not present then a null object is returned. See also the handlers property. The second optional parameter, bUIEngine, is boolean that defaults to false, if not present. If true then getHandler returns the existing signature handler engine that is also hooked up to the UI (eg can login via UI). If false (default) then returns a new engine. The caller can create as many new engines as desired and each call to getHandler will create a new engine; however, there is only one UI engine
Example: This code selects the PPKLite Signature Handler Object
// validate signatures on open security.validateSignaturesOnOpen = true; // list all available signature handlers var a = security.handlers; for (var i = 0; i < a.length; i++) console.println("a["+i+"] = "+a[i]); // use "Adobe.PPKLite" handler engine for the UI var ppklite = security.getHandler("Adobe.PPKLite", true); // login ppklite.login("dps017", "/C/signatures/DPSmith.apf");
See also the example following signatureSign for a continuation of this example.

Sound Object

5.0 The Sound object is the representation of a sound that is stored in the document. The array of all sound objects can be obtained from the Doc.sounds property. See also the getSound, importSound, and deleteSound methods of the Doc Object.

Sound Object Properties

name Type: String This property is the name associated with this sound object. Example:
console.println("Dumping all sound objects in this document."); var s = this.sounds; for (var i = 0; i < this.sounds.length; i++) console.println("Sound[" + i + "]=" + s[i].name);

Sound Object Methods

play Parameters: None Returns: Nothing This method plays the sound asynchronously.
pause Parameters: None Returns: Nothing This method pauses the currently playing sound. If the sound is already paused then the sound play is resumed.
stop Parameters: None Returns: Nothing This method stops the currently playing sound.

Spell Object

The JavaScript Spell object allows users to check the spelling of form and annotation text fields and other spelling domains. To be able to use the Spell object, the user must have installed the Acrobat Spelling plug-in and the spelling dictionaries.

var f = this.getField("Text Box") /* a form text box */ f.value = spell.checkText(f.value); /* let the user pick the dictionary */

checkWord 5.0

Parameters: cWord, [aDictionary] Returns: null | Array This method checks the spelling of a word, cWord. If the word is correct a null object is returned, otherwise an array of alternative spellings for the unknown word is returned. The optional aDictionary parameter is the array of dictionary names that Acrobat should use. The order of the dictionaries in the array is the order Acrobat will use to check for misspelled
words. An array of the currently installed dictionaries can be obtained using the dictionaryNames method. When this parameter is omitted the Doc.spellDictionaryOrder list will be searched followed by the spell.dictionaryOrder list. Example:
var word = "subpinna"; /* misspelling of "subpoena" */ var dictionaries = ["English USA Legal", "English USA"]; var f = this.getField("Alternatives") /* alternative spellings listbox */ f.clearItems(); f.setItems(spell.checkWord(word, dictionaries));
Example: The following script goes through the document and marks with a squiggle annot any misspelled word. The contents of the squiggle annot contains the suggested alternative spellings. The script can be executed from the console, as a mouse up action within the document, or as a batch sequence.
var ckWord, numWords; for (var i = 0; i < this.numPages; i++ ) { numWords = this.getPageNumWords(i); for (var j = 0; j < numWords; j++) { ckWord = spell.checkWord(this.getPageNthWord(i, j)) if ( ckWord != null ) { this.addAnnot({ page: i, type: "Squiggly", quads: this.getPageNthWordQuads(i, j), author: "A. C. Acrobat", contents: ckWord.toString() }); } } }

removeDictionary 5.0 E

Parameters: cName Returns: Boolean This method will remove a user dictionary that was added via addDictionary. cName must be the same name as was used with addDictionary.
The removeDictionary method returns true on success, false, otherwise

removeWord 5.0 E

Parameters: cWord, cName Returns: Boolean Use this method to remove the word cWord from a dictionary. If successful it returns true, otherwise, false. The required cName parameter is the dictionary name. An array of the currently installed dictionaries can be obtained using the dictionaryNames method. See also the addWord method.
Internally the SpellCheck Object will scan the user dictionary and remove the previously added word if it is there. Otherwise the word will be added to the user s "Not-A-Word" dictionary. The actual dictionary is not modified.

userWords 5.0 E

Parameters: cName, bAdded Returns: Array This method returns the array of words a user has added or removed from a dictionary. See also the addWord and checkWord methods. The required cName parameter is the dictionary name. An array of the currently installed dictionaries can be obtained using the dictionaryNames property. The required bAdded parameter indicates which of the two arrays should be returned. When true, the user s array of added words are returned. When false, the user s array of removed words are returned.

Setting tab order In order to traverse the document in a reasonable manner, the tab order for the fields must be set in a logical way. This is important as most users use the tab key to move through the document. For visually impaired users this is a necessity as they cannot rely on mouse movements or visual cues.
Use the TTS object In cases that the default behavior of Acrobat with respect to forms is insufficient to give context or indication of the current state of the form fields in the document, the author is encouraged to make use of the TTS Object to supplement that behavior.
Default Behavior The default behavior of Acrobat 4.05 with respect to accessibility is as follows: 1. Tab key: pressing the tab (shift-tab) key when there is no form field that has the keyboard focus will cause the first (last) field in the tab order on the current page to become active. If there are no form fields on the page then Acrobat will inform the user of this via a speech cue. Using tab (shift-tab) while a field has the focus tabs forward (backward) in the tab order to the next (previous) field. If the field is the last (first) field on the page and the tab (shifttab) key is pressed, the focus is set to the first (last) field on the next (previous) page if one exists. If such a field does not exist, then the focus loops to the first (last) field on the current page. 2. Sound Cues: sound cues are user-configurable sounds that play when certain events occur and give the user an indication of context. The following actions have sound cues attached to them:
Document open, close, activate, save, print Page turn Keystroke handling when interacting with a field 3. Speech cues: speech cues are user configurable strings that are spoken by the text to speech engine to give the disabled user an indication of context. The following actions have speech cues attached to them: Application initialize Document open, close, activate, save, print Page turn Field focus, blur Alert dialogs Keystroke handling when interacting with a field.
How can I define globals in JavaScript?
The Acrobat extensions to JavaScript define a Global object to which you can attach global variables as properties. To define a new global called myVariable and set it equal to the null string, you would type:
global.myVariable = "";
All of your scripts, no matter where they are in a document, will now be able to reference this variable.

var f = this.getField("myButton");
Field Properties The top of the UI, above the tab fields, there are listed three general properties.
General Field Properties Name Name Type Short Description Use Example console.println(f.name); console.println(f.type); f.userName = "Submit Button"

name type userName

Table Notes The name and type are read-only properties. They can be set at creation time, either through the UI, or programmatically, with addField. See the example above. It is possible through the UI in Acrobat to specify the Appearance of the field, its Options and its Actions, all of which appear as tabs in the UI for a button field. All these properties can be accessed through field level JavaScript properties and methods. Appearance The appearance tab allows you to set the basic appearance of the field. The table below summarizes how the appearance can be set programmatically using JavaScript. In the table, it is assumed that the variable f is a field object.
The Appearance Tab Region Border Border Color Background Color Width Style Text Text Color Font Size Common Properties Read Only Form Field is Orientation Use Example
strokeColor fillColor lineWidth borderStyle textColor textFont textSize readonly display
f.strokeColor = color.black; f.fillColor = color.ltGray; f.lineWidth = 1; f.borderStyle = style.b
f.textColor = color.blue; f.textFont = font.Times; f.textSize = 16;
f.readonly = true; f.display = display.visible See tables notes
Table Notes There is no property to set the orientation of a form field; however, by rotating the page, creating the button, then rotating back again, a rotated button can be created.
this.setPageRotations(this.pageNum, this.pageNum, 90); var f = this.addField("actionField", "button", 0, [200, 250, 300, 200]); f.delay = true; f.strokeColor = color.black; f.fillColor = color.ltGray; f.borderStyle = style.b; f.delay=false; this.setPageRotations(this.pageNum, this.pageNum);
Options The option tab allows you to set the highlighting, the layout and the button-face attributes.
The Options Tab Highlight Layout Advanced Layout Scale When Scale How Button Button Face Attributes Text Select Icon

Try it: Copy this code contents and paste it into the console. Highlight all the code and execute it strokeColor by pressing Ctrl-Enter, or the Enter key on the number pad. The phrase author mark up annotation above should be highlighted in yellow. See checkWord for a spell check example.