Hide Notes 

Slide 1: bc Adobe® Acrobat® Technical Note # 5186 Acrobat JavaScript Object Specification Version 5.0 Revised: March 1, 2001
Slide 2: © 2001 Adobe Systems Incorporated. All rights reserved. The information in this document is furnished for informational use only, is subject to 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, 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 JavaScript Object Specification 2
Slide 3: Table of Contents Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Welcome to Acrobat™ JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is JavaScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is Acrobat™ JavaScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Quick Bars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . If You Need Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Useful Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Started with Acrobat™ JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where Can You Use JavaScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JavaScripts within the Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JavaScripts external to the Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A Quick Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Core Language Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Undefined Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Punctuation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Specification for Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Quick Help for Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dealing With Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing JavaScripts in Acrobat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Editing all JavaScripts in a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . External Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tabbing within the Internal Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Interactive JavaScript Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executing JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tips for Writing Reliable Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using JavaScript in PDF Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Organizing Your Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Binding Field Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formatting and Validation Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advanced Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PDF Is Not HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 15 15 15 16 16 16 17 18 20 20 20 23 24 25 25 27 28 29 29 30 31 31 5.0 32 33 33 33 33 34 34 36 36 37 38 38 39 40 What’s New For . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.0 Acrobat Forms - JavaScript Object Specification 1
Slide 4: 41 Other . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.0 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 ADBC Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADBC properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JavaScript Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADBC methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getDataSourceList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . newConnection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Annot Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Annotation Access from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Annot Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . arrowBegin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . arrowEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . attachIcon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . fillColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gestures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . modDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . noteIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . noView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . point. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . points. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . popupOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . popupRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . quads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . readOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strokeColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . textFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . textSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . soundIcon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 46 46 46 47 47 47 49 49 50 50 51 51 52 52 52 52 53 53 54 54 54 54 55 55 55 55 56 56 57 57 57 57 58 58 58 58 59 59 59 60 Acrobat Forms - JavaScript Object Specification 2
Slide 5: Annot Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setProps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . App Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . App Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . activeDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . calculate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . focusRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . formsVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . fs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . fullscreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . numPlugIns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . openInPlace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . plugIns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toolbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toolbarHorizontal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toolbarVertical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viewerType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viewerVariation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viewerVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . App Object Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . addMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . addSubMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . alert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . beep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clearInterval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clearTimeOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . execMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getNthPlugInName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . goBack. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . goForward . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hideMenuItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hideToolbarButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listMenuItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . listToolbarButtons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mailMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . newDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . openDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . popUpMenu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setInterval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTimeOut. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 60 60 61 62 62 62 62 63 63 63 63 64 65 65 65 65 66 66 66 67 67 67 67 67 68 69 70 70 71 71 72 73 73 73 73 74 74 75 75 76 77 78 78 79 Acrobat Forms - JavaScript Object Specification 3
Slide 6: Bookmark Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bookmark Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . children . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bookmark Object Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createChild . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . insertChild . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Color Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Color Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Color Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Color Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . convert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connection Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connection methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . newStatement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTableList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getColumnList. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Console Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Console Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . println . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . creationDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . modDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MIMEType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 81 81 81 82 82 82 82 83 83 83 84 84 84 86 86 87 87 87 88 89 89 89 89 90 92 92 92 92 92 92 93 93 93 93 93 93 94 94 Doc Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Doc Access from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Acrobat Forms - JavaScript Object Specification 4
Slide 7: Doc Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . baseURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . bookmarkRoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . calculate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . creator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . creationDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dataObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dirty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . external . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filesize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . modDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . numFields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . numPages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . numTemplates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pageNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . producer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . securityHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . selectedAnnots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spellDictionaryOrder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . subject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . zoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . zoomType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Doc Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . addAnnot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . addField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . addIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . addThumbnails. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . addWeblinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . bringToFront . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . calculateNow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . closeDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createDataObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createTemplate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deletePages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deleteSound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 95 96 96 96 97 97 97 97 98 98 98 98 99 100 101 101 101 101 101 102 102 102 102 103 103 103 104 104 104 105 105 105 106 106 106 107 108 108 109 109 109 110 110 111 111 Acrobat Forms - JavaScript Object Specification 5
Slide 8: exportAsFDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . exportAsXFDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . exportDataObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . extractPages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . flattenPages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getAnnot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getAnnots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getDataObject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getNthFieldName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getNthTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPageBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPageLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPageNthWord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPageNthWordQuads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPageNumWords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPageRotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPageTransition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getSound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gotoNamedDest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . importAnFDF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . importAnXFDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . importDataObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . importIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . importSound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . importTextData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . insertPages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mailDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mailForm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . movePage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeDataObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeField. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeThumbnails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeWeblinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . replacePages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . resetForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . saveAs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . scroll. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . selectPageNthWord. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setPageBoxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 113 114 114 115 116 116 118 118 119 119 119 120 120 121 121 122 122 123 123 124 124 124 125 125 126 127 128 129 129 130 131 131 132 133 133 133 133 134 134 135 135 136 137 137 137 Acrobat Forms - JavaScript Object Specification 6
Slide 9: setPageLabels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setPageRotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setPageTransitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spawnPageFromTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . submitForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . syncAnnotScan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Type/Name Combinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . App/Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Batch/Exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bookmark/Mouse Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Console/Exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Doc/DidPrint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Doc/DidSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Doc/Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Doc/WillClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Doc/WillPrint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Doc/WillSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . External/Exec. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field/Blur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field/Calculate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field/Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field/Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field/Keystroke. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field/Mouse Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field/Mouse Enter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field/Mouse Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field/Mouse Up. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field/Validate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Link/Mouse Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Menu/Exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page/Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page/Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Event Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form Event Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . changeEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . commitKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . keyDown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . modifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . selEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . selStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 139 139 140 141 143 144 144 144 144 144 145 145 145 145 146 146 146 146 147 147 147 148 148 149 149 149 149 150 150 150 151 151 151 152 152 152 152 153 153 154 154 154 154 154 Acrobat Forms - JavaScript Object Specification 7
Slide 10: shift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . targetName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . willCommit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field Access from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . borderStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . buttonAlignX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . buttonAlignY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . buttonPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . buttonScaleHow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . buttonScaleWhen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . calcOrderIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . charLimit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . currentValueIndices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . defaultValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doNotScroll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doNotSpellCheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . editable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . exportValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . fileSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . fillColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . highlight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lineWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . multiline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . multipleSelection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . numItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . readonly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strokeColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 155 155 155 156 156 157 158 158 158 158 158 159 159 160 160 160 161 161 161 163 163 163 163 164 164 165 165 165 166 166 167 167 168 168 169 169 169 169 170 170 170 171 171 172 Acrobat Forms - JavaScript Object Specification 8
Slide 11: submitName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . textColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . textFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . textSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . userName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . valueAsString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . browseForFileToSubmit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . buttonGetCaption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . buttonGetIcon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . buttonImportIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . buttonSetCaption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . buttonSetIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . checkThisBox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clearItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . defaultIsChecked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deleteItemAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getItemAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . insertItemAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . isBoxChecked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . isDefaultChecked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setAction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setFocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setItems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . signatureInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . signatureSign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . signatureValidate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FullScreen Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FullScreen Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . backgroundColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clickAdvances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cursor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . defaultTransition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . escapeExits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . isFullScreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . timeDelay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . usePageTiming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . useTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 172 173 174 174 174 175 176 176 176 176 177 177 178 179 180 180 180 181 181 182 183 183 184 184 185 185 186 188 189 191 191 191 191 191 192 192 192 192 193 193 193 194 Global Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Acrobat Forms - JavaScript Object Specification 9
Slide 12: Global Object Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setPersistent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . subscribe. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Identity Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Identity Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . corporation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . loginName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index Object Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PlugIn Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PlugIn Object Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . certified. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . loaded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PPKLite Signature Handler Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PPKLite Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . isLoggedIn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . loginName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . loginPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . signInvisible. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . signVisible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uiName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PPKLite Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . newUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setPasswordTimeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 195 195 196 198 198 198 198 198 198 199 199 199 199 199 199 200 200 200 200 200 201 201 202 203 203 204 204 204 204 205 205 205 205 205 206 206 207 Report Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Report Object properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Acrobat Forms - JavaScript Object Specification 10
Slide 13: absIndent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . breakPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . divide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . indent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . outdent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . writeText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Search Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Search Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . matchCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . maxDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . proximity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . refine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . soundex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . thesaurus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Search Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . addIndex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getIndexForPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . validateSignaturesOnOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security Object Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sound Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sound Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sound Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . play. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 208 209 209 209 209 210 210 210 211 211 211 213 213 213 213 213 214 214 214 214 214 215 215 215 215 215 216 217 217 217 217 217 217 219 219 219 219 219 219 219 Spell Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 Acrobat Forms - JavaScript Object Specification 11
Slide 14: Spell Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dictionaryNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dictionaryOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . domainNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Spell Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . addDictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . addWord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . checkText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . checkWord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeDictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeWord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . userWords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Statement Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Statement properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . columnCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rowCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Statement methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getColumnArray. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . nextRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Template Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Template Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Template Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spawn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TTS Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TTS Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . numSpeakers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . soundCues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . speaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . speechCues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . speechRate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . volume. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TTS Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getNthSpeakerName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 220 220 220 221 221 221 222 222 223 223 224 225 225 226 226 226 226 226 226 227 228 228 229 231 231 231 231 231 231 233 233 233 233 233 234 234 234 234 234 235 235 235 Acrobat Forms - JavaScript Object Specification 12
Slide 15: qSilence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . qSound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . qText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . resume. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . talk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 235 236 236 236 236 237 this Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 Variable and Function Name Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 Util Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Util Object Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . printf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . printd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . printx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . scand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 240 240 241 243 243 A Short Acrobat JavaScript FAQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Where can JavaScripts be found and how are they used?. . . . . . . . . . . . . . . . . . . 245 Folder Level JavaScripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Document level. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Field level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 How should I name my form fields? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 How do I use date objects? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Converting from a Date to a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Converting from a string to a date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Date arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 How can I make my document secure? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Restricting Access to the Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Restricting Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Digital Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 How can I lock a document after a signature field has been signed?. . . . . . . . . 252 How can I make my documents accessible? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Document Meta-Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Short Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Setting tab order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Use the TTS object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Default Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 How can I define globals in JavaScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Making Globals Persistent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 How can I send form data to an e-mail address? . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 How can I hide a field based on the value of another? . . . . . . . . . . . . . . . . . . . . . . 256 How can I query a field value in another open form from the form I'm working on? 256 How can I intercept keystrokes one by one as they occur? . . . . . . . . . . . . . . . . . . 256 Acrobat Forms - JavaScript Object Specification 13
Slide 16: How can I build a nested popup menu? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How can I construct my own colors? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How can I prompt the user for a response in a dialog?. . . . . . . . . . . . . . . . . . . . . . How can I fetch an URL from JavaScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How can I change the hot-help text for a field dynamically? . . . . . . . . . . . . . . . . How can I change the zoom factor programmatically? . . . . . . . . . . . . . . . . . . . . . How can I determine if the mouse has entered/left a certain area? . . . . . . . . . . What are Rotated User Space and Default User Space? . . . . . . . . . . . . . . . . . . . . . Rotated User Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default User Space. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Graphical Relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How can I create a form field programmatically? . . . . . . . . . . . . . . . . . . . . . . . . . . Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Check Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Combo Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . List Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Radio Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Quick Reference: Forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appearance: All Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Action: All Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Options: Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Options: Check Box and Radio Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Options: Combo and List Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Options: Text Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format: Combo and Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validate: Combo and Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calculate: Combo and Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Signed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selection Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How can I create an Annotation programmatically?. . . . . . . . . . . . . . . . . . . . . . . . Circle and Square Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Line Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stamp Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FreeText Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Text Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ink Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Highlight, Strikeout, Underline and Squiggle . . . . . . . . . . . . . . . . . . . . . . . . . 257 257 257 257 258 258 258 258 258 258 259 261 261 264 265 269 270 271 273 275 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 Acrobat Forms - JavaScript Object Specification 14
Slide 17: Acrobat JavaScript Object Specification Introduction Welcome to Acrobat™ JavaScript Welcome to the Acrobat 5.0 JavaScript Reference Manual. In the pages to follow, you'll find all the information you need to get started using JavaScript in your PDF documents. With the aid of Acrobat's powerful JavaScript binding, you'll be able to customize forms and other documents in ways that greatly enhance their appearance, utility, and interactivity. This manual is not only a reference for Acrobat’s JavaScript objects, properties and methods, it also includes some instruction on the basics of JavaScript programming and numerous useful examples that illustrate the properties and methods of Acrobat JavaScript as well as relevant programming techniques. What Is JavaScript? JavaScript is the powerful, object-oriented scripting language developed by Netscape Communications to enhance web-page interactivity. Originally designed for Netscape's browser software, JavaScript has rapidly evolved to become a widely used, general-purpose programming language. It is now accepted as a standard under ISO-16262 of the International Standards Organization. (The first industry-standard version of the language, endorsed by the European Computer Manufacturers Association, was known as ECMAScript.) The core language has undergone several revisions, the most current being version 1.5, the one used by Acrobat 5.0. What Is Acrobat™ JavaScript? Core JavaScript has been extended in various implementations to meet various needs. Clientside (browser based) JavaScript adds objects and methods to manipulate browser windows and their contents. Server-side JavaScript adds File and Database objects to deal with database queries and other typical server-side actions. Acrobat™ JavaScript extends the language by adding objects and methods designed to allow easy access to (and manipulation of) PDF document contents. The various extensions to the language that make this possible are described in detail in this manual. The same characteristics that make browser-based JavaScript easy to work with—relaxed data typing, C-like syntax, built-in Math and String classes—are applicable to Acrobat™ Acrobat JavaScript Object Specification 15
Slide 18: JavaScript as well. In fact, Acrobat™ JavaScript is built on top of core JavaScript. All of the core-language features that you might be accustomed to working with in browser-based, JavaScript are available in Acrobat™ JavaScript, including Math, String, Date, Array, and RegExp (regular expression) classes. Space considerations preclude a detailed discussion of core-JavaScript features here. This manual assumes that you have had some exposure to JavaScript as it is typically used in a browser environment. (For more information on the core language, you should visit http:// developer.netscape.com/library/documentation/javascript.html on the Web, or consult the computer programming section of any good bookstore.) If you already have some JavaScript programming experience, you will still find this manual helpful for making the transition from browser-based JavaScript to Adobe Acrobat JavaScript. You will learn how to access information about the PDF document, including properties like zoom factor and file size, as well as information about the runtime environment, such as the host computer platform and whether a document is being viewed in Acrobat, or Acrobat Reader. In addition, you will learn how to use built-in methods to access the field information in forms and modify form contents (including appearance attributes) at runtime. Document Conventions Tips From time to time, you will see tips offered in boxes, like this: Tip: This is where you’ll find a good idea or two. The comments offered in these boxes are optional—you can skip over them, if you want. Nevertheless, they are designed to give you practical “real-world” solutions to problems or situations that you are likely to encounter in your coding. Quick Bars There are symbols that are shown at the beginning of most every property or method in a “quick” bar for quick interpretation. Example: 5.0 = B V #.# The first column is a number that indicates indicates in which version of the software a property or method became available. As this document pertains to Acrobat version 5.0, there exist some compatibility issues with older versions of the software. If the number is specified, then the property or method is available only in versions of the Acrobat software greater than Acrobat Forms - JavaScript Object Specification 16
Slide 19: or equal to that number. Before accessing this property or method, the script should check that the forms version is greater than or equal to that number if backwards compatibility is desired. Example: if (typeof app.formsVersion != "undefined" && app.formsVersion >= 5.0) { // Perform version specific operations. } If the first column is blank, then no compatibility checking is necessary. 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 L in the version column. = The second column, if not blank, indicates that using this method or property will modify the PDF document. If the document is subsequently saved, the effects of this method are saved as well. E The second column can also contain the preferences symbol that indicates that even though this property does not change the document, it can permanently change a user’s application preferences. during certain events for security reasons (e.g. batch event, application start, or execution within the console). See the discussion in the section on the Event Object for more details of the various Acrobat events. B The third column, if not blank, indicates that this method or property may only be available V The fourth column, if not blank, indicates that this method or property is not available in the Acrobat Reader. If You Need Help The Web offers a great many resources to help you with JavaScript in general as well as JavaScript for PDF. For example: • http://www.adobe.com/support/forums/main.html—Adobe Systems, Inc. provides dedicated online support forums for all Adobe products, including Acrobat and Acrobat Reader. • http://www.adobe.com/support/database.html—In addition to the forums, Adobe maintains a searchable support database with answers to commonly asked questions. • http://www.pdfzone.com/resources/lists.html—The PDFZone website operates discussion forums on PDF forms, PDF development, and Acrobat usage, among other topics. Experts from around the world participate in these forums to help answer users' questions. • http://forum.planetpdf.com/—This popular area of the PlanetPDF website contains discussion forums for beginners, developers, forms integrators, and more. As with the PDFZone lists, experts from around the world participate in the Planet PDF Forum (formerly known as AcroBuddies). Acrobat Forms - JavaScript Object Specification 17
Slide 20: • PlanetPDF (http://www.planetpdf.com) has a section specifically devoted to JavaScript examples, called Planet PDF Developers. The ultimate authority on the core JavaScript language continues to be its originator, Netscape Communications. See http://developer.netscape.com/library/documentation/javascript.html for a list of current documentation devoted to JavaScript. Useful Documents Core JavaScript 1.4 Documentation Complete documentation for JavaScript 1.5, the version used by Acrobat 5.0, is available on the web at http://developer.netscape.com/docs/manuals/javascript.html. Core JavaScript Guide, Part I. Core Language Features, Netscape Communications Corporation. Part I of this document gives a conceptual overview of the core JavaScript language. Available in both html and PDF format. http://developer.netscape.com/docs/manuals/ js/core/jsguide15/contents.html. Note: The rest of the document concerns Netscape’s extensions to core JavaScript and are not applicable in the Acrobat environment. Core JavaScript Reference, Part I. Object Reference and Part II. Language Elements, Netscape Communications Corporation. Parts I and II are a reference to the core JavaScript language. Available in both html and PDF format. http://developer.netscape.com/docs/manuals/js/core/ jsguide15/contents.html. Note: The rest of the document concerns Netscape’s extensions to core JavaScript and are not applicable in the Acrobat environment. Adobe Web Documentation PDF Reference, second edition, Adobe Portable Document Format, Version 1.3, Adobe Systems Incorporated, published by Addison-Wesley, July 2000. This document is available in bookstores, and in electronic form at http://partners.adobe.com/asn/developer/acrosdk/docs/ PDFRef.pdf. Technical Note #5190, Acrobat Viewer plug-in API Overview. Gives an overview of the objects and methods provided by the plug-in API of the Acrobat viewer. This document is available with the Adobe Acrobat Plug-ins SDK CD-ROM or on the Adobe Web site http:// partners.adobe.com/asn/developer/acrosdk/docs/apiovr.pdf. Technical Note #5167, Acrobat Viewer plug-in API Development. Describes 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://partners.adobe.com/ asn/developer/acrosdk/docs/apidev.pdf. Technical Note #5191, 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 with the Adobe Acrobat Plug-ins SDK CD-ROM or on the Adobe Web site http:// partners.adobe.com/asn/developer/acrosdk/docs/apiref.pdf. Acrobat Forms - JavaScript Object Specification 18
Slide 21: Adobe CD Documentation There are a variety of documents and samples on the Acrobat CD that discuss using JavaScript in a variety of ways. Batch Sequences: an indepth discussion of batch sequences and how to use JavaScript to solve common problems. Getting Started with ADBC: a primer for accessing database information through the Acrobat Database Connectivity object including a sample mail merge batch sequence. Tutorial on form field authoring: discusses creating and manipulating form fields with a stepby-step introduction to authoring an invoice. Forms System Implementation Notes: this document discusses interfacing Acrobat and web servers for form submission. What’s In A Name: this document talks about how the names for fields can make a big difference in form authoring and processing. Acrobat Forms - JavaScript Object Specification 19
Slide 22: Getting Started with Acrobat™ JavaScript JavaScript programming opens up exciting new vistas for authors of PDF documents. With relatively little effort, you'll find that you can use JavaScript to enhance PDF documents in countless ways. For example, you can use JavaScript to: • Execute menu commands (in Acrobat or Reader) programmatically. • Issue system beeps and alerts. • Format form input as the user is entering it. • Bind field dependencies in a form. • Change the appearance of form fields (including background colors and text fonts) in response to user actions. • Cause e-mail to be sent automatically if the user clicks a link or button. • Query a user for input via a “response” dialog, from a regular PDF document or inside a form. • And much more. In this section, we'll explore the basics of the JavaScript language and begin to look at some of the ways in which the core language has been expanded to accommodate PDF-related features and functionality. Along the way, we'll provide a few tips for making your code more reliable and easier to maintain. If you are new to programming, don't expect to understand every single point. It takes a while to get used to programming conventions, and during the learning process you're bound to make mistakes. But with relatively little effort, you should be able to craft your own basic JavaScripts (based on the working code examples shown here) in no time. Where Can You Use JavaScript? JavaScripts are either part of the PDF document itself, or exterior to the document. JavaScripts within the Document There are six ways in which you can attach JavaScript to PDF documents: 1. You can add JavaScript to Page Open or Page Closed actions. (In Acrobat, use Document->Set Page Action...) Scripts added here will execute each time a page opens (or closes), including the first time a document opens or immediately before a document closes. You can add JavaScripts to Document Actions. (In Acrobat, use Tools-> JavaScript-> Set Document Actions...). Scripts can be added for several types of document related actions like Document Will Close (when a document closes), Document Will Save (right before a document is 2. Acrobat Forms - JavaScript Object Specification 20
Slide 23: saved), Document Did Save (right after a document is saved), Document Will Print (right before a document is printed), Document Did Print (right after a document is printed). 3. You can add JavaScript to Bookmarks. In Acrobat, after creating a Bookmark with Control-B (or Command-B), bring up the Bookmark Properties dialog using Control-I (or Command-I). Be sure a Bookmark is selected first. When the Bookmark Properties dialog appears, choose JavaScript from the Action popup menu, as shown below: After choosing JavaScript, click the Edit… button to add a script to the Bookmark. The script you add here will execute every time the Bookmark is clicked. 4. You can also add JavaScript to a Link created by means of Acrobat's Link Tool. Either select an existing link, or enable the Link tool (by pressing the 'L' key on your keyboard) and drag out the outline of a new link somewhere on the page. When you've created a new link, the Create Link/Link Properties dialog will appear. (If you've selected a preexisting link, you can make the Link Properties dialog appear with Control-I/Command-I.) In the Action Type popup, select JavaScript and hit the Edit… button to add or edit your script. Acrobat Forms - JavaScript Object Specification 21
Slide 24: 5. Document-level (or so-called "top level") JavaScripts can be added in Acrobat by using Tools->JavaScript->Document JavaScripts... When the dialog appears, you can add your own custom JavaScript functions here, as shown below: Any code you add at this level can be "seen" (that is, called or used) from any other JavaScripts in the document, which is why this is often called "top-level" code. Acrobat Forms - JavaScript Object Specification 22
Slide 25: 6. Finally, you can add JavaScript to individual form fields created using the Form Tool. Either doubleclick an existing field, or use the Form Tool (type 'F' on the keyboard to enable it) and drag out the outline of a new field, to bring up the Field Properties dialog: Within this dialog, there are several ways to add JavaScripts to a field. The Actions tab exposes a pane (as shown above) in which you can add JavaScripts via the Add… button. Note that when adding JavaScripts to Button fields (the case shown here), you can attach separate scripts to Mouse Up, Mouse Down, Mouse Enter, and Mouse Exit button events, as well as On Focus and On Blur. You can also add more than one script to one event (they are executed sequentially in the order you add them.) Other field types expose other areas where JavaScripts can be added. For example, Text fields not only have mouse-event actions but can accept JavaScripts as Format, Validate, and/or Calculation scripts. (Appropriate panes exist for these options when "Text" is selected in the Type popup in the Field Properties dialog.) JavaScripts external to the Document In addition to JavaScripts that are saved with the document, JavaScripts external to the document can be executed as well. There are three other ways external JavaScripts can be executed. Acrobat Forms - JavaScript Object Specification 23
Slide 26: 1. Folder Level JavaScripts: JavaScripts can be saved in a file, with file extension of .js, and placed in one of the two JavaScript folders (the application and user folders). When the Acrobat application starts up, the application reads these folders and executes any JavaScript files found. Console JavaScripts: JavaScripts can be typed into the Acrobat console and executed. See the Console Object for a discussion of this feature. This is mostly a testing feature of Acrobat. Batch JavaScripts, also called batch sequences. Beginning with Acrobat 5.0, a powerful batch system for the execution of JavaScript for each file that has been selected to be processed. See the document “Batch Sequences: Tips, Tricks and Examples” available one the Acrobat CD for more details. 2. 3. A Quick Example One of the most common uses for JavaScript is to enable a calculation or other action in conjunction with a mouse or keyboard event associated with a form field. For example, you may want a script to execute whenever a user presses a button on a form. To set this up, you would click the Actions tab inside the Form Properties dialog (as shown above), then Add a JavaScript to a mouse event—most likely a mouse-up event. When adding JavaScript to a form field, you will see the following kind of dialog box for doing script editing: Whatever you type in this box will be executed when the appropriate event occurs in conjunction with the field that the script is attached to. In this example, we have attached a small script (with one line of JavaScript code) to a Button field's mouse-up event. The code issues a standard system beep, using the beep method of the App Object class. The net result is that whenever the user presses the button in the form, the mouse-up event occurring inside the Acrobat Forms - JavaScript Object Specification 24
Slide 27: button will generate a system beep. (This is obviously a rather trivial example, but it shows how to attach custom JavaScript code to mouse events in form fields.) Tip: It is considered a good user interface design practice to associate script actions with mouse-up (rather than mouse-down) events. The reason most scripts should execute only after the user lets his finger off the mouse button is that until then, the user may wish to reconsider what he is doing and move the mouse outside the button (cancelling the action before it happens). This is the default button behavior in most commercial software applications. Core Language Features Before we discuss features of Acrobat™ JavaScript that apply specifically to PDF documents, let's take a moment to review some of the fundamental concepts on which the JavaScript language is based. Data Types JavaScript supports primitive (core) data types—such as Booleans, numbers, and strings—as well as composite data types, like objects and functions. You’ll be working with primitive data types a lot. Consequently, it’s important that you understand what they mean and how JavaScript interprets them. Booleans are the simplest data type, since they can have just two values: true and false. Tip: Internally, JavaScript represents true and false values as 1 and 0, respectively. But anything that has a non-zero value will be evaluated by the JavaScript interpreter as true in a Boolean context. Numbers are represented using the standard scientific notation, for example, 3.14, 2000, or 6.023e+23. Unlike some other languages, JavaScript does not distinguish between integer or floating-point values: In JavaScript, all numbers (regardless of how you write them) are represented internally as 64-bit IEEE floating-point values. In base-ten terms, you have about 20 digits of precision in which to work, which ought to be fine for most applications. (If you can’t achieve the precision you’re looking for in JavaScript, chances are you won’t easily find it in other languages, either.) Note that you should not write integer values with preceding zeros in JavaScript, since JavaScript interprets '021' as the octal representation of the base-ten number 17. (In addition to octal triplets, you can write numbers in hexadecimal using the '0x' prefix: e.g., 0xFF represents a value of 255.) Acrobat Forms - JavaScript Object Specification 25
Slide 28: A string is a sequence of letters, digits, punctuation, or other characters enclosed in quotation marks. Single quotations or double quotations can be used; it doesn't matter. (If your string happens to contain double-quotes as part of the desired string sequence, you should enclose the entire string in single quotes. Likewise, if your string happens to contain single-quotes as part of the string sequence, you should enclose the entire string in double quotes.) The following are all legal string values: 'This will work.' "3.14" 'The password is "zxcv"' JavaScript recognizes a number of escape sequences for representing characters inside strings that would otherwise be impossible to represent. The following table summarizes those escape sequences. Table 1 JavaScript Escape Sequences Character Backspace Form feed Newline Carriage return Tab Single quote Double quote Backslash Unicode character specified by four hexadecimal digits Sequence \b \f \n \r \t \’ \” \\ \uXXXX Arrays are collections of data values. In JavaScript, the members of an array can be any primitive data type, and the same array can (if you want) hold different data types. As in the C language, members of an array are specified or accessed by numeric indexes enclosed in square brackets. Thus, to talk about the value stored in the first element of an array called names, you would refer to names[0]. The second element of the array would be names[1]; the third element, names[2], and so on. Tip: Bear in mind that core JavaScript has built-in classes, with many helpful (and powerful) utility methods, for Strings and Arrays, not to mention additional core-language classes such as Math, Date, and RegExp. All of these classes (and their associated methods) are available to you in Acrobat™ JavaScript. (For information on these classes and methods, consult any good book on JavaScript.) Acrobat Forms - JavaScript Object Specification 26
Slide 29: Variables JavaScript allows you to declare your own variables using the 'var' keyword. Some things you should know about variables in JavaScript: • All identifiers in JavaScript are case-sensitive, which means that a variable named 'MyVariable' is not the same as one named 'myVariable'. • Variables created in JavaScript are permanent, within their scope. Once you declare a variable, there is no way to "undeclare" or destroy it. (JavaScript's garbage-collection mechanism will automatically deallocate variables when you're through with them.) • All variables in JavaScript have a scope, which determines the variable's lifetime and accessibility (i.e., whether it is usable at a given time). Variables declared inside functions are said to have local scope, which means they can be used only inside the function in which they were declared. To declare a variable, simply type: var circumference; Or, you can declare a variable and initialize it in one statement: var circumference = 6.28; After declaring a variable, you no longer need to preface it with the 'var' keyword. You can simply use it in expressions as you would use any primitive data type. Tip: It is legal, in JavaScript, to declare a variable without using the 'var' keyword. But since (as we mentioned) all JavaScript variables must have a scope, this leaves the interpreter in a bit of a quandary as to how to "scope" a non-'var' variable. The interpreter resolves this problem by attaching the unscoped variable to the global object (the "mother of all runtime objects"), which has the effect of making the variable in question "usable" from all points in a program. This may or may not be what you want. Usually, it is not. Unlike most other “high level languages”, JavaScript is rather relaxed when it comes to variable typing. This means that you, as a programmer, don’t have to worry about telling JavaScript whether a given variable should behave like a number or a string. JavaScript will take its “best guess” and make a variable behave as a number in numeric contexts and as a string in string contexts. JavaScript is an object-oriented language, yet unlike Java or C++ requires no prototyping of objects. To create a new object, you can simply type: Acrobat Forms - JavaScript Object Specification 27
Slide 30: var hue = new Object(); This statement calls JavaScript's object constructor function which creates a generic, propertyless object. Once an object has been created, you can then assign fields (which can be properties or methods, depending on whether they refer to primitive data types or functions) to the object as follows: hue.favorite = "taupe"; hue.worst = "teal"; hue.maximum = 15; hue.sum = function (a,b) { return a + b; } All four statements are legal. The first three statements create properties and assign values to them. (In one case, the value is numeric; in the other two cases, the values are strings.) The fourth statement creates a new method for the object by assigning a function to it. The method can be called and used just like any other function: var x = hue.sum( 2, 2 ); // 'x' now has the value '4' In some ways, arrays and objects are alike, because both are collections of arbitrary data types. With arrays, the component pieces are accessed using numeric indexes and square brackets. With objects, the components are accessed through identifiers, using a period between the object name and the component name. Undefined Variables In JavaScript, as in other languages, if you attempt to use a variable in an expression without declaring it first, you will generate a runtime error. Odds are, the console window (in Acrobat Business Tools or full Acrobat) or a message box (in Acrobat Reader) will pop up, telling you (or your user!) that “such-and-so variable is not defined”. Consider the following code: function memberSum() { var member = new Object(); member.john = 1; return (totalmembers + member.john); } // create a new, blank object // create a new property, 'john' // error! In this scenario, totalmembers is a new variable that was not declared anywhere. Using it inside the return expression generates a runtime error. The line of code that creates member.john and assigns a value of '1' to it is not an error, since in JavaScript, you can create new properties for your objects on-the-fly like this. (See discussion under "Objects," above.) Earlier, we said that JavaScript has relaxed typing rules. This is not the same as saying that it is an untyped language. JavaScript does have data types; in fact, it is this very property that allows you to check a variable at runtime to see if it is defined. To test a variable to see if it is defined use the typeof operator: Acrobat Forms - JavaScript Object Specification 28
Slide 31: if (typeof aVariable == "undefined") // undefined variable? app.alert("Undefined variable."); else { // the variable is safe to use } Here, we use the App Object's predefined alert method to put an alert dialog onscreen if the variable being tested is not defined. Notice that JavaScript uses the C-like == operator to test for equality. Also note that strings are compared by value; hence two strings can be compared directly using the == operator. Comments You can insert comments in your JavaScript code using either the C++ or C-style commenting protocol. That is to say, any text between a double-slash (//) and the end of a line will be ignored by JavaScript. Also, any text between /* and */ will be treated as a non-executable item (or comment). The following are valid comment styles: // This is a single-line comment. /* This is also a comment. */ // as is this /* * * You can, if you want, also do this. * */ Comments are extremely important tools because they make programs much more readable and easier to maintain. JavaScript uses a succinct, C-like syntax, which means that you can accomplish a lot in just a few lines of code. Unfortunately, that also means you can very easily wind up with programs that are compact, but nearly indecipherable and hard to debug. As a result, you should take extra care to “comment your code” liberally as you write it. The net result will be code that's more reliable and more likely to make sense when you sit down six weeks from now to look at it again. Punctuation Strictly speaking, you do not have to put semicolons at the end of JavaScript statements (as you do with C or Java statements). Statements without semicolons will execute normally. However, it is good practice to insert semicolons wherever appropriate. Likewise, you can omit parentheses from certain constructor functions, such as: var n = new Object; But this, too, is not good form. Most functions require parentheses; using them in every case promotes consistency and readability. Acrobat Forms - JavaScript Object Specification 29
Slide 32: Parameter Specification for Methods 5.0 The parameter (or argument) list of a Acrobat JavaScript method can be specified in two ways: 1. Use the standard core JavaScript technique of listing the parameters separated by commas. Optional parameters may be specified, skipped over using an empty string, or truncated from the list. The parameters must be listed in the correct order. For example, app.alert("Hello World!", 1, 1); app.alert("Hello World!","",1); // Take default for second parameter app.response("How are you today?"); app.response("How are you today?","", "Fine"); // Specify cDefault only 2. Use an object literal to pass argument information to the method. An object literal is a “list of zero or more pairs of property names and associated values of an object, enclosed in curly braces ({})” 1. The following code lines repeat the examples above: app.alert( {cMsg: "Hello World!", nIcon: 1, nType: 1} ); app.alert( {cMsg: "Hello World!", nType: 1} ); app.response( {cQuestion: "How are you today?"} ); app.response( {cQuestion: "How are you today?", cDefault: "Fine"} ); The property names that appear in the object literal are the parameter names given in the specification of the method; for example, the app.response method begins this way: response Parameters: cQuestion, [cTitle], [cDefault], [bPassword] Returns: cResponse or null on cancel There is one required parameter, and three optional ones. The names of the parameters are the ones used in the creating the object literal as the argument of the App.response, see the examples above. (There is no significance to the name of the return value, cResponse, other than to suggest that the method returns a string.) Note: The object literal method of specifying parameters may not available be for all Acrobat JavaScript functions. 1. "Core JavaScript Guide", Version 1.4, Netscape Communications Corporation, October 30, 1998, page 31. Acrobat Forms - JavaScript Object Specification 30
Slide 33: Quick Help for Methods 5.0 As an added convenience, if you give any Acrobat method an argument of acrohelp and execute that method (for example, in the console editor), the method will return a list of its arguments names and types. Example: In the console, type app.response(acrohelp); While the cursor is still on the line you entered, press either Ctrl-Enter or the Enter key on the numeric key pad. The output to the console is seen to be: uncaught exception: Console:Exec:1: Help for App.response ====> [cQuestion: string] ====> [cTitle: string] ====> [cDefault: string] ====> [bPassword: boolean] Optional arguments are listed in square brackets; required parameters have no brackets. Dealing With Exceptions 5.0 Acrobat JavaScript methods will throw an exception on error. The script writer can better control these exceptions by using the try/catch/finally (JavaScript 1.4), possibly in conjunction with the throw statement. For example, try to connect to a database using the ADBC plugin. function getConnected() { try { ConnectADBCdemo = ADBC.newConnection("ADBCdemo"); if (ConnectADBCdemo == null) throw "Could not connect"; statement = ConnectADBCdemo.newStatement(); if (statement == null) throw "Could not execute newStatement"; if (statement.execute("Select * from ClientData")) throw "Could not execute the requested SQL"; statement.nextRow() // Statement.nextRow() throws an exception... return true; // if there is no next row } catch(e) { app.alert(e); return false; } Acrobat Forms - JavaScript Object Specification 31
Slide 34: } Developers and script writer can gain information about the structure of the exception object by executing the following script: try { app.alert(); // force an exception, one argument required for alert } catch(e) { for ( var i in e ) console.println( i + ": " + e[i]) // now display the error message, which is e.toString() console.println("e: " + e ); } Error handlers can be written to deal with exceptions thrown by one of the Acrobat plugins and by custom written JavaScript code, such as the first (very simple) example above. A very common case for throwing an exception is if the underlying object no longer exists (i.e. it is dead but a reference to the object still exists). Consider the following piece of code: var myDoc = app.newDoc(); myDoc.close(); myDoc.pageNum = 3; This will throw an exception when the third line is executed. The document has been closed and no longer exists. A reference to this document is still being held in myDoc and any attempt to use it will throw an exception: uncaught exception:Console :Exec:1: Doc.pageNum object is dead. Editing JavaScripts in Acrobat 5.0 5.0 V Editing all JavaScripts in a Document The user can now view and edit all JavaScripts in a PDF document via the Acrobat menu item Edit All JavaScripts (Tools-> JavaScript -> Edit All JavaScripts...). All the scripts will be displayed and organized by XML tags. You'll notice that you can easily identify one script among many via the XML tags content. It's very important not to edit the XML tags added for script identification purposes by Acrobat. Your changes may not be ccepted in case Acrobat finds they have been edited. The same feature can be accessed via buttons strategically located in some dialogs (e.g.: the Actions tab in the Form Fields Properties dialog). Acrobat Forms - JavaScript Object Specification 32
Slide 35: External Editor The user can now specify an External Editor program to edit JavaScripts in Acrobat. (Edit-> Preferences-> General-> JavaScript). You can choose and specify an external editor program which will be used any time a JavaScript has to be edited from inside Acrobat. Acrobat will generate a temporary file and open it in the external editor program. The user has to save the file in order for his changes to be accepted by Acrobat. Acrobat will be inaccessible to the user while the file is being edit in the external editor program. Close the editor to regain access to Acrobat. Note: This feature is not available on the Macintosh. Tabbing within the Internal Editor Pressing the Tab key will insert four spaces at the insertion point. Pressing Shift+Tab will move the cursor four (or less) spaces to the left. Highlighting a line, or a portion of a line, and then pressing Tab (or, Shift+Tab) will move the whole line to the right (respectively, to the left) four spaces (or less, in the case of Shift+Tab). Blocks of lines can be tabbed in the same way by first highlighting the lines then pressing either Tab or Shift+Tab. Interactive JavaScript Console 5.0 V The Acrobat JavaScript console is now editable and interactive. Any JavaScript code that you write to the console can now be immediately evaluated. The alternate <Enter> key on the Numeric pad, or, for Win and Mac users, the Ctrl+Return key combination, is used for that purpose. The descriptions for executing JavaScript and for tabbing within the console given below are valid for any of the internal JavaScript editors: the console, the document level JavaScript editor, the form action JavaScript editor, and so on. Executing JavaScript There are two basic ways of evaluating JavaScript code on the console. To evaluate a block of code, just type in the code, highlight it and hit the <Enter> key (Ctrl+Return). To evaluate a line of code, just locate the cursor on the line you want evaluated and hit the <Enter> key (Ctrl+Return) to obtain the results. Any immediate results of the code evaluated will be printed to the console. Be aware that when evaluating a block of code, only the result from the last JavaScript expression in the block will be printed to the console. Also, the result of an expression is not the same as the value of a Acrobat Forms - JavaScript Object Specification 33
Slide 36: variable set in the expression. For example, when evaluating the following expression where the variable "x" is set to a value of 0: var x = 0; The result below will be printed to the console: undefined This does not mean that the value of "x" is "undefined". It just means that the expression as a whole returns "undefined". To get the value of "x", highlight only the letter "x" in the expression, and hit the <Enter> key to get the value 0 as result. Sometimes it's also useful to use the console.println() method when using the console to get quick results. The native Acrobat JavaScript edit dialog can also be used to evaluate JavaScript code. It behaves the same way as the console except for the fact that the results will still be output to the console. This is so that the code you are entering on the edit dialog doesn't get messed up by the printing of evaluation results. Parameter Help If you give an Acrobat method an argument of "?" (including the double quotes) and execute that method in console editor (or any internal JavaScript editor), the method will return a list of its own arguments: Example: In the console, type app.response("?") While the cursor is still on the line you entered, press either Ctrl-Enter or the Enter key on the numeric pad. The output to the console is seen to be: uncaught exception: Console:Exec:1: Help for App.response ====> [cQuestion: string] ====> [cTitle: string] ====> [cDefault: string] ====> [bPassword: boolean] Parameters listed in square brackets indicate optional parameters. Tips for Writing Reliable Code Bugs are a fact of life in programming. Most of us would just as soon not have to deal with any, however. You shouldn't pass up any opportunity to make your code more reliable through good coding practices. Here are some tips for getting more gain, and less pain, from your code: Acrobat Forms - JavaScript Object Specification 34
Slide 37: 1. If you are new to programming, the easiest way to learn is to start by modifying somebody else's already-debugged example code. Make one small change at a time until you understand the full effect of your changes. Choose meaningful names for your variables. A descriptive name like numberOfAvailableColors, while long, is usually preferable to a short but cryptic name, such as num or n. Be consistent about variable-naming. Some programmers like to use descriptive prefixes on variable names, such as 'n' at the beginning of numeric variable names (like nTotal, nMaximum, etc.), 'b' at the beginning of Booleans, 's' on strings, 'g' on the front of variables with global scope, etc. Anything you can do to introduce consistency into your code will pay big dividends later. Watch out for uninitialized variables. Declaring a variable and initializing it (assigning an initial value to it) are two different things. If you try to use a variable that has no value (in a comparison statement, for example), you will generate an error. Assigning a safe "dummy value" to every variable at the time it's created will prevent this kind of error. Go for legibility, not elegance. If an operation can be more clearly expressed in two JavaScript statements than in one, use two statements. You're not going to win any awards for conciseness, and in many cases, execution speed is the same (or nearly so) with two statements as it is with one. Use Cut and Paste operations when editing code, to save on keystrokes. The fewer keystrokes you use, the less chance you have of introducing typos into working code. Balance those brackets and parentheses. Check nested statements carefully (or write them on more than one line) to be sure every left-paren is balanced by a right-paren and every left-bracket is balanced by a right-bracket. Make liberal use of comments. Code that is sparsely commented is hard to maintain. "Factor out" complex operations into short functions. Generally speaking, it's easier to understand and debug six two-line functions than it is to understand and debug one 12-line function. Also, factoring out your code will pay dividends in terms of code reuse. 2. 3. 4. 5. 6. 7. 8. 9. 10. Always have working code. Make frequent backup copies as you work. Before editing an existing piece of "good" code, make a copy of it so that you can revert to working code if you end up with seemingly unfixable bugs in your new code. 11. Study other programmers' code every chance you get. Don't reinvent the wheel. Learn from what others have done. Incorporate the best ideas into your own scripts. Soon, you'll be coding like a pro yourself! Acrobat Forms - JavaScript Object Specification 35
Slide 38: Using JavaScript in PDF Forms JavaScript can be particularly useful in conjunction with AcroForms. By attaching scripts to buttons, text fields, combo lists, and other “form widgets”, you can greatly enhance the interactivity, appearance, and reliability of your forms. For example, you can use JavaScript to format and validate user input; submit form data to CGI scripts on a server, or to e-mail addresses; or create custom actions for buttons. In this section, we’ll take a look at some common script actions and how to set up typical form interactions using JavaScript. Organizing Your Code As mentioned in Where Can You Use JavaScript?, it is possible to attach JavaScript to PDF documents in several ways: at the Field level (attached to Actions, or as custom Format, Validation, or Calculation scripts); at the level of Page Open or Page Closed actions; in links or bookmarks; and/or at the Document level. Deciding where to place your code is usually a simple matter: Code should usually be linked as closely as possible to the action or form field it is designed to control. In large projects, however, you will often find that the same kinds of operations need to be performed in many different places. For example, you may have a recurring need to calculate the average of a group of numbers. Rather than write the same number-averaging code over and over, it makes more sense to write one utility function that does this task and store that function at the document level, where it can be accessed by any other script, anywhere in your document. For example, in Tools->JavaScript->Document JavaScripts... , you could type: function average() { if (arguments.length == 0) // nothing to do return 0; var sum = 0.0; for (var i = 0; i < arguments.length; i++) sum += arguments[i] - 0; return sum/arguments.length; } Then, from any other code at any place in the document, you could call on this function to perform numeric averaging. Tip: Note that the above function makes use of the core-JavaScript arguments array, which is available inside any JavaScript function. You can pass any number of arguments to the average() function, and it will calculate the average of the passed-in arguments—even if some or all of those arguments are strings! Subtracting zero from arguments[i] is a standard JavaScript trick for forcing the interpreter to convert arguments[i] to a number, if it's a string. Thus, average(1,5,9) will return the same value as average("1","5","9"). Acrobat Forms - JavaScript Object Specification 36
Slide 39: Storing often-used functions at the document level is beneficial in several ways. It not only reduces clutter and streamlines your field-level code but promotes code reuse and contributes to readability (hence maintainability). “Factoring out” utility functions into document-level scripts will make your projects more manageable and easier to debug. Working with Fields One very common use for JavaScripts is to perform calculations on user input. To do this, you have to be able to fetch the value associated with a given form field. This is really a two-step process. The JavaScript is quite straightforward: var theField = this.getField("City"); var theValue = theField.value; Let’s take a careful look at what’s going on in the first line of code. First, we are declaring a new variable, theField, and assigning a value to it. On the right side of the assignment operator (the equal sign) is this.getField("City"). The reference to 'this' is a JavaScript shortcut. In a document-level script or field-level script, 'this' means the current document object. Among the many predefined methods associated with the document object (see Doc Object) is the getField() method. This method takes a string argument—a string containing the name of the field whose properties you wish to manipulate or examine. For this example, we've assumed that the form contains a field somewhere with the name "City". The second line of code declares a second variable, theValue, which will actually hold the value of the field (that is, whatever the user typed in). Field objects have their own properties and methods (see Field Object). The 'value' property contains the field's user-assigned value. For a text field, this value will be a string. Field values can be altered at runtime by means of JavaScript. To do this, you have to set the 'value' property of the appropriate Field object to whatever value you want it to have. Note the correct and incorrect ways of doing this: var theValue = "San Jose"; var theField.value = "San Jose"; // Wrong. Does not alter field. // Correct. Will alter field. The first line sets our local variable, theValue, to a new value, but this is not the same as making a permanent change to the "City" field of our form. All we have done in this case is change the value of a local variable, not a field. To act on the field requires that we have access to the Field Object itself. Since we obtained a reference to this object in theField, we can use the second method shown above to alter the value shown in the form. (The form will update its appearance immediately to show the new value.) Another way to change the value in this field would simply be to write: this.getField("City").value = "San Jose"; In one line of code, we have successfully overwritten the old value (if any) of our form's "City" field with a new value. Acrobat Forms - JavaScript Object Specification 37
Slide 40: Binding Field Dependencies Another common use for JavaScript is to bind field dependencies in forms. For example, shipping charges might depend on the "Zip Code" field of a form; or you might want to keep a running subtotal of user purchases in a "Subtotal" field. Usually, the best way to set up these sorts of dependencies is to use Calculation scripts. Create a new form field (or doubleclick on an existing one) to bring up the Field Properties dialog. Make sure the field type is either Text or Combo Box. Then select the Calculation tab within the Field Properties dialog: To enter a Calculation script, which will be executed every time the form is updated, toggle the Custom calculation script radio button and hit the Edit... pushbutton on the right. Tip: Note that you can change the calculation order of fields manually, in Acrobat, using Tools -> Forms -> Set Field Calculation Order...; or you can set the calculation order programmatically, using the calcOrderIndex property of the Field Object. Acrobat’s default ordering of fields may not always be what you want. Formatting and Validation Scripts You can use JavaScript to automatically format and/or validate user input as it is happening. Inside the Field Properties dialog (for Text and Combo Box fields only), you will find Format and Validate tabs. When selected, these tabs expose dialog panes that allow you to attach Acrobat Forms - JavaScript Object Specification 38
Slide 41: custom scripts to the field for formatting or validation purposes. What's the difference? Think of format scripts as having to do with the appearance of user-entered data (for example, whether phone number area codes have parentheses), whereas validation scripts have to do with the underlying value of the data (the phone number itself). If you want to filter the user's keystrokes as they happen, select the Format tab in Field Properties and enter a custom keystroke script. In this kind of script, you will typically examine the value of the change property of the Event Object, and either accept or reject the value that the user has entered. The following short script checks to see that the user is entering only numeric values, rejecting all other types of input: if (event.change.match(/\D+/g)) { app.alert("Enter numeric characters only."); event.rc = false; } The condition check (the top line of this code fragment) uses the built-in match() method of JavaScript's String class to check the user's input against a regular expression representing non-numeric characters. (That’s what \D means.) Tip: Regular expressions use a special symbol notation to achieve patternmatching based on well-defined rules. Consult any good JavaScript text for more information on how to use regular expressions to perform powerful string-search, replace, and match operations. If the user enters a value that contains a non-numeric character, two things happen: First, an alert dialog appears onscreen asking the user to enter numeric characters only; then the 'rc' property of the Event Object is set to false, which has the effect of preventing the user’s input from appearing onscreen. Note that event.change is a string. It could very well refer to a lengthy string of just-pasted text, rather than a single typed character. For that reason, we treat it like a string and check every possible character in it. Advanced Formatting Sometimes, it is necessary to apply strict formatting criteria to user-entered field data. For example, it may be necessary to limit numeric values to two decimal places of precision, or apply a particular set of formatting criteria to user-entered dates or currency values, etc. Accomplishing this can be trickier than it first appears. Many formatting options can be handled using Acrobat's built-in formatting options for dates, times, currency values, etc. (See the Format tab in Field Properties.) But occasionally you may need to supplement Acrobat's built-in filters with custom scripts of your own. There are two sources of help to consider here. First, be aware of the fact that the Util Object class offers several built-in methods that can be Acrobat Forms - JavaScript Object Specification 39
Slide 42: helpful in performing formatting. For example, the printx method can be used to apply formatting to strings of numbers: var v = "aaa14159697489zzz"; v = util.printx("9 (999) 999-9999", v); In this instance, the string "aaa14159697489zzz" ends up formatted as "1 (415) 969–7489". (See printx for more information.) Likewise, the printd and scand methods are useful for formatting dates according to various criteria. The C-language standby printf is also available. A second source of help for carrying out low-level formatting consists of the utility functions in the AForm.js file, found in the JavaScripts directory (Acrobat->JavaScripts). This Adobesupplied file contains numerous convenience functions and utilities for carrying out manipulation of date strings and numeric values. For example, the function AFMakeNumber() attempts to make a number out of a string that may or may not use a period as the separator. (In many parts of the world, a comma is used instead.) The source code for this and many other utility functions is given in AForm.js. Tip: Note that AForm.js is loaded automatically whenever Acrobat (or Reader) runs. All of the global variables and functions contained in AForm.js are available to your scripts at runtime. PDF Is Not HTML If you are used to writing JavaScript code for HTML web pages, you may be tempted (from time to time) to call on methods like window.open() or document.write(). You'll find, however, that many of the objects, methods, and properties you're accustomed to working with in a browser environment either don't work or don't exist at all in PDF JavaScript. That's because JavaScript for PDF runs inside Acrobat or Acrobat Reader. The runtime interpreter, in this case, isn't in the browser. The objects and methods you use in PDF JavaScript are scoped to the PDF document itself, not to an HTML page. Whether you realized it before or not, many of the objects and methods you are used to seeing in HTML-based JavaScript are not part of the core language. Rather, they are part of the client-side extensions to the core language. Server-based JavaScript, likewise, makes use of other “added in” methods and objects, relevant to the server environment. These are serverside extensions. PDF, in turn, has its own objects and methods. Always remember that the code you write for an HTML page executes in the browser; the code you write for server-side JavaScript executes in the server; and JavaScript for PDF documents executes in Acrobat (or Acrobat Reader). The methods available in each case differ. This also means, of course, that any JavaScript you write for an HTML page cannot “see inside” a PDF document. Nor can the code you write for a PDF document see inside an HTML page. (However, both types of code can communicate back to the server.) Acrobat Forms - JavaScript Object Specification 40
Slide 43: What’s New For 5.0 Object Properties Methods ADBC Object Annot Object alignment, AP, arrowBegin, arrowEnd, attachIcon, author, contents,doc, fillColor, hidden, modDate, name, noteIcon, noView, page, point, popupRect, print, points, print, rect, readOnly, rotate, strokeColor, textFont, type, soundIcon, width activeDocs, fs, plugIns, viewerVariation getDataSourceList(), newConnection() destroy(), setProps(), setProps() App Object addMenuItem(), addSubMenu(), clearInterval(), clearTimeOut(), listMenuItems(), listToolbarButtons(), newDoc(), openDoc(), popUpMenu(), setInterval(), setTimeOut() createChild(),execute(), insertChild(), remove() convert(), equal() newStatement(), getTableList(), getColumnList() Bookmark Object Color Object Connection Object Data Object children, doc, name, open, parent, style creationDate creationDate, modDate, MIMEType, name, path, size Acrobat JavaScript Object Specification 41
Slide 44: Object Properties Methods Doc Object bookmarkRoot, icons, info, layout, securityHandler, selectedAnnots, sounds, templates, URL addAnnot(), addField(), addIcon(), addThumbnails(), addWeblinks(), bringToFront(), closeDoc(), createDataObject(), createTemplate(), deletePages(), deleteSound(), exportAsXFDF(), exportDataObject(), extractPages(), flattenPages(), getAnnot(), getAnnots(), getDataObject(), getIcon(), getPageBox(), getPageLabel(), getPageNthWord(), B: This method will throw an exception if the document security is set to prevent content extraction.(), getPageRotation(), getPageTransition(), getSound(), importAnXFDF(), importDataObject(), importIcon(), importSound(), importTextData(), insertPages(), movePage(), print(), removeDataObject(), removeField(), removeIcon(), removeTemplate(), removeThumbnails(), removeWeblinks(), replacePages(), saveAs(), selectPageNthWord(), setPageBoxes(), setPageLabels(), setPageRotations(), setPageTransitions(), submitForm(), syncAnnotScan() Event Object Field Object changeEx, keyDown, targetName buttonAlignX, buttonAlignY, buttonPosition, buttonScaleHow, buttonScaleWhen, currentValueIndices, doNotScroll, doNotSpellCheck, exportValues, fileSelect, multipleSelection, rect, strokeColor, submitName, valueAsString browseForFileToSubmit(), buttonGetCaption(), buttonGetIcon(), buttonSetCaption(), buttonSetIcon(), checkThisBox(), defaultIsChecked(), isBoxChecked(), isDefaultChecked(), setAction(), signatureInfo(), signatureSign(), signatureValidate() Acrobat JavaScript Object Specification 42
Slide 45: Object Properties Methods FullScreen Object backgroundColor, clickAdvances, cursor, defaultTransition, escapeExits, isFullScreen, loop, timeDelay, transitions, usePageTiming, useTimer subscribe() corporation, email, loginName, name available, name, path, selected certified, loaded, name, path, version appearances, isLoggedIn, loginName, loginPath, name, signInvisible, signVisible, uiName size, absIndent, color login(),logout(), newUser(), setPasswordTimeout(), Global Object Identity Object Index Object PlugIn Object PPKLite Signature Handler Object Report Object Report(), writeText(), breakPage(), divide(), indent (), outdent(), open(), save(),mail() addIndex(), getIndexForPath(), query(), removeIndex() Search Object available, indexes, matchCase, maxDocs, maxDocs, proximity, proximity, refine, soundex, stem handlers, validateSignaturesOnOpen Security Object getHandler() Acrobat JavaScript Object Specification 43
Slide 46: Object Properties Methods Spell Object available, dictionaryNames, dictionaryOrder, domainNames columnCount, rowCount addDictionary(), addWord(), check(), checkText(), checkWord(), removeDictionary(), removeWord(), userWords() execute(), getColumn(), getColumnArray(), getRow(), nextRow() spawn() Statement Object Template Object hidden, Although reading this property is valid, setting this property in Acrobat Reader will generate an exception. Other 5.0 Changes This manual contains an extensive appendix entitled A Short Acrobat JavaScript FAQ. If particular importance are the sections How can I create a form field programmatically?, Quick Reference: Forms and How can I create an Annotation programmatically? which summarize how the numerous properties and methods (both old and new) can can be use to create form fields and annotations (also called comments). Many interesting examples and programming tips are contained in these sections. In addition to the new objects, properties and methods outlined in the table above, there has been a number of other changes and enhancements that should be noted. Added: The console can now act as an editor and can execute JavaScript code, see the section entitled Interactive JavaScript Console. Changed/Enhanced: The following properties and methods have been enhanced: App.language, App.execMenuItem; Event.type; Doc.exportAsFDF, Doc.print, Doc.submitForm; Field.buttonImportIcon, Field.textFont, Field.getItemAt, Field.value; Util.printd. The section related to Event Object has been greatly enhanced to facilitate better understanding of the Acrobat JavaScript Event model. Deprecated: The following properties and methods have been deprecated: App.fullscreen, App.numPlugIns, App.getNthPlugInName; Doc.author, Doc.creationDate, Doc.creator, Doc.getNthTemplate, Doc.keywords, Doc.modDate, Doc.numTemplates, Doc.producer, Doc.spawnPageFromTemplate, Doc.title; Field.hidden; Tts.soundCues, Tts.speechCues. Acrobat JavaScript Object Specification 44
Slide 47: ADBC Object 5.0 V The Acrobat Database Connectivity (ADBC) plug-in allows JavaScripts inside of PDF documents to access databases through a consistent object model that is identical across platforms. The object model is based on general principles used in the object models for the ODBC and JDBC APIs. Like ODBC and JDBC, ADBC is a means of communicating with a database though SQL or Structured Query Language. ADBC is a Windows-only feature and requires ODBC (Open Database Connectivity from Microsoft Corporation) to be installed on the client machine. Security B: It is important to note that ADBC provides no security for any of the databases it is programmed to access. It is the responsibility of the database administrator to keep all data secure. The ADBC Object is a global object whose methods allow a JavaScript to create database connection contexts or connections. In addition to the ADBC Object, described below, there are several related objects as well: Object Brief Description An object through which a list of accessible databases can be obtained and a connection can be made to one of them. An object through which a list of tables in the connected database can be obtained. An object through which SQL statements can be executed and rows retrieved based on the query. ADBC Object Connection Object Statement Object Acrobat JavaScript Object Specification 45
Slide 48: ADBC properties SQL Type 5.0 V The ADBC object has several constant properties representing various SQL Types: Name SQLT_BIGINT SQLT_BINARY SQLT_BIT SQLT_CHAR SQLT_DATE SQLT_DECIMAL SQLT_DOUBLE SQLT_FLOAT SQLT_INTEGER SQLT_LONGVARBINARY value 0 1 2 3 4 5 6 7 8 9 Name SQLT_LONGVARCHAR SQLT_NUMERIC SQLT_REAL SQLT_SMALLINT SQLT_TIME SQLT_TIMESTAMP SQLT_TINYINT SQLT_VARBINARY SQLT_VARCHAR value 10 11 12 13 14 15 16 17 18 The type property of the Column Object and type property of the ColumnInfo Object both return this SQL Type property. JavaScript Type 5.0 V The ADBC object has several constant properties representing various JavaScript data types. Name Numeric String Binary Boolean value 0 1 2 3 Name Time Date TimeStamp value 4 5 6 The methods getColumn and getColumnArray of the Statement Object both use these types. Acrobat JavaScript Object Specification 46
Slide 49: ADBC methods getDataSourceList 5.0 V Parameters: None Returns: Array The getDataSourceList method is used to obtain information about the databases accessible from a given system. It takes no parameters and returns a (possibly empty) array containing a DataSourceInfo Object for each accessible database on the system. This method never fails but may return a zero-length array. The properties of the DataSourceInfo Object are listed in the table below. DataSourceInfo Object The DataSourceInfo object is an object that contains very basic information about a particular database. Property name Type string Access R Description A string that represents the identifying name of a database. This string could be passed to newConnection to establish a connection to the database that the DataSourceInfo object is associated with. A string that contains database dependent information about the database. description string R See newConnection for an example. newConnection 5.0 V Parameters: cDSN, [cUID], [cPWD] Returns: connection object | null The newConnection method is used to create a Connection Object associated with the database identified by the cDSN (Data Source Name) parameter. Optionally, the cUID parameter can supply a user ID and possibly a password, cPWD. On success, this method returns a Connection object. On failure, it returns null. Example: // First, get the array of DataSourceInfo Objects available on the system var aList = ADBC.getDataSourceList(); Acrobat JavaScript Object Specification 47
Slide 50: console.show(); console.clear(); try { // now display them, while searching for the one named "q32000data". var DB = "", msg = ""; if (aList != null) { for (var i=0; i < aList.length; i++) { console.println("Name: "+aList[i].name); console.println("Description: "+aList[i].description); // and choose one of interest if (aList[i].name=="q32000data") DB = aList[i].name; } } // did we find the database? if (DB != "") { // yes, establish a connection. console.println("The requested database has been found!"); var Connection = ADBC.newConnection(DB); if (Connection == null) throw "Not Connected!" } else // no, display message to console. throw "Could not find the requested database."; } catch (e) { console.println(e); } // alternatively, we could simple connect directly. var Connection = ADBC.newConnection("q32000data"); Acrobat JavaScript Object Specification 48
Slide 51: Annot Object The functionality of the Acrobat Annotation Plug-in is exposed to JavaScript methods through the Annot Object. The Annot object represents any particular Acrobat annotation (that is, an annotation created using the Acrobat annotation tool, or by using addAnnot method from the Doc Object). The types of annotations available are Circle, FileAttachment, FreeText, Highlight, Ink, Line, Sound, Square, Squiggly, Stamp, StrikeOut, Text and Underline. (There is no user interface to the Squiggly annot type; Squiggly can be accessed only through JavaScript.) In addition to addAnnot, used for the creation of annotations, there are two other Doc Object methods for gathering annotations from documents, getAnnot and getAnnots Note also that the section How can I create an Annotation programmatically? provides detailed examples of most all annotations and JavaScript techniques. Note: The user interface in Acrobat refers to annotations as comments. Annotation Access from JavaScript Before an Annotation can be accessed, it must be “bound” to a JavaScript variable through a method provided by Doc Object methods interface: var a = this.getAnnot(0, "Important"); This example allows the script to now manipulate the annotation named “Important” on page 1 (zero-based page numbering system) via the variable a. For example, the following code var thetype = a.type; // read property a.author = "John Q. Public"; // write property first stores the type of annotation in the variable thetype, then changes the author to "John Q. Public". Annot Object: Quick Reference Annotation Types All types Circle FileAttachment Properties type, rect, page, author, name, contents, modDate point, popupRect, fillColor, strokeColor, width print, attachIcon Acrobat JavaScript Object Specification 49
Slide 52: Annot Object: Quick Reference Annotation Types FreeText Properties alignment, fillColor, rotate, strokeColor, textFont, textSize, width quads, strokeColor, point, popupRect gestures, strokeColor, point, popupRect, width points, arrowBegin, arrowEnd, point, popupRect, fillColor, strokeColor, width print, soundIcon point, popupRect, fillColor, strokeColor, width quads, strokeColor, point, popupRect point, popupRect, AP quads, strokeColor, point, popupRect print, noteIcon, point, popupRect quads, strokeColor, point, popupRect Highlight Ink Line Sound Square Squiggly Stamp StrikeOut Text Underline Annot Properties alignment 5.0 = V Annots: FreeText Access: R/W Type: Number Acrobat JavaScript Object Specification 50
Slide 53: The property controls the alignment of the text for a FreeText annotation. Alignment Left aligned Centered Right aligned Value 0 1 2 See the section on FreeText Annotations for an example of the use of the alignment property. AP 5.0 = V Annots: Stamp Access: R/W Type: String The value of this property is the named appearance of the stamp to be used in displaying a stamp annotation. The names of the standard stamp annotations are "Approved", "AsIs", "Confidential", "Departmental", "Draft", "Experimental", "Expired", "Final", "ForComment", "ForPublicRelease", "NotApproved", "NotForPublicRelease", "Sold" and "TopSecret". Example: var annot = this.addAnnot({ page: 0, type: "Stamp", author: "A. C. Robat", name: "myStamp", rect: [400, 400, 550, 500], contents: "Try it again, this time with order and method!", AP: "NotApproved" }); Note: The name of a particular stamp can be found by opening the PDF file in the Stamps folder that contains the stamp in question. Now open the menu File > Form > Page Templates, a listing of all appearances and their names can then be seen. For a list of stamp names currently in use in the document, see the icons property of the Doc Object. arrowBegin 5.0 = V Annots: Line Access: R/W Type: String Acrobat JavaScript Object Specification 51
Slide 54: The value of arrowBegin determines the line cap style which specifies the shape to be used at the beginning of a Line annotation. Permissible values are "Circle", "ClosedArrow", "Diamond", "None" (the default), "OpenArrow" and "Square". See arrowEnd and setProps (for an example), as well as the section on Line Annotations. arrowEnd 5.0 = V Annots: Line Access: R/W Type: String The value of arrowEnd determines the line cap style which specifies the shape to be used at the end of a Line annotation Permissible values are "Circle", "ClosedArrow", "Diamond", "None" (the default), "OpenArrow" and "Square". See arrowBegin and setProps (for an example), as well as the section on Line Annotations. attachIcon 5.0 = V Annots: FileAttachment Access: R/W Type: String The value of this property is the name of an icon to be used in displaying the annotation. Recognized values are "Paperclip", "PushPin" (the default), "Graph", and "Tag". author 5.0 = V Annots: all Access: R/W Type: String The author of the annotation. See contents for an example of usage. contents 5.0 = V Type: String Annots: all Access: R/W The contents of any annotation having a popup can be accessed through this property. In the case of Sound and FileAttachment annotations, the contents property specifies the text to be displayed as the description of the sound or file attachment. Acrobat JavaScript Object Specification 52
Slide 55: Example: var annot = this.addAnnot({ page: 0, type: "Text", point: [400,500], author: "A. C. Robat", contents: "Call Smith to get help on this paragraph.", noteIcon: "Help" }); See also the addAnnot method. doc 5.0 V Annots: all Access: R Type: doc object This property returns the Doc Object of the document in which the annotation resides. Example: var inch = 72; var annot = this.addAnnot({ type: "Square", rect: [1*inch, 3*inch, 2*inch, 3.5*inch] }); /* displays, e.g., "file:///C|/Adobe/Annots/myDoc.pdf" */ console.println(annot.doc.URL); fillColor 5.0 = V Annots: Circle, Square, Line, FreeText Access: R/W Type: Color This property sets the background color for the Circle, Square, Line and FreeText annotations. 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. For an example, see Circle and Square Annotations. Acrobat JavaScript Object Specification 53
Slide 56: gestures 5.0 = V Annots: Ink Access: R/W Type: Array An array of arrays, each representing a stroked path. Each array is a series of alternating x and y coordinates in Default User Space, specifying points along the path.When drawn, the points are connected by straight lines or curves in an implementation-dependent way. See “Ink Annotations” in the PDF Reference, page 415, for more details. See Ink Annotations for an extensive example. hidden 5.0 = V Type: Boolean Annots: all Access: R/W If hidden is set to true, then the annotation is not shown and there is no user interaction, display or printing of the annotation. modDate 5.0 Type: Date V Annots: all Access: R This property returns the last modification date for the annotation. Example: // This example prints the modification date to the console console.println(util.printd("mmmm dd, yyyy", annot.modDate)); name 5.0 = V Annots: all Access: R/W Type: String The name of an annotation can be used by getAnnot to find and access the properties and methods of the annotation. Acrobat JavaScript Object Specification 54
Slide 57: Example: // This code locates the annotation named "myNote" and appends a comment. var gannot = this.getAnnot(0, "myNote"); gannot.contents += "\r\rDon’t forget to check with Smith"; noteIcon 5.0 = V Annots: Text Access: R/W Type: String The value of this property is the name of an icon to be used in displaying the annotation. Recognized values of noteIcon are "Comment", "Help", "Insert", "Key", "Note" (the default), "NewParagraph", and "Paragaph". See the contents property for an example and the section entitled Text Annotations. noView 5.0 = V Annots: all Access: R/W Type: Boolean If noView is set to true, then the annotation is hidden, but if the annotation has an appearance, that appearance should be used for printing only. page 5.0 = V Annots: all Access: R/W Type: Integer This property is the page on which the annotation resides. The code, for example, annot.page = 2; moves the Annot object, annot, from its current page to page 3 (zero-based page numbering system). point 5.0 = V Annots: Text, Sound, FileAttachment Access: R/W Type: Array Acrobat JavaScript Object Specification 55
Slide 58: An Array of two numbers, [x ul , y ul ] which specifies the upper left-hand corner in default, user’s space, of an annotation’s Text, Sound, or FileAttachment icon. Example: var annot = this.addAnnot({ page: 0, type: "Text", point: [400,500], contents: "Call Smith to get help on this paragraph.", popupRect: [400,400,550,500], popupOpen: true, noteIcon: "Help" }); See also addAnnot and noteIcon. points 5.0 = V Annots: Line Access: R/W Type: Array An Array of two points, [[x 1, y 1], [x 2 , y 2 ]], specifying the starting and ending coordinates of the line in Default User Space. Example: var annot = this.addAnnot({ type: "Line", page: 0, author: "A. C. Robat", contents: "Look at this again!", points: [[10,40],[200,200]], }) See addAnnot, arrowBegin, arrowEnd and setProps and Line Annotations. popupOpen 5.0 = V Annots: all but Sound, FreeText, FileAttachment Access: R/W Type: Boolean If popupOpen is true then the popup text note will appear open when the page is displayed. See the print property for an example. Acrobat JavaScript Object Specification 56
Slide 59: popupRect 5.0 = V Annots: all but FreeText, FileAttachment, Sound Access: R/W Type: Array 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 of the popup annotation associated with a parent annotation and defines the location of the popup annotation on the page. See the print property for an example. print 5.0 = V Annots: all Access: R/W Type: Boolean If print property indicates whether the annotation should be printed. When set to true, the annotation will be printed. quads 5.0 = V Annots: Highlight, StrikeOut,Underline, Squiggly Access: R/W Type: Array 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 = V Annots: all Access: R/W Type: Array 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. Acrobat JavaScript Object Specification 57
Slide 60: readOnly 5.0 = V Annots: all Access: R/W Type: Boolean When readOnly is set to true, this indicates that the annotation should display, but not interact with the user. rotate 5.0 = V Annots: FreeText Access: R/W Type: Integer 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 = V Annots: all Access: R/W Type: color 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 = V Annots: FreeText Access: R/W Type: String 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: Acrobat JavaScript Object Specification 58
Slide 61: 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. // Create FreeText annotation with Helvetica var annot = this.addAnnot({ page: 0, type: "FreeText", textFont: font.Helv, // or, textFont: "Viva-Regular", textSize: 10 rect: [200, 300, 200+150, 300+3*12], // height for three lines width: 1, alignment: 1 }); textSize 5.0 = V Annots: FreeText Access: R/W Type: Integer This property determines the text size (in points) that is used in a FreeText annotation. Valid text sizes include zero and the range from 4 to 144 inclusive. A text size of zero means that the largest point size that will allow all the text data to still fit in the annotations’s rectangle should be used. See textFont for an example. type 5.0 = V Annots: all Access: R Type: String This property can be used to determine the type of annotation. The valid values of type are "Circle", "FileAttachment", "FreeText", "Highlight", "Ink", "Line", "Sound", "Square", "Squiggly", "Stamp", "StrikeOut", "Text" and "Underline". Note: The “type” of the annotation can only be set within the object literal argument of the addAnnot method . soundIcon Type: String Annots: Sound Access: R/W Acrobat JavaScript Object Specification 59
Slide 62: 5.0 = V The value of this property is the name of an icon to be used in displaying the annotation. A value of "Speaker" is recognized. width 5.0 = V Annots: Square, Circle, Line, Ink, FreeText Access: R/W Type: Number The border width in points. If this value is 0, no border is drawn. The default value is 1. Annot Methods destroy 5.0 = V Parameters: None Returns: Nothing This method destroys the annot, removing it from the page. The object becomes invalid. Example: // remove all "FreeText" annotations on page 0 var annots = this.getAnnots({ nPage:0 }); for (var i = 0; i < annots.length; i++) if (annots[i].type == "FreeText") annots[i].destroy(); getProps 5.0 V Parameters: None Returns: object literal This methods returns an object literal of the properties of the annotation. The object literal is just like the one passed to addAnnot. This method can be used to copy an annotation. Example: var annot = this.addAnnot({ type: "Text", rect: [40, 40, 140, 140] Acrobat JavaScript Object Specification 60
Slide 63: }); // Make a copy of the properties of annot var copy_props = annot.getProps(); // Now create a new annot with the same properties on every page var numpages = this.numPages; for (var i=0; i < numpages; i++) { var copy_annot = this.addAnnot(copy_props); // but move it to page i copy_annot.page=i; } setProps 5.0 = V Parameters: object literal Returns: annotation object Sets many properties of the annotation simultaneously. The object literal is just like the one passed to addAnnot. Example: var annot = this.addAnnot({type: "Line"}) annot.setProps({ page: 0, points: [[10,40],[200,200]], strokeColor: color.red, author: "A. C. Robat", contents: "Check with Jones on this point.", popupOpen: true, popupRect: [200, 100, 400, 200], // place rect at tip of the arrow arrowBegin: "Diamond", arrowEnd: "OpenArrow" }) Acrobat JavaScript Object Specification 61
Slide 64: 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 activeDocs 5.0 Type: Array Access: R This property returns an array containing the Doc Object for each active document open in the viewer. If no documents are active, activeDocs returns nothing, or has the same behavior as d=new Array(0) in core JavaScript. With this property, it is possible to perform cross-document operations. Example: /* This example searches among the open documents for the document with a title of "C", then it inserts a button in that document using addField */ var d = app.activeDocs; for (var i=0; i < d.length; i++) if (d[i].info.Title == "myDoc") { var f = d[i].addField("myButton", "button", 0 , [20, 100, 100, 20]); f.setAction("MouseUp","app.beep(0)"); f.fillColor=color.gray; } calculate L 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 occurring. Its default value is true. See also the document calculate property which supersedes this property in later versions. Acrobat JavaScript Object Specification 62
Slide 65: focusRect 4.05 E Access: R/W Type: Boolean This property turns on and off the focus rectangle. The focus rectangle is the faint dotted line around buttons, check boxes, radio buttons, and signatures to indicate that the form field has the keyboard focus. formsVersion 4.0 Type: Number Access: R 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.0) { // Perform version specific operations here. } fs 5.0 E Access: R Type: object Returns the FullScreen Object which can be used to access the fullscreen properties. Example: // This code puts the viewer into fullscreen (presentation) mode. app.fs.isFullScreen = true; See also isFullScreen in the FullScreen Object. fullscreen L Type: Boolean Access: R/W Acrobat JavaScript Object Specification 63
Slide 66: 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 the 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. Note: A PDF document being viewed from within a web browser cannot be put into fullscreen mode. Fullscreen mode can, however, be initiated from within the browser, but will not occur unless there is a document open in the Acrobat viewer application; in this case, the document open in the viewer will appear in fullscreen, not the PDF document open in the web browser. See the isFullScreen property of the FullScreen Object; this property supersedes App.fullscreen in later versions. See also App.fs, which returns a FullScreen Object which can be used to access the fullscreen properties. language Type: String Access: R This property defines the language of the running Acrobat Viewer. It returns the following strings: String CHS CHT DAN DEU ENU ESP FRA ITA Language Chinese Simplified Chinese Traditional Danish German English Spanish French Italian String KOR JPN NLD NOR PTB SUO SVE Language Korean Japanese Dutch Norwegian Brazilian Portuguese Finnish Swedish Acrobat JavaScript Object Specification 64
Slide 67: numPlugIns L Type: Number Access: R This property indicates the number of plug-ins that have been loaded by Acrobat. See the plugIns property which supersedes this property in later versions. openInPlace 5.0 E Access: R/W Type: Boolean This property determines whether cross-document links are opened in the same window or opened in a new window. platform Type: String Access: R This property returns the platform that the script is currently executing on. Valid values include "WIN", "MAC", and "UNIX". plugIns 5.0 Type: Array Access: R Used to determine which plug-ins are currently installed in the viewer. Returns an array of PlugIn Objects. Example: // Get array of PlugIn Objects var aPlugins = app.plugIns; // Get number of plugins var nPlugins = aPlugins.length; // Enumerate names of all plugins for ( var i = 0; i < nPlugins; i++) console.println("Plugin \#"+i+" is " + aPlugins[i].name); Acrobat JavaScript Object Specification 65
Slide 68: toolbar E 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 L E Type: Boolean Access: R/W 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). Note: Acrobat 5.0 has drastically changed the notion of what a toolbar is and where it can live within the frame of the application. This property has been deprecated as a result. If accessed, it will act like the toolbar property. toolbarVertical L E Type: Boolean Access: R/W 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). Note: Acrobat 5.0 has drastically changed the notion of what a toolbar is and where it can live within the frame of the application. This property has been deprecated as a result. If accessed, it will act like the toolbar property. Acrobat JavaScript Object Specification 66
Slide 69: viewerType Type: String Access: R This property determines if the running Acrobat Viewer is Reader vs. the full product. Its value is "Reader" or "Exchange" respectively. viewerVariation 5.0 Type: String Access: R This property indicates the packaging of the running Acrobat Viewer. Its value is "Reader", "Fill-In", "Business Tools", or "Full". viewerVersion 4.0 Type: Number This property indicates the version number of the current viewer. Access: R App Object Methods addMenuItem 5.0 B Parameters: cName, [cUser], cParent, [nPos], cExec, [cEnable], [cMarked] Returns: Nothing Adds a menu item to the application. cName is the language independent name of the menu item. This language independent name is used to access the menu item for other methods (e.g. hideMenuItem). cUser is the user string (language dependent name) to display as the menu item name. If cUser is not specified then cName is used. cParent is the name of the parent menu item. Its submenu will have the new menu item added to it. If cParent has no submenu then an exception is thrown. Menu item names can be discovered via the listMenuItems method. Language independent names for menu items can also be obtained from the Acrobat Viewer plug-in API On-Line Reference (See Useful Documents). Acrobat JavaScript Object Specification 67
Slide 70: nPos is the position within the submenu to locate the new menu item. The default behavior is to append to the end of the submenu. Specifying nPos as 0 will add to the top of the submenu. cExec is an expression string to evaluate when the menu item is selected by the user. cEnable is an expression string that determines whether or not to enable the menu item. The default is that the menu item is always enabled. This expression should set event.rc to false to disable the menu item. cMarked is an expression string that determines whether or not the menu item has a check mark next to it. Default is that the menu item is not marked. This expression should set event.rc to false to uncheck the menu item and true to check it. Example: // This example adds a menu item to the top of the file submenu that puts up an // alert dialog displaying the active document title. This menu is only // enabled if a document is opened. app.addMenuItem({ cName: "Hello", cParent: "File", cExec: "app.alert(app.activeDocs[0].info.title, 3);", cEnable: "event.rc = app.activeDocs.length > 0", nPos: 0}); See also the addSubMenu, execMenuItem, hideMenuItem, and listMenuItems methods. Security B: This method can only be executed during application initialization or console events. See the Event Object for a discussion of Acrobat JavaScript events. addSubMenu 5.0 B Parameters: cName, [cUser], cParent, [nPos] Returns: Nothing Adds a menu item with a submenu to the application. cName is the language independent name of the menu item. This language independent name is used to access the menu item for hideMenuItem, for example. cUser is the user string (language dependent name) to display as the menu item name. If cUser is not specified then cName is used. cParent is the name of the parent menu item to receive the new submenu. Acrobat JavaScript Object Specification 68
Slide 71: Menu item names can be discovered via the listMenuItems method. Language independent names for menu items can also be obtained from the Acrobat Viewer plug-in API On-Line Reference (See Useful Documents). nPos is the position within the parent’s submenu to locate the new submenu. Default is to append to the end of the parent’s submenu. Specifying nPos as 0 will add to the top of the parent’s submenu. Example: // This example adds a submenu "One" to the top of the File submenu. // It has two additional menu items that display an alert message. app.addSubMenu({ cName: "One", cParent: "File" }); app.addMenuItem({ cName: "Two", cParent: "One", cExec: "app.alert('Two', 3);"}); app.addMenuItem({ cName: "Three", cParent: "One", cExec: "app.alert('Three', 3);"}); See also the addMenuItem, execMenuItem, hideMenuItem, and listMenuItems methods. Security B: This method can only be executed during application initialization or console events. See the Event Object for a discussion of Acrobat JavaScript events. alert Parameters: cMsg, [nIcon], [nType] Returns: nButton This method displays an alert dialog on the screen. The minimum required parameter is a string, cMsg, 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 Note: The Macintosh OS does not distinguish between warnings and questions, so it only has three different types of icons. Acrobat JavaScript Object Specification 69
Slide 72: Additionally, a button group type can be specified by using the nType parameter: 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 OK Cancel No Yes Value 1 2 3 4 beep Parameters: [nType] Returns: None This method causes the system to play a sound. The various sounds and the values used are as follows: Message Type Error Warning Question Status Default (the default) Value 0 1 2 3 4 Note: On Apple Macintosh and UNIX systems the beep type is ignored. clearInterval Parameters: oInterval Acrobat JavaScript Object Specification 70
Slide 73: 5.0 Returns: Nothing This method cancels a previously registered interval, oInterval, such an interval is initially set by the setInterval method. See also the setTimeOut and clearTimeOut methods. An example of use follows the description of the setTimeOut method. clearTimeOut 5.0 Parameters: oTime Returns: Nothing This method cancels a previously registered time-out interval, oTime; such an interval is initially set by the setTimeOut method. See also the setInterval, and clearInterval methods. An example of use follows the description of the setTimeOut method. execMenuItem 4.0 Parameters: cMenuItem Returns: Nothing This method executes the specified menu item. Menu item names can be discovered via the listMenuItems method. Language independent names for menu items can also be obtained from the Acrobat Viewer plug-in API On-Line Reference (See Useful Documents). 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"); See also the addMenuItem, addSubMenu, hideMenuItem methods. The listMenuItems method conveniently lists the names of all menu items to the console. 5.0 Additions Acrobat JavaScript Object Specification 71
Slide 74: App.execMenuItem("SaveAs") saves the current file to the user’s hard drive; a “SaveAs” dialog opens to ask the user to select a folder and file name. Executing the “SaveAs” menu item will save the current file as a linearized file, provided “Save As creates Fast View Adobe PDF files” is checked in the Edit > Preferences > General > Options dialog. Security B: App.execMenuItem("SaveAs") can only be executed during batch, console or menu events. See the Event Object for a discussion of Acrobat JavaScript events. Note: If the user preferences are set to “Save As creates Fast View Adobe PDF files”, do not expect a form object to survive a "SaveAs"; field objects are no longer valid, and an exception may be thrown when trying to access a field object immediately after a "SaveAs". See examples that follow. Example: var f = getField("myField"); app.execMenuItem("SaveAs"); // Assume preferences set to save linearized f.value = 3; // exception thrown, field not updated Example: var f = getField("myField"); app.execMenuItem("SaveAs"); // Assume preferences set to save linearized var f = getField("myField"); // re-get the field after the linear save f.value = 3; // field updated to a value of 3 Note: For security reasons, scripts are not allowed to execute the "Quit" menu item. getNthPlugInName L Parameters: nIndex Returns: cName This method returns the name of the nth plug-in that has been loaded by the viewer. See also the numPlugIns property. See the plugIns property which supersedes this property in later versions. Acrobat JavaScript Object Specification 72
Slide 75: 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 4.0 B Parameters: cName Returns: Nothing This method allows an integrator to customize the look of the Acrobat viewer by removing the menu item specified by cName. Menu item names can be discovered via the listMenuItems method. 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 addMenuItem, addSubMenu, execMenuItem, and listMenuItems methods. Security B: This method can only be executed during application initialization or console events. See the Event Object for a discussion of Acrobat JavaScript events. hideToolbarButton 4.0 B Parameters: cName Returns: Nothing Acrobat JavaScript Object Specification 73
Slide 76: 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. Security B: This method can only be executed during application initialization or console events. See the Event Object for a discussion of Acrobat JavaScript events. 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 Acrobat JavaScript Object Specification 74
Slide 77: 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 V 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."} ); Note: On Windows: The client machine must have its default mail program configured to be MAPI enabled in order to use this method. newDoc 5.0 B V Parameters: [nWidth], [nHeight] Returns: Doc object Acrobat JavaScript Object Specification 75
Slide 78: This method creates a new document in the Acrobat Viewer and returns the Doc Object of the newly created document. The optional parameters, nWidth and nHeight, are used to specify the media box dimensions in points of the document. The default values are nWidth = 612 and nHeight = 792. Example: Add a "New" item to the Acrobat File menu. Within "New", there are three menu items: "Letter", "A4" and "Custom". This script should go in a Folder Level JavaScripts folder. app.addSubMenu({ cName: "New", cParent: "File", nPos: 0 }) app.addMenuItem({ cName: "Letter", cParent: "New", cExec: "var d = app.newDoc();"}); app.addMenuItem({ cName: "A4", cParent: "New", cExec: "app.newDoc(420,595)"}); app.addMenuItem({ cName: "Custom...", cParent: "New", cExec: "var nWidth = app.response({ cQuestion: 'Enter Width in Points',\ cTitle: 'Custom Page Size'});" +"if (nWidth == null) nWidth = 612;" +"var nHeight = app.response({ cQuestion: 'Enter Height in Points',\ cTitle: 'Custom Page Size'});" +"if (nHeight == null) nHeight = 792;" +"app.newDoc({ nWidth: nWidth, nHeight: nHeight })"}); The code is a little incomplete. In the case of the "Custom" menu item, additional lines can be inserted to prevent the user from entering the empty string, or a value too small or too large. See the “General Implementation Limits", page 546, of the PDF Reference for the current limitations. Security B: This method can only be executed during batch, console or menu events. See the Event Object for a discussion of Acrobat JavaScript events. openDoc 5.0 = Parameters: cPath, [oDoc] Returns: Doc object This method opens the PDF document specified by cPath; the return value is the Doc Object of the document opened by this method, which can, in turn, be used by the script to call methods, or to get or set properties in the newly opened document. cPath is a device independent path to the document to be opened. The path can be a relative path if the second parameter, oDoc, gets passed. The parameter oDoc and target document, must both live in the default file system. Acrobat JavaScript Object Specification 76
Slide 79: oDoc is a Doc Object to use as a base to resolve a relative cPath. Example: /* This example opens another document, inserts a prompting message into a text field, sets the focus in the field, then closes the current document. */ var otherDoc = app.openDoc("/c/temp/myDoc.pdf"); otherDoc.getField("name").value="Enter your name here: " otherDoc.getField("name").setFocus(); this.closeDoc(); Same example as above, but a relative path is given. var otherDoc = app.openDoc("myDoc.pdf", this); otherDoc.getField("name").value="Enter your name here: " otherDoc.getField("name").setFocus(); this.closeDoc(); Note: The current document as well as the target document must be in the default file system. See also the closeDoc and setFocus methods. popUpMenu 5.0 Parameters: [cItem | Array ] ... Returns: cItem This method creates a pop-up menu at the current mouse position. The menu will contain one or more items as specified by the supplied arguments. The method returns the name of the menu item that was selected. The menu item name "-" is reserved to draw a separator line in the menu. If the argument is a string then it is listed in the menu as a menu item. If the argument is an array then it appears as a submenu where the first element in the array is the parent menu item. This array can contain further submenus if desired. var cItem = app.popUpMenu("Introduction", "-", "Chapter 1", [ "Chapter 2", "Chapter 2 Start", "Chapter 2 Middle", [ "Chapter 2 End", "The End"]]); app.alert("You chose the \"" + cItem + "\" menu item"); Acrobat JavaScript Object Specification 77
Slide 80: Note: It is important, given the platform dependent interaction between the mouse and the popup menu, to only invoke this method on a Field/Mouse Down event. If it is issued at any other time, it may work on some platforms and not on others. response Parameters: cQuestion, [cTitle], [cDefault], [bPassword] 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. cQuestion is the question to be posed to the user. cTitle is an optional title to appear in the dialog’s window title. cDefault is a default value for the answer to the question. If not specified, no default value is presented. bPassword, if true, indicates that the user’s response should show as asterisks (*) or bullets (•) to mask the response, which might be sensitive information. 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. Example: var cResponse = app.response({ cQuestion: "How are you today?", cTitle: "Your Health Status", cDefault: "Fine" }); if ( cResponse == null) app.alert("Thanks for trying anyway."); else app.alert("You responded, \""+cResponse+"\", to the health question.",3); setInterval 5.0 Parameters: cExpr, nMilliseconds Returns: timeout object This method registers an expression to be evaluated each time the specified period elapses (specified in milliseconds). For example, to create a simple color animation on a field called "Color" that changes every second: Acrobat JavaScript Object Specification 78
Slide 81: function DoIt() { var f = this.getField("Color"); var nColor = (timeout.count++ % 10 / 10); // Various shades of red. var aColor = new Array("RGB", nColor, 0, 0); f.fillColor = aColor; } timeout = app.setInterval("DoIt()", 1000); // Add a property to our timeout object so that DoIt() can keep a count going. timeout.count = 0; See also the clearInterval, setTimeOut and clearTimeOut methods. See the setTimeOut method for an additional example. setTimeOut 5.0 Parameters: cExpr, nMilliseconds Returns: timeout object This method registers an expression to be evaluated after a specific period elapses (specified in milliseconds). See also the clearTimeOut, setInterval and clearInterval methods. Example: This example creates a simple running marquee. Assume there is a text field named "marquee". The default value of this field is "Adobe Acrobat version 5.0 will soon be here!". // Document level JavaScript function function runMarquee() { var f = this.getField("marquee"); var cStr = f.value; var aStr = cStr.split(""); aStr.push(aStr.shift()); cStr = aStr.join(""); f.value = cStr; } // // // // // get field value convert to an array move first char to last back to string again put new value in field // Insert a mouse up action into a "Go" button run = app.setInterval("runMarquee()", 100); // stop after a minute stoprun=app.setTimeOut("app.clearInterval(run)",6000); // Insert a mouse up action into a "Stop" button try { app.clearInterval(run); Acrobat JavaScript Object Specification 79
Slide 82: app.clearTimeOut(stoprun); }catch (e) {} Here, we protect the "Stop" button code with a try/catch. If the user presses the "Stop" button without having first pressed the "Go", run and stoprun will be undefined, and the "Stop" code will throw an exception. When the exception is thrown, the catch code is executed. In the above example, code does nothing if the user presses "Stop" first. Acrobat JavaScript Object Specification 80
Slide 83: Bookmark Object A bookmark object represents a node in the bookmark tree that appears in the bookmarks navigational panel. Bookmarks are typically used as a “table of contents” allowing the user to navigate quickly to topics of interest. Bookmark Object Properties children 5.0 Type: Array Access: R Returns an array of bookmark objects that are the children of this bookmark in the bookmark tree. See also the parent property and the bookmarkRoot property of the Doc Object. Example: /* Dump all bookmarks in the document. */ function DumpBookmark(bm, nLevel) { var s = ""; for (var i = 0; i < nLevel; i++) s += " "; console.println(s + "+-" + bm.name); if (bm.children != null) for (var i = 0; i < bm.children.length; i++) DumpBookmark(bm.children[i], nLevel + 1); } console.clear(); console.show(); console.println("Dumping all bookmarks in the document."); DumpBookmark(this.bookmarkRoot, 0); color 5.0 = V Access: R/W Type: Array This property specifies the color for a bookmark. Values are defined by using 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. See also the style property. Example: The following fun script will color the top level bookmark red, green and blue. Acrobat JavaScript Object Specification 81
Slide 84: var bm = bookmarkRoot.children[0] bm.color = color.black; var C = new Array(1, 0, 0); var run = app.setInterval( 'bm.color = ["RGB",C[0],C[1],C[2]]; C.push(C.shift());', 1000); var stoprun=app.setTimeOut( "app.clearInterval(run); bm.color=color.black",12000); Note: This property is read-only in Acrobat Reader. doc 5.0 Type: Object This property is the Doc Object that the bookmark resides in. name 5.0 = Type: String Access: R/W Access: R This property is the text string for the bookmark that the user sees in the navigational panel. open 5.0 = Type: boolean Access: R/W This property determines whether the bookmark shows its children in the navigation panel (open) or whether the children sub-tree is collapsed (closed). parent 5.0 Type: object | null Access: R Acrobat JavaScript Object Specification 82
Slide 85: Returns the parent bookmark of the bookmark or null if the bookmark is the root bookmark. See also the children property and the bookmarkRoot property of the Doc Object. style 5.0 = V Access: R/W Type: Integer This property specifies the style for the bookmark’s font: 0 indicates normal, 1 is italic, 2 is bold, and 3 is bold-italic. See also the color property. Note: This property is read-only in Acrobat Reader. Bookmark Object Methods createChild 5.0 = Parameters: cName, [cExpr], [nIndex] Returns: Nothing Creates a new child bookmark at the specified location. cName is the name of the bookmark that the user will see in the navigation panel. cExpr is an expression to be evaluated whenever the user clicks on the bookmark. Default is no expression. This is equivalent to creating a bookmark with a JavaScript action, see the PDF Reference, “JavaScript Action” for more details. nIndex is the zero-based index into the children array of the bookmark to create the new child at. Default is zero. See also the children property and the insertChild and remove methods. Example: // Create a bookmark at the top of the bookmark panel that takes you to the // next page in the document. bookmarkRoot.createChild("Next Page", "this.pageNum++"); Acrobat JavaScript Object Specification 83
Slide 86: execute 5.0 Parameters: None Returns: Nothing Executes the action associated with this bookmark. This can have a variety of behaviors. See the PDF Reference, Section 7.5.3, “Actions Types” for a list of common action types. See also the createChild property. insertChild 5.0 = Parameters: oBookmark, [nIndex] Returns: Nothing Inserts the specified bookmark as a child of this bookmark. If the bookmark already exists in the bookmark tree it is unlinked before inserting it back into the tree. In addition, the insertion is checked for circularities and disallowed if one exists. This prevents users from inserting a bookmark as a child or grandchild of itself. bookmark is a bookmark object to add as the child of this bookmark. nIndex is the zero-based index into the children array of the bookmark to insert the new child at. The default is zero. See also the children property and the createChild and remove methods. Example: // Take the first child bookmark and move it to the end of the bookmarks. var bm = bookmarkRoot.children[0]; bookmarkRoot.insertChild(bm, bookmarkRoot.children.length); remove 5.0 = Parameters: None Returns: Nothing Removes the bookmark (and all its children) from the bookmark tree. See also the children property and the createChild and insertChild methods. Example: Acrobat JavaScript Object Specification 84
Slide 87: // Remove all bookmarks from the document. bookmarkRoot.remove(); Acrobat JavaScript Object Specification 85
Slide 88: 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 Transparent Gray RGB CMYK String "T" "G" "RGB" "CMYK" # of Additional Elements 0 1 3 4 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 JavaScript Object Specification 86
Slide 89: 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 Equivalent JS [ "T" ] [ "G" 0 ] [ "G" 1 ] [ "RGB" 1 0 0 ] [ "RGB" 0 1 0 ] [ "RGB" 0 0 1 ] [ "CMYK" 1 0 0 0 ] [ "CMYK" 0 1 0 0 ] [ "CMYK" 0 0 1 0 ] [ "G" 0.25 ] [ "G" 0.5 ] [ "G" 0.75 ] 4.0 4.0 4.0 Version 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 */ f.target.textColor = event.value < 0 ? color.red : color.black; Color Methods convert 5.0 Parameters: color array, cColorspace Returns: color array This method converts the colorspace and color values specified by the color object to the specified colorspace. Note that conversion to the gray colorspace is lossy in the same fashion that displaying a color TV signal on a black and white TV is lossy. For printing pundits: the conversion of RGB to CMYK does not take into account any black generation or under color removal parameters. Acrobat JavaScript Object Specification 87
Slide 90: equal 5.0 Parameters: color array 1, color array 2 Returns: bEqual This method compares two color arrays to see if they are the same. The routine will perform conversions, if necessary, to determine if the two colors are indeed equal (i.e. [ "RGB" 1 1 0 ] is equal to [ "CMYK" 0 0 1 0 ]). var f = this.getField("foo"); if (color.equal(f.textColor, f.fillColor)) app.alert("Foreground and background color are the same!"); Acrobat JavaScript Object Specification 88
Slide 91: Connection Object 5.0 V The Connection object is the object that encapsulates a session with a database. Connection objects are returned by the newConnection method of the ADBC Object. Connection methods newStatement 5.0 V Parameters: None Returns: a statement object | null The newStatement method is used to create a Statement Object through which database operations may be performed. It returns a Statement object on success or null on failure. Example: // get a connection object, see newConnection var con = ADBC.newConnection("q32000data"); // now get a statement object var statement = con.newStatement(); var msg = (statement == null) ? "Failed to obtain newStatement!" : "newStatement Object obtained!"; console.println(msg); getTableList 5.0 V Parameters: None Returns: An array of objects The getTableList method is used to get information about the various tables in a database. It returns an array of TableInfo Objects. This method never fails but may return a zero-length array. Acrobat JavaScript Object Specification 89
Slide 92: Below is a table that lists the properties of the TableInfo Object returned by the getTableList method. TableInfo Object The TableInfo object contains basic information about a table. Property name Type string Access R Description A string that represents the identifying name of a table. This string could be used in SQL statements to identify the table that the TableInfo object is associated with. A string that contains database dependent information about the table. description string R Example /* Assuming we have a Connection object (con) already in hand (see newStatement and newConnection), get the list of tables */ var tableInfo = con.getTableList(); console.println("A list of all tables in the database."); for (var i = 0; i < tableInfo.length; i++) { console.println("Table name: "+ tableInfo[i].name); console.println("Description: "+ tableInfo[i].description); } getColumnList 5.0 V Parameters: cName Returns: An array of columninfo objects The getColumnList method is used to get information about the various columns in the table cName is the name of the table to get column information about. Returns an array of ColumnInfo Objects. This method never fails but may return a zero-length array. Acrobat JavaScript Object Specification 90
Slide 93: Below is a table that lists the properties of the ColumnInfo Object. ColumnInfo Object The ColumnInfo object contains basic information about a column of data. Property name Type string Acc ess R Description A string that represents the identifying name of a column. This string could be used in getColumn calls to identify the column that the ColumnInfo object is associated with. A string that contains database dependent information about the column. A numeric value identifying the SQL Type of the data contained in the column associated with the ColumnInfo object. A string identifying the type of the data contained in the column associated with the ColumnInfo object. This is NOT the same information contained in the type property as it is a database dependent string representing the data type. This property may give useful information about user defined data types. description type string number R R typeName string R Example: /* Assuming we have a Connection object (con) already in hand (see and newConnection), get list of all column names */ var con = ADBC.newConnection("q32000data"); var columnInfo = con.getColumnList("sales"); console.println("Column Information"); for (var i = 0; i < columnInfo.length; i++) { console.println(columnInfo[i].name); console.println("Description: "+ columnInfo[i].description); } newStatement Acrobat JavaScript Object Specification 91
Slide 94: Console Object V The Console object is a static object to access the JavaScript console for displaying debug messages and executing JavaScript. It does not function in the Acrobat Reader. Console Methods show Parameters: None Returns: Nothing This method shows the console window. hide Parameters: None Returns: Nothing This method closes the console window. println Parameters: cMessage Returns: Nothing This method prints the string value of cMessage to the console window with an accompanying carriage return. // 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 JavaScript Object Specification 92
Slide 95: Data Object 5.0 The Data object is the representation of an embedded file or data stream that is stored in the document. Data objects are stored in the name tree in the document. See the section on the Names Tree and Embedded File Streams in the PDF Reference Manual for more details. Data objects can be inserted from the external file system, queried, and extracted. This is a good way to associate and embed source files, meta-data, and other associated data with a document. See also the Doc Object dataObjects property, the Document createDataObject, exportDataObject, getDataObject, importDataObject, and removeDataObject methods and the Data Object. Data Object Properties creationDate Type: Date This property is the creation date of the file that was embedded. modDate Type: Date This property is the modification date of the file that was embedded. MIMEType Type: String This property is the MIME type assoicated with this data object. name Type: String This property is the name associated with this data object. Example: console.println("Dumping all data objects in the document."); var d = this.dataObjects; for (var i = 0; i < d.length; i++) console.println("DataObject[" + i + "]=" + d[i].name); Access: R Access: R Access: R Access: R Acrobat JavaScript Object Specification 93
Slide 96: path Type: String This property is the device independent path to the file that was embedded. size Type: Number This property is the size, in bytes, of the uncompressed data object. Access: R Access: R Acrobat JavaScript Object Specification 94
Slide 97: 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 in a variety of ways. The most common method is through this Object, which usually points to the Doc object of the underlying document. Some properties and methods return Doc objects; for example, activeDocs, openDoc, or extractPages all return Doc objects. Example: // Access through "this" var nPages = this.numPages; var aCrop = this.getPageBox(); // get number of pages in "this" document // get the crop box for "this" document /* Access through return values: From one document, open, modify, save and ** close another. */ var myDoc = app.openDoc("myNovel.pdf", this); // path relative to "this" doc myDoc.info.Title = "My Great Novel"; myDoc.saveAs(myDoc.path); myDoc.closeDoc(true); JavaScript is executed as a result of some event. For each event, an Event Object is created. A Doc object can often be accessed through the target property of the Event object. The target property returns the Field Object that initiated the event for all mouse, focus, blur, calculate, validate, and format events; Doc object access is then through the doc property of Field Object. For all other events, the target property points to the Doc object. Example: Access through the Event Object. // In Mouse, calculate, validate, format, focus, blur events var myDoc = event.target.doc; // In all other events (e.g., batch or console events) var myDoc = event.target; Doc Object Properties author L = V Access: R/W Type: String Acrobat JavaScript Object Specification 95
Slide 98: This property defines the author of the document. See also the document info property which supersedes this property in later versions. Note: This property is read-only in Acrobat Reader. baseURL 5.0 = Type: String Access: R/W Base URL for the document. The base URL is used to resolve relative web links within the document. console.println("Base URL was " + this.baseURL); this.baseURL = "http://www.adobe.com/products/"; console.println("Base URL is " + this.baseURL); See also the URL property. bookmarkRoot 5.0 Type: object Access: R Returns the root bookmark for the bookmark tree. This bookmark is not displayed to the user; it is simply a programmatic construct to access the tree and access the child bookmarks. See the Bookmark Object an example of usage. calculate 4.0 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. Acrobat JavaScript Object Specification 96
Slide 99: creator L Type: String Access: R This property defines the creator of the document (e.g. "Adobe FrameMaker", "Adobe PageMaker", etc.). See also the document info property which supersedes this property in later versions. creationDate L Type: Date Access: R This property defines the document’s creation date. See also the document info property which supersedes this property in later versions. dataObjects 5.0 Type: Array Returns an array comprised of all the named data objects in the document. Example: var d = this.dataObjects; for (var i = 0; i < d.length; i++) console.println("Data Object[" + i + "]=" + d[i].name); Access: R See also the Document dataObjects property, the Document createDataObject, exportDataObject, getDataObject, importDataObject, and removeDataObject methods and the Data Object. delay 4.0 Type: Boolean Access: R/W This property can delay the redrawing of any appearance changes to every field in the document. It is generally used to buffer a series of changes to fields before requesting that the fields regenerate their appearance. Setting the property to true forces all changes to be queued until delay is reset to false. Once set to false then all the fields on the page are re-drawn. Acrobat JavaScript Object Specification 97
Slide 100: See also the field level delay property. dirty = Type: Boolean Access: R/W This property identifies whether the document has been dirtied as the result of a changes to the document (and therefore needs to be saved). It is useful to reset the dirty flag in a document when performing changes that do not warrant saving, for example, updating a status field in the document. var f = this.getField("Status"); var b = this.dirty; f.value = "Press the reset button to clear the form."; this.dirty = b; external 4.0 Type: Boolean Access: R This property indicates whether the current document is being viewed in the Acrobat application or in an external window (such as a web browser). filesize Type: Integer This property determines the file size of the document in bytes. icons 5.0 Type: Array Access: R Access: R Returns an array of named Icon Objects that are present in the document level named icons tree. Example: if (this.icons == null) console.println("No named icons in this doc"); else Acrobat JavaScript Object Specification 98
Slide 101: console.println("There are " + this.icons.length + " named icons in this doc"); Here is a summary listing of the properties of the icon object Icon Object An icon object is an opaque representation of a Form XObject appearance stored in the document. Icons are mostly used with Field Objects of type button. Property name Type string Access R Description This property returns the name of the icon. An icon may or may not have a name depending on whether it exists the document level named icons tree. Example: // list all named icons for (var i = 0; i < this.icons.length; i++) { console.println("icon[" + i + "]=" + this.icons[i].name); } See also the addIcon, getIcon, importIcon, and removeIcon methods of the Doc Object, the buttonGetIcon, buttonImportIcon, and buttonSetIcon methods of the Field Object, and the Icon Object. info 5.0 Type: object Access: R For the Acrobat Reader, this property returns an object with properties from the document information dictionary in the PDF file. Standard entries include Title, Author, Subject, Keywords, Creator, Producer, CreationDate, ModDate, and Trapped. See Table 8.2 on page 475, Entries in a document information dictionary, in the PDF Reference, for more details. Example: // get title of document var docTitle = this.info.Title; 5.0 = V Access: R/W Type: object Within Acrobat, properties for the info object are read/write access and setting a property in this object will dirty the document. Additional document information fields can be added by Acrobat JavaScript Object Specification 99
Slide 102: setting non-standard properties. Writing to any property in this object in the Acrobat Reader will throw an exception. Example: The following script, this.info.Title = "JavaScript, The Definitive Guide"; this.info.ISBN = "1-56592-234-4"; this.info.PublishDate = new Date(); for (var i in this.info) console.println(i + ": "+ this.info[i]); could produce the following output: CreationDate: Mon Jun 12 14:54:09 GMT-0500 (Central Daylight Time) 2000 Producer: Acrobat Distiller 4.05 for Windows Title: JavaScript, The Definitive Guide Creator: FrameMaker 5.5.6p145 ModDate: Wed Jun 21 17:07:22 GMT-0500 (Central Daylight Time) 2000 SavedBy: Adobe Acrobat 4.0 Jun 19 2000 PublishDate: Tue Aug 8 10:49:44 GMT-0500 (Central Daylight Time) 2000 ISBN: 1-56592-234-4 Note: Standard entries are case insensitive, that is, doc.info.Keywords is the same as doc.info.keywords. keywords L = V Access: R/W Type: String This property specifies the keywords that describe the document (e.g. "forms", "taxes", "government"). See also the document info property which supersedes this property in later versions. Note: This property is read-only in the Acrobat Reader. Acrobat JavaScript Object Specification 100
Slide 103: layout 5.0 Type: String Access: R/W Changes the page layout of the current document. Valid values for this property include "SinglePage", "OneColumn", "TwoColumnLeft", and "TwoColumnRight". modDate L Type: Date Access: R This property contains the date the document was last modified. See also the document info property which supersedes this property in later versions. 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. numTemplates Access: R L 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. Acrobat JavaScript Object Specification 101
Slide 104: 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 L Type: String Access: R 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. Acrobat JavaScript Object Specification 102
Slide 105: 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); Access: R 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. Acrobat JavaScript Object Specification 103
Slide 106: 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. subject L = V Access: R/W Type: String This property defines the document’s subject. See also the document info property which supersedes this property in later versions. Note: This property is read-only in Acrobat Reader. templates 5.0 Type: Array This property returns an array of all of the template objects in the document. See also the createTemplate, getTemplate, and removeTemplate methods of the Doc Object, and the Template Object. title Access: R L = V Access: R/W Type: String This property specifies the title of the document. See also the document info property which supersedes this property in later versions. Note: This property is read-only in Acrobat Reader. Acrobat JavaScript Object Specification 104
Slide 107: URL 5.0 Type: String Access: R This property specifies the document’s URL. If the document is local, it will return an URL with a "file:///" scheme. This may be different than the baseURL. zoom Type: Integer Access: R/W This property is used to get or set the current page zoom level. The values allowed are 8.33% and 1600% specified as an integer. // This example will zoom in to twice the current zoom level. this.zoom *= 2; // This now sets the zoom to 200% this.zoom = 200; zoomType Type: String Access: R/W This property specifies the current zoom type of the document. Valid zoom types are: none, fit page, fit width, fit height, and fit visible width. A convenience zoomType object that defines all the valid zoom types is provided for use from JavaScript. It provides the following zoom types: Zoom Type NoVary FitPage FitWidth FitHeight FitVisibleWidth Preferred Keyword zoomtype.none zoomtype.fitP zoomtype.fitW zoomtype.fitH zoomtype.fitV zoomtype.pref Example: // This example sets the zoom type of the document to fit the width. this.zoomType = zoomtype.fitW; Acrobat JavaScript Object Specification 105
Slide 108: Doc Object Methods addAnnot 5.0 = V Parameters: object literal Returns: Annot Object This method creates an Annot Object having the given object literal. An object literal is a generic object (see Parameter Specification for Methods) which specifies the properties of the Annot Object annotation, such as type, rect, and page, to be created. Example // This example creates a "Square" annotation. var sqannot = this.addAnnot({type: "Square", page: 0}); The above is a minimal example; sqannot will be created as annotation of type "Square" located on page 0 (0 based page numbering). Note: Properties not specified in the object literal are given their default values for the specified type of annotation. Example: var annot = this.addAnnot({ page: 0, type: "Square", rect: [0, 0, 100, 100], name: "OnMarketShare", author: "A. C. Robat", contents: "This section needs revision." }); addField 5.0 = V Parameters: cName, cFieldType, nPageNum, oCoords Returns: object Creates a new form field and returns a Field Object. cName is the name of the new field to create. This name can use the dot separator syntax to denote a hierarchy (e.g. name.last will create a parent node, name, and a child node, last). Acrobat JavaScript Object Specification 106
Slide 109: cFieldType is the type of form field to create. Valid types include "text", "button", "combobox", "listbox", "checkbox", "radiobutton", or "signature". nPageNum is the zero-based index of the page to add the field to. oCoords is an array of four numbers in Rotated User Space that specifies the size and placement of the form field. These four numbers are, in this order: upper-left x, upper-left y, lower-right x and lower-right y coordinates. See also Field.rect. Example: The following code might be used in a batch sequence to create a navigational icon on every page of a document, for each document in a selected set of documents. var inch = 72; for (var p = 0; p < this.numPages; p++) { var aRect = this.getPageBox( {nPage: p} ); aRect[0] += .5*inch; // position rectangle (.5 inch, .5 inch) aRect[2] = aRect[0]+.5*inch; // from upper left hand corner of page. aRect[1] -= .5*inch; // Make it .5 inch wide aRect[3] = aRect[1] - 24; // and 24 points high // now construct button field with a right arrow from ZapfDingbats var f = this.addField("NextPage", "button", p, aRect ) f.setAction("MouseUp", "this.pageNum++"); f.delay = true; f.borderStyle = border.s; f.highlight = "push"; f.textSize = 0; // auto sized f.textColor = color.blue; f.fillColor = color.ltGray; f.textFont = font.ZapfD f.buttonSetCaption("\341") // a right arrow f.delay = false; } See setAction for another example. Note: For developers that use the info panel to obtain the coordinates of the bounding rectangle, be warned, the info panel uses the upper left corner as the origin of its coordinate system. To transform from info space to rotated user space, simply subtract the info space y-coordinate from the onscreen page height. addIcon Parameters: cName, icon object. Acrobat JavaScript Object Specification 107
Slide 110: 5.0 = Returns: Nothing This function adds a new named Icon Object to the document level icon tree, storing it under the name specified by cName. Example: This example takes an icon already attached to a form button field in the document and assigns a name to it. This name can be used to retrieve the icon object with a getIcon for use in another button, for example. var f = this.getField("myButton"); this.addIcon("myButtonIcon", f.buttonGetIcon()); See also the icons property and the getIcon, importIcon and removeIcon methods of the Doc Object, the buttonGetIcon, buttonImportIcon, and buttonSetIcon methods of the Field Object, and the Icon Object. addThumbnails 5.0 = V Parameters: [nStart], [nEnd] Returns: Nothing Creates thumbnails for the specified pages in the document. nStart and nEnd are zero-based indexes that define an inclusive range of pages. If nStart and nEnd are not specified then the range of pages is for all pages in the document. If only nStart is specified then the range of pages is the single page specified by nStart. If only nEnd is specified then the range of a pages is 0 to nEnd. See also the removeThumbnails method. addWeblinks 5.0 = V Parameters: [nStart], [nEnd] Returns: integer Scans the specified pages looking for instances of text with an http: scheme and converts them into links with URL actions. nStart and nEnd are zero-based indexes that define an inclusive range of pages. If nStart and nEnd are not specified then the range of pages is for all pages in the document. If only nStart Acrobat JavaScript Object Specification 108
Slide 111: is specified then the range of pages is the single page specified by nStart. If only nEnd is specified then the range of a pages is 0 to nEnd. Returns the number of web links added to the document. See also the removeWeblinks method. bringToFront 5.0 Parameters: None Returns: Nothing This method brings the document, open in the Viewer, to the front, if it’s not already there. Example: /* This example searches among the documents open in the Viewer for the document with a title of "Annual Report" and brings it to the front */ var d = app.activeDocs; for (var i = 0; i < d.length; i++) if (d[i].info.Title == "Annual Report") d[i].bringToFront(); calculateNow Parameters: None Returns: Nothing Use this function to force computation of all calculation fields in the current document. closeDoc 5.0 Parameters: [bNoSave] Returns: false This method closes the document corresponding to the Doc object. If bNoSave is false, the default, the user is prompted to save the document, if it has been modified. If bNoSave is true, the document is closed without prompting the user and without saving, even if the document has been modified. Because this can cause data loss without user approval, use this feature judiciously. Acrobat JavaScript Object Specification 109
Slide 112: Note: It is important to use this method carefully as it is an abrupt change in the document state that can affect any JS executing after the close. Triggering this method off of a Page event or Document event could cause the application to behave strangely. createDataObject 5.0 = V Parameters: cName, cValue, [cMIMEType] Returns: nothing Data objects can be constructed adhoc. This is useful if the data is being created in JavaScript from other sources instead of an external file (e.g. ADBC database calls). cName is the name to associate with the data object. cValue is a string containing the data to be embedded. cMIMEType is the MIME type of the data. Default is "text/plain". Example: this.createDataObject("MyData", "This is some data."); See also the Document dataObjects property, the Document createDataObject, exportDataObject, getDataObject, importDataObject, and removeDataObject methods and the Data Object. createTemplate 5.0 = B V Parameters: cName, [nPage] Returns: template object Use this function to create a visible template from the specified page. cName is the name to be associated with this page. nPage is the zero-based index of the page to operate on. If nPage is not specified then nPage is the first page in the document. Returns the newly created Template Object. See also the templates property, the getTemplate, and removeTemplate methods of the Doc Object, and the Template Object. Acrobat JavaScript Object Specification 110
Slide 113: Security B: This method can only be executed during batch, console, or menu events. See the Event Object for a discussion of Acrobat JavaScript events. deletePages 5.0 = V Parameters: [nStart], [nEnd] Returns: Nothing Deletes pages from the document. nStart is the zero-based index of the first page in the range of pages to be deleted. The optional nEnd parameter indicates the last page in the range of pages to be deleted. If nEnd is not specified then only the page specified by nStart is deleted. Both nStart and nEnd have a default value of zero, so if this.deletePages() is executed, the first page (page 0) will be deleted. See also the insertPages, extractPages and replacePages methods. Note: You cannot delete all pages in a document: there must be at least one page remaining. deleteSound 5.0 = Parameters: cName Returns: Nothing This method deletes the sound object with the specified name from the document. Example: this.deleteSound("Moo"); See also the sounds property, the getSound and importSound methods, and the Sound Object. Acrobat JavaScript Object Specification 111
Slide 114: exportAsFDF 4.0 V Parameters: [bAllFields], [bNoPassword], [aFields], [bFlags], [cPath] Returns: Nothing Use this method to export a FDF file to the local hard drive. The optional bAllFields parameter indicates, if true, that all fields are exported, including those that have no value, and if false (the default) to exclude those that currently have no value. The optional bNoPassword parameter indicates, if true (the default), not to include in the exported FDF text fields that have the "password" flag set. The optional aFields parameter is the array of field names to submit or a string containing a single field name. If this parameter is present then only the fields indicated are exported, except those excluded by parameter bAllFields or bNoPassword. If this parameter is omitted or is null then all fields in the form are exported (again subject to the restrictions of bAllFields and bNoPassword). This parameter can contain non-terminal field names in order to export an entire subtree of fields, see the example below. The optional bFlags parameter indicates, if true, that field flags should be included in the exported FDF. The default is false. 5.0 Additions The optional cPath, is a string specifying the device-independent pathname for the FDF. (See Section 3.10.1 of the PDF Reference for a description of the device-independent pathname format.) The pathname may be relative to the location of the current document. If the parameter is omitted a dialog will be shown to let the user select the file to export to. Example: /* Export the entire form (including empty fields) with flags. */ this.exportAsFDF(true, true, null, true); /* Export the name subtree with no flags. */ this.exportAsFDF(false, true, "name"); The example above illustrates a shortcut to exporting a whole subtree. Passing "name" as part of the aFields parameter, exports "name.title", "name.first", "name.middle" and "name.last", etc. Acrobat JavaScript Object Specification 112
Slide 115: Security B: If the "cPath" parameter is specified, then this method can only be executed during batch, console, or menu events. See the Event Object for a discussion of Acrobat JavaScript events. exportAsXFDF 5.0 V Parameters: [bAllFields], [bNoPassword], [aFields], [cPath] Returns: Nothing Use this method to export an XFDF file to the local hard drive. XFDF is an XML representation of Acrobat form data. See the Adobe CD Documentation Forms System Implementation Notes for more details. The optional bAllFields parameter indicates, if true, that all fields are exported, including those that have no value, and if false (the default) to exclude those that currently have no value. The optional bNoPassword parameter indicates, if true (the default), not to include in the exported XFDF text fields that have the "password" flag set. The optional aFields parameter is the array of field names to submit or a string containing a single field name. If this parameter is present then only the fields indicated are exported, except those excluded by parameter bAllFields or bNoPassword. If this parameter is omitted or is null then all fields in the form are exported (again subject to the restrictions of bAllFields and bNoPassword). The optional cPath, is a string specifying the device-independent pathname for the XFDF. (See Section 3.10.1 of the PDF Reference for a description of the device-independent pathname format.) The pathname may be relative to the location of the current document. If the parameter is omitted a dialog will be shown to let the user select the file. If this parameter is omitted, a dialog will be shown to let the user select the file to export to. Security B: If the cPath parameter is specified, then this method can only be executed during batch, console or menu events. See the Event Object for a discussion of Acrobat JavaScript events. Acrobat JavaScript Object Specification 113
Slide 116: exportDataObject 5.0 B V Parameters: cName, [cDIPath] Returns: nothing This method extracts the specified data object to an external file. cName is the name of the data object to extract. cDIPath is optional and specifies a device independent path to extract the data object to. This path may be absolute or relative to the current document. If cDIPath is not specified then the user will be prompted to specify a save location. See File Specification Strings in the PDF Reference Manual for the exact syntax of the path. Example: // Prompt the user for a file and location to extract to. this.extractDataObject("MyData"); // Extract to Foo.xml. this.extractDataObject("MyData2", "../Foo.xml"); See also the Document dataObjects property, the Document createDataObject, exportDataObject, getDataObject, importDataObject, and removeDataObject methods and the Data Object. Security B: 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. extractPages 5.0 = B V Parameters: [nStart], [cEnd], [cPath] Returns: doc object | null Creates a new document consisting of pages extracted from the current document. nStart and nEnd are zero-based indexes that define an inclusive range of pages in the source document to extract. If nStart and nEnd are not specified then the range of pages is for all pages in the document. If only nStart is specified then the range of pages is the single page specified by nStart. If only nEnd is specified then the range of pages is 0 to nEnd. cPath specifies the device-independent pathname to save the new document to. See 3.10.1 of the PDF Reference Manual for a description of the device independent path name format. The Acrobat JavaScript Object Specification 114
Slide 117: path name may be relative to the location of the current document. The return value in this case is the null object as the new document has been saved to this path and closed. If cPath is not specified then the new document is opened in the viewer and the Doc Object for the new document is returned by the call. See also the deletePages, insertPages, and replacePages methods. Example: The following batch sequence would take each of the selected files and extract each page and save the page to a folder with an unique name. This example may be useful in the following setting. Clients one-page bills are produced by an application and placed in a single PDF file. It is desired to separate the pages for distribution and/or separate printing jobs. /* Extract Pages to Folder */ // regular expression acquire the base name of file var re = /.*\/|\.pdf$/ig; // filename is the base name of the file Acrobat is working on var filename = this.path.replace(re,""); try { for (var i = 0; i < this.numPages; i++) this.extractPages( { nStart: i, cPath: "/F/temp/"+filename+"_" + i +".pdf" }); } catch (e) { console.println("Aborted: "+e) } Security B: If the cPath 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. flattenPages 5.0 = V Parameters: [nStart], [cEnd] Returns: Nothing Converts all annotations in the specified page range to page contents. Acrobat JavaScript Object Specification 115
Slide 118: nStart and nEnd are zero-based indices that define an inclusive range in the current document. If only nStart is specified, then the page range is the single page specified by nStart. If neither parameter is specified, then the page range is all the pages in the current document. Note: Great care must be used when using this method. All annotations— including form fields, comments and links— on the specified range of pages will be flattened; they may have appearances, but they will no longer be annotations. getAnnot 5.0 Parameters: nPage, cName Returns: annot object | null This method returns the Annot Object on the given page, nPage, and with the given name, cName. If there is no such annotation with the specified description, the method returns null. Example: var ann = this.getAnnot(0, "OnMarketShare"); if (ann == null) console.println("Not Found!") else console.println("Found it! type: " + ann.type); getAnnots 5.0 Parameters: [nPage], [nSortBy], [bReverse], [nFilterBy] Returns: array of annot objects This method takes the criteria set down by the optional parameters and returns an array of Annot Objects satisfying this criteria. If specified, nPage is the zero-based page number that causes the method to return only annotations on the given page. If nPage is not specified then the annotations from all pages are retrieved that meet the search criteria. Acrobat JavaScript Object Specification 116
Slide 119: nSortBy, if specified, is a sort method applied to the array. The following table lists the valid values for nSortBy: Values of nSortBy Name Description ANSB_None ANSB_Page ANSB_Author ANSB_ModDate ANSB_Type default; do not sort; equivalent to leaving nSortBy out use the page number as the primary sort criteria use the author as the primary sort criteria use the modification date as the primary sort criteria use the annot type as the primary sort criteria bReverse, if true, causes the array to be reverse sorted with respect to nSortBy. nFilterBy, if specified, causes only annots satisfying certain criteria to appear in the resultant list. The valid values for nFilterBy are given below: Values of bFilterBy Name Description ANFB_ShouldNone ANFB_ShouldPrint ANFB_ShouldView ANFB_ShouldEdit ANFB_ShouldAppearInPanel ANFB_ShouldSummarize ANFB_ShouldExport default; equivalent to leaving nFilterBy out only include annots that should print only include annots that should view only include annots that should be editable only include annots that should appear in the annotations pane only include annots that should be included in a summarization only include annots that should be included in an export Example: this.syncAnnotScan(); var annots = this.getAnnots({ nPage:0, nSortBy: ANSB_Author, bReverse: true }); console.show(); console.println("Number of Annots: " + annots.length); Acrobat JavaScript Object Specification 117
Slide 120: var msg = "%s in a %s annot said: \"%s\""; for (var i = 0; i < annots.length; i++) console.println(util.printf(msg, annots[i].author, annots[i].type, annots[i].contents)); See also getAnnot and syncAnnotScan, especially the note that follows that method. getDataObject 5.0 Parameters: cName Returns: data object This method returns the data object corresponding to the specified name. cName is the name of the data object to get. Example: var d = this.getDataObject("MyData"); console.show(); console.clear(); for (var i in d) console.println("MyData." + i + "=" + d[i]); See also the Document dataObjects property, the Document createDataObject, exportDataObject, getDataObject, importDataObject, and removeDataObject methods and the Data Object. getField Parameters: cName Returns: Field object Use this function to map a Field Object in the PDF document to a JavaScript variable. The cName parameter is the name of the field of interest. This function returns a Field Object representing the form field in the PDF document. Example: // Make a text field multiline and triple its height var f = this.getField("myText"); var aRect = f.rect; // get bounding rectangle f.multiline = true; // make it multiline var height = aRect[1]-aRect[3]; // calculate height aRect[3] -= 2* height; // triple the height of the text field f.rect = aRect; // and make it so Acrobat JavaScript Object Specification 118
Slide 121: getIcon 5.0 Parameters: cName Returns: icon object This function returns an Icon Object associated with the specified name in the document or null if no icon of that name exists. Example: The following is a custom keystroke script from a combobox. The face names of the items in the combobox are the names of some of the icons that populate the document. As the user chooses different items from the combobox, the corresponding icon appears as the button face of the field "myPictures". if (!event.willCommit) { var b = this.getField("myPictures"); var i = this.getIcon(event.change); b.buttonSetIcon(i); } See buttonSetIcon for a more elaborate variation on this example. See also the icons property and the addIcon, importIcon, and removeIcon methods of the Doc Object, the buttonGetIcon, buttonImportIcon, and buttonSetIcon methods of the Field Object, and the Icon Object. getNthFieldName 4.0 Parameters: nIndex Returns: String Use this function to obtain the nth field name in the document (see the numFields property). Example: // Enumerate through all of the fields in the document. for (var i = 0; i < this.numFields; i++) console.println("Field[" + i + "] = " + this.getNthFieldName(i)); getNthTemplate L V Parameters: nIndex Acrobat JavaScript Object Specification 119
Slide 122: Returns: String Use this function to retrieve the name of the nth template within in the document. This method is superceded by use of the Doc Object’s templates property and the getTemplate method, and the Template Object object in later versions. getPageBox 5.0 Parameters: [cBox], [nPage] Returns: array of four numbers cBox can be one of "Art", "Bleed", "BBox", "Crop" (the default), or "Trim". For definitions of these boxes please see Section 8.6.1, “Page Boundaries”, page 524, in the PDF Reference. Default is "Crop". nPage is the zero-based index of the page to operate on. If nPage is not specified then nPage is the first page in the document. Returns a rectangle in Rotated User Space that encompasses the named box for the page. See also the setPageBoxes method. Example: Get the dimensions of the Media box. var aRect = this.getPageBox("Media"); var width = aRect[2] - aRect[0]; var height = aRect[1] - aRect[3]; console.println("Page 1 has a width of " + width + " and a height of " + height); getPageLabel 5.0 Parameters: [nPage] Returns: String Returns page label information for the specified page. nPage is the zero-based index of the page to operate on. If nPage is not specified then nPage is the first page in the document. See also the setPageLabels method for a good example. Acrobat JavaScript Object Specification 120
Slide 123: getPageNthWord 5.0 Parameters: [nPage], [nWord], [bStrip] Returns: String Returns the nth word on the page. nPage is the zero-based index of the page to operate on. If nPage is not specified then nPage is the first page in the document. nWord is the zero-based index of the word to obtain. If nWord is not specified then nWord is the first word on the page. bStrip is a boolean indicating that punctuation and whitespace should be removed from the word before returning. Default is true. See also the getNthTemplate, getPageNumWords, and selectPageNthWord methods. Security B: This method will throw an exception if the document security is set to prevent content extraction. getPageNthWordQuads 5.0 B Parameters: [nPage], [nWord] Returns: Array of quads Returns the quads list for the nth word on the page. The quads can be used for constructing text markup annotations, Underline, StrikeOut, Highlight and Squiggly. nPage is the zero-based index of the page to operate on. If nPage is not specified then nPage is the first page in the document. nWord is the zero-based index of the word to obtain. If nWord is not specified then nWord is the first word on the page. See also the B: This method will throw an exception if the document security is set to prevent content extraction. method. Example: The following example underlines the fifth word on the second page of a document. var annot = this.addAnnot({ page: 1, type: "Underline", Acrobat JavaScript Object Specification 121
Slide 124: quads: this.getPageNthWordQuads(1, 4), author: "A. C. Acrobat", contents: "Fifth word on second page" }); See checkWord and Highlight, Strikeout, Underline and Squiggle for more interesting examples. Security B: This method will throw an exception if the document security is set to prevent content extraction. getPageNumWords 5.0 Parameters: [nPage] Returns: number Returns the number of words on the page. nPage is the zero-based index of the page to operate on. If nPage is not specified then nPage is the first page in the document. Example: // count the number of words in a document var cnt=0; for (var p = 0; p < this.numPages; p++) cnt += getPageNumWords(p); console.println("There are " + cnt + " words on this page."); See also the getNthTemplate, getPageNthWord, and selectPageNthWord methods. getPageRotation 5.0 Parameters: [nPage] Returns: integer Gets the rotation of the specified page. nPage is the zero-based index of the page to operate on. If nPage is not specified then nPage is the first page in the document. Returns 0, 90, 180, or 270. Acrobat JavaScript Object Specification 122
Slide 125: See also the setPageRotations method. getPageTransition 5.0 Parameters: [nPage] Returns: array Gets the transition of the specified page. nPage is the zero-based index of the page to operate on. If nPage is not specified then nPage is the first page in the document. The routine returns an array of three values: [ nDuration, cTransition, nTransDuration ]. nDuration is the maximum amount of time the page is displayed before the viewer automatically turns to the next page. A duration of -1 indicates that there is no automatic page turning. cTransition is the name of the transition to apply to the page. See the application property transitions for a list of valid transitions. cTransDuration is the duration (in seconds) of the transition effect. See also the setPageTransitions method. getSound 5.0 Parameters: cName Returns: Sound object This method returns the sound object corresponding to the specified name. Example: var s = this.getSound("Moo"); console.println("Playing the " + s.name + " sound."); s.play(); See also the sounds property, the importSound and deleteSound methods, and the Sound Object. Acrobat JavaScript Object Specification 123
Slide 126: getTemplate 5.0 Parameters: cName Returns: template object | null Use this function to retrieve the named template from the document. Returns null if the named template does not exist in the document. cName is the name of the template to retrieve. See also the templates property, the createTemplate, and removeTemplate methods of the Doc Object, and the Template Object. getURL 4.0 = Parameters: cURL, [bAppend] Returns: Nothing This method retrieves the specified URL over the internet using a GET. cURL can either be fully qualified or a relative URL. It is permissible to have a query string at the end of the URL. If the current document is being viewed inside the browser, or Acrobat Web Capture is not available, it uses the Weblink plug-in to retrieve the requested URL. If running inside Acrobat, then the URL of the current document is obtained either from the document’s Base URL, or from the URL of page #0 (if the document was WebCaptured), or from the file system. The bAppend optional parameter indicates, if true (the default), that the resulting page(s) should be appended to the current document. This flag is considered to be false if the document is running inside the web browser, the Acrobat Web Capture plug-in is not available, or if the URL is of type "file:///". gotoNamedDest Parameters: cName Returns: Nothing Use this method to go to a named destination within the PDF document. For more details on named destinations and how to create them, see page 387 of the PDF Reference. Acrobat JavaScript Object Specification 124
Slide 127: Example: The following example opens a document then goes to a named destination within that document. // open new document var myNovelDoc = app.openDoc("/c/fiction/myNovel.pdf"); // go to destination in this new doc myNovelDoc.gotoNamedDest("chapter5"); // close old document this.closeDoc(); importAnFDF 4.0 = V Parameters: [cPath] Returns: Nothing This method imports the specified FDF file. The cPath parameter specifies the deviceindependent pathname to the FDF file. See Section 3.10.1 of the PDF Reference for a description of the device-independent pathname format. It should look like the value of the /F key in an FDF exported via the submitForm method or via the "File->Export->Form Data" menu item. The pathname may be relative to the location of the current document. If this parameter is omitted a dialog will be shown to let the user select the file. Example: The following code, which is an action of a Page Open event, checks whether a certain function, ProcResponse, is already defined, if not, it installs a document level JavaScript, which resides in an FDF file. if (typeof ProcResponse == "undefined") this.importAnFDF("myDLJS.fdf"); Here, the pathname is a relative one. This technique may be useful for automatically installing document level JavaScripts for PDF files distilled from a PostScript file. See also importAnXFDF and importTextData. importAnXFDF 5.0 = V Parameters: [cPath] Returns: Nothing This method imports the specified XFDF file containing XML form data. The cPath parameter specifies the device-independent pathname to the XFDF file. See Section 3.10.1 of the PDF Reference for a description of the device-independent pathname format. The pathname may be Acrobat JavaScript Object Specification 125
Slide 128: relative to the location of the current document. If the parameter is omitted, a dialog will be shown to let the user select the file. See also importAnFDF and importTextData. For a description of XFDF, please read the Forms System Implementation Notes in the Adobe CD Documentation. importDataObject 5.0 = B V Parameters: cName, [cDIPath] Returns: nothing This method imports an external file into the document and associates the specified name with the "data object", Data objects can later be extracted or manipulated. cName is the name to associate with the data object. cDIPath is optional and specifies a device independent path to a data file on the user’s hard drive. This path may be absolute or relative to the current document. If cDIPath is not specified then the user will be prompted to locate a data file. See File Specification Strings in the PDF Reference Manual for the exact syntax of the path. Example: function DumpDataObjectInfo(dataobj) { for (var i in dataobj) console.println(dataobj.name + "[" + i + "]=" + dataobj[i]); } // Prompt the user for a data file to embed. this.importDataObject("MyData"); DumpDataObjectInfo(this.getDataObject("MyData")); // Embed Foo.xml (found in parent director for this doc). this.importDataObject("MyData2", "../Foo.xml"); DumpDataObjectInfo(this.getDataObject("MyData2")); See also the Document dataObjects property, the Document createDataObject, exportDataObject, getDataObject, importDataObject, and removeDataObject methods and the Data Object. Security B: 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. Acrobat JavaScript Object Specification 126
Slide 129: importIcon 5.0 = B 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 0 1 -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"); Acrobat JavaScript Object Specification 127
Slide 130: 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. Security B: 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 = B 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. Security B: 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. Acrobat JavaScript Object Specification 128
Slide 131: importTextData 5.0 = V 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 0-based; 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. First Al George Alan Bill Middle Recount Dubya Cutrate Outgoing Last Gore Bush Greenspan Clinton // Import the first row of data from "myData.txt". this.importTextData("/c/data/myData.txt", 0) /* ** ** if The following code is a mouse up action for a button. Clicking on the button cycles through the text file and populates the three fields "First", "Middle" and "Last" with the name data. */ (typeof cnt == "undefined") cnt = 0; this.importTextData("/c/data/textdata.txt", cnt++ % 4) The same functionality can be obtained using the ADBC Object and associated properties and methods. The data file can be a spreadsheet or a database. insertPages 5.0 = B V Parameters: [nPage], cPath, [nStart], [nEnd] Acrobat JavaScript Object Specification 129
Slide 132: Returns: Nothing Inserts pages from the source document into the current document. nPage is the zero-based index of the page to insert the source document pages after. To insert pages before the first page of the document nPage can be set to -1. cPath specifies the device-independent pathname to the PDF file that will provide the inserted pages. See Section 3.10.1 of the PDF Reference for a description of the device-independent pathname format. The pathname may be relative to the location of the current document. nStart and nEnd are zero-based indexes that define an inclusive range of pages in the source document to insert. If nStart and nEnd are not specified, then the range of pages is for all pages in the document. If only nStart is specified then the range of pages is the single page specified by nStart. If only nEnd is specified then the range of pages is 0 to nEnd. See also the deletePages and replacePages methods. Security B: This method can only be executed during batch, console, or menu events. See the Event Object for a discussion of Acrobat JavaScript events. mailDoc 4.0 V Parameters: [bUI], [cTo], [cCc], [cBcc], [cSubject], [cMsg] Returns: Nothing This method saves the current PDF document and mails it as an attachment to all recipients with or without user interaction depending on the value of bUI. If it is set to true (the default) then the rest of the 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 all 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 */ this.mailDoc(true); /* This will send out the mail with the attached PDF file to fun1@fun.com and fun2@fun.com */ this.mailDoc(false, "fun1@fun.com", "fun2@fun.com", "", "This is the subject", "This is the body."); Acrobat JavaScript Object Specification 130
Slide 133: Note: On Windows, the client machine must have its default mail program configured to be MAPI enabled in order to use this method. mailForm 4.0 V Parameters: bUI, cTo, [cCc], [cBcc], [cSubject], [cMsg] Returns: Nothing This method exports the form data and mails the resulting FDF file as an attachment to all recipients, with or without user interaction depending on the value of bUI. If it is set to true then the rest of the 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 all 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 */ this.mailForm(true); /* This will send out the mail with the attached FDF file to fun1@fun.com and fun2@fun.com */ this.mailForm(false, "fun1@fun.com; fun2@fun.com", "", "", "This is the subject", "This is the body of the mail."); Note: On Windows, the client machine must have its default mail program configured to be MAPI enabled in order to use this method. movePage 5.0 = V Parameters: [nPage], [nAfter] Returns: Nothing Moves a page within the document. nPage is the zero-based index of the page to move. Default is 0. Acrobat JavaScript Object Specification 131
Slide 134: nAfter is the zero-based index of the page to move the page after. To move the page before the first page of the document nAfter can be set to -1. Default is the last page in the document. Example: reverse the pages in the document. for (i = this.numPages - 1; i >= 0; i--) this.movePage(i); print Parameters: [bUI], [nStart], [nEnd], [bSilent], [bShrinkToFit], [bPrintAsImage], [bReverse], [bAnnotations] Returns: Nothing Use this function to print all or a specific number of pages of the document. bUI, if true (the default), will cause a UI to be pre-populated with any parameters supplied and presented to the user to obtain the missing information and confirm the action. nStart and nEnd are zero-based indexes that define an inclusive range of pages. If nStart and nEnd are not specified then the range of pages is for all pages in the document. If only nStart is specified then the range of pages is the single page specified by nStart. If only nEnd is specified then the range of a pages is 0 to nEnd. If nStart and nEnd parameters are used, bUI must be false. bSilent, if true, suppresses the cancel dialog box while the document is printing. Default is false. 5.0 Additions bShrinkToFit, if true, the page is shrunk (if necessary) to fit within the imageable area of the printed page. If false, it is not. The default is false. bPrintAsImage, if true, print pages as an image. The default is false. bReverse, if true, print from nEnd to nStart. The default is false. bAnnotations, if true (the default), annotations are printed. Example: // This Example will print current page the document is on this.print(false, this.pageNum, this.pageNum); // print a file silently this.print({bUI: false, bSilent: true, bShrinkToFit: true}); Acrobat JavaScript Object Specification 132
Slide 135: removeDataObject 5.0 = V Parameters: cName Returns: nothing This method deletes the data object corresponding to the specified name from the document. cName is the name of the data object to remove. Example: this.removeDataObject("MyData"); See also the Document dataObjects property, the Document createDataObject, exportDataObject, getDataObject, importDataObject, and removeDataObject methods and the Data Object. removeField 5.0 = V Parameters: cName Returns: Nothing Removes the field specified by cName from the document. If the field appears on more than one page then all representations are removed. removeIcon 5.0 = Parameters: cName Returns: Nothing This function removes the specified named icon from the document. See also the icons property and the addIcon, getIcon and importIcon methods of the Doc Object, the buttonGetIcon, buttonImportIcon, and buttonSetIcon methods of the Field Object, and the Icon Object. removeTemplate 5.0 = B V Parameters: cName Returns: Nothing Acrobat JavaScript Object Specification 133
Slide 136: Use this function to remove the named template from the document. cName is the name of the template to remove. See also the templates property, the createDataObject and getSound methods of the Data Object, and the Template Object. Security B: This method can only be executed during batch or console events. See the Event Object for a discussion of Acrobat JavaScript events. removeThumbnails 5.0 = V Parameters: [nStart], [nEnd] Returns: Nothing Deletes thumbnails for the specified pages in the document. nStart and nEnd are zero-based indexes that define an inclusive range of pages. If nStart and nEnd are not specified then the range of pages is for all pages in the document. If only nStart is specified then the range of pages is the single page specified by nStart. If only nEnd is specified then the range of a pages is 0 to nEnd. See also the addThumbnails method. removeWeblinks 5.0 = V Parameters: [nStart], [nEnd] Returns: integer Scans the specified pages looking for links with actions to go to a particular URL on the web and deletes them. nStart and nEnd are zero-based indexes that define an inclusive range of pages. If nStart and nEnd are not specified then the range of pages is for all pages in the document. If only nStart is specified then the range of pages is the single page specified by nStart. If only nEnd is specified then the range of a pages is 0 to nEnd. Returns the number of web links removed from the document. See also the addWeblinks method. Acrobat JavaScript Object Specification 134
Slide 137: Note: This method will only remove weblinks authored in the application using the UI. Web links that are executed via JavaScript (e.g. getURL) are not removed. replacePages 5.0 = B V Parameters: [nPage], cPath, [nStart], [nEnd] Returns: Nothing Replaces pages in the current document with pages from the source document. nPage is the zero-based index of the page to start replacement at. Default is 0. cPath specifies the device-independent pathname to the PDF file that will provide the replacement pages. See Section 3.10.1 of the PDF Reference for a description of the deviceindependent pathname format. The pathname may be relative to the location of the current document. nStart and nEnd are zero-based indexes that define an inclusive range of pages in the source document to be used for replacement. If nStart and nEnd are not specified then the range of pages is for all pages in the document. If only nStart is specified then the range of pages is the single page specified by nStart. If only nEnd is specified then the range of pages is 0 to nEnd. See also the deletePages, extractPages and insertPages methods. Security B: This method can only be executed during batch, console, or menu events. See the Event Object for a discussion of Acrobat JavaScript events. resetForm = Parameters: [aFields] Returns: Nothing Use this method to reset the field values within a document. If the aFields parameter is present, then only the fields indicated are reset. If not present or null then all fields in the form are reset. You can include non-terminal fields in the array. Use this as a simple shortcut for having a whole subtree reset. For example, if you pass "name" as part of the fields array then "name.first", "name.last", etc. will be reset. Acrobat JavaScript Object Specification 135
Slide 138: var fields = new Array(2); fields[0] = "P1.OrderForm.Description"; fields[1] = "P1.OrderForm.Qty"; this.resetForm(fields); Note: Resetting a field causes it to take on its default value which in the case of text fields is usually blank. saveAs 5.0 B V Parameters: cPath Returns: nothing This method saves the file to the device independent path specified by the required parameter, cPath. The file is not saved in linearized format. Example: The following code could appear as a batch sequence. Assume there is a PDF file already open containing form files that needs to be populated from a database and saved. Below is an outline of the script: var aDocs = app.activeDocs; // get all active docs var myForm = aDocs[0]; // assume our file is the only one open in viewer // code lines to read from a database and populate the form with data // now save file to a folder; use customerID from database record as name var row = statement.getRow(); ....... myForm.saveAs("/c/customer/invoices/" + row.customerID + ".pdf"); Example: You can use the newDoc and addField methods to dynamically layout a form, then populate it from a database and save. var myDoc = app.newDoc() // layout some dynamic form fields // connect to database, populate with data, perhaps from a database .......... // save the doc and/or print it; print it silently this time to default printer myDoc.saveAs("/c/customer/invoices/" + row.customerID + ".pdf"); myDoc.closeDoc(true); // close the doc, no notification Security B: This method can only be executed during batch, console, or menu events. See the Event Object for a discussion of Acrobat JavaScript events. Acrobat JavaScript Object Specification 136
Slide 139: scroll Parameters: nX, nY Returns: Nothing Use this function to scroll the point on the current page specified by nX and nY into middle of the current view. These coordinates must be defined in Rotated User Space. Please refer to the PDF Reference, page 126, for more details on the user space coordinate system. selectPageNthWord 5.0 Parameters: [nPage], [nWord], [bScroll] Returns: Nothing Changes the current page number to nPage and selects the specified word on the page. nPage is the zero-based index of the page to operate on. If nPage is not specified then nPage is the first page in the document. nWord is the zero-based index of the word to obtain. If nWord is not specified then nWord is the first word on the page. bScroll indicates whether or not to scroll the selected word into the view if it isn’t already viewable. Default is true. See also the getNthTemplate, getPageNthWord and getPageNumWords methods. setPageBoxes 5.0 = V Parameters: [cBox], [nStart], [nEnd], [rBox] Returns: Nothing Sets a rectangle that encompasses the named box for the specified pages. nStart and nEnd are zero-based indexes that define an inclusive range of pages in the document to be operated on. If nStart and nEnd are not specified then the range of pages is for all pages in the document. If only nStart is specified then the range of pages is the single page specified by nStart. cBox can be one of "Art", "Bleed", "Crop", "Media", or "Trim". Note that "BBox" is read-only and only supported in getPageBox. For definitions of these boxes please see Section 8.6.1, “Page Boundaries”, page 524, in the PDF Reference. Acrobat JavaScript Object Specification 137
Slide 140: rBox is an array of four numbers in Rotated User Space that the specified box will be set to. If rBox is not provided then the specified box is removed. See also the getPageBox method. setPageLabels 5.0 = V Parameters: [nPage], [aLabel] Returns: Nothing This method establishes the numbering scheme for the specified page and all pages following it until the next page with an attached label is encountered. nPage is the zero-based index that defines the page to be labelled. If aLabel is not supplied, any page numbering for the page and any others up to the next specified label is removed. When specified, aLabel is an array of three items [ cStyle, cPrefix, nStart ]. cStyle is the style of page numbering and one of "D" (decimal numbering), "R", "r" (roman numbering upper/lower), "A", "a" (alphabetic numbering upper/lower). See the PDF Reference, Section 7.3.1, for the exact definitions of these styles. cPrefix is a string to prefix to the numeric portion of the page label. nStart is the ordinal to start numbering the pages at. Example: 10 pages in the document, label the first 3 with small roman numerals, the next 5 with numbers (starting at 1) and the last 2 with an "Appendix- prefix" and alphabetics. this.setPageLabels(0, [ "r", "", 1]); this.setPageLabels(3, [ "D", "", 1]); this.setPageLabels(8, [ "A", "Appendix-", 1]); var s = this.getPageLabel(0); for (var i = 1; i < this.numPages; i++) s += ", " + this.getPageLabel(i); console.println(s); Would produce the following output on the console: i, ii, iii, 1, 2, 3, 4, 5, Appendix-A, Appendix-B Example: remove all page labels from a document. for (var i = 0; i < this.numPages; i++) { if (i + 1 != this.getPageLabel(i)) { Acrobat JavaScript Object Specification 138
Slide 141: // Page label does not match ordinal page number. this.setPageLabels(i); } } See also the getPageLabel method. setPageRotations 5.0 = V Parameters: [nStart], [nEnd], [nRotate] Returns: Nothing Rotates the specified pages in the current document. nStart and nEnd are zero-based indexes that define an inclusive range of pages in the document to be operated on. If nStart and nEnd are not specified then the range of pages is for all pages in the document. If only nStart is specified then the range of pages is the single page specified by nStart. If only nEnd is specified then the range of pages is 0 to nEnd. nRotate specifies the amount of rotation that should be applied to the target pages. It should be either 0, 90, 180, or 270. If nRotate is not specified then nRotate is zero. See also the getPageRotation method. setPageTransitions 5.0 = V Parameters: [nStart], [nEnd], [aTrans] Returns: Nothing nStart and nEnd are zero-based indexes that define an inclusive range of pages in the document to be operated on. If nStart and nEnd are not specified then the range of pages is for all pages in the document. If only nStart is specified then the range of pages is the single page specified by nStart. If aTrans is not present any page transitions for the pages are removed. The page transition array consists of three values: [ nDuration, cTransition, nTransDuration ]. nDuration is the maximum amount of time the page is displayed before the viewer automatically turns to the next page. Setting nDuration to -1 indicates that automatic page turning should be turned off. Acrobat JavaScript Object Specification 139
Slide 142: cTransition is the name of the transition to apply to the page. See transitions for a list of valid transitions. nTransDuration is the duration (in seconds) of the transition effect. See also the getPageTransition method. spawnPageFromTemplate L = V Parameters: cTemplate, [nPage], [bRename], [bOverlay] Returns: Nothing Use this method with a template name, cTemplate, such as the ones returned by getNthTemplate. The optional parameter nPage, represents the page number (zero-based) into which the template will be spawned. If that page already exists, then the template contents are appended to that page (but see parameter bOverlay). If nPage is omitted, a new page is created at the end of the document. The optional parameter bRename, is a boolean that indicates whether fields should be renamed. The default for bRename is true. 4.0 Addition If bOverlay is false then the template is inserted before the page specified by nPage as opposed to being overlaid on top of that page. The default for bOverlay is true. Example: var n = this.numTemplates; var cTempl; for (i = 0; i < n; i++) { cTempl = this.getNthTemplate(i); this.spawnPageFromTemplate(cTempl); } See also the Doc Object’s templates property and the createTemplate method and the Template Object’s spawn method which supersedes this method in later versions. Note: The template feature does not work in Acrobat Reader. Acrobat JavaScript Object Specification 140
Slide 143: submitForm Parameters: cURL, [bFDF], [bEmpty], [aFields], [bGet], [bAnnotations], [bXML], [bIncrChanges], [bPDF], [bCanonical], [bExclNonUserAnnots], [bExclFKey], [cPassword] Returns: Nothing Use this method to submit the form to a specific URL. The first parameter, cURL, is the URL to submit to. This string must end in "#FDF" if the result from the submission is FDF and the document is being viewed inside a browser window. The optional bFDF parameter is a boolean that indicates to submit as FDF or HTML. If set to true, the default, it submits the form data as FDF. If false, it submits it as HTML (URL encoded). The optional bEmpty parameter is a boolean that indicates, when true, that all fields are submitted, including those that have no value and if false to exclude those that currently have no value. The default for bEmpty is false. The optional aFields parameter is the array of field names to submit or a string containing a single field name. If this parameter is present then only the fields indicated are submitted, except those excluded by parameter bEmpty. If this parameter is omitted or is null then all fields in the Form are submitted (again subject to the restrictions of bEmpty). 4.0 Addition The optional bGet parameter is a boolean that indicates, if true, that the submission uses the GET HTTP method and if false (the default) a POST. GET is only allowed if using Acrobat Web Capture to submit (the browser interface only supports POST) and only if the data is sent as HTML (i.e. parameters bFDF, bXML and bPDF should all be false). 5.0 Additions The optional bAnnotations parameter is a boolean that indicates, if true, that the annotations should be included in the submitted FDF or XML. The default is false. Only applicable if bFDF or bXML are true. The optional bXML parameter is a boolean that indicates, if true, to submit as XML. The default is false. The optional bIncrChanges parameter is a boolean that indicates, if true, to include in the submitted FDF the incremental changes to the PDF. The default is false. Only applicable if bFDF is true. Not available in the Acrobat Reader. Acrobat JavaScript Object Specification 141
Slide 144: The optional bPDF parameter is a parameter that indicates, if true, to submit the complete PDF document itself. The default is false. If bPDF is true, then the only other parameter that is relevant is cURL. Not available in the Acrobat Reader. The optional bCanonical parameter is a boolean that indicates, if true, to convert any dates being submitted to standard format (i.e. D:YYYYMMDDHHmmSSOHH’mm’ see the PDF Reference for more details). The default is false. The optional bExclNonUserAnnots parameter is a boolean that indicates, if true, to exclude any annotations that are not owned by the current user. The default is false. The optional bExclFKey parameter is a boolean that indicates, if true, to exclude the "F" key. The default is false. If the FDF needs to be encrypted before getting submitted, then a password, cPassword, needs to be provided that will be used to generate the encryption key. Alternatively, a boolean can be passed instead: if cPassword is true (no quotes), then a dialog will be presented to the user requesting the password. This dialog will be skipped, however, if the user has previously (within this Acrobat session) entered a password as he submitted or received an encrypted FDF (in which case that password will be used instead). Regardless of whether an actual password is passed in, or one is requested from the user via dialog, this new password is remembered (within this Acrobat session) for future outgoing or incoming encrypted FDFs. This parameter is only valid if bFDF is true. You can include non-terminal fields in the array or the string passed as a parameter: this is a simple shortcut for having a whole subtree submitted. Example: /* Submit the form to the server */ this.submitForm("http://myserver/cgi-bin/myscript.cgi#FDF"); /* Or */ this.submitForm("http://myserver/cgi-bin/myscript.cgi#FDF", true, false, "name"); The example above illustrates a shortcut to submitting a whole subtree. Passing "name" as part of the field parameter, submits "name.title", "name.first", "name.middle" and "name.last". Example: this.submitForm({ cURL: "http://myserver/cgi-bin/myscript.cgi#FDF", bXML: true }); Note: You need to be running inside a web browser or have the Acrobat Web Capture plug-in installed, in order to call the submitForm method (unless the URL uses the "mailto" scheme, in which case it will be honored even if not running inside a web browser, as long as the SendMail plug-in is present). Acrobat JavaScript Object Specification 142
Slide 145: Usage of the https protocol is supported for secure connections. syncAnnotScan 5.0 Parameters: None Returns: Nothing In order to show or process annotations for the entire document all annotations must have been detected. Normally, a background task runs that examines every page and looks for annotations during idle time as this scan is a time consuming task. Calling this method simply guarantees that all annots will be scanned by the time this method returns. Example: this.syncAnnotScan(); annots = this.getAnnots({nSortBy:ANSB_Author}); // now, do something with the annotations. The second line of code will not be executed until syncAnnotScan returns and this will not occur until the annot scan of the document is completed. Note: Much of the code in annots works gracefully even when the full list of annots is not yet acquired by background scanning. In general, you should probably do syncAnnotScan if want the entire list of annots. See also getAnnots. Acrobat JavaScript Object Specification 143
Slide 146: Event Object All JavaScripts are executed as the result of a particular event. Each event has a type and a name.The events detailed here are listed as type/name name pairs. For each of these events, Acrobat JavaScript creates an event object. During the occurrence of each event, this event object can be accessed, information about the current state of the event can be obtained and possibly manipulated. It is important for JavaScript writers to know when these events occur and in what order they are processed. Some methods or properties can only be accessed during certain events; therefore, a knowledge of these events will prove useful. Event Type/Name Combinations App/Init When the Viewer is started, the Application Initialization Event occurs. Script files, called Folder Level JavaScripts, are read in from the application and user JavaScript folders. They load in the following order: Config.js, glob.js, all other files, then any user files. This event defines the name and type properties for the event object. This event does not listen to the rc return code. Batch/Exec 5.0 A batch event occurs during the processing of each document of a batch sequence. JavaScripts that authored as part of a batch sequence can access the event object upon execution. This event defines the name, target, and type properties for the event object. The target in this event is the document object. This event listens to the rc return code. If the return code is set to false, the batch sequence is stopped. Bookmark/Mouse Up 5.0 This event occurs whenever a user clicks on a bookmark that executes a JavaScript. Acrobat JavaScript Object Specification 144
Slide 147: This event defines the name, target, and type properties for the event object. The target in this event is the bookmark object that was clicked. This event does not listen to the rc return code. Console/Exec 5.0 A console event occurs whenever a user evaluates a JavaScript in the console. This event defines the name, and type properties for the event object. This event does not listen to the rc return code. Doc/DidPrint 5.0 This event is triggered after a document has printed. This event defines the name, target, and type properties for the event object. The target in this event is the document object. This event does not listen to the rc return code. Doc/DidSave 5.0 This event is triggered after a document has been saved. This event defines the name, target, and type properties for the event object. The target in this event is the document object. This event does not listen to the rc return code. Doc/Open This event is triggered whenever a document is opened. When a document is opened document level script functions are scanned and any exposed scripts are executed. This event defines the name, target, targetName, and type properties for the event object. The target in this event is the document object. Acrobat JavaScript Object Specification 145
Slide 148: This event does not listen to the rc return code. Doc/WillClose 5.0 This event is triggered before a document is closed. This event defines the name, target, and type properties for the event object. The target in this event is the document object. This event does not listen to the rc return code. Doc/WillPrint 5.0 This event is triggered before a document is printed. This event defines the name, target, and type properties for the event object. The target in this event is the document object. This event does not listen to the rc return code. Doc/WillSave 5.0 This event is triggered before a document is saved. This event defines the name, target, and type properties for the event object. The target in this event is the document object. This event does not listen to the rc return code. External/Exec 5.0 This event is the result of an external access, e.g. through OLE, AppleScript, or loading an FDF. This event defines the name and type properties for the event object. This event does not listen to the rc return code. Acrobat JavaScript Object Specification 146
Slide 149: Field/Blur 4.05 The blur event occurs after all other events just as the field loses focus. This event is generated regardless of whether or not a mouse click is used to deactivate the field (e.g. tab key). This event defines the modifier, name, shift, target, targetName, type, and value properties for the event object. The target in this event is the field whose validation script is being executed. This event does not listen to the rc return code. Field/Calculate This event is defined when a change in a form requires that all fields that have a calculation script attached to them be executed. All fields that depend on the value of the changed field will now be re-calculated. These fields may in turn generate additional Field/Validate, Field/ Blur, and Field/Focus events. Calculated fields may have dependencies on other calculated fields whose values must be determined beforehand. The calculation order array contains an ordered list of all the fields in a document that have a calculation script attached. When a full calculation is needed, each of the fields in the array is calculated in turn starting with the zeroth index of the array and continuing in sequence to the end of the array. To change the calculation order of fields, use the Tools->Forms->Set Field Calculation Order... menu item in Adobe Acrobat. This event defines the name, source, target, targetName, type, and value properties for the event object. The target in this event is the field whose calculation script is being executed. This event does listen to the rc return code. If the return code is set to false, the field’s value is not changed. If true, the field takes on the value found in the value property. Field/Focus 4.05 The focus event occurs after the mouse down but before the mouse up after the field gains the focus. This routine is called whether or not a mouse click is used to activate the field (e.g. tab key) and is the best place to perform processing that must be done before the user can interact with the field. This event defines the modifier, name, shift, target, targetName, type, and value properties for the event object. The target in this event is the field whose validation script is being executed. This event does not listen to the rc return code. Acrobat JavaScript Object Specification 147
Slide 150: Field/Format Once all dependent calculations have been performed the format event is triggered. This event allows the attached JavaScript to change the way that the data value appears to a user (also known as its presentation or appearance). For example, if a data value is a number and the context in which it should be displayed is currency, the formatting script can add a dollar sign ($) to the front of the value and limit it to two decimal places past the decimal point. This event defines the commitKey, name, target, targetName, type, value, and willCommit properties for the event object. The target in this event is the field whose format script is being executed. This event does not listen to the rc return code. However, the resulting value property is used as the fields formatted appearance. Field/Keystroke The keystroke event occurs whenever a user types a keystroke into a text box or combobox (this includes cut and paste operations), or selects an item in a combobox drop down or listbox field. A keystroke script may want to limit the type of keys allowed. For example, a numeric field might only allow numeric characters. The user interface for Acrobat allows the author to specify a Selection Change script for listboxes. The script is triggered every time an item is selected. This is implemented as the keystroke event where the keystroke value is equivalent to the user selection. This behavior is also implemented for the combobox—the "keystroke" could be thought to be a paste into the text field of the value selected from the drop down list. There is a final call to the keystroke script before the validate event is triggered. This call sets the willCommit property to true for the event. With keystroke processing, it is sometimes useful to make a final check on the field value before it is committed (pre-commit). This allows the script writer to gracefully handle particularly complex formats that can only be partially checked on a keystroke by keystroke basis. This event defines the commitKey, change, changeEx, keyDown, modifier, name, selEnd, selStart, shift, target, targetName, type, value, and willCommit properties for the event object. The target in this event is the field whose keystroke script is being executed. This event does listen to the rc return code. If set to false, the keystroke is ignored. The resulting change property is used as the keystroke if the script desires to replace the keystroke code. The resultant selEnd and selStart properties can change the current text selection in the field. Acrobat JavaScript Object Specification 148