Macromedia Acrobat - 7.0.5 User Manual
Adobe® Acrobat® 7.0.5
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Acrobat JavaScript Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Acrobat JavaScript Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
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
Creating PDF Documents with Acrobat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Acrobat PDFMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Adobe PDF Printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Save As or Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
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 or Removing Menus and Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Adding Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Adding a New Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
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
Using Online Collaboration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
How FDF Files Are Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Online Collaboration and Acrobat JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
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
The Adobe XML Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
XML Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
XML Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Extensible Metadata Platform (XMP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
SOAP and Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
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
Types of Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
XML Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Acrobat Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
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
Types of Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Document Information Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
Metadata Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
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
The Acrobat Search Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Creating Custom Searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Search Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Searching across Multiple Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Replacing the Acrobat Search Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
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
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.
Preface
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
● Guide to SDK Samples provides an overview of the samples provided with the Acrobat
®
Events, OLE and DDE.
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.
Additional documents that you should have available for reference are listed below.
● 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/.
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
Conventions Used in This Book
The Acrobat documentation uses text styles according to the following conventions:
Font Used for Examples
monospaced Paths and filenames
Code examples set off
from plain text
monospaced bold Code items within plain
C:\templates\mytmpl.fm
These are variable declarations:
AVMenu commandMenu,helpMenu;
The GetExtensionID method ...
text
Parameter names and
literal values in
The enumeration terminates if proc
returns
false.
reference documents
monospaced italic Pseudocode
Placeholders in code
examples
ACCB1 void ACCB2 ExeProc(void)
{ do something }
AFSimple_Calculate(cFunction,
cFields)
blue Live links to Web pages The Adobe Solutions Network URL is:
http://partners.adobe.com/
Live links to sections
See Using the SDK.
within this document
Live links to code items
Test whether an ASAtom exists.
within this document
bold PostScript language and
The setpagedevice operator
PDF operators,
keywords, dictionary
key names
User interface names The File menu
italic Document titles that are
Acrobat and PDF Library API Overview
not live links
New terms User space specifies coordinates for...
PostScript variables filename deletefile
14 Acrobat SDK User’s Guide
Getting Started
1
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
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.
®
(see below) and also allows users to more effectively manage
Acrobat SDK User’s Guide 15
Getting Started
1
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 LiveCycle™ 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
®
Adobe Document Server
.
®
and
Related Adobe Technologies
● Adobe LiveCycle™ 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 LiveCycle™ Document Security
®
provides digital signature and encryption
capabilities in a server environment, enabling your organization to securely automate
essential business processes.
16 Acrobat SDK User’s Guide
What Is the Acrobat SDK?
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 Create plug-ins that are dynamically linked to and extend the
functionality of Acrobat or Adobe Reader.
Getting Started
What Is the Acrobat SDK?
1
Interapplication
Communication
(IAC)
Write a separate application process that uses interapplication
communication (IAC) to control Acrobat functionality.
are supported on Windows, and Apple events/AppleScript on the
Macintosh. IAC is not available on Unix
®
.
DDE and OLE
Acrobat SDK User’s Guide 17
Getting Started
1
What’s New in PDF 1.6?
What’s New in PDF 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
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
® environments. A Unix version of the Acrobat SDK is also available from
“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
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.
“Accessing the JSObject
Acrobat SDK User’s Guide 19
Technologies Supported by the Acrobat SDK
2
Plug-ins
Acrobat JavaScript Contexts
Acrobat JavaScripts can be applied at a variety of levels:
folder level These scripts contain variables and functions that may be generally
useful to the Acrobat application, and are visible from all documents.
document level These scripts are function and variable definitions that are generally
useful to a given document, but are not applicable outside the
document.
field level 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
Forms” on page 79.
batch level These scripts can be applied to a collection of documents, and
operate at the application 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.
“XML
Plug-ins
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 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
Adobe Reader startup.
Plug_ins folder or directory and is initialized during Acrobat or
20 Acrobat SDK User’s Guide
Technologies Supported by the Acrobat SDK
There are three types of plug-ins:
Regular Acrobat plug-ins These plug-ins run on Acrobat Professional and Acrobat
Standard. Plug-ins for Acrobat Professional can use any of
the Acrobat SDK APIs. Plug-ins for Acrobat Standard do not
have access to some APIs. See the Acrobat Plug-in Guide for
more information.
Plug-ins
2
Adobe Reader-enabled plug-ins
Certified plug-ins These plug-ins have undergone extensive testing to ensure
Plug-ins are:
● DLLs on Windows. Note, however, that plug-in names must end in .API, not .DLL.
● Code fragments on Mac OS X.
● Shared libraries on UNIX.
Certified Plug-ins
Certified plug-ins have undergone extensive testing by Adobe to ensure that they do not
compromise the integrity of Acrobat’s security model. There is a checkbox in the Acrobat
and Adobe Reader user interface that can be used to ensure that only certified plug-ins
load. This means that other plug-ins will not load. Certified plug-ins can be provided only
by Adobe.
These plug-ins use a restricted set of APIs. Adobe Readerenabled plug-ins are developed with permission from
Adobe and require special processing to load under Adobe
Reader. See
“Adobe Reader-enabled Plug-ins” on page 21 for
more information.
that they do not compromise the integrity of Acrobat’s
security model. See
“Certified Plug-ins” on page 21.
Adobe Reader-enabled Plug-ins
Adobe Reader only accepts Reader-enabled plug-ins. Adobe Reader-enabled plug-ins can
only access a limited set of APIs. Reader-enabled plug-ins require permission and licensing
from Adobe. For information on enabling plug-ins for Adobe Reader, see the document,
Adobe Reader-enabled Plug-ins.
Plug-ins for Adobe Reader can use additional APIs if the PDF document has additional
usage rights. For more information, see
Acrobat SDK User’s Guide 21
Chapter 10, “Rights-enabled PDF Documents”.
Technologies Supported by the Acrobat SDK
2
Plug-ins
Development Environments
Windows
Windows developers can develop plug-ins using C and C++ with Visual Studio . NET 2003.
There is currently no support for development of plug-ins using managed languages such
as C# or VB.NET.
However, managed languages are fully supported for use with interapplication
communication (IAC) and specifically with the
take full advantage of Acrobat’s functionality via the JavaScript bridge. For more
information, see
Mac OS X
Beginning in Acrobat 7.0, all plug-ins developed on the Mac OS X must use the Mach-O
runtime architecture. A plug-in can be built as either a bundle or a framework. Apple Xcode
1.2 or 1.5 is required because SDK projects depend on certain header files that are included
with the Xcode development environment. However, The Acrobat SDK does not support
development with the Xcode tools.
Plug-ins developed in previous SDK versions must be rebuilt under Mach-O. For more
information on migrating plug-ins from previous versions of Acrobat, see the Acrobat SDK
Plug-in Guide.
“Interapplication Communication (IAC)” on page 25.
JSObject. This enables those languages to
The Acrobat Core API
Plug-ins access and control the resources of the Acrobat application host environment
using the Acrobat Core API. The core API consists of a set of methods that operate on
objects. The objects have types and encapsulate their data. This object orientation is a
conceptual model, implemented using a standard ANSI C programming interface. Methods
are C functions; objects are opaque data types. The Core API is supported on Microsoft 32bit Windows, Apple Macintosh, and UNIX
platforms.
22 Acrobat SDK User’s Guide
Technologies Supported by the Acrobat SDK
The core API methods are organized into the hierarchy shown in Figure 2.1.
FIGURE 2.1 Overview of Core API
Acrobat Viewer (AV) Layer
(menu selections, other user-level actions)
Acrobat Support
Portable Document (PD) Layer
(bookmarks, pages, thumbnails, annotations, ...)
PDFEdit
(page content)
PDSEdit
(structure info)
(AS)
(file access,
platform-
independent
utilities, callbacks,
exceptions, ...)
Cos Layer
(strings, numbers, dictionaries, ...)
Plug-ins
2
Acrobat Viewer Layer
The Acrobat Viewer (AV) layer, also known as AcroView or AV Model, works with the Acrobat
or Adobe Reader application. Its methods allow plug-ins to manipulate components of the
Acrobat or Adobe Reader application itself, such as menus and menu items.
Portable Document Layer
The Portable Document (PD) layer, also known as PDModel, provides access to components
of PDF documents. Its methods allow plug-ins to manipulate document components such
as document pages and annotations. Two method groups are closely related to the
PD
layer, each controlling a different aspect of a PDF document:
● PDFEdit methods deal with the physical representation of a PDF document. More
specifically, PDFEdit methods treat page content as a list of objects whose values and
attributes can be modified by a plug-in. The methods allow your plug-in to read, write,
edit, and create page contents and page resources, which may contain objects such as
fonts and images.
● PDSEdit methods deal with the logical structure-tree information of a PDF document. A
PDF document’s logical structure is built independently of its physical representation,
with pointers between the logical structure and the physical representation. PDSEdit
methods allow your plug-in to add, modify, navigate, search and extract data from PDF
documents. For example, PDSEdit methods can obtain logically-ordered content,
independently of drawing order.
For more information about logical structure and tagged PDF files, see “Creating Tagged
PDF Documents” on page 43.
Acrobat SDK User’s Guide 23
Technologies Supported by the Acrobat SDK
2
Plug-ins
Acrobat Support
The Acrobat Support (AS) layer provides platform-independent utility functions and allows
plug-ins to override the built-in file-handling mechanisms.
Cos Layer
The Cos Object System (Cos) layer provides access to the building blocks used to construct
documents. Cos methods allow plug-ins to manipulate low-level data such as dictionary
and string objects in a PDF file.
Whenever possible, you should use higher level APIs to access and manipulate PDF files.
Though you can use the Cos layer APIs to perform most types of access or manipulation of a
PDF file, it can be very difficult and requires in-depth knowledge of PDF file structure.
Platform-Specific Methods
In addition to the method groups represented in Figure 2.1, the core API includes
platform-specific plug-in utilities to handle issues that are unique to Macintosh, Windows
and UNIX platforms. For more information, see the Acrobat SDK Plug-in Guide.
Extended APIs For Plug-ins
Plug-ins may expose their own functionality and make it available to other plug-ins, in the
same way that Acrobat functionality is available through the core API. For example, Acrobat
contains several plug-ins, such as Search and Digital Signatures, whose APIs are available to
plug-ins. In fact, the Acrobat architecture encourages the use of plug-ins to “expose” APIs
for use by other plug-ins. Acrobat uses many plug-ins to implement features; some of these
plug-ins expose their APIs.
API “exposure” is accomplished through a mechanism called the Host Function Table (HFT).
A plug-in can export an HFT for use by other plug-ins, and it can import the HFTs of other
plug-ins.
To learn how to import and export HFTs, see the Acrobat SDK Plug-in Guide and the Acrobat
and PDF LIbrary API Overview.
Plug-in APIs
The following are the plug-ins that export HFTs. For more information, see the Acrobat and
PDF Library Overview and the Acrobat and PDF Library Reference.
● The Catalog Plug-in creates full-text indices, searchable with the Acrobat Search plug-in.
● The Digital Signature Plug-in handles the generic functions common to all digital
signatures. You can write a plug-in that handles your specific kinds of signatures
(signing methods), such as public-private key (PPK), handwriting, retinal scans, or
fingerprints.
● The Forms Plug-in helps make Acrobat a more powerful and comprehensive tool for
creating and filling out electronic forms. With it, you can convert a PDF file into an
electronic form that looks just like the original paper form.
● The PDF Consultant Plug-in allows you to inspect, analyze, and repair PDF documents.
24 Acrobat SDK User’s Guide
Technologies Supported by the Acrobat SDK
Interapplication Communication (IAC)
● The Search Plug-in allows you to make queries, using the index created by Catalog. Using
events and DDE messages, remote clients can submit queries and manipulate a list of
indexes.
● The Spelling Plug-in allows users to spell-check text in comments and form fields.
● The Weblink Plug-in adds the ability to link to the World Wide Web. The Weblink driver
performs low-level platform-specific functions with a Web browser on behalf of
Weblink.
● The SaveAsXML Plug-in allows you to extend the “Save as type” choices in the SaveAs
dialog box to allow a tagged PDF document to be saved in XML, HTML, or similar textbased formats. See Using the Save as XML Plug-in.
Adobe Dialog Manager
The Adobe Dialog Manager (ADM) is a cross-platform API for implementing dialog
interfaces for Adobe applications. In Acrobat 5.0 and above, ADM allows plug-in developers
to use a single code base to implement dialog behavior on both Macintosh and Windows.
The Adobe Dialog Manager Programmer’s Guide and Reference explains the fundamentals of
ADM and describes its functions in detail, as well as the specific steps Acrobat plug-in
developers must take in order to access ADM functionality.
2
AcroColor API
The Acrocolor API is an HFT that allows you to access the AcroColor engine (ACE), which
controls color profile management. Strictly speaking, it is not an “extended API” since
methods are accessed in a manner similar to the core APIs. However, it constitutes its own
“layer” in a manner similar to ADM, so it is described in these terms.
Interapplication Communication (IAC)
Acrobat provides support for interapplication communication (IAC) through Apple events
and AppleScript on Macintosh platforms, and through OLE automation and DDE on
Windows platforms. Adobe Reader also supports IAC, but does not support OLE on
Windows.
IAC support allows programs to control Acrobat or Adobe Reader in much the same way a
user would. You can also use IAC support to render a PDF file into an external application
window instead of the Acrobat window. The IAC support methods and events serve as
wrappers for some of the core API calls in the SDK.
Development Environments
On Windows, you can develop IAC applications using any of the following languages:
● Visual Basic .NET
● Visual C++ .NET
● Visual C# .NET
Acrobat SDK User’s Guide 25
Technologies Supported by the Acrobat SDK
2
Interapplication Communication (IAC)
On a Macintosh, you develop IAC applications using CodeWarrior 9.2.
Interapplication Communication Objects
You can think of the Acrobat API as having two distinct layers that use IAC objects:
● The Acrobat Viewer (AV) level
● The Portable Document (PD) layer.
An example of an AV layer object is the view of a document. You would expect to see the
view of a document object residing in the layer associated with the Viewer. An example of a
PD layer is a page in the document.
For more information about the Acrobat PDF layers, see “The Acrobat Core API” on page 22.
Using the Acrobat Distiller API
You can use the automation interface of the Acrobat Distiller API to remotely control PDF
creation from an external application. For more information, see
from an Authoring Application” on page 39.
“Creating PDF Documents
IAC and Windows
OLE Support on Windows
Acrobat is an OLE server and also responds to a variety of OLE automation messages. You
can embed PDF documents into documents created by an application that is an OLE client.
Adobe Reader does not support OLE on Windows.
For complete descriptions of the Acrobat parameters associated with OLE automation
methods, see the OLE automation sections of the Acrobat Interapplication Communication
Reference.
PDF Browser Controls
On Windows, you may use the AcroPDF library to display a PDF document in applications
using simplified browser controls. In this case, the PDF is treated as an ActiveX document,
and the interface is available in Adobe Reader.
Once the PDF document is loaded, you can implement browser controls to:
● Determine which page to display as well as the display
● Control view and zoom modes
● Determine whether to display bookmarks, thumbs, scrollbars, and toolbars
● Print pages using various options
● Highlight a text selection.
For more information, see the Acrobat Interapplication Communication Overview.
26 Acrobat SDK User’s Guide
Technologies Supported by the Acrobat SDK
Interapplication Communication (IAC)
Accessing the JSObject Interface
Acrobat 7.0 provides a rich set of JavaScript programming interfaces that are designed to
be used from within the Acrobat environment. It also provides a mechanism (known as the
JSObject) that allows external clients to access the same functionality from
environments such as VB .NET, Visual C++ .NET and Visual C# .NET.
Programming Acrobat JavaScript Using Visual Basic gives you the information you need to
get started using the extended functionality of JavaScript from a Visual Basic programming
environment. It provides a set of examples to illustrate the key concepts.
In precise terms, the JSObject is an interpretation layer between an OLE Automation
client such as a Visual Basic application and the JavaScript functionality provided by
Acrobat. From a programmer's point of view, the end result is that programming
JSObject from a Visual Basic environment is quite similar to programming in JavaScript
using the Acrobat console.
DDE Support
Dynamic Data Exchange (DDE) is a feature of Windows that allows two programs to share
data or send commands directly to each other. The DDE messages that are supported by
Acrobat are listed in the Acrobat Interapplication Communication Overview.
2
IMPORTANT: You should use OLE automation instead of DDE whenever possible, since DDE is
not a COM technology.
Apple Event Support
The Acrobat viewers support Apple Events and a number of Apple Event objects on the
Macintosh platforms. IAC support includes some of the objects and events described in
Apple Event Registry: Standard Suites, as well as Acrobat-specific objects and events. For
more information, see the Acrobat Interapplication Communication Overview.
NOTE: You can find information on Apple Events supported by the Acrobat Search plug-in
by referring to the
additional Apple Events are described in the
When programming for Macintosh platforms, it is advised that you use AppleScript with
Acrobat whenever possible. There are some Apple Events not available through
AppleScript; these can be handled with C or other programming languages. When
programming in C, use the declarations in
of the parameters, see the Acrobat Interapplication Communication Reference.
Acrobat and PDF LIbrary API Reference. Other plug-ins supporting
Acrobat and PDF LIbrary API Overview.
AcroAETypes.h. For a complete description
Using Plug-ins for Interapplication Communication
You can extend the functionality of the IAC interfaces by writing plug-ins that use core API
objects that are not already part of the IAC support system. The Acrobat SDK provides a
sample, DDEServer, which demonstrates this functionality.
See the Acrobat Interapplication Communication Overview for more information.
Acrobat SDK User’s Guide 27
Technologies Supported by the Acrobat SDK
2
The Adobe PDF Library
Technical Limitations of Using the IAC API With Adobe Reader
Adobe Reader does not support OLE automation.
Adobe Reader supports only limited DDE message and Apple events. See the Acrobat
Interapplication Communication Reference for more details.
There are licensing restrictions on functionality that may be added to Adobe Reader by
plug-ins. See
http://partners.adobe.com/asn.
The Adobe PDF Library
The Adobe PDF Library is based on the core technology of the Adobe Acrobat line of
products and offers complete functionality for generating, manipulating, rendering, and
printing Adobe PDF documents.
NOTE: The PDF Library is licensed separately from Acrobat and the Acrobat SDK. For more
information, see
Designed specifically for OEMs, ISVs, system integrators, and enterprise IT developers, the
Adobe PDF Library SDK contains a powerful set of functions for developing third-party
solutions and workflows around the Adobe Portable Document Format (PDF).
http://partners.adobe.com/asn.
The library enables Adobe PDF functionality to be seamlessly embedded within
applications. It also provides reliable, accurate and Adobe-supported implementation of
the latest PDF specification.
The Adobe PDF Library and the Adobe Acrobat SDK
There is a significant overlap between the functionality provided by the PDF Library
Software Development Kit (SDK) and by the Acrobat SDK. They differ in providing access to
the Acrobat user interface:
● The Acrobat SDK is meant for the plug-in environment, and allows you to control and
interact with the Acrobat user interface.
● The PDF Library SDK is intended for interaction between PDF and other applications,
such as high volume batch processing and PDF generation applications. It does not
export methods for creating or managing Acrobat user interface elements—that is, the
AcroView (AV) layer of the core API.
For more information, see the Acrobat and PDF Library API Overview and the Acrobat and
PDF Library API Reference.
28 Acrobat SDK User’s Guide
Deciding Which Acrobat SDK
3
Technology to Use
This chapter describes general issues that factor into decisions about which Acrobat SDK
technology to use. Subsequent chapters provide overview information about different
application-specific tasks that you can do with the Acrobat SDK and discuss the capabilities
and limitations of each technology in performing those tasks.
● Getting Started
● When to Use Interapplication Communication
● Deciding Between Plug-ins and JavaScript
● Samples Provided with the Acrobat SDK
Getting Started
You can develop software that integrates with Acrobat and Adobe Reader in three ways:
● Acrobat JavaScript
● Plug-ins
● Interapplication Communication (IAC)
Based on your application’s requirements, you choose the appropriate technologies for
development. In some situations, the desired functionality is only available using one
particular technology. In other situations, you can choose between two or more
technologies. For example, you can add menu items to Acrobat using either JavaScript or a
plug-in.
You can also use more than one technology in a single application or single document. For
example, you can use both plug-ins and JavaScript to implement a particular functionality.
Also, you can extend the functionality of intercommunication application interfaces by
writing plug-ins that use core API objects not already part of the IAC support system (see
“Using Plug-ins for Interapplication Communication” on page 27).
Acrobat SDK User’s Guide 29
Deciding Which Acrobat SDK Technology to Use
3
When to Use Interapplication Communication
When to Use Interapplication Communication
To take advantage of Acrobat functionality from within an external application, you use
Interapplication Communication (IAC).
Viewing PDF Documents from an External Application
If your Windows application only views a PDF document and does not need to edit it in any
way, it is recommended that you use the PDF Browser Controls to view the document from
your external VB or C# application. When you open a document for viewing using the PDF
Browser Controls, the document is displayed in the application window. Acrobat toolbars
are also displayed and can be used with no additional API calls. The toolbars can optionally
be hidden. See
Communication Overview for more details.
NOTE: Acrobat or Adobe Reader must be installed on the end-user’s computer for the PDF
Browser Controls to function correctly.
You can also use the IAC API to open and view a PDF document. However, when you use
the IAC API, no toolbars are displayed; you must place your own buttons with
corresponding API calls for standard toolbar tasks such as printing and searching.
“PDF Browser Controls” on page 26 or the Acrobat Interapplication
The following table summarizes some of the issues to consider when deciding whether to
use the PDF Browser Controls or IAC APIs.
TABLE 3.1 Comparing the PDF Browser Controls and IAC APIs
PDF Browser
Controls
IAC API
● Acrobat toolbars can be displayed with no additional API calls.
● Supports only viewing, not editing, of PDF documents.
● Supports editing PDF documents and manipulating Acrobat or
Adobe Reader through a richer set of APIs than the PDF Browser
Controls. Note that the set of APIs for Adobe Reader is limited unless
the PDF document has rights enabled (see
enabled PDF Documents”).
● Acrobat toolbars cannot be displayed.
Controlling Acrobat From an External Application
If you need to do more than just view a PDF document from your application, you can use
either the IAC API or, if your application is written in VB, you can access Acrobat JavaScript
using the
JSObject.
Chapter 10, “Rights-
30 Acrobat SDK User’s Guide
Loading...