Adobe ACROBAT FORMS JAVASCRIPT OBJECT SPECIFICATION

Adobe

Acrobat

Technica l Note # 5186

Acrobat Forms JavaScript

Object Specification

Version 4.0

Revised: January 27, 1999

The information in this document is furnished for informational use only, is subject t change without notice, and should not be construed a s a commitment by Adobe Systems Incorporated. Adobe Syst ems Incorporated assumes no responsibility or liability for any err ors or inaccuracies that may appear in this document. The software described in this document is f urnished under licens e and may only be used or copied in accordance with the terms of such license.

Adobe, the Adobe logo, Acr obat, Acrobat Capture, Acrobat Exchange, and Distiller are trademarks of Adobe Syste ms Incorporated. Microsoft and Windows are registered trademarks and ActiveX is a t rademark of Microsoft in the U.S. and other countries. Macintosh is a trademark of Apple Computer, Inc. registered in the U.S. and other countries. P owerPC is a trademark of International Business Machines Corporation. UNIX is a registered trademark in the U.S. and other countr ies, licensed exclusively through X/Open Co. Ltd. All other pr oducts or name brands a re trademarks of their respective holders.

Acrobat Forms - JavaScript Object Specification

Table Of Contents

Introdu ction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Other useful documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Document Co nventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

What’s New f or 4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Acrobat Forms JavaScri pt Object Mode l . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

App Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

App Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

calculat e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

formsVersion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

fullscreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

numPlugI ns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

openInPlace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

toolbarH orizontal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

toolbarVe rtical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

viewerType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

viewerVe rsion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

App Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

alert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

beep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

execMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

getNthPlugInName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

goBack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

goForward . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

hideMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

hideToo lb a rButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

mailMs g. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

respons e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Color Ar rays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Color Obje ct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Color Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Console Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Console Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

printl n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Acrobat Forms - JavaScript Object Specification

iii

Doc Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Doc Access from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Doc Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

calculat e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

creator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

creati on Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

delay. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

dirty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

exter nal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

filesize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

modDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

numField s. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

numPages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

numTempl ates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

pageNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

produc e r . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

subject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

zoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

zoomType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Doc Object Me th ods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

calculat e N ow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

exportAsFDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

getFiel d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

getNthFi e ldName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

getNthT e mplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

getURL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

gotoNa medDest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

import An FDF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

mailDoc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

mailForm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

resetForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

scroll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

spawnPage FromTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

submitForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Event Obje ct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Event Pr ocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Mouse Ent e r . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Mouse Dow n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Mouse Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Mouse Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Acrobat Forms - JavaScript Object Specification

Keystr oke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Validat e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Calcul ate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Event Ob je ct Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

commitK ey. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

modifie r . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

rc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

selEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

selStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

shift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

willCo mmit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Field Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Field Acce s s from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

alignmen t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

borderS ty le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

calcOr derI ndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

charLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

defaul tV alue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

editable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

fillCo lo r . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

highlig ht . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

lineWi dth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

multili n e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

numItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

readonly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

requir e d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

strokeC ol or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

textCol or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

textFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

textSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

userNam e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Acrobat Forms - JavaScript Object Specification

value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Field Metho d s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

button I mp ortIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

clearItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

deleteI temAt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

getArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

getItem At . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

insert I temAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

setItem s. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Global Objec t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Global Obj e ct Me thods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

setPersistent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

this Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Variable and Fu nction Name Conf li cts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Util Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Util Objec t Me th ods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

printf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

printx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

printd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

scand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Impleme nt ation Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

JavaScri pt Locations and Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Plug-in folder level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Document level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Field level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Form Field Hierarchies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Form Fiel d Hi e rarchies with Jav aScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Working Wi th The Date Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Converting a Date to a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Converting a String to a Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Date Ari th metic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Acroba t Forms and Securit y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Restri cting Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Restri cting Permiss io ns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Digital S ignatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Working w it h S ignature Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Acrobat Forms - JavaScript Object Specification

JavaScript Object

Specification

Introduction

JavaScript, the scripting language developed by Netscape C ommunications, enables you to easily create interactive We b pages .

JavaScript v1.2 comes with six predef ined classes: Boolean, Number, Date, Math, String,and Array . As part of the integration with Adobe® Acrobat® Forms, we have defined additional classes and objects to allow acces s to portions of the PDF file.

This document describ es these classes, as wel l as details the load and e xecution of JavaScripts in the Adobe Acrobat environment. Of particular note is the Field Object section which handles all pr ocessing of Acrobat Form fields including their formatting, calculation, and validation.

The intended audience of this document is assumed to be f amiliar with Adobe Acrobat, the Acrobat Forms plug-in a nd the Adobe Ac robat plug-in API.

Document Conventions

As this document pertains to Acrobat Forms version 3.5 and greater, there exists s ome compatibility issues with older versions of the software. If a property, method, or object is

marked with a symbol, then it is available only in ver sions of the Acrobat Forms sof tware

#.#

greater than or equal to #.#. Before accessing this object, proper ty, or method, the script should check that the application version is greater than or equal to #.# if backwards compatibility is desired.

Example:

if (typeof app.formsVersion != "undefined" && app.formsVersion >= 4.0) {

// Perform version specific operations.

}

As the JavaScr ipt extensions to Acrobat Forms have evolved, some properties or methods have been superseded by other, mor e flexible or appropriate properties or methods. The use of these older m ethods are discouraged and marked by Mr. Unhappy.

Acrobat Forms - JavaScript Object Specification

What’s New for 4.0

Object Properties Methods

App Object

Colo r O b j e ct Doc Object calculate, delay,

Field Object Util Object

formsVersion, numPlugIns openInPlace toolbarHori z ontal toolbarV ertical viewerVersion

dkGra y, gray, ltGray

external

display setItems(), deleteItemAt()

, numFields

getNthPlugInName(), hideMenuItem hideToolbarButton

exportAsFDF(), getNthFieldName importAnFDF mailForm

spawnPageFromTemplate submitFor m

scand()

(),

(), mailMsg()

(), getURL(),

(), mailDoc(),

(),

()

(),

Note: Items shown in italics are not new to this release but they have been

modified or added t o.

New sections of the documentation for 4. 0:

New Section Description

Working With The Date Object

Acrobat Forms and Security

Working with Signature Fields

Describes the proper methods for formatting and parsing dates and performing date arithmetic.

Shows how to properly define security settings in a form so that it cannot be tampered with.

Details the proper usage of scripts when signing documents includ ing inverse operations upon form reset

Acrobat Forms - JavaScript Object Specification

Acrobat Forms JavaScript Object Model

Acrobat Forms de fines an object model on top of JavaScript 1.2. These objects are only defined within the Adobe Acr obat realm and are specific to Acrobat Forms. They basically mirror the Acrobat Forms components and give the forms developer a way to access these components programmatically in or der to query and change their properties. In addition to defining forms specific objects, ther e are additional generic objects that allows the developer to ac cess the underlying document and perform certain actions on it.

App Object

The App object is a static JavaScript object that defines a number of Acrobat specific functions plus a variety of utility routines and convenience functions.

App Object Properties

calculate

Type: Boolean Access: R/W

If this property is s et to true, it will allow calculations to be performed. If set to false,this property prevents all calculations in all documents from happening. Its default value is true. See a lso the document calculate property which supersedes this property in later versions.

formsVersion

Type: Number Access: R

This property indicates the version number of the forms software running inside the view er. Use this method to determine whethe r objects , properties, or methods in newer ver sions of the software are available if you wish to maintain backwards compatibility in your scr ipts. See

Document Conventions for more details.

Example:

if (typeof app.formsVersion != "undefined" && app.formsVersion >= 4.5) {

// Perform version specific operations here.

}

4.0

fullscreen

Type: Boolean Access: R/W

Acrobat Forms - JavaScript Object Specification

This pr operty puts the Acrobat viewer in fullscreen mode vs. regular viewing mode. Example:

// on mouse up, set to fullscreen mode app.fullscreen = true;

In the above example, the Adobe Acrobat viewer is set to fullscreen mode when app.fullscreen is set to tr u e .Ifapp.fullscreen was false then def ault viewing mode would be set. The default viewing mode is defined as the original mode the Acrobat application was in before full s creen mode wa s initiated.

language

Type: String Access: R

This property defines the language of the running Acrobat Viewer. It returns the following strings:

String Language, Country

DEU German, Germany ENU English, The United States of Am erica ESP Spanish, Spain FRA French, France ITA Italian, Italy JPN Japanese, Japan NLD Dutch, The Netherlands SVE Swedish, Sweden

numPlugIns

4.0

Type: Number Access: R

This property indicates the number of plug-ins that have been loa ded by Acr obat. See als o the

getNthPlugInName method.

openInPlace

4.0

Type: Number Access: R/W

This property determines whether cross-document links are opened in the same window or opened in a new window.

Acrobat Forms - JavaScript Object Specification

platform

Type: String Access: R

This propert y returns the pla tform that the script is currently executing on. Valid values include “WIN”, “MAC”, and “UNIX ”.

toolbar

Type: Boolean Access: R/W

This pr operty allows a script to show or hide both the horizontal and ve rtical Acrobat tool bars. It does not hide the tool bar in external windows (i.e. in an Acrobat window within a Web browser).

Example:

// Opened the document, now remove the toolbar. app.toolbar = false;

toolbarHorizontal

Type: Boolean Access: R/W

This pr operty allows a script to show or hide the Acr obat horizontal tool bar. It does not hide the tool bar i n external windows (i.e. in an Acrobat window within a Web browser).

toolbarVertical

Type: Boolean Access: R/W

This property allows a script to show or hide the Ac robat ve rtical tool bar. It does not hide the tool bar in external windows ( i.e. in an Acrobat window within a Web browser).

viewerType

Type: String Access: R

This property determines if the r unning Acrobat Viewer is the Rea der vs. Exchange. Its value is “Reader” or “Exchange” r espectivel y.

4.0

viewerVersion

Type: Number Access: R

This pr operty indicates the version number of the current viewer (i.e. Reader or Exchange) .

Acrobat Forms - JavaScript Object Specification

4.0

App Object Methods

alert

Parameters: cMessage, [nIcon], [nType] Returns: nButton

This method displays an alert dialog on the screen. The minimum required parameter is a string containing the message to be displayed. Optionally, an icon type can be specified by using t he nIcon par ameter. The following is a list of icons and their associated values:

Icon Value

Error (default) 0 Warning 1 Question 2 Status 3

Additionally, a button group type can be specified:

Button Group Value

OK (default) 0 OK, Cancel 1 Yes, No 2 Yes, No, Cancel 3

This method returns the type of the button that was pressed by the user:

Button Type Value

Error 0 OK 1 Cancel 2 No 3 Yes 4

beep

Parameters: [nType] Return s: n one

Acrobat Forms - JavaScript Object Specification

This method causes the system to play a s ound. The various sounds and the values used are as follows:

Message Type Value

Error (default) 0 Warning 1 Question 2 Status 3 Default 4

On Apple Ma cintosh a nd UNIX systems the beep type is ignored.

execMenuItem

4.0

Parameters: cMenuItem Returns: nothing

This method executes the spe cified menu item. To find out the exact menu item name, see the

Acrobat Viewer Plug-in API On-line Reference under § Lists: Menu item names. The menu

item name is case sensitive and has to exactly match strings in the list. Example:

/* This example executes File->Open menu item. It will display a dialog to the user asking for the file to be opened. */ app.execMenuItem("Open");

Note: For s ecurity reasons, we will not allow the script to execute t he SaveAs and

Close menu items. If either of those two menu items is passed as cMenuItem,

this function will do nothing.

getNthPlugInName

4.0

Parameters: nIndex Returns: cName

This method returns the name of the Nth plug-in that has bee n loaded by the view er. See also the numPlugIns property.

Acrobat Forms - JavaScript Object Specification

goBack

Parameters: None Returns: nothing

Use this function to go to the previous view on the view stac k. This is equivalent to pressing the go back button on the Acrobat tool bar.

goForward

Parameters: None Returns: nothing

Use t his function to go to the next view on the view stack. This is equivalent to pressing the go forward button on the Acrobat tool ba r.

hideMenuItem

Parameters: cName Returns: nothing

This method only works in the Config.js Plug-i n fo lder l evel script. It allows a forms integrator to customize the look of the Acrobat viewer by removing the m enu item specified by cName . Language independent names for toolbar buttons can be obtaine d fr om the Acrobat Viewer Plug-In API On-line Reference (Technical Note #5168).SeeO ther use ful docum ents for more details.

hideTo olbarButt on

Parameters: cName Returns: nothing

This method only works in the Config.js Plug-i n fo lder l evel script. It allows a forms integrator to customize the look of the Acrobat viewer by removing the toolbar button specified by

cName. Language independe nt names for toolbar buttons can be obtained from the Acrobat Viewer Plug-In API On-line Reference (Technical Note #5168).SeeOther use ful doc um ent s for

more details.

4.0

mailMsg

Parameters: bUI, cTo, [ cCc], [cBcc] , [cSubje ct], [cMsgBody] Returns: nothing

This method sends out an e-mail message with or without user interaction depending on the value of bUI. I f it is set to true then the rest parame ters are used to seed the compose new message window that is displayed to the user.

Acrobat Forms - JavaScript Object Specification

4.0

If bUI is set to false, the cTo para meter 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 cMsgBody 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.");

Note: This is a Windows-only feature. In addition, the client machine must have its

default mail program configured to be MAPI enabled in order to use this method.

response

Parameters: cQuestion [cTitle], [cOldValue] Returns: cResponse or null on cancel

This method displays a dialog box containing a question and an entry field for the user to reply to the question. Optionally, the dialog may have a title or a de fault value for the answer to the question. The return va lue is a string c ontaining the user’s response. I f the user presses the cancel button on the dialog the r esponse is the null object.

Acrobat Forms - JavaScript Object Specification

Color Arrays

A color is represented in JavaScript as an array containing 1, 2, 4, or 5 elements corresponding to a transpar ent, gray, RGB, or CMYK color space, respectively. The first element in the arr ay is a string denoting the color space type. The subsequent elements are numbers that range between zero and one inclusive. The following table illustrates this:

Color Space String #of Additional

Elements

Transparent “T” 0 Gray “G” 1 RGB “RGB” 3 CMYK “CMYK” 4

For example, the color red can be represent ed as [“RGB” 1 0 0]. Invalid strings or ins ufficient elements in a color array cause the color to be interpreted as the

color black. A transparent color spa ce indicates a complete absence of color and will allow those portions

of the document underlying the current field to show through. Colors in the gray color space are represented by a single value—the intensity of achromatic

light. In this color space, 0 is black, 1 is white, and intermediate values represent shades of gray (i.e. “.5”, “.7” etc.).

Colors in the RGB colo r space are represented by three values: the intens ity of the r ed, green, and blue components in the output. RGB is commonly used f or video displays bec ause they are generally bas ed on red, green, and blue phosphors.

Colors in the CMYK color spa ce are represented by four values. These va lues are the amounts of the cyan, magenta, yellow, and black components in the output. This color space is commonly used for color printers, where they are the colors of the inks traditionally us ed in four-color printing. Only cya n, magenta, and yellow are necessary, but black is generally us ed in printing because black ink produces a better black than a mixture of cyan, magenta, and yellow inks , and because black ink is less expensive than the other inks.

Color Object

The colo r object is a convenience static object that defines the basic colors . These colors are accessed in JavaScr ipts via the color obj ect. Use t his objec t whene ver you want to set a property or call a method tha t require a color array. T he color object is defined in AForm.js.

Acrobat Forms - JavaScript Object Specification

Color Properties

The color object defines the following color s and there associated keywords:

Color Object Keyword Version

Transparent color.transparent Black color.black White color.white Red color.red Green color.green Blue color.blue Cyan color.cyan Magenta color.magenta Yellow color.yellow

Example:

// This example sets the text color of the field to red // if the value of the field is negative, else it sets it // to black. var f = event.target; /* field that the event occurs at */ if (event.value < 0)

else

Dark Gray color.dkGray

Gray color.gray

Light Gray color.ltGray

f.textColor = color.red;

f.textColor = color.black;

4.0

Acrobat Forms - JavaScript Object Specification

Console Object

The Console objec t is a static object to acces s the JavaScript console for displaying debug messages. I t functions only within Acrobat Exchange.

Console Methods

show

Parameters: none Return s: n one

This method shows the console window.

hide

Parameters: none Return s: n one

This method closes the console window.

println

Parameters: cMessage Return s: n one

This method prints the string value of cMessage to the console window with an accompanying carriage return.

Example:

// This example prints the value of a field to the console window var f = event.target; console.println("Field value="+f.value);

clear

Parameters: none Returns: nothing

This method clears the cons ole windows buffer of any output.

Acrobat Forms - JavaScript Object Specification

Doc Object

The JavaScript Doc objec t provides the interfaces between a PDF document open in the viewer and the J avaScript interpreter. It provides methods and properties of the PDF document.

Doc Access from JavaScript

Accessing the Doc object f rom JavaScript can be done either through the this Object , which usually points to the Doc object of the underlying document. The target event property points to the field that initiated the event for all mouse, calculate, validate, and format events. For all other events, it directly points to the Doc object. The examples below illustrates the use of the Event object to access the Doc object of the underlying document.

// In Mouse, calculate, validate, format events var doc = event.target.doc;

// In all other events var doc = event.target;

Doc Object Properties

author

Type: String Access: R/W

This property defines the author of the document.

this.author = "Robert Frost";

calculate

Type: Boolean Access: R/W

If this property is set to true, it will allow calculations to be performed for this document. If set to false, this property prevents all calculations from happening for this document. Its default value is true. This property supersedes the application level calculate property whose use is now discouraged.

creator

Type: String Access: R

4.0

This property defines the creator of the document (e.g. “Adobe FrameMaker”,“Adobe PageMaker”, etc.).

Acrobat Forms - JavaScript Object Specification

+ 44 hidden pages