User manual ADOBE ACROBAT 7.0.5 SDK

® Acrobat® 7.0.5 Adobe Acrobat SDK User's Guide July 27, 2005 Adobe Solutions Network -- http://partners.adobe.com © 2005 Adobe Systems Incorporated. All rights reserved. Acrobat® SDK User's Guide If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide 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 the informational content contained in this guide. Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner. Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization. Adobe, the Adobe logo, Acrobat, Acrobat Capture, the Adobe PDF logo, Distiller, PostScript, the PostScript logo and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Apple, Mac OS, Macintosh, and Power Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries. PowerPC is a trademark of International Business Machines Corporation in the United States and/or other countries. ActiveX, Microsoft, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. UNIX is a trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. All other trademarks are the property of their respective owners. This software is based in part on the work of the Independent JPEG Group. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Notice to U.S. Government End Users. The Software and Documentation are "Commercial Items," as that term is defined at 48 C.F.R. §2.101, consisting of "Commercial Computer Software" and "Commercial Computer Software Documentation," as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference. Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Resources and Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 How This Document Is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Conventions Used in This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Chapter 1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 What Is Acrobat? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 What Is the Acrobat SDK?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 What's New in PDF 1.6? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Chapter 2 Technologies Supported by the Acrobat SDK . . . . . . . . . . . 19 Acrobat JavaScript Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Acrobat JavaScript Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Acrobat JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Certified Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Adobe Reader-enabled Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Development Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 The Acrobat Core API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Extended APIs For Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Interapplication Communication (IAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Development Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Interapplication Communication Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Using the Acrobat Distiller API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 IAC and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Apple Event Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Using Plug-ins for Interapplication Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Technical Limitations of Using the IAC API With Adobe Reader . . . . . . . . . . . . . . . . . . . . 28 The Adobe PDF Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 The Adobe PDF Library and the Adobe Acrobat SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Acrobat SDK User's Guide 3 Contents Chapter 3 Deciding Which Acrobat SDK Technology to Use . . . . . . . . . 29 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 When to Use Interapplication Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Viewing PDF Documents from an External Application . . . . . . . . . . . . . . . . . . . . . . . . . 30 Controlling Acrobat From an External Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Deciding Between Plug-ins and JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 General Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 What You Can Do with Plug-ins That You Can't Do with JavaScript . . . . . . . . . . . . . . . . . . 33 What You Can Do with JavaScript That You Can't Do with a Plug-in . . . . . . . . . . . . . . . . . 33 Samples Provided with the Acrobat SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Plug-in Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Acrobat JavaScript Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Interapplication Communication Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Chapter 4 Creating PDF Documents . . . . . . . . . . . . . . . . . . . . . . . 37 Acrobat PDFMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Adobe PDF Printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Save As or Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Creating PDF Documents with Acrobat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Creating PDF Documents from an Authoring Application . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Acrobat Distiller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Apple Event Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Distiller Automation on Windows Using OLE Automation . . . . . . . . . . . . . . . . . . . . . . . 40 Automated, Silent Creation of PDF Documents from Windows . . . . . . . . . . . . . . . . . . . . 41 Choosing an Adobe PDF Settings File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Automatically Generating Advanced Acrobat Features . . . . . . . . . . . . . . . . . . . . . . . . . 41 Inserting PostScript Code into a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Attaching the Native Document to the PDF File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Batch Processing with Distiller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Creating Tagged PDF Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 PDF Logical Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 The Structure Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Adding Structure Data to a PDF Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Using pdfmark to Add Structure Data to PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Creating PDF Documents Using Plug-ins or Acrobat JavaScript . . . . . . . . . . . . . . . . . . . . . . 45 Creating an Empty PDF File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Creating PDF Files from Multiple Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Creating PDF Files Without Using Acrobat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 4 Acrobat SDK User's Guide Contents Generating PDF Files Without Using Adobe Applications. . . . . . . . . . . . . . . . . . . . . . . . 46 Chapter 5 Working with PDF Documents . . . . . . . . . . . . . . . . . . . . 47 Automating Processes: Opening PDF Documents Silently . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Adding Navigation to PDF Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Adding and Managing Bookmarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Adding and Managing Thumbnails. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Adding and Managing Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Using Actions for Special Effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Manipulating Pages of a PDF File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Creating and Editing Page Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 PDFEdit API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 PDFEdit Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Using Document Logical Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Adding Structure Data to a PDF Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Using pdfmark to Add Structure Data to PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Modifying PDF Documents in Other Ways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Adding Watermarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Fixed Printing for Engineering Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Spell-Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Using Multimedia. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Interacting with OBDC Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Printing PDF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Customizing and Automating Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Working with Embedded Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Large Page Sizes in PDF Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Wireframe Drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Chapter 6 Modifying the User Interface . . . . . . . . . . . . . . . . . . . . 59 Adding Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Adding a New Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Adding or Removing Menus and Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Modifying the Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Adding Items to an Existing Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Creating a New Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Using the Adobe Dialog Manager (ADM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 ADM Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Acrobat SDK User's Guide 5 Contents ADM Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Using ADM from Acrobat JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Using the ADM API from a Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Customizing Acrobat Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Controlling the "About" Box and Splash Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Placing Plug-in Help Files in a Standard Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Customizing the How-To Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Chapter 7 Using Online Collaboration and Annotations . . . . . . . . . . . 67 How FDF Files Are Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Online Collaboration and Acrobat JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Using Online Collaboration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Using Annotations in Document Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Annotations and JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Annotations and Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Annotations and the IAC API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Creating New Annotation Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Using Stamps in Approval Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Chapter 8 XML and the Acrobat SDK . . . . . . . . . . . . . . . . . . . . . . 73 XML Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 XML Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Extensible Metadata Platform (XMP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 SOAP and Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 The Adobe XML Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Converting PDF Documents to XML Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Converting to XML Format Using Acrobat JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . 76 The SaveAsXML Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Managing XML-based Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Chapter 9 Forms and the Acrobat SDK . . . . . . . . . . . . . . . . . . . . . 79 XML Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Acrobat Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Types of Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Forms Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Elements of Acrobat Forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 6 Acrobat SDK User's Guide Contents Guidelines for Creating a New Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Acrobat Forms and the Acrobat SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Acrobat JavaScript for Acrobat Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 The Forms API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 OLE Automation for Acrobat Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 XML Forms and the Acrobat SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Automatically Populating Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Creating Web-Ready Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Punchcard/Barcode Form Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Collecting Data from Completed Forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 XML and XDP Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 FDF and XFDF Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Saving Data to a Microsoft Excel Spreadsheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Submitting Data from Attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Exporting Data as Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 XML Form Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Chapter 10 Rights-enabled PDF Documents . . . . . . . . . . . . . . . . . . . 87 Additional Usage Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Differences between Usage Rights and Reader Enabling . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Creating Rights-enabled Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Accessing Additional Usage Rights. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Applying and Validating Additional Usage Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Effects of Reader Extensions on Acrobat Standard and Acrobat Professional . . . . . . . . . . . . . . 90 Enabling Collaboration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Chapter 11 Providing Document Security . . . . . . . . . . . . . . . . . . . . 91 Acrobat Security Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Encryption and Decryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Digital IDs and Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Obtaining a Digital ID from a Third Party . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Digital IDs and the Acrobat SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Security Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 PPKLite and PPKMS Security Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Security Handlers and Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Security Handlers and Acrobat JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Digitally Signing Adobe PDF Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Acrobat SDK User's Guide 7 Contents Signing Adobe PDF Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Certifying PDF Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Validating Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Security Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Using Adobe Policy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Encrypting PDF Documents Using Security Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Using eEnvelopes to Send Secure Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Document Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Chapter 12 Working with Metadata . . . . . . . . . . . . . . . . . . . . . . . 101 Document Information Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 Metadata Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 Types of Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101 Extensible Metadata Platform (XMP). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 Accessing XMP Metadata Using Acrobat JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . .103 Accessing XMP Metadata From a Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 Acrobat Distiller and XMP Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 The Adobe XMP Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 Searching Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104 Object Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104 Creating Object Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105 Searching and Accessing Object Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105 Chapter 13 Searching and Indexing . . . . . . . . . . . . . . . . . . . . . . . 107 Creating Custom Searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107 Search Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108 Searching across Multiple Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108 Replacing the Acrobat Search Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108 The Acrobat Search Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107 Indexing PDF Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109 Extracting and Highlighting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109 Indexing and Acrobat JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109 The Acrobat Catalog Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109 Chapter 14 Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Accessibility Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111 Optimizing the Accessibility of PDF Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112 8 Acrobat SDK User's Guide Contents Making Forms Accessible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112 Setting Tab Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113 Annotations and Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113 Tagged Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113 Text-To-Speech . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113 Accessibility and Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113 Microsoft's Active Accessibility (MSAA) Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114 Chapter 15 Working With PDF Layers . . . . . . . . . . . . . . . . . . . . . . 115 About Adobe PDF layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115 Creating Layered PDF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116 Navigating with Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116 Working with Layers from Acrobat JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116 Working with Layers from a Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Acrobat SDK User's Guide 9 Contents 10 Acrobat SDK User's Guide Preface Description This guide provides an introduction to the Adobe® Acrobat® Software Development Kit (SDK). It provides a general overview of the types of things you can do with the SDK and the technologies that are available to you through the SDK. Audience This guide is meant for both experienced Acrobat SDK developers and those who are new to the Acrobat SDK. For those new to the Acrobat SDK, this guide provides information about Acrobat SDK technologies and the many different ways that developers can extend Acrobat using the SDK. For developers who have used earlier versions of the SDK, this guide provides information on new and changed features in this version of the Acrobat SDK. Resources and Samples The following resources and samples provide further information about the Acrobat SDK: Acrobat and PDF Library API Overview provides a high-level overview of the Acrobat and PDF Library APIs. Acrobat and PDF Library API Reference contains the method prototypes and details on arguments. By using this reference online, you can copy prototypes directly into your plug-in as you are coding it. Acrobat JavaScript Scripting Guide provides an overview of how to use Acrobat JavaScript to develop and enhance standard workflows. Acrobat JavaScript Scripting Reference describes in detail all objects, properties and methods within the Acrobat extension to JavaScript, and gives code examples. Acrobat Plug-in Guide explains how to use the Acrobat core and extended APIs to write plug-ins for Acrobat and Adobe Reader. It describes basic Acrobat development concepts and provides information on upgrading plug-ins from Acrobat 6 to Acrobat 7. Acrobat Interapplication Communication Overview explains the interapplication communication (IAC) support concepts, such as objects and commands universally understood by applications. Acrobat SDK User's Guide 11 Preface How This Document Is Organized Acrobat Interapplication Communication Reference provides a detailed reference of all the calls needed for Apple® Events, OLE and DDE. Guide to SDK Samples provides an overview of the samples provided with the Acrobat SDK. SnippetRunner Cookbook provides an overview of the plug-in snippets provided with the Acrobat SDK. PDF Reference, fifth edition, Version 1.6 provides a description of the PDF file format, as well as suggestions for producing efficient PDF files. It is intended for application developers who wish to produce PDF files directly, or who wish to gain a detailed understanding of the PDF file format. Adobe Dialog Manager Programmer's Guide and Reference describes how to create platform-independent dialog boxes for your plug-in. Developing for Adobe Reader provides an introduction to those portions of the Adobe Acrobat Software Development Kit (SDK) that pertain to your development efforts for Adobe Reader. Adobe Reader-enabled Plug-ins describes the steps required to enable a plug-in to be loaded by Adobe Reader. PostScript Language Reference, third edition describes the syntax and semantics of the PostScript language and the Adobe imaging model. The samples and snippets included in the Acrobat SDK. For more information, visit the Adobe Solutions Network at http://partners.adobe.com/asn/. Additional documents that you should have available for reference are listed below. How This Document Is Organized This document is organized as follows: Chapter 1, "Getting Started," introduces the Acrobat SDK and summarizes new features in the Acrobat SDK and in PDF 1.6. Chapter 2, "Technologies Supported by the Acrobat SDK," describes the technologies that make up the Acrobat SDK. Chapter 3, "Deciding Which Acrobat SDK Technology to Use," describes general issues that factor into decisions about which Acrobat SDK technology to use. Chapter 4, "Creating PDF Documents," provides information about how to use the Acrobat SDK to create PDF documents. Chapter 5, "Working with PDF Documents," describes how to use the Acrobat SDK to add navigation, how to modify and manipulate PDF documents, and how to print PDF documents. Chapter 6, "Modifying the User Interface," describes how to change the Acrobat or Adobe Reader user interface using the Acrobat SDK. 12 Acrobat SDK User's Guide Preface How This Document Is Organized Chapter 7, "Using Online Collaboration and Annotations," describes online collaboration workflows, annotations, and stamps. Chapter 8, "XML and the Acrobat SDK," describes the Adobe XML architecture and the role that Acrobat and the Acrobat SDK play in XML-based workflows. Chapter 9, "Forms and the Acrobat SDK," describes how to extend the functionality of forms using both Acrobat and XML Forms. Chapter 10, "Rights-enabled PDF Documents," describes how to work with PDF documents with additional usage rights in Acrobat and Adobe Reader. Chapter 11, "Providing Document Security," describes how to use the Acrobat SDK to provide security to PDF documents. Chapter 12, "Working with Metadata," describes how to access and manipulate document metadata and object data using the Acrobat SDK. Chapter 13, "Searching and Indexing," describes how to customize Acrobat's searching and indexing capabilities using the Acrobat SDK. Chapter 14, "Accessibility," describes Acrobat and Acrobat SDK support for accessibility of documents to visually-impaired users. Chapter 15, "Working With PDF Layers," describes Acrobat features to support layers in PDF documents. Acrobat SDK User's Guide 13 Preface Conventions Used in This Book Co nve nt i on s Use d i n Th i s B o o k The Acrobat documentation uses text styles according to the following conventions: Font monospaced Used for Paths and filenames Code examples set off from plain text monospaced bold Code items within plain text Parameter names and literal values in reference documents monospaced italic Pseudocode Placeholders in code examples blue Live links to Web pages Live links to sections within this document Live links to code items within this document bold PostScript language and PDF operators, keywords, dictionary key names User interface names italic Document titles that are not live links New terms PostScript variables Examples C:\templates\mytmpl.fm These are variable declarations: AVMenu commandMenu,helpMenu; The GetExtensionID method ... The enumeration terminates if proc returns false. ACCB1 void ACCB2 ExeProc(void) { do something } AFSimple_Calculate(cFunction, cFields) The Adobe Solutions Network URL is: http://partners.adobe.com/ See Using the SDK. Test whether an ASAtom exists. The setpagedevice operator The File menu Acrobat and PDF Library API Overview User space specifies coordinates for... filename deletefile 14 Acrobat SDK User's Guide 1 Getting Started This chapter introduces you to Acrobat and the Acrobat SDK, and summarizes the changes to the SDK in the current release. The chapter consists of the following sections: What Is Acrobat? What Is the Acrobat SDK? What's New in PDF 1.6? What Is Acrobat? Adobe® Acrobat® 7.0 consists of a family of products for creating, modifying, indexing, searching, displaying, and manipulating PDF (Portable Document Format) files. For further information about the Acrobat family of products, see http://partners.adobe.com/links/acrobat. What is the Acrobat Family? Adobe Reader for viewing, navigating, and printing PDF documents. Adobe Reader is free software that lets anyone view and print Adobe PDF files on all major computer platforms, as well as fill in and submit Adobe PDF forms. Adobe has distributed more than 500 million copies of the software worldwide. Acrobat for adding navigational links, annotations, and security options, in addition to the functionality provided by Adobe Reader. Acrobat 7.0 is offered in two configurations: ­ Acrobat 7.0 Standard -- Offers all of the Adobe PDF creation and distribution tools in Acrobat Elements® (see below) and also allows users to more effectively manage document review cycles. Acrobat Standard's intuitive review and commenting tools help streamline collaboration and reduce the costs and inefficiencies of paper-based review processes. ­ Acrobat 7.0 Professional -- Contains all of the functionality of Acrobat 7.0 Standard and Acrobat Elements (see below). In addition, it offers the most advanced control over document creation, exchange, review, and output. It is intended for users who need to perform sophisticated tasks, such as preflighting print files, distributing layered CAD drawings, and creating interactive forms. Acrobat SDK User's Guide 15 1 Getting Started What Is Acrobat? Acrobat Elements for organizations requiring widespread PDF creation capability without the need to install the full Acrobat/Distiller product on every desktop. Acrobat Elements allows organizations to extend their investments in Microsoft® Office® by standardizing on Adobe PDF for document distribution. Acrobat Elements is available through licensing with minimum orders of 1,000 seats. There is no public API for Acrobat Elements. What Are the Tools For Creating PDF Files? The Adobe Acrobat family. Adobe Acrobat 7.0 Standard and Professional both include Acrobat Distiller® for creating PDF files from PostScript files created with your favorite applications (including desktop publishing software). Acrobat Capture® with OCR (Optical Character Recognition) for creating text-searchable PDF documents from scanned paper originals. The Adobe LiveCycleTM products, which provide core document services designed to align with your organization's services-oriented architecture and leverage open standards including J2EE and XML. They provide key functions such as document generation, document control and security, document collaboration, and process management for electronic forms. These products include Adobe LiveCycle Forms® and Adobe Document Server®. Adobe LiveCycleTM Reader Extensions® provides advanced services and functionality for documents and forms accessed by Adobe Reader clients, extending users' capabilities for participating in form applications or workflows without requiring the full Adobe Acrobat product. Adobe Policy Server® enables document authors and IT administrators to create usage policies that dynamically control who can view a PDF document, determine whether the recipient can modify, copy, print, or forward the document, and establish document expiration dates. Adobe LiveCycleTM Document Security® provides digital signature and encryption capabilities in a server environment, enabling your organization to securely automate essential business processes. Related Adobe Technologies 16 Acrobat SDK User's Guide Getting Started What Is the Acrobat SDK? 1 Wh at I s t h e Ac rob at S D K ? The Acrobat SDK is a set of tools that help you develop software that interacts with Acrobat technology. The SDK contains header files, type libraries, simple utilities, sample code, and documentation. Using the Acrobat SDK, you can develop software that integrates with Acrobat and Adobe Reader in the following ways: Acrobat JavaScript Write Acrobat JavaScript scripts, either in an individual PDF document or externally, to extend the functionality of Acrobat or Adobe Reader. Plug-ins Interapplication Communication (IAC) Create plug-ins that are dynamically linked to and extend the functionality of Acrobat or Adobe Reader. Write a separate application process that uses interapplication communication (IAC) to control Acrobat functionality. DDE and OLE are supported on Windows, and Apple events/AppleScript on the Macintosh. IAC is not available on Unix®. Acrobat SDK User's Guide 17 1 Getting Started What's New in PDF 1.6? Wh at 's N ew i n P D F 1 . 6 ? The following features are new in the PDF 1.6 specification. For complete details, see the PDF 1.6 Reference. An enhancement to the syntax of DeviceN color spaces to support NChannel color spaces, which give applications greater flexibility when representing colors that are not available on a target device. Encryption enhancements to support using the AES encryption algorithm and to selectively encrypt embedded files. Enhancements to digital signatures related to usage rights and MDP (modification detection and prevention). Additional support for embedded file attachments, including cross-document linking to and from embedded files. The ability to define user properties that contain non-drawing-related information about objects on a page. The ability to accurately specify relationships between the dimensions of objects on a page and their real-world counterparts. An increase to the maximum page size of a PDF document, by specifying the size of the unit in default user space. The ability to specify objects that should be printed at a specific size, regardless of the dimensions of the printed page. New facilities for embedding OpenType fonts in PDF files. Enhancements to markup annotations, including the ability to group them. The ability to specify non-rectangular regions for link annotations. Greater flexibility in specifying the visibility of graphics based on the state of optional content groups, and the ability to lock the states of groups. The addition of Tagged PDF attributes relating to the layout of content in columns. The ability to incorporate models of three-dimensional graphical data, using the 3DIF format, in a PDF file. 18 Acrobat SDK User's Guide 2 Technologies Supported by the Acrobat SDK As mentioned in "What Is the Acrobat SDK?" on page 17, you can develop software that integrates with Acrobat and Adobe Reader in three ways: Acrobat JavaScript Plug-ins Interapplication Communication (IAC) The Acrobat SDK provides support for development on both Windows® and Apple Macintosh® environments. A Unix version of the Acrobat SDK is also available from http://partners.adobe.com/asn. It has release notes containing UNIX-specific information. Besides the technologies provided by the Acrobat SDK, you can also use the Adobe PDF Library (PDFL) to develop applications that create and manipulate PDF documents but do not interact with Acrobat. The Adobe PDF Library is licensed separately from the Acrobat SDK. An overview of the PDF Library is provided in "The Adobe PDF Library" on page 28. Acrobat JavaScript Acrobat JavaScript is a cross-platform scripting language. Through its JavaScript extensions, Acrobat exposes much of the functionality of Acrobat and its plug-ins to the document author. Acrobat JavaScript objects, properties and methods can also be accessed through Visual Basic or C# to automate the processing of PDF documents. See "Accessing the JSObject Interface" on page 27. For complete information on Acrobat JavaScript objects, see the Acrobat JavaScript Scripting Guide and the Acrobat JavaScript Scripting Reference. Acrobat JavaScript Objects Acrobat JavaScript defines several objects that allow your code to interact with the Acrobat application, a PDF document, or fields within a PDF document. The most commonly used objects control the Acrobat or Adobe Reader application, the Acrobat JavaScript console, the PDF document, the Adobe Dialog Manager, SOAP web services, databases, security, searches, and JavaScript events. For a complete list of Acrobat JavaScript objects, see the Acrobat JavaScript Scripting Reference. Acrobat SDK User's Guide 19 2 Technologies Supported by the Acrobat SDK Plug-ins Acrobat JavaScript Contexts Acrobat JavaScripts can be applied at a variety of levels: folder level document level These scripts contain variables and functions that may be generally useful to the Acrobat application, and are visible from all documents. These scripts are function and variable definitions that are generally useful to a given document, but are not applicable outside the document. These scripts can be associated with any component within a document. In the case of dynamic XML forms, such scripts are only visible to that component and execute as actions or events. See "XML Forms" on page 79. These scripts can be applied to a collection of documents, and operate at the application level. field level batch level Each of these levels represents a context in which processing occurs, which affects when the scripts are loaded and how they are accessed inside and outside documents. The placement of a JavaScript at a given level also determines its reusability. Folder level scripts are available within all documents, document level scripts are available to all fields within a given document, and field level scripts are visible only to the fields with which they are associated. For more information, see the Acrobat JavaScript Scripting Guide. Plug-ins Plug-ins are dynamically-linked extensions to Acrobat or Adobe Reader. They can hook into the user interface in a number of ways and can register to be called when a variety of events occur in the application. A plug-in is a program written in ANSI C/C++ that uses the Acrobat public APIs. It adds functionality to Acrobat Professional, Acrobat Standard, or Adobe Reader. A plug-in program file goes into a Plug_ins folder or directory and is initialized during Acrobat or Adobe Reader startup. 20 Acrobat SDK User's Guide