User manual ADOBE ACROBAT FORMS JAVASCRIPT OBJECT SPECIFICATION

bc Adobe® Acrobat® Technical Note # 5186 Acrobat Forms JavaScript Object Specification Version 4.0 Revised: January 27, 1999 © 1999 Adobe Systems Incorporated. All rights reserved. The information in this document is furnished for informational use only, is subject t change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The software described in this document is furnished under license and may only be used or copied in accordance with the terms of such license. Adobe, the Adobe logo, Acrobat, Acrobat Capture, Acrobat Exchange, and Distiller are trademarks of Adobe Systems Incorporated. Microsoft and Windows are registered trademarks and ActiveX is a trademark 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. PowerPC is a trademark of International Business Machines Corporation. UNIX is a registered trademark in the U.S. and other countries, licensed exclusively through X/Open Co. Ltd. All other products or name brands are trademarks of their respective holders. Acrobat Forms - JavaScript Object Specification 2 Table Of Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Other useful documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 What's New for 4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Acrobat Forms JavaScript Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 App Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 App Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 calculate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 formsVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 fullscreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 numPlugIns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 openInPlace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 toolbarHorizontal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 toolbarVertical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 viewerType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 viewerVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 App Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 alert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 beep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 execMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 getNthPlugInName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 goBack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 goForward . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 hideMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 hideToolbarButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 mailMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Color Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Color Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Color Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Console Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Console Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 println . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Acrobat Forms - JavaScript Object Specification iii Doc Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Doc Access from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Doc Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 calculate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 creator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 creationDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 delay. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 dirty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 external . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 filesize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 modDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 numFields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 numPages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 numTemplates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 pageNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 producer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 subject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 zoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 zoomType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Doc Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 calculateNow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 exportAsFDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 getField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 getNthFieldName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 getNthTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 getURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 gotoNamedDest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 importAnFDF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 mailDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 mailForm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 resetForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 scroll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 spawnPageFromTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 submitForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Event Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Event Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Mouse Enter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Mouse Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Mouse Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Mouse Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Acrobat Forms - JavaScript Object Specification iv Keystroke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Validate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Calculate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Event Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 commitKey. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 modifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 rc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 selEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 selStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 shift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 willCommit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Field Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Field Access from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 borderStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 calcOrderIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 charLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 defaultValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 editable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 fillColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 highlight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 lineWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 multiline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 numItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 readonly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 strokeColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 textColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 textFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 textSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 userName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Acrobat Forms - JavaScript Object Specification v value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Field Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 buttonImportIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 clearItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 deleteItemAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 getArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 getItemAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 insertItemAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 setItems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Global Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Global Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 setPersistent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 this Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Variable and Function Name Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Util Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Util Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 printf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 printx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 printd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 scand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Implementation Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 JavaScript Locations and Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Plug-in folder level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Document level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Field level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Form Field Hierarchies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Form Field Hierarchies with JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Working With The Date Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Converting a Date to a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Converting a String to a Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Date Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Acrobat Forms and Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Restricting Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Restricting Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Digital Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Working with Signature Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Acrobat Forms - JavaScript Object Specification vi JavaScript Object Specification Introduction JavaScript, the scripting language developed by Netscape Communications, enables you to easily create interactive Web pages. JavaScript v1.2 comes with six predefined 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 access to portions of the PDF file. This document describes these classes, as well as details the load and execution of JavaScripts in the Adobe Acrobat environment. Of particular note is the Field Object section which handles all processing of Acrobat Form fields including their formatting, calculation, and validation. The intended audience of this document is assumed to be familiar with Adobe Acrobat, the Acrobat Forms plug-in and the Adobe Acrobat plug-in API. Other useful documents For more information on JavaScript, please see Netscape's JavaScript Reference Manual for details on JavaScript objects and on language syntax. Portable Document Format Reference Manual, version 1.2 or later, describes the PDF representation of a form and its fields. Appendix H, describes the Forms Data Format, which is one of the formats of data exported from an Acrobat form. This document is available with the Adobe Acrobat Plug-ins SDK CD-ROM or on the Adobe Web site http://www.adobe.com/ supportservice/devrelations/PDFS/TN/PDFSPEC.PDF. Technical Note #5166, Acrobat Viewer plug-in API Overview. Gives an overview of the objects and methods provided by the Acrobat viewers' plug-in API. This document is available with the Adobe Acrobat Plug-ins SDK CD-ROM or on the Adobe Web site http://beta1.adobe.com/ ada/acrosdk/DOCS/VWRPIOVR.PDF. Technical Note #5167, Acrobat Viewer plug-in API Development. Tells how to develop Acrobat viewer plug-ins on the various platforms available. This document is available with the Adobe Acrobat Plug-ins SDK CD-ROM or on the Adobe Web site http://beta1.adobe.com/ ada/acrosdk/DOCS/VWRPIDEV.PDF Technical Note #5168, Acrobat Viewer plug-in API On-Line Reference. Describes in detail the objects and methods provided by the Acrobat viewer's plug-in API. This document is available Acrobat Forms - JavaScript Object Specification 7 with the Adobe Acrobat Plug-ins SDK CD-ROM or on the Adobe Web site http:// beta1.adobe.com/ada/acrosdk/DOCS/VWRPIREF.PDF. Document Conventions As this document pertains to Acrobat Forms version 3.5 and greater, there exists some 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 versions of the Acrobat Forms software greater than or equal to #.#. Before accessing this object, property, 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 JavaScript extensions to Acrobat Forms have evolved, some properties or methods have been superseded by other, more flexible or appropriate properties or methods. The use of these older methods are discouraged and marked by Mr. Unhappy. Acrobat Forms - JavaScript Object Specification 8 What's New for 4.0 Object App Object Properties formsVersion, numPlugIns, openInPlace, toolbarHorizontal, toolbarVertical, viewerVersion dkGray, gray, ltGray calculate, delay, external, numFields exportAsFDF(), getNthFieldName(), getURL(), importAnFDF(), mailDoc(), mailForm(), spawnPageFromTemplate(), submitForm() setItems(), deleteItemAt() scand() Methods getNthPlugInName(), hideMenuItem(), hideToolbarButton(), mailMsg() Color Object Doc Object Field Object Util Object display Note: Items shown in italics are not new to this release but they have been modified or added to. New sections of the documentation for 4.0: New Section Working With The Date Object Acrobat Forms and Security Working with Signature Fields Description 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 including inverse operations upon form reset Acrobat Forms - JavaScript Object Specification 9 Acrobat Forms JavaScript Object Model Acrobat Forms defines an object model on top of JavaScript 1.2. These objects are only defined within the Adobe Acrobat 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 order to query and change their properties. In addition to defining forms specific objects, there are additional generic objects that allows the developer to access 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 set 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 also the document calculate property which supersedes this property in later versions. formsVersion Type: Number Access: R 4.0 This property indicates the version number of the forms software running inside the viewer. Use this method to determine whether objects, properties, or methods in newer versions of the software are available if you wish to maintain backwards compatibility in your scripts. See Document Conventions for more details. Example: if (typeof app.formsVersion != "undefined" && app.formsVersion >= 4.5) { // Perform version specific operations here. } fullscreen Type: Boolean Access: R/W Acrobat Forms - JavaScript Object Specification 10 This property 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 true. If app.fullscreen was false then default viewing mode would be set. The default viewing mode is defined as the original mode the Acrobat application was in before full screen mode was initiated. language Type: String Access: R This property defines the language of the running Acrobat Viewer. It returns the following strings: String DEU ENU ESP FRA ITA JPN NLD SVE Language, Country German, Germany English, The United States of America Spanish, Spain French, France Italian, Italy Japanese, Japan Dutch, The Netherlands Swedish, Sweden numPlugIns Type: Number Access: R 4.0 This property indicates the number of plug-ins that have been loaded by Acrobat. See also the getNthPlugInName method. openInPlace Type: Number Access: R/W 4.0 This property determines whether cross-document links are opened in the same window or opened in a new window. Acrobat Forms - JavaScript Object Specification 11 platform Type: String Access: R This property returns the platform that the script is currently executing on. Valid values include "WIN", "MAC", and "UNIX". toolbar Type: Boolean Access: R/W This property allows a script to show or hide both the horizontal and vertical 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 4.0 This property allows a script to show or hide the Acrobat horizontal tool bar. It does not hide the tool bar in external windows (i.e. in an Acrobat window within a Web browser). toolbarVertical Type: Boolean Access: R/W 4.0 This property allows a script to show or hide the Acrobat vertical 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 running Acrobat Viewer is the Reader vs. Exchange. Its value is "Reader" or "Exchange" respectively. viewerVersion Type: Number Access: R 4.0 This property indicates the version number of the current viewer (i.e. Reader or Exchange). Acrobat Forms - JavaScript Object Specification 12 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 the nIcon parameter. The following is a list of icons and their associated values: Icon Error (default) Warning Question Status Value 0 1 2 3 Additionally, a button group type can be specified: Button Group OK (default) OK, Cancel Yes, No Yes, No, Cancel Value 0 1 2 3 This method returns the type of the button that was pressed by the user: Button Type Error OK Cancel No Yes Value 0 1 2 3 4 beep Parameters: [nType] Returns: none Acrobat Forms - JavaScript Object Specification 13 This method causes the system to play a sound. The various sounds and the values used are as follows: Message Type Error (default) Warning Question Status Default Value 0 1 2 3 4 On Apple Macintosh and UNIX systems the beep type is ignored. execMenuItem Parameters: cMenuItem Returns: nothing 4.0 This method executes the specified 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 security reasons, we will not allow the script to execute the SaveAs and Close menu items. If either of those two menu items is passed as cMenuItem, this function will do nothing. getNthPlugInName Parameters: nIndex Returns: cName 4.0 This method returns the name of the Nth plug-in that has been loaded by the viewer. See also the numPlugIns property. Acrobat Forms - JavaScript Object Specification 14 goBack Parameters: None Returns: nothing Use this function to go to the previous view on the view stack. This is equivalent to pressing the go back button on the Acrobat tool bar. goForward Parameters: None Returns: nothing Use this function to go to the next view on the view stack. This is equivalent to pressing the go forward button on the Acrobat tool bar. hideMenuItem Parameters: cName Returns: nothing 4.0 This method only works in the Config.js Plug-in folder level script. It allows a forms integrator to customize the look of the Acrobat viewer by removing the menu item specified by cName. Language independent names for toolbar buttons can be obtained from the Acrobat Viewer Plug-In API On-line Reference (Technical Note #5168). See Other useful documents for more details. hideToolbarButton Parameters: cName Returns: nothing 4.0 This method only works in the Config.js Plug-in folder level script. It allows a forms integrator to customize the look of the Acrobat viewer by removing the toolbar button specified by cName. Language independent names for toolbar buttons can be obtained from the Acrobat Viewer Plug-In API On-line Reference (Technical Note #5168). See Other useful documents for more details. mailMsg Parameters: bUI, cTo, [cCc], [cBcc], [cSubject], [cMsgBody] Returns: nothing 4.0 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. Acrobat Forms - JavaScript Object Specification 15 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 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 default value for the answer to the question. The return value is a string containing the user's response. If the user presses the cancel button on the dialog the response is the null object. Acrobat Forms - JavaScript Object Specification 16 Color Arrays A color is represented in JavaScript as an array containing 1, 2, 4, or 5 elements corresponding to a transparent, gray, RGB, or CMYK color space, respectively. The first element in the array 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 0 1 3 4 Transparent Gray RGB CMYK "T" "G" "RGB" "CMYK" For example, the color red can be represented as ["RGB" 1 0 0]. Invalid strings or insufficient elements in a color array cause the color to be interpreted as the color black. A transparent color space 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 color space are represented by three values: the intensity of the red, green, and blue components in the output. RGB is commonly used for video displays because they are generally based on red, green, and blue phosphors. Colors in the CMYK color space are represented by four values. These values 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 used in four-color printing. Only cyan, magenta, and yellow are necessary, but black is generally used 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 color object is a convenience static object that defines the basic colors. These colors are accessed in JavaScripts via the color object. Use this object whenever you want to set a property or call a method that require a color array. The color object is defined in AForm.js. Acrobat Forms - JavaScript Object Specification 17 Color Properties The color object defines the following colors and there associated keywords: Color Object Transparent Black White Red Green Blue Cyan Magenta Yellow Dark Gray Gray Light Gray Keyword color.transparent color.black color.white color.red color.green color.blue color.cyan color.magenta color.yellow color.dkGray color.gray color.ltGray Version 4.0 4.0 4.0 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) f.textColor = color.red; else f.textColor = color.black; Acrobat Forms - JavaScript Object Specification 18 Console Object The Console object is a static object to access the JavaScript console for displaying debug messages. It functions only within Acrobat Exchange. Console Methods show Parameters: none Returns: none This method shows the console window. hide Parameters: none Returns: none This method closes the console window. println Parameters: cMessage Returns: none 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 console windows buffer of any output. Acrobat Forms - JavaScript Object Specification 19 Doc Object The JavaScript Doc object provides the interfaces between a PDF document open in the viewer and the JavaScript interpreter. It provides methods and properties of the PDF document. Doc Access from JavaScript Accessing the Doc object from 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 4.0 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 This property defines the creator of the document (e.g. "Adobe FrameMaker", "Adobe PageMaker", etc.). Acrobat Forms - JavaScript Object Specification 20