® 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 Documen ...