Adobe Acrobat SDK User’s Guide 7.0.5 User's

User Manual: adobe Acrobat - 7.0.5 - SDK User's Guide Free User Guide for Adobe Acrobat Reader Software, Manual

Open the PDF directly: View PDF PDF.
Page Count: 122

DownloadAdobe Acrobat SDK User’s Guide - 7.0.5 User's
Open PDF In BrowserView PDF
®
®
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

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 SDK User’s Guide

●

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.

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.

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:

12

●

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.

Acrobat SDK User’s Guide

Preface
How This Document Is Organized

Acrobat SDK User’s Guide

●

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.

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

Used for

Examples

monospaced

Paths and filenames

C:\templates\mytmpl.fm

Code examples set off
from plain text

These are variable declarations:

Code items within plain
text

The GetExtensionID method ...

Parameter names and
literal values in
reference documents

The enumeration terminates if proc
returns false.

Pseudocode

ACCB1 void ACCB2 ExeProc(void)
{ do something }

Placeholders in code
examples

AFSimple_Calculate(cFunction,
cFields)

Live links to Web pages

The Adobe Solutions Network URL is:
http://partners.adobe.com/

Live links to sections
within this document

See Using the SDK.

Live links to code items
within this document

Test whether an ASAtom exists.

PostScript language and
PDF operators,
keywords, dictionary
key names

The setpagedevice operator

User interface names

The File menu

Document titles that are
not live links

Acrobat and PDF Library API Overview

New terms

User space specifies coordinates for...

PostScript variables

filename deletefile

monospaced bold

monospaced italic

blue

bold

italic

14

AVMenu commandMenu,helpMenu;

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?

Acrobat SDK User’s Guide

●

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.

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 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® and
Adobe Document Server®.

Related Adobe Technologies
●

●

●

16

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.

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.

Acrobat SDK User’s Guide

Plug-ins

Create plug-ins that are dynamically linked to and extend the
functionality of Acrobat or Adobe Reader.

Interapplication
Communication
(IAC)

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

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.

18

●

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.

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

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 “XML
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.
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

Technologies Supported by the Acrobat SDK
Plug-ins

2

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.

Adobe Reader-enabled
plug-ins

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.

Certified plug-ins

These plug-ins have undergone extensive testing to ensure
that they do not compromise the integrity of Acrobat’s
security model. See “Certified Plug-ins” on page 21.

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.

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 Chapter 10, “Rights-enabled PDF Documents”.

Acrobat SDK User’s Guide

21

2

Technologies Supported by the Acrobat SDK
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 JSObject. This enables those languages to
take full advantage of Acrobat’s functionality via the JavaScript bridge. For more
information, see “Interapplication Communication (IAC)” on page 25.
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.

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
Plug-ins

2

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)

Portable Document (PD) Layer
(bookmarks, pages, thumbnails, annotations, ...)

PDFEdit

PDSEdit

(page content)

(structure info)

Acrobat Support
(AS)
(file access,
platformindependent
utilities, callbacks,
exceptions, ...)

Cos Layer
(strings, numbers, dictionaries, ...)

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:

Acrobat SDK User’s Guide

●

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.

23

2

Technologies Supported by the Acrobat SDK
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.

24

●

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.

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.

2

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.
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:

Acrobat SDK User’s Guide

●

Visual Basic .NET

●

Visual C++ .NET

●

Visual C# .NET

25

2

Technologies Supported by the Acrobat SDK
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 “Creating PDF Documents
from an Authoring Application” on page 39.

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)

2

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.
I MP O R TA N T:

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 Acrobat and PDF LIbrary API Reference. Other plug-ins supporting
additional Apple Events are described in the Acrobat and PDF LIbrary API Overview.

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 AcroAETypes.h. For a complete description
of the parameters, see the Acrobat Interapplication Communication Reference.

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

2

Technologies Supported by the Acrobat SDK
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 http://partners.adobe.com/asn.

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).
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

3

Deciding Which Acrobat SDK
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

3

Deciding Which Acrobat SDK Technology to Use
When to Use Interapplication Communication

Wh en to Use Inte ra p p li cation Co mmu n ication
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 “PDF Browser Controls” on page 26 or the Acrobat Interapplication
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.
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 Chapter 10, “Rightsenabled 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.

30

Acrobat SDK User’s Guide

Deciding Which Acrobat SDK Technology to Use
Deciding Between Plug-ins and JavaScript

3

Using IAC
Using the IAC API, you can:
●

Get annotations, text and form data from a PDF document

●

Search a PDF document

●

Manipulate a PDF document, editing and adding content

●

Control Acrobat remotely. You cannot remotely control Adobe Reader.

From the Acrobat Viewer layer, you can use the IAC API to display PDF files in your
application’s windows. You can change the control you have over the application’s user
interface and appearance of its window by either using a PD layer object, PDPage, or by
using an AV layer object, AVDoc. PDPage gives you access to Acrobat’s rendering
capabilities. For more control, you can create your application with AVDoc that can be used
to display text annotations and active links in your application’s window.
From the PD layer, you can perform basic manipulations of PDF documents, such as
deleting, moving or replacing pages, as well as changing annotation attributes. You can
print PDF pages, select text, manipulate text, and create or delete thumbnails.
For more information on the IAC API, see “Interapplication Communication (IAC)” on
page 25 and the Acrobat Interapplication Communication Reference.
You can extend the functionality of the IAC interfaces by writing plug-ins that use core API
objects not already part of the IAC support system. For more information, see “Using Plugins for Interapplication Communication” on page 27 and the Acrobat Interapplication
Communication Overview.
Executing Acrobat JavaScript
You can execute Acrobat JavaScript commands from the IAC API by using the IAC API
ExecuteThisScript method of the AcroForm plug-in. On Windows, you can also use
the JSObject to access the JavaScript object model through the Acrobat automation
interface. For more information, see “Accessing the JSObject Interface” on page 27 and
Programming Acrobat JavaScript Using Visual Basic. On Mac OS X, you can execute JavaScript
scripts using Do Script in AppleScript.

Deciding Between Plug-ins and JavaScript
This section presents topics to consider as you decide whether to use plug-ins or JavaScript
to implement a particular functionality.
The section contains the following topics:

Acrobat SDK User’s Guide

●

General Issues

●

What You Can Do with Plug-ins That You Can’t Do with JavaScript

●

What You Can Do with JavaScript That You Can’t Do with a Plug-in

31

3

Deciding Which Acrobat SDK Technology to Use
Deciding Between Plug-ins and JavaScript

NOTE:

Subsequent chapters of this document discuss specific tasks you can do using the
Acrobat SDK and which technologies you can use to perform those tasks.

General Issues
The table below lists other general issues that are relevant to deciding between plug-ins
and JavaScript.
TABLE 3.2

Plug-ins vs. JavaScript - General Issues

Scope

●
●

Installation/
Distribution

●

●

Low-level Access

●

●

Execution Speed

●
●

Ease of
Implementation

●

●

Cross-platform
compatibility

●

●

32

A plug-in affects all PDF documents viewed by Acrobat.
JavaScript can affect either a single document or all PDF
documents in a particular folder.
Plug-ins must be placed in the Plug_ins folder or directory by
an installer or by the user.
Document-level JavaScripts are easier to distribute since they can
be included directly within the PDF file and do not require an
installer. Folder-level JavaScripts must be placed in the Acrobat
application JavaScript folder or the user’s JavaScript folder.
Plug-ins can access and manipulate low-level objects in the PDF
object model, such as the Cos layer.
JavaScript scripts can only access a limited set AV and PD layer
objects.
Plug-ins are compiled and loaded when Acrobat initializes.
Execution of JavaScript code is generally slower than plug-in code
because it is interpreted instead of compiled. The difference is
noticeable only in very computation-intensive applications, such
as a full-text search in a large PDF file.
Plug-ins are developed in C or C++ and are compiled and linked in
the appropriate development environment. You must be careful to
include all necessary header files for your application.
JavaScript scripts are easier to write and implement since they are
developed using the editor and debugger that come as part of
Acrobat Professional. Developers can also use an external editor to
create and edit JavaScripts.
Plug-ins must be built on different platforms to handle certain
platform-specific issues.
JavaScript is cross-platform compatible.

Acrobat SDK User’s Guide

Deciding Which Acrobat SDK Technology to Use
Deciding Between Plug-ins and JavaScript

3

What You Can Do with Plug-ins That You Can’t Do with JavaScript
In general, plug-ins allow for more direct control over Acrobat than JavaScript. There is a
much richer set of APIs that you can use from a plug-in.
The following can only be done using a plug-in; there is no equivalent JavaScript
functionality:
NOTE:

The following is not meant to be a complete list. For more detailed information, see
the subsequent chapters of this document.

●

Accessing Cos and other low-layer objects

●

Creating new menus or toolbars

●

Manipulating PDF content streams

●

Creating new annotation or action types

●

Modifying the ASFixed scale factor for large PDF file sizes.

●

Accessing platform-specific services or events

●

Getting and setting wireframe drawing mode

What You Can Do with JavaScript That You Can’t Do with a Plug-in
The following can be done easily using Acrobat JavaScript, but have no plug-in equivalent
API.

Acrobat SDK User’s Guide

NOTE:

Some tasks, such as SOAP and web services, can be done with a plug-in by using
low-level APIs. However, this is a very time-consuming approach and requires an indepth knowledge of the Cos and other other low-level APIs.

NOTE:

The following is not meant to be a complete list. For more detailed information, see
the subsequent chapters of this document.

●

Using SOAP and other web services

●

Manipulating multimedia in PDF documents

●

Setting up an automated email review workflow

●

Describing the state model for the review

●

Searching Acrobat Help

●

Using Acrobat Security Policies

33

3

Deciding Which Acrobat SDK Technology to Use
Samples Provided with the Acrobat SDK

S am p l e s Prov i d e d w i t h t h e Ac ro b at S D K
The Acrobat SDK contains a large number of sample applications, plug-ins, and scripts to
demonstrate how to use the SDK technologies.
NOTE:

Samples are regularly being added to the Acrobat SDK. Please refer to
http://partners.adobe.com/links/acrobat for the current complete list of samples
available for the Acrobat SDK.

Plug-in Samples
There are two types of plug-in samples in the Acrobat SDK: complete plug-ins and plug-in
snippets. Complete plug-ins are stand-alone plug-ins that you can compile and run in
Acrobat. Snippets are small fragments of code demonstrating how to use a single API that
are run using the SnippetRunner plug-in.
Complete Plug-in Samples
The “Starter” and “BasicPlugin” samples provide the most basic frameworks for developing
an Acrobat plug-in. The “DebugWindowADM” sample demonstrates how to build tools to
help you debug your plug-in.
Plug-in Snippets Using SnippetRunner
The SnippetRunner plug-in provides infrastructure to snippets. It is accessed from
Advanced > Acrobat SDK> AcroSDK Snippets. Each snippet can determine what context
should exist before it is called. For example, a snippet that reports the type of the current
selection does not need to open a document and set a selection before reporting its type—
it can assume the user has performed these tasks prior to invoking the snippet (the snippet
should still check that a document has been opened, however). The snippet obtains the
context from the utility code.
For more information, see the Guide to SDK Samples and the SnippetRunner Cookbook.

34

Acrobat SDK User’s Guide

Deciding Which Acrobat SDK Technology to Use
Samples Provided with the Acrobat SDK

3

Acrobat JavaScript Samples
JavaScript samples are divided into six categories, each in its own folder in the Acrobat
7.0 SDK/JavaScriptSupport/Samples folder:
Outside PDF

JavaScript files that live outside an Acrobat file — for example, the code
used in JavaScript folders, the console, and batch processes.

Inside PDF

Scripts written in JavaScript that live inside a PDF file.

Multimedia

Scripts that demonstrate the use of multimedia in PDF documents.

ADBC

Scripts that demonstrate database connectivity using ADBC.

SOAP

Scripts that demonstrate how to use SOAP services using Acrobat
JavaScript

UI

Scripts that demonstrate how to manipulate the Acrobat user interface.

Interapplication Communication Samples
The Acrobat SDK includes samples that demonstrate IAC functionality in both the
Macintosh and Windows development environments.

Acrobat SDK User’s Guide

35

3

36

Deciding Which Acrobat SDK Technology to Use
Samples Provided with the Acrobat SDK

Acrobat SDK User’s Guide

4

Creating PDF Documents

This chapter provides information about how to use the Acrobat SDK to create PDF
documents.
This chapter consists of the following sections:
●

Creating PDF Documents with Acrobat

●

Creating PDF Documents from an Authoring Application

●

Creating Tagged PDF Documents

●

Creating PDF Documents Using Plug-ins or Acrobat JavaScript

●

Creating PDF Documents with Acrobat

Creating PDF Documents with Acrobat
There are several ways that you can create PDF documents using software distributed as
part of the Acrobat product.

Acrobat PDFMaker
Files created in many applications can be converted directly to Adobe PDF files without
leaving the authoring application. The authoring application uses PDFMaker for the
conversion and the resulting files are Adobe PDF files.
In Windows, the default Acrobat installation installs the PDFMaker feature for the following
third-party applications:

Acrobat SDK User’s Guide

●

Autodesk AutoCAD 2002, 2004, and 2005

●

Microsoft Access 2000, 2002, and 2003

●

Microsoft Excel 2000, 2002, and 2003

●

Microsoft Internet Explorer 6.0

●

Microsoft Outlook 2000, 2002, and 2003

●

Microsoft PowerPoint 2000, 2002, and 2003

●

Microsoft Publisher 2002 and 2003

●

Microsoft Project 2000, 2002, and 2003

●

Microsoft Visio 2000, 2002, and 2003

●

Microsoft Word 2000, 2002, and 2003

37

4

Creating PDF Documents
Creating PDF Documents with Acrobat

For the Mac OS, the default Acrobat installation installs the PDFMaker feature for the
Professional, Standard, and Student and Teacher Editions of the following Microsoft
applications:
●

Microsoft Excel X (SR-1), 2004

●

Microsoft PowerPoint X (SR-1), 2004

●

Microsoft Word X (SR-1), 2004

When you install Acrobat using the default installation settings, the installer identifies thirdparty applications on your computer that support PDFMaker and installs the necessary
PDFMaker files to enable those applications to convert files to PDF files. The PDFMaker files
are also automatically installed if you install such a third-party application after installing
Acrobat on Windows.

Adobe PDF Printer
In an application that does not have a PDFMaker, you can still create a PDF file using the
Adobe PDF printer. Your source document is converted to PostScript and fed directly to
Distiller for conversion to PDF, without manually starting Distiller. The current Distiller
preference settings and Adobe PDF settings are used to convert the file.

Save As or Export
Use the Save As or Export command to create an Adobe PDF file from the current file.
This method is available in authoring applications such as Adobe InDesign, Adobe
Photoshop®, Adobe Illustrator®, and Adobe PageMaker. All the necessary components
for creating Adobe PDF files are installed and configured automatically when you
perform a typical installation.

38

Acrobat SDK User’s Guide

Creating PDF Documents
Creating PDF Documents from an Authoring Application

4

Cre at i n g P D F D o c u m e n t s f ro m a n Aut h o r i n g Ap p l i c at i o n
Authoring applications can simplify the creation of PDF files by making the following steps
appear seamless:
●

Invoking Distiller through Apple events or DDE.

●

“Printing” to a PostScript file.

●

Automatically generating advanced Acrobat features using pdfmark.

This section consists of the following subsections:
●

Acrobat Distiller

●

Apple Event Support

●

Distiller Automation on Windows Using OLE Automation

●

Automated, Silent Creation of PDF Documents from Windows

●

Choosing an Adobe PDF Settings File

●

Automatically Generating Advanced Acrobat Features

●

Inserting PostScript Code into a Job

●

Attaching the Native Document to the PDF File

●

Batch Processing with Distiller

Acrobat Distiller
Acrobat Distiller is essentially a PostScript interpreter that can be used to convert PostScript
to PDF. Distiller is the PDF creation application intended for batch processing use and for
the creation of PDF files containing high-end print publishing features such as OPI
comments, CMYK color spaces, and spot colors. Distiller also has the ability to interpret
PostScript extensions called pdfmarks and convert them to PDF objects such as links,
bookmarks, optional content (OC), and annotations. See “Choosing an Adobe PDF Settings
File” on page 41.
For more information on the Distiller program, see the following documents or
http://partners.adobe.com/links/acrobat:

Acrobat SDK User’s Guide

●

Acrobat Distiller API Reference

●

Acrobat Distiller Parameters

●

pdfmark Reference Manual

39

4

Creating PDF Documents
Creating PDF Documents from an Authoring Application

Apple Event Support
The Macintosh version of Distiller supports Apple events. Apple events can be used from
external applications written in programming languages such as C or from AppleScript.
Because AppleScript is more straightforward, using it is the recommended way to use
Apple events with Distiller.
Distiller supports the following Apple events:
●

The Distill command distills one or more PostScript language files, creating a PDF
file for each.

●

The run command launches Distiller.

●

The quit command quits Distiller.

Distiller Automation on Windows Using OLE Automation
For Windows, you can automate Distiller under Microsoft Windows through the
Automation interface also known as OLE Automation (commonly referred to as ActiveX or
COM). The Automation interface makes it easy to create and control a Distiller from any
programming language that supports Automation. Distiller supports programming
environments written for the following languages:
●

Visual Basic

●

Visual C++ with and without MFC

Distiller exposes one interface: PdfDistiller. This interface provides methods and
properties to invoke Distiller and to customize Distiller properties. For example, you can:
●

Specify that a particular settings file be used rather than the default settings file

●

Apply security to the generated PDF file

●

Specify whether to spool the job or execute it immediately

You can also use the Distiller API to check the status and errors associated with a Distiller
job.
As it processes each job, Distiller fires several events to notify you of its progress. These
events can be accessed using the PdfDistiller interface.
In addition, certain features of Distiller can be controlled directly through the PostScript
language file (see “Choosing an Adobe PDF Settings File” on page 41). Authoring
applications that control Distiller should also provide an interface to their users to allow
control of font embedding and image compression as well as downsampling in the PDF file.
For more information, see the Acrobat Distiller API Reference.

40

Acrobat SDK User’s Guide

Creating PDF Documents
Creating PDF Documents from an Authoring Application

4

Automated, Silent Creation of PDF Documents from Windows
In the Acrobat 7.0.5 SDK, there is a new set of APIs that allow you to automate the silent
creation of PDF files from an external Windows application.
When you use the OLE Automation described above, the Distiller splashscreen and status
are displayed even when the process is automated. With this API, there is no interaction
with the user and no display on the screen; the printing is done “silently.”
This API allows you to specify the name and location of the output PDF. To do so, you must
make modifications to the Windows registry. See the Distiller API Reference for more
information on what registry modifications are required.
NOTE:

This procedure involves editing the registry. Adobe Systems Incorporated does not
provide support for editing the registry, which contains critical system and
application information. It is recommended that you back up the registry before
modifying it.

To check status and errors, use the Distiller API. For more information, see the Acrobat
Distiller API Reference and the Acrobat SDK Samples Guide.

Choosing an Adobe PDF Settings File
You can control the Adobe PDF settings file through the Distiller user interface, or you can
control Distiller programmatically through the various Distiller automation methods. For
details on automation methods, see “Creating PDF Documents from an Authoring
Application” on page 39 and the Acrobat Distiller API Reference.
At the user interface level, you can set Distiller parameters by selecting a file of predefined
Adobe PDF settings, or by creating your own set of Adobe PDF settings. Each Distiller
settings file defines compression, font embedding, color management, PDF/X-compliance,
and many other properties for all PDF files that Distiller creates.
Distiller comes with several predefined Adobe PDF settings files, with settings defined for
common scenarios. You choose which settings file to use as a parameter to the Distiller
Automation API. For a complete list of settings, see the Acrobat Distiller API Reference.

Automatically Generating Advanced Acrobat Features
The most convenient place to generate advanced Acrobat features is in the authoring
application itself, since this application knows the most about the structure of the
document. Advanced PDF features are generated using the pdfmark PostScript operator.
The authoring application must generate a PostScript language file that contains the
appropriate pdfmark operators for the document structure desired. The resulting
PostScript language file is converted into a PDF file via Distiller. In addition, Acrobat allows
logical structure information to be added to a document. For instance, paragraphs in a
page’s contents can be associated with a structural element representing a paragraph.
For more information, see “Creating Tagged PDF Documents” on page 43 and the pdfmark
Reference Manual.

Acrobat SDK User’s Guide

41

4

Creating PDF Documents
Creating PDF Documents from an Authoring Application

Inserting PostScript Code into a Job
Acrobat Distiller contains a PostScript 3 interpreter with two Distiller-specific operators,
setdistillerparams and currentdistillerparams. An Adobe PDF settings file can be
thought of as a Postscript file that contains setdistillerparams key-value pairs, followed by
the PostScript setpagedevice operator with two key-value pairs. The Adobe PDF settings
file is the first file processed by Distiller, but parameters can subsequently be set or
changed within the PostScript job itself.
See Distiller Parameters for more information.

Attaching the Native Document to the PDF File
Another way that an authoring application can integrate with Acrobat or Adobe Reader is
to allow the user access to the original authoring document through the Acrobat user
interface. Through the use of private data in a PDF file, an authoring application can embed
the entire authoring document as part of the PDF file that represents it. This way, not only
can the resulting electronic document be viewed by anyone using Acrobat, it can also be
edited by users who have the authoring application. You must write a plug-in for Acrobat n
to allow users to embed and extract the authoring document. This plug-in would simply
add the authoring document as a private data stream when embedding, and, when
extracting, save the stream to a temporary file and invoke the authoring application.
NOTE:

Acrobat and Adobe Reader ignore private data. Embedding authoring documents in
PDF files greatly increases the size of the PDF file.

Using Links to Associate a Native Document with the PDF File
An association between the PDF file and the authoring document can also be maintained
through the use of links in the PDF file. Links can be created that invoke files and their
associated applications. If a document management system places such a link in the PDF
file, users can invoke the original authoring document by executing the link.

Batch Processing with Distiller
Due to the built-in functionality of Distiller, you do not need to use the Distiller API to
integrate it with your product. Distiller has the ability to watch directories over a network
and to convert any PostScript files saved to those directories to PDF. It is also possible to set
different job options for each directory so that one directory can be used, for example, for
high-end color output, while the other can generate a more compressed file suitable for
Web use. These features of Distiller are not supported by Acrobat Developer Support.
Check the help documentation packaged with the product or books by Adobe Press and
other publishers for using Distiller through the user interface.
The Distiller API can be used to programmatically process files and set the output path and
file names. The API is documented in the Acrobat Distiller API Reference. Also, the Acrobat
Professional product can be used to set up watched folders.

42

Acrobat SDK User’s Guide

Creating PDF Documents
Creating Tagged PDF Documents

NOTE:

4

Server use of the Distiller software is not allowed. The End User License Agreement
allows for use only on a single system. Access to, and use of, the Distiller software
over a network is prohibited. The only exception is installation of the software. You
are permitted to keep a copy of the software on a server so that users who have a
license for the software can download and install it. A separate product, Acrobat
Distiller Server, can be purchased or licensed from Adobe for server use.

Creating Tagged PDF Documents
PDF files are well known for representing the physical layout of a document; that is, the
page markings that comprise the page contents. In addition, PDF versions 1.3 and beyond
provide a mechanism for describing logical structure in PDF files. This includes information
such as the organization of the document into chapters and sections, as well as figures,
tables, and footnotes.
PDF 1.4 and Acrobat 5 introduced tagged PDF, which is a particular use of structured PDF
that allows page content to be extracted and used for various purposes, including:
●

Reflow of text and graphics

●

Conversion to file formats such as HTML and XML

●

Access for the visually impaired (see Chapter 14, “Accessibility”).

PDF Logical Structure
PDF logical structure is layered on top of a document’s page contents using a special
markup language. HTML and XML use a similar layout for logical structure: text enclosed in
a hierarchy of tags. In HTML, each component is wrapped with a set of tags that define its
structure. For example, the text of a top-level header begins with a 

tag and ends with a

tag. PDF provides similar constructs with its marked content operators. In fact, HTML logical structure can be preserved in a PDF document. The Web Capture feature introduced in Acrobat 4.0 allows converting HTML to PDF. Such PDF may optionally contain structure information from the HTML data. Acrobat can generate bookmarks from this structure data. The Structure Tree Logical structure is independent of, though related to, the page content (that is, the actual marks on the page made by the marking operators). In a PDF document, logical structure is represented by a tree of elements called a structure tree. There are pointers from the logical structure to the page contents, and vice versa. The structure tree provides additional capability to navigate, search, and extract data from PDF documents. By accessing a PDF document via its structure tree, for instance, you can obtain logically ordered content independently of the drawing order of the page contents. Acrobat SDK User’s Guide 43 4 Creating PDF Documents Creating Tagged PDF Documents Adding Structure Data to a PDF Document Creating a tagged document directly from an authoring application is the best way to make PDF documents accessible to screen readers and reflow correctly on handheld devices. If your PDF document was created without tags, Acrobat can add them. The tagging feature identifies most elements of a PDF document, including irregularly shaped columns, bulleted lists, captions that span columns, images that overlap text, and colored backgrounds. From a plug-in, you can add structural information to any PDF file with the PDSEdit API. Once a file has logical structure, PDSEdit allows you to use it. For more information, see “Using Document Logical Structure” on page 51 and the Acrobat and PDF Library API Overview. Using pdfmark to Add Structure Data to PDF Advanced Acrobat features are generated using the pdfmark PostScript operator. The authoring application must generate a PostScript language file that contains the appropriate pdfmark operators for the document structure desired. This resulting PostScript language file is converted into a PDF file via Distiller. The pdfmark operator is not a standard PostScript operator, but is provided as a PostScript language extension used by Distiller to describe features that are present in PDF, but not in standard PostScript. The pdfmark operator has been available beginning with Distiller 3.0, and has evolved with each release of the PDF specification. NOTE: While the pdfmark operator provides for greater extensibility, it is not intended to define every feature that is present in PDF but not in standard PostScript. For more information, see the pdfmark Reference Manual and the PDF Reference. 44 Acrobat SDK User’s Guide Creating PDF Documents Creating PDF Documents Using Plug-ins or Acrobat JavaScript 4 Cre at i n g P D F D o c u m e n t s Us i n g P l u g - i n s o r Acro b at Jav a S c r i p t You can use Acrobat and the Acrobat SDK to create a new, empty PDF file and to create a PDF file from supported file types. ● Creating an Empty PDF File ● Creating PDF Files from Multiple Files Creating an Empty PDF File Using either a plug-in or Acrobat JavaScript, you can dynamically create a new PDF file and modify its contents in an automated fashion. This can help make a document responsive to user input and enhance the workflow process. Using Acrobat JavaScript Acrobat JavaScript provides support for dynamic PDF file creation and content generation. This means that it is possible to dynamically create a new PDF file and modify its contents in an automated fashion. Using a Plug-in Using a plug-in, you can use the PDDocCreate API to create a new, empty PDF file. You can then use the PDDocCreatePage or PDDocInsertPages to add content to the created file. Creating PDF Files from Multiple Files It is possible to use either a plug-in, IAC or JavaScript to dynamically add content from other sources into a new PDF file. The sources may include files whose types conform to Multipurpose Internet Mail Extensions (MIME) type definitions. Using Acrobat JavaScript To import an external file into a PDF document, invoke the doc object’s importDataObject method. After doing this, it is possible to extract information from the data object for placement and presentation within the PDF document. You can automate the insertion of multiple PDF files into a single PDF document through a series of calls to the doc object’s insertPages and replacePages methods. Finally, to use a portion of the current document to create a new document, you can invoke the doc object’s extractPages method. Using a Plug-in or IAC You can use the AVConversionToPDFHandler API to extract data from other file types, and then bind the resulting PDF files into one PDF file using PDDocInsertPages. These APIs can also be conveniently executed directly from an IAC application. Acrobat SDK User’s Guide 45 4 Creating PDF Documents Creating PDF Files Without Using Acrobat Creating PDF Files Without Using Acrobat This section briefly discusses other ways that you can create documents without using the Acrobat SDK. The subsequent sections are specific to creating PDF documents using the Acrobat SDK. ● Acrobat Capture 3.0.x Acrobat Capture 3.0.x is a separate Adobe product designed for the batch conversion of image files to PDF and creating searchable text PDF files from the resulting PDF files. For more information on the Acrobat Capture 3.0.x SDK, see partners.adobe.com/links/acrobat. ● Adobe LiveCycle family of products The Adobe LiveCycle products, including Adobe LiveCycle Forms, Adobe LiveCycle Designer, and Adobe Document Server. Adobe LiveCycle products enable businesses to dynamically generate customized PDF documents for more targeted and effective customer communications, allowing you to: – Flow XML data into richly formatted templates – Assemble and manipulate compound documents – Extract content from interactive Adobe PDF forms – Create customized, visually rich charts and graphics – Extend PDF documents using Adobe Reader extensions Generating PDF Files Without Using Adobe Applications Some developers have successfully developed the capability of generating PDF from their own applications without using Adobe products. Some of these developers have chosen to use Adobe’s PDF Library product to extend their own application. Others have built PDFgeneration capability into their applications from scratch. This type of development is not supported by Adobe. The best resource for building PDF-generation capability from scratch is the PDF Reference, which fully documents the PDF 1.6 specification. The PDF file format is quite complex, and developing code to generate it requires a significant amount of development. In estimating development time, we suggest you look at the methods used to compress and encrypt the page content streams, as well as the requirements of the byte offset table at the end of the PDF file. The LZW compression technique is the subject of United States patent number 4,558,302 owned by the Unisys Corporation. Independent software vendors may be required to license this patent directly from Unisys to develop software using LZW. Further information can be obtained from Welch Licensing Department, Law Department, M/S C2SW1, Unisys Corporation, Blue Bell, Pennsylvania, 19424. 46 Acrobat SDK User’s Guide 5 Working with PDF Documents This chapter details how you can work with PDF documents using the Acrobat SDK. This chapter consists of the following sections: Acrobat SDK User’s Guide ● Automating Processes: Opening PDF Documents Silently ● Adding Navigation to PDF Documents ● Manipulating Pages of a PDF File ● Creating and Editing Page Content ● Using Document Logical Structure ● Modifying PDF Documents in Other Ways ● Adding Watermarks ● Spell-Checking ● Using Multimedia ● Interacting with OBDC Databases ● Printing PDF Files ● Working with Embedded Fonts ● Large Page Sizes in PDF Documents ● Wireframe Drawing 47 5 Working with PDF Documents Automating Processes: Opening PDF Documents Silently Automating Processes: Opening PDF Documents Silently To open documents using automated processes, it may sometimes be necessary to suppress the warning indicating that the version number of the document is greater than the version of Acrobat or Reader being used. To address this issue in the Windows registry for Acrobat, set HKEY_CURRENT_USER\Software\Adobe\Adobe Acrobat\7.0\AVAlert\cCheckbox\idocNewerVersionWarning to 1. For Reader, the registry entry is HKEY_CURRENT_USER\Software\Adobe\Acrobat Reader\7.0\AVAlert\cCheckbox\idocNewerVersionWarning. NOTE: This procedure involves editing the registry. Adobe Systems Incorporated does not provide support for editing the registry, which contains critical system and application information. It is recommended that you back up the registry before modifying it. To modify the property list entry for Acrobat on a Macintosh, use the property list file :library:preferences:com.adobe.acrobat.pro7.0.plist and assign the value 1 to . For Reader, the property list file is :library:preferences:com.adobe.acrobat.reader7.0.plist. This warning can also be suppressed interactively by checking Do not show this message again in the warning dialog box that appears. NOTE: 48 In both cases, bear in mind that PDF files from future versions of Acrobat or other sources could conflict with the current version of Acrobat or Reader without displaying this warning, although Adobe Systems, Inc. makes every effort to avoid such backward compatibility issues. Acrobat SDK User’s Guide Working with PDF Documents Adding Navigation to PDF Documents 5 Adding Navigation to PDF Documents This section describes ways that you can add navigation to your PDF file using the Acrobat SDK. ● Adding and Managing Bookmarks ● Adding and Managing Thumbnails ● Adding and Managing Links Adding and Managing Bookmarks A bookmark corresponds to an outline object in a PDF document. A document outline consists of a tree-structured hierarchy of bookmarks that displays the document’s structure, allowing the user to navigate interactively from one part of the document to another. Each bookmark has: ● A title that appears on screen ● An action that specifies what happens when the user clicks on the bookmark Bookmarks can be either created interactively through the Acrobat user interface or generated programmatically. Typically, a user-created bookmark is used to move to another location in the current document, although other actions can be specified, such as opening a web link, opening a file, playing a sound or executing a JavaScript script. Each bookmark in the bookmark tree structure has zero or more children that appear indented, and zero or more siblings that appear at the same indentation level. All bookmarks except the bookmark at the top level of the hierarchy have one parent, the bookmark under which it is indented. A bookmark is said to be open if its children are visible, and closed if they are not. You can use Acrobat JavaScript, a plug-in, or IAC to get or set: ● The open attribute of a bookmark ● The text used for the bookmark’s title ● The action that is invoked when the bookmark is selected The object associated with each Acrobat SDK technology is shown below: Acrobat SDK User’s Guide JavaScript Bookmark Plug-in PDBookmark IAC AcroExch.PDBookmark 49 5 Working with PDF Documents Adding Navigation to PDF Documents Adding and Managing Thumbnails Page thumbnails are miniature previews of the pages in a document. You can use page thumbnails in Acrobat to jump quickly to a selected page and to adjust the view of the page. When you move, copy, or delete a page thumbnail, you actually move, copy, or delete the corresponding page. You can embed page thumbnails in a PDF document so that they need not be redrawn every time you select the Pages tab. They can easily be removed and embedded again if necessary. You can use the Acrobat SDK to: ● Create thumbnails in a PDF document ● Remove thumbnails from a PDF document The object associated with each Acrobat SDK technology is shown below: JavaScript doc.addThumbnails, doc.removeThumbnails Plug-in PDThumb IAC AcroExch.PDDoc methods Adding and Managing Links Links, or hyperlinks, let users jump to other locations in the same document, to other electronic documents, or to Web sites. You can use links when you want to ensure that your reader has immediate access to related information. You can also use links to initiate actions. The Acrobat SDK provides support for the addition, customization, or removal of links within PDF documents. These links may be used to access URLs, file attachments, or destinations within the document. The objects associated with each Acrobat SDK technology is shown below: JavaScript doc, Link Plug-in PDLink IAC AcroExch.PDAnnot The doc object contains methods for adding, retrieving, and removing links. This is used in conjunction with the Link object, which contains properties as well as a setAction method for customizing the appearance and behavior of a given link. In addition, the Acrobat JavaScript app object contains a property called openInPlace, which can be used to specify whether cross-document links are opened in the same window or in a new one. 50 Acrobat SDK User’s Guide Working with PDF Documents Manipulating Pages of a PDF File 5 Using Actions for Special Effects Thumbnails, bookmarks, links, and other objects have actions associated with them, and you may use Acrobat JavaScript to customize their behavior. For example, you can use them to display messages, jump to destinations in the same document or any other, open attachments, open Web pages, execute menu commands, or perform a variety of other tasks. You can also customize these actions so that they change their appearance after the user has clicked on them. For a button, you can invoke its highlight property, which allows you to specify how the button will appear once it has been clicked. M a n i p u l at i n g Pa g e s o f a P D F Fil e You can use the Acrobat SDK to insert or remove pages from a PDF document. The following table shows the methods to use for each Acrobat SDK technology: Acrobat JavaScript doc object method Core API method Create an empty page in the current document newPage PDDocCreatePage Insert pages from another document into the current document insertPages Move a page to another location in the same document movePage Replace pages with pages from another document replacePages Delete pages from the current document deletePages NOTE: Acrobat SDK User’s Guide PDDocInsertPages PDDocMovePage PDDocReplacePages PDDocDeletePages IAC method ● Windows ● Apple Script ● Not available Not available ● InsertPages ● insert pages ● MovePage ● Not available ● ReplacePages ● replace pages ● DeletePages ● delete pages ● You can also access Acrobat JavaScript functionality using the JSObject from an external application. See “Accessing the JSObject Interface” on page 27. 51 5 Working with PDF Documents Creating and Editing Page Content Creating and Editing Page Content Page content is a major component of a PDF file. It represents the visible marks on a page that are drawn by a set of PDF marking operators. The set of marking operators for a page is also referred to as a display list, since it is a list of marking operations that represent the displayed portion of a page. See the PDF Reference for an overview of page content streams and references to other chapters that describe the marking operators in detail. PDFEdit API The PDFEdit API provides easy access to PDF page contents. With PDFEdit, your plug-in can treat a page’s contents as a list of objects rather than manipulating the content stream’s marking operators. PDFEdit is meant to be used in conjunction with the Acrobat PD layer and Cos layer methods for manipulating PDF documents. To use PDFEdit effectively, you should be familiar with PDF page marking operators and the PD layer of the core API, described in the Acrobat and PDF LIbrary API Overview. Acrobat Distiller and PDFWriter create documents from PostScript or as output from a printer driver. Non-PDFEdit methods in the core API allow displaying and printing documents, and provide the ability to rearrange pages and to add annotations. However, most of these manipulations are creation-centered, or only deal with objects at the page level and above. PDFEdit methods, on the other hand, allow your plug-in to deal with objects at the level of a page’s contents. There is no Acrobat JavaScript equivalent to the PDFEdit API to allow you to manipulate page content. For more information, see the Acrobat and PDF Library API Overview. PDFEdit Samples There are several “snippets” available from the SnippetRunner sample plug-in that demonstrate how to add data to the contents of a page. Using the Acrobat core API greatly simplifies modifying and creating PDF page contents. In addition, Acrobat updates the byte offset table and page resources to ensure that the PDF file is still readable after modification. This would be significantly more complex if this were attempted by parsing and rewriting the page contents without using the core API, and could result in an unreadable PDF file. For more information, see the SnippetRunner Cookbook. 52 Acrobat SDK User’s Guide Working with PDF Documents Using Document Logical Structure 5 Using Document Logical Structure As discussed in “Creating Tagged PDF Documents” on page 43, you can insert logical structure into a PDF document by creating a tagged PDF document. The PDSEdit API provides the ability to add, modify and view this logical structure. For more information, see the Acrobat and PDF Library API Overview. Navigating a PDF Document PDSEdit methods allow you to navigate through a document according to its structure. Bookmarks made from structure can go to an individual paragraph or a whole section, rather than just to a point on a page. PDSEdit also allows searching within structure elements. For example, you can search for a word within elements of a certain type, such as headings. It can be used to move around a document, to analyze its content, and to traverse its hierarchical structure. Extracting Data From a PDF Document The PDSEdit API allows you to extract portions of pages according to their context, such as all of the headings or tables. The extracted data can be used in different ways, such as summarizing document information, importing the data into another document, or creating a new PDF document. Adding Structure Data to a PDF Document Authoring applications create documents that can be converted to PDF. When the document is converted to PDF and viewed, Acrobat does not automatically add structure to the document. You can add structural information to any PDF file with the PDSEdit API. Once a file has logical structure, you can use PDSEdit to access and modify that structure. Using pdfmark to Add Structure Data to PDF Authoring applications may add structure pdfmarks to the PostScript language code generated when a document is printed. When the Acrobat Distiller application creates a PDF file from such PostScript code, it generates structure information in the PDF file from the pdfmarks. This approach requires that either the authoring application to add structure pdfmarks to the PostScript code it generates, or that some other application generates the pdfmarks. See “Adding Structure Data to a PDF Document” on page 44 and the pdfmark Reference for more information. Acrobat SDK User’s Guide 53 5 Working with PDF Documents Modifying PDF Documents in Other Ways Modifying PDF Documents in Other Ways You can also use a plug-in or Acrobat JavaScript to modify a PDF document by: ● Cropping and rotating pages ● Numbering pages ● Adding headers and footers For more information, see the Acrobat JavaScript Scripting Guide and the Acrobat and PDF LIbrary API Overview. Addin g Waterm arks Acrobat JavaScript provides methods to create watermarks within a document, and place them in optional content groups (OCGs). There are no high-level C APIs for adding watermarks. However, you can add watermarks using lower-level APIs. The Acrobat SDK contains a sample plug-in that adds a watermark. See the Guide to SDK Samples for more information. Fixed Printing for Engineering Documents To meet government requirements, it is often necessary that a watermark be included on any printed pages of large documents. To support this requirement, there is a new type of object in a PDF similar to an Optional Content Group. It is called a FixedPrint element and it prints at the same size and scale factor and in the same location on any printout (or export as Postscript) regardless of the settings used at print time. The FixedPrint object is only used when printing or exporting to PostScript. It is not visible from within Acrobat. The content of a FixedPrint is fixed to a region of a printed page. FixedPrint uses marked content so that any content is permitted. The placement coordinates can be either relative or absolute. You can access FixedPrint using the improved header, footer and watermarking tools in the Acrobat user interface. There are no high-level plug-in APIs for manipulation FixedPrint objects. You can, however, manipulate FixedPrint from using PDEdit and Cos level APIs. There are no equivalent Acrobat JavaScript APIs. 54 Acrobat SDK User’s Guide Working with PDF Documents Spell-Checking 5 Spell-Checking Acrobat provides a Spelling plug-in that can scan a document for spelling errors. Using any of the Acrobat SDK technologies, you can do the following: ● Add or remove a dictionary from the list of available dictionaries ● Add or remove a spelling domain (search scope) from the Spell Check dialog box ● Add or remove a word in the user’s dictionary ● Check the spelling of an individual word ● Ignore all occurrences of a word in a document when spell-checking ● Scan a text buffer and return the next word ● Set the document’s dictionary search order ● Set the document’s dictionary search order from an array of ISO 639-2 and 3166 language codes, allowing you to identify a dictionary by language rather than by name The following additional functionality is available to plug-ins and external applications, but is not available using Acrobat JavaScript: ● Check a text object and optionally receive a callback for each change as the user interacts with the Spell Check dialog box ● Count the words in a text buffer that are contained in each of a set of dictionaries ● Create a new custom user dictionary and add it to the list of available dictionaries Using Multimedia Multimedia objects can be included in the content of PDF documents, as well as in annotations. You can only manipulate multimedia objects and players using JavaScript; you cannot use a plug-in. Using Acrobat JavaScript, you can: ● Customize the settings, renditions, and events associated with media players ● Access and control the properties for all monitors connected to the system ● Add movie and sound clips ● Add and edit renditions ● Control rendition settings ● Set multimedia preferences that apply throughout a document For more information, see the Acrobat SDK JavaScript Scripting Guide and the Acrobat SDK JavaScript Scripting Reference. Acrobat SDK User’s Guide 55 5 Working with PDF Documents Interacting with OBDC Databases Interacting with OBDC Databases Acrobat JavaScript provides an ODBC-compliant object model called Acrobat Database Connectivity (ADBC), which can be used in document-level scripts to connect to a database for the purposes of inserting new information, updating existing information, and deleting database entries. ADBC provides a simplified interface to ODBC, which it uses to establish a connection to a database and access its data, and supports the usage of SQL statements for data access, update, deletion, and retrieval. To use ADBC, ODBC must be installed on a client machine running a Microsoft Windows operating system. Note that ADBC does not provide security measures with respect to database access; it is assumed that the database administrator will establish and maintain the security of all data. Pri nt in g PD F Fi le s Using the Acrobat SDK, you can control the way that Acrobat, Adobe Reader or your external application prints PDF files. Customizing and Automating Printing Using any of the Acrobat technologies, you can customize the way that a PDF document is printed. Printing from Acrobat JavaScript Since printing involves sending pages to an output device, there are many options that can affect print quality. Acrobat JavaScript can be used to enhance and automate the use of these options in print production workflows, primarily through the use of the PrintParams object. For a complete list of parameters, see the Acrobat JavaScript Scripting Guide. Printing from a Plug-in You can use AVDoc methods to customize and control how a PDF file is printed from Acrobat or Adobe Reader. Depending on the methods you use, a user interface is either invoked or not. The AVDocDoPrint method invokes the print user interface, where the user can then specify printing parameters. The AVDocPrintPages method prints a document to the current printer using the current print settings and job settings with no user interface. You can specify a page range, a PostScript version and whether to shrink the pages to fit the printer. 56 Acrobat SDK User’s Guide Working with PDF Documents Working with Embedded Fonts 5 To set more specific parameters for printing without a user interface, you must use the AVDocPrintPagesWithParams method. Among the parameters that you can set with this method are: ● The printer to be used ● Output file name (path and filename) ● Whether to embed the output in a bounding rectangle on the screen ● Whether to print the document as an image ● Whether to tile the output ● Output transparency level Printing from an External Application Using the IAC APIs, you can print a PDF file from an external application. On Windows, the IAC API’s AVDoc object has several methods for printing. In AppleScript, the document object’s print pages method prints a specified range of pages without displaying a print dialog box. For more information, see the Acrobat Interapplication Communication Overview. Working with Embedded Fonts This section discusses embedded font-related operations using the Acrobat SDK. Acrobat Distiller and the PDF Library add font embedding information to fonts that are embedded in PDF files. With the inclusion of this information, your code can determine how an embedded font can be used. The operations discussed in this section also largely apply to code used with the PDF Library SDK. Acrobat plug-in developers can remove and embed fonts within an existing PDF document. They can also use fonts that are already embedded in a PDF document for preview and printing, as well as editing. However, allowing editing using embedded fonts is not recommended, and in some cases it is impractical. For example, CJK fonts potentially include thousands of glyphs, so applications must subset these fonts when embedding them in a PDF file. This precludes embedded CJK fonts from being used for editing by a plug-in. PDF Library users can perform all of the above operations using an existing PDF document, or create a PDF document from scratch that includes embedded fonts. Creating a document from scratch cannot be performed by a plug-in, but it can be done by using PDF library calls from within a compiled application that includes the PDF Library. Acrobat SDK User’s Guide 57 5 Working with PDF Documents Large Page Sizes in PDF Documents Large Page Sizes in PDF Documents In previous versions of Acrobat, the maximum size of a PDF document was 200 by 200 inches due to the internal use of ASFixed variables for all coordinates. In Acrobat 7, pages in a PDF document now have a scaling factor associated with them that allows the same number of ASFixed points to represent feet, yards, meters, hectares or other measurements. The value of this scaling factor is per page and can be retrieved in a plug-in using the PDPageGetUserUnitSize API. There are no Acrobat JavaScript APIs to access the unit size information. Wire f ra m e D raw i n g In order to improve the speed of drawing large and complex documents, Acrobat has a new mode that only draws the strokes of objects as simple, one-unit lines as seen in the figure below. It does not affect filled shapes or text. You can get and set wireframe mode from a plug-in using the following APIs: ● AVPageViewGetWireframeDrawing ● AVPageViewSetWireframeDrawing There are no Acrobat JavaScript APIs for wireframe drawings. 58 Acrobat SDK User’s Guide 6 Modifying the User Interface This section describes how to change the Acrobat or Adobe Reader user interface using the Acrobat SDK. This chapter consists of the following sections: ● Adding or Removing Menus and Menu Items ● Modifying the Toolbar ● Using the Adobe Dialog Manager (ADM) ● Customizing Acrobat Help Adding or Removing Menus and Menu Items You can use the Acrobat SDK to manipulate menu items, menus and menu bars. For complete information on what functionality is available with each SDK technology, see the Acrobat and PDF Library API Reference. the Acrobat JavaScript Scripting Reference, or the Acrobat Interapplication Communication Reference. Adding Menu Items You can use a plug-in or Acrobat JavaScript to add or remove menu items or submenus to an existing menu. From JavaScript, use the app object’s AddMenuItem, HideMenuItem, and AddSubMenu methods. Plug-ins can access the methods of the AVMenu and AVMenuItem objects. With IAC OLE automation, you can remove a menu item using the App.MenuItemRemove method. However, you cannot use IAC to add a menu item. Menu items added by plug-ins can have shortcuts (keyboard accelerators). Acrobat and Adobe Reader do not ensure that plug-ins add unique shortcuts, but it is possible for a plug-in to check which shortcuts are already in use before adding its own. Note that the only way to ensure there are no shortcut conflicts is for all plug-ins to check for conflicts before adding their own shortcuts. You are encouraged to have your plug-in add its menu items to the Tools menu. When it is launched, Acrobat or Adobe Reader automatically adds this menu, as well as the About Plug-ins and Plug-in Help menus (see “Placing Plug-in Help Files in a Standard Location” on page 64). After Acrobat or Adobe Reader loads all plug-ins, it checks these three menus and removes any that are empty. Acrobat SDK User’s Guide 59 6 Modifying the User Interface Modifying the Toolbar Adobe keeps a registry of plug-in menu item names to help avoid conflicts between plugins. For more information on registering and using plug-in prefixes, see the Acrobat SDK Plug-in Guide. Adding a New Menu To create a new menu, use the AVMenuNew method from a plug-in. Add a new (or an existing) menu to a menu bar using the AVMenuBarAddMenu method. You cannot create menus or add menus to menu bars using Acrobat JavaScript or IAC. Modifying the Toolbar You can use the Acrobat SDK to manipulate tool buttons and toolbars. For complete information on what functionality is available with each SDK technology, see the Acrobat and PDF Library API Reference, the Acrobat JavaScript Scripting Reference, or the Acrobat Interapplication Communication Reference. Adding Items to an Existing Toolbar You can add or remove buttons to the toolbar, although the size and resolution of the user’s monitor can limit the number of tool buttons that can be added. From a plug-in, use the methods of the AVToolBar and AVToolButton objects. From Acrobat JavaScript, use the app object’s addToolButton and removeToolButton methods. With IAC OLE automation, you can remove a menu item using the App.MenuItemRemove method. However, you cannot use IAC to add a menu item. Creating a New Toolbar Plug-ins also can create new toolbars, called flyouts, that can be attached to buttons on the main toolbar. The selection tools, for example, are all on a flyout. As of Acrobat 4.0, it is no longer true that all tool buttons are located on the main toolbar; some may be located on a flyout. You cannot create a flyout with Acrobat JavaScript or IAC. 60 Acrobat SDK User’s Guide Modifying the User Interface Using the Adobe Dialog Manager (ADM) 6 Us i n g t h e Ado b e D ia l o g M a n a g e r (AD M ) The Adobe Dialog Manager (ADM) is a cross-platform API for implementing dialog interfaces for Adobe applications such as Acrobat, Adobe Reader, Photoshop, Illustrator, and After Effects. This document describes ADM structures and how to access them. You should already be familiar with the concept of dialogs and dialog items. For complete information about ADM, see the Adobe Dialog Manager Programmer’s Guide and Reference. This section covers the following topics: ● ADM Controls ● ADM Objects ● Using ADM from Acrobat JavaScript ● Using the ADM API from a Plug-in ADM Controls ADM enables developers to create and manage cross-platform dialogs. Two types of dialogs are supported: modal dialogs and modeless dialogs. The latter dialogs “float” over the host application windows, while the former are displayed and disappear upon conclusion of the user input. With a modal dialog, a user cannot work elsewhere in the application until the dialog is closed. In both cases, ADM supports a wide variety of control types, including basic ones such as buttons and text, and more complicated types such as lists and hierarchy lists. In addition to providing a wide array of custom and standard user interface elements, ADM also provides some very useful features, such as tab palettes, docking palettes, and automatically tracking and displaying the correct selection in grouped radio buttons. Finally, ADM provides a consistent Adobe interface and “look and feel.” The following types of controls are available using ADM: Acrobat SDK User’s Guide ● Push button ● Check box ● Radio button ● List box ● Hierarchical list box ● Static text box ● Editable text box ● Popup control ● OK button ● OK and Cancel button 61 6 Modifying the User Interface Using the Adobe Dialog Manager (ADM) ● OK, Cancel, and Other button You can also create containers or frames to work with sets of controls. The following is an example of a cluster of several items: ADM Objects ADM user interfaces are built from ADM user interface objects. These objects include the dialog windows (dialog objects) and the dialog items (item objects) within the windows. FIGURE 6.1 ADM Objects A plug-in or application using ADM has access to standard ADM dialog types (modal and non-modal) and items (buttons and other user interface controls). The user interface can be built using code or by using resource definitions. For instance, standard platform resources 62 Acrobat SDK User’s Guide Modifying the User Interface Using the Adobe Dialog Manager (ADM) 6 can be used to define the layout of the user interface objects. All objects have properties and events that determine their default behavior and allow them to be modified or extended. These can also be set in code or using a resource. ADM has an object-oriented design even though its interfaces are exported as procedural C functions. This is important since many of the properties, behaviors, and callback functions of the various types of ADM user interface objects (dialogs or dialog items) are the same. Understanding the fundamentals of managing one type of ADM user interface object results in understanding how to manipulate other ADM objects as well. Some ADM objects require additional support functions or properties. A window object, for instance, has functions to perform operations such as setting the minimum and maximum window size. ADM edit text items have additional functions to support properties such as justification and numeric precision. Using ADM from Acrobat JavaScript Acrobat JavaScript provides a convenient interface to ADM through which you may implement modal dialogs containing list objects and other controls normally included in graphical user interfaces. The app object’s execDialog method is the Acrobat JavaScript method used to execute ADM dialogs. The method requires a single parameter: an object literal known as a dialog descriptor, which contains properties and method handlers for all the dialog elements. For more information, see the Acrobat JavaScript Scripting Guide. Using the ADM API from a Plug-in Acrobat exposes ADM functionality to plug-in developers. This allows developers to use a single code base to implement dialog behavior on both Macintosh and Windows. NOTE: You do not have to write platform-specific code to support Macintosh and Windows. However, it is still necessary to create platform-specific dialog resources using the appropriate tools on each platform. The Acrobat SDK provides header files to simpify the use of ADM. In addition, several samples and snippets in the Acrobat SDK illustrate the use of ADM. ADM contains a series of suites, each of which implements different functionality. Each suite has its own header file that declares its functions, data types, constants, and so on. For more informaton, see the Adobe Dialog Manager Programmer’s Guide and Reference. Macintosh Issues Carbon is a set of programming interfaces that can be used to build Mac OS X applications that also run on Mac OS 8 and 9 (versions 8.1 and later). It includes a set of header files and a library called CarbonLib. These interfaces include most of the functions commonly used by Macintosh developers. By developing with these interfaces and linking with CarbonLib Acrobat SDK User’s Guide 63 6 Modifying the User Interface Customizing Acrobat Help (instead of previous libraries such as InterfaceLib), a “carbonized” executable is produced which can run under Macintosh OS X (in native mode) as well as Macintosh OS 8/9. The Acrobat 5.0 and above products are carbonized. In order for a plug-in to use ADM, it must also be carbonized. NOTE: Plug-ins which do not use ADM will still work on versions other than Mac OS X even if they are not carbonized. To use ADM with Acrobat on a Macintosh, you must also use a plist. For more information, see the Adobe Dialog Manager Programmer’s Guide and Reference. Customizing Acrobat Help You can manipulate specific parts of the Acrobat help system using a plug-in. There is no equivalent functionality from Acrobat JavaScript or IAC. Controlling the “About” Box and Splash Screen Plug-ins can set values in the preferences file (using the AVAppSetPreference method) to prevent the Acrobat or Adobe Reader “About” box and/or splash screen from appearing before displaying the first document. These changes take effect the next time Acrobat or Adobe Reader is launched. Placing Plug-in Help Files in a Standard Location The Help directory that accompanies Acrobat or Adobe Reader provides a standardized location for your plug-in help files. About Acrobat Plug-Ins is a standard menu item in the Help menu. This menu item contains a submenu. You are encouraged to have your plug-in add a menu item to the submenu to bring up its own “About” box. You cannot use Acrobat JavaScript to set values in the preferences file. You can place a help file either in the Help directory or in a subdirectory of the Help directory. If, for example, your plug-in is localized for Japanese, you might want to place its Japanese help file in a Help_JPN subdirectory. To aid in opening locale-specific help files, the core API provides the AVAppOpenHelpFileWithParams method. There is no equivalent Acrobat JavaScript functionality. For more information, see the Acrobat and PDF LIbrary API Reference. 64 Acrobat SDK User’s Guide Modifying the User Interface Customizing Acrobat Help 6 Customizing the How-To Panel The core API provides several methods to customize the How-To panel from a plug-in. Use AVAppRegisterHowToPanel to register an HTML or XML file to appear in the How-To panel. AVAppAutoShowHowToPanel opens the How-To panel and fills it with the specified panel’s contents, if that panel’s AutoShow attribute is true. You can toggle the AutoShow attribute using AVAppSetHowToPanelAutoShow. There is no equivalent Acrobat JavaScript functionality. For more information, see the Acrobat and PDF LIbrary API Reference. Acrobat SDK User’s Guide 65 6 66 Modifying the User Interface Customizing Acrobat Help Acrobat SDK User’s Guide 7 Using Online Collaboration and Annotations This chapter describes how to use the Acrobat SDK to assist with online collaboration workflows and annotations. This chapter includes the following sections: ● Using Online Collaboration ● Using Annotations in Document Workflows ● Using Stamps in Approval Workflows Using Online Collaboration Acrobat provides a platform for the development of a variety of collaborative review systems to fit various needs. A complete, integrated Acrobat and Adobe PDF online collaboration solution includes the following major elements: ● Adobe PDF documents created from source documents authored in various word processing, page layout, and other applications. ● A Web browser environment, running the Adobe Acrobat plug-in, which allows users to view a PDF document on a network folder or a Web server, add comments to it, and work online with comments from the whole workgroup. ● A central, online comment repository for collecting and storing reviewer comments separate from the associated PDF document being reviewed. ● Optionally, depending on the complexity of the solution required, a user interface to the review and comment workflow, potentially including automated routing and notification, implemented by the solution developer using server-side applications. ● A Review Management feature which allows users to invite new reviewers, send reminders, and go back online after working offline. This online collaboration process allows multiple users to comment on a single document and to view comments from others in real time. Also, they can comment on a document at their own convenience and upload their comments at a later time with the offline option. For all repository types, commenting can only occur when the user opens the PDF file within a Web browser. For more information about setting up online collaboration using Acrobat, see Acrobat Online Collaboration: Setup and Administration. Acrobat SDK User’s Guide 67 7 Using Online Collaboration and Annotations Using Online Collaboration How FDF Files Are Used FDF (Forms Data Format) is an Acrobat-specific format used to store form data and other information from a PDF file. An FDF file that is created during a comment upload contains only the reviewer’s comments and a reference to the reviewed PDF file. Consequently, the FDF file is typically more compact than the corresponding PDF file, and does not need to be stored under the same parent directory or even on the same machine. For more information about FDF, see the PDF Reference. FDF files can also contain JavaScript code that can be used to automatically configure the server preferences. For example, a user can navigate to an FDF file on a server and doubleclick on it. Acrobat then executes the JavaScript code in the file, which automatically configures the server preferences for the user. Online Collaboration and Acrobat JavaScript For online collaboration, Acrobat JavaScript provides several important capabilities: ● Interface to a database — Acrobat JavaScript provides objects to interact with a database via ADBC (Acrobat Database Connectivity). Using JavaScript, you can read values from a database, update or insert new data, and delete information. See “Interacting with OBDC Databases” on page 54 for more information. ● Set the comment repository preference — To use Acrobat’s collaborative review capabilities, you must specify the type of comment repository to be used, as well as its location. Those preferences can be set manually, or with Acrobat JavaScript placed in either the PDF document or its associated FDF file. ● Interface to a web service — Acrobat JavaScript provides objects to interact with a web service via SOAP, which is an XML-based transport protocol used for exchanging information. Because it is the developer's choice as to which operations are performed by a given remote procedure, the Acrobat JavaScript SOAP support enables a more customized collaboration workflow. For more information, see “SOAP and Web Services” on page 74. Extensibility You can extend the Acrobat Online Collaboration feature in several ways: ● You can write JavaScript code to customize your review process and comment handling. ● You can integrate Acrobat’s Online Collaboration feature into a larger document management system. ● You can use Acrobat JavaScript to add additional annotations. ● Through the use of the Acrobat JavaScript SOAP object, you can customize the way that Acrobat handles annotations. For more information, see the Acrobat JavaScript Scripting Guide and the Acrobat JavaScript Scripting Reference. 68 Acrobat SDK User’s Guide Using Online Collaboration and Annotations Using Annotations in Document Workflows 7 Using Annotations in Document Workflows An annotation associates an object such as a note, sound, or movie with a location on a page of a PDF document, or provides a way to interact with the user via the mouse and keyboard. PDF includes a wide variety of standard annotation types, described in detail in the PDF 1.6 Reference. Many of the standard annotation types can be displayed in either the open or the closed state. When closed, they appear on the page in some distinctive form depending on the specific annotation type, such as an icon, a box, or a rubber stamp. When the user activates the annotation by clicking it with the mouse, it exhibits its associated object, such as opening a pop-up window displaying a text note or playing a sound or a movie. You can access and manipulate annotation data from both a plug-in and Acrobat JavaScript. However, you can only create new annotation types using a plug-in or the IAC API; you cannot create new annotation types from JavaScript. Annotations and JavaScript You can set, modify and access annotation information using the Acrobat JavaScript annot object. However, you cannot create a new annotation type from JavaScript. To do this, you must use a plug-in or the IAC API. Using the annot object, you can: Acrobat SDK User’s Guide ● Add note comments ● Make text edits ● Highlight, cross out, or underline text ● Add or delete custom stamps (see “Using Stamps in Approval Workflows” on page 71) ● Add comments in a text box ● Add attachments ● Spell check in comments and forms (see “Using Stamps in Approval Workflows” on page 71) ● Add commenting preferences ● Change colors, icons, and other comment properties 69 7 Using Online Collaboration and Annotations Using Annotations in Document Workflows Annotations and Plug-ins The PDAnnot class is the abstract superclass for all annotations (see the PDF Reference). Acrobat and Adobe Reader have two built-in annotation classes: PDTextAnnot and PDLinkAnnot. Plug-ins can add movie, Widget (form field), and other annotation types. You can define new annotation subtypes by creating new annotation handlers (see “Creating New Annotation Types” on page 70). There are no objects of type PDAnnot, but your plug-in can use PDAnnot methods on any subclass of PDAnnot. The Acrobat SDK provides three useful macros to cast among PDAnnot and its text annotation and link annotation subclasses. These are: ● CastToPDAnnot ● CastToPDTextAnnot ● CastToPDLinkAnnot The PDAnnot methods include: PDAnnotGetRect Gets an annotation’s size and location. PDAnnotGetSubtype Gets an annotation’s subtype. PDAnnotIsValid Tests whether an annotation is valid. See the Acrobat and PDF Library API Reference for more information. Annotations and the IAC API You can use the AcroExch.PDAnnot object in the IAC API to set, modify, and access annotation information from external applications. Creating New Annotation Types PDF supports many standard annotation types. Your plug-in can create new annotation types, including any data they need. For example, a custom annotation type might allow a user to draw (not just type) in an annotation, provide support for multiple fonts or text styles, or support annotations that can only be viewed by specific users. Support for new annotation types can be added by defining and registering an annotation handler. The Acrobat Movie plug-in, for example, uses this to support video annotations. To add a new annotation type, a plug-in must provide a set of callbacks, specify them in the AVAnnotHandler structure, and register them with AVAppRegisterAnnotHandler. For more information, see the Acrobat and PDF Library API Overview. 70 Acrobat SDK User’s Guide Using Online Collaboration and Annotations Using Stamps in Approval Workflows 7 Using Stamps in Approval Workflows Use the Stamp tool to apply a stamp, dynamic stamp, or custom stamp to a PDF document. A stamp can be created from a set of predefined stamps, dynamically created using system and identity information, or customized from PDF files or common graphic formats. Using Acrobat JavaScript or a plug-in, you can apply any predefined or custom stamp. However, you cannot create custom stamps using the Acrobat SDK. There is also no Acrobat SDK support for Hanko and Inkan stamps to support Japanese workflows. These types of stamps can only be created using the Acrobat user interface. Acrobat SDK User’s Guide 71 7 72 Using Online Collaboration and Annotations Using Stamps in Approval Workflows Acrobat SDK User’s Guide 8 XML and the Acrobat SDK The Adobe XML architecture offers enterprises a step-by-step migration from manual, paper-based workflows to streamlined, automated processes that accelerate the flow of business-critical information between employees, customers, suppliers, and constituents. This chapter describes the central role that Acrobat and the Acrobat SDK play in XML-based workflows. This chapter consists of the following sections: ● The Adobe XML Architecture ● Converting PDF Documents to XML Format ● Managing XML-based Information The Adobe XML Architecture The Adobe XML architecture leverages the capabilities of XML and PDF to support a variety of business applications, while offering connectivity to systems through a variety of industry-standard and Adobe technologies. Acrobat SDK User’s Guide 73 8 XML and the Acrobat SDK The Adobe XML Architecture XML Forms The Adobe XML Forms model uses a Document Object Model (DOM) architecture to manage the components that comprise a form. These include the base template, the form itself, and the data contained within the form fields. In addition, all calculations, validations, and formatting are specified and managed within the DOM and XML processes. Static XML forms were supported in Acrobat 6, and dynamic XML forms are now supported in Acrobat 7. Both types are created using Adobe Designer. A static form presents a fixed set of text, graphics, and field areas at all times. Dynamic XML forms are created by dividing a form into a series of subforms and repeating subforms. They support dynamically changing fields that can grow or shrink based on content, variable-size rows and tables, and intelligent data import/export features. For more information, see Chapter 9, “Forms and the Acrobat SDK. XML Templates Acrobat JavaScript defines a Template object that supports interactive form architectures. In this context, a Template is a named page within a PDF document that provides a convenient format to automatically generate and manipulate a large number of form fields. These pages contain visibility settings, and can be used to spawn new pages containing identical sets of form controls to those defined within the template. For more information, see “XML Form Templates” on page 86. Extensible Metadata Platform (XMP) Adobe’s Extensible Metadata Platform (XMP) is a labeling technology that allows you to embed metadata into the file itself. With XMP, desktop applications and back-end publishing systems use a common method for capturing, sharing, and leveraging metadata. For more information, see Chapter 12, “Working with Metadata. SOAP and Web Services Most current models of web services use the Extensible Markup Language (XML), which facilitates interoperability by permitting the exchange of information between applications and platforms in a text-based manner. The Simple Object Access Protocol (SOAP) is an XMLbased messaging protocol used as a medium for information and instruction exchange between web services. Information sent using the SOAP standard is placed in a file called a SOAP envelope. The Web Services Description Language (WSDL) is an XML-based standard for describing web services and their capabilities. Adobe Acrobat’s support for these standards makes it possible for PDF documents to locate services, understand their capabilities, and interact with them. In order to guarantee interoperability between various platforms and applications, it is necessary that exchanged information adhere to a standardized format for data types. To 74 Acrobat SDK User’s Guide XML and the Acrobat SDK The Adobe XML Architecture 8 address this need, the XML Schema Definition Language (XSD) provides a standard set of definitions for the various data types that can be exchanged in SOAP envelopes. Acrobat 7 provides support for the SOAP 1.1 and 1.2 standards to enable PDF forms to communicate with web services. This makes it possible to include both SOAP header and body information, send binary data more efficiently, use document/literal encoding, and facilitate authenticated or encrypted communications. In addition, it also provides the ability to locate network services using DNS Service Discovery. All of this enables the integration of PDF files into existing workflows by binding Adobe XML forms to schemas, databases, and web services. These workflows include the ability to share comments remotely or invoke web services through form field actions. For more information, see the Acrobat JavaScript Scripting Guide. DNS Service Discovery If the exact URL for a given service is not known, but it is available locally because it has been published using DNS Service Discovery (DNS-SD), Acrobat JavaScript provides methods to locate the service on the network and bind to it for communications. For more information, see the Acrobat JavaScript Scripting Guide. Workflow Applications A SOAP-based collaboration server can be used to share comments remotely via a Webbased comment repository. Through the DNS Service Discovery support, it is possible to enable dynamic discovery of collaboration servers, initiation workflows, and RSS feeds that can provide customized user interfaces, via XML, directly inside of Acrobat 7. In addition, it is possible to deploy Web-based JavaScripts that always maintain the most updated information and processes, and to connect to those scripts via form field actions that invoke web services. For more information, see the Acrobat JavaScript Scripting Guide and Acrobat Online Collaboration: Setup and Administration. Acrobat SDK User’s Guide 75 8 XML and the Acrobat SDK Converting PDF Documents to XML Format Co nve r t i n g P D F D o c u m e n t s t o X M L For m at Because XML representation is the basis for the exchange of information with Web Services and enterprise infrastructures, it is often useful to convert your PDF documents into XML format. Converting to XML Format Using Acrobat JavaScript It is a straightforward process to do this using the doc object’s saveAs method, which not only performs the conversion to XML, but also to a number of other formats. To convert your PDF document to a given format, you must determine the deviceindependent path to which you will save your file, and the conversion ID used to save in the desired format. For XML, the conversion ID is ”com.adobe.acrobat.xml-1-00”. For more information, see the Acrobat JavaScript Scripting Guide and the Acrobat JavaScript Scripting Reference. The SaveAsXML Plug-in SaveAsXML is a plug-in for Acrobat which extends the “Save as type” choices in the Save As dialog box to allow a Tagged PDF document to be saved as a number of XML, HTML, or similar text-based formats. Mapping Tables are used to control the conversion process for the SaveAsXML feature. The Mapping Tables are a script of hierarchically-organized directives written in a custom language defined in XML syntax. This allows developers to create custom Mapping Tables for formats other than those provided in this package. Overview of the SaveAsXML Process When the SaveAsXML plug-in registers itself with Acrobat, it inspects the set of XML files in the MappingTables folder to determine the number of conversion services that are available. The MappingTables folder must be found in the same folder as the SaveAsXML.api file. Files in this folder are the only ones that are inspected as potential conversion services supported by the plug-in. This folder may not contain any files with the .xml extension that are not Mapping Tables. If the registration process finds the Root element and its menu-name attribute, it adds the menu name to the list of file format choices available in the Save As dialog box. (The menu name must be unique in order to avoid confusion by similarly identified entries in the Save As dialog box’s file formats. ) For more complete examples of the usage of these directives, see the Mapping Tables distributed with SaveAsXML. Every directive that is currently supported has been used in one or more of these tables. 76 Acrobat SDK User’s Guide XML and the Acrobat SDK Managing XML-based Information 8 For more information, including a sample Mapping Table that demonstrates the basic operation of the SaveAsXML processing, see Using the SaveAsXML Plug-in. Managing XML-based Information Acrobat JavaScript provides support for XML-based information generated within workflows by providing an XML object, which represents an XML document tree that can be manipulated via the XFA Data DOM. (For example, it is possible to apply an XSL transformation to a node and its children.) For more information, see the Acrobat JavaScript Scripting Guide. Acrobat SDK User’s Guide 77 8 78 XML and the Acrobat SDK Managing XML-based Information Acrobat SDK User’s Guide 9 Forms and the Acrobat SDK You can use the Acrobat SDK to extend the functionality of Acrobat Forms and XML forms created in Adobe Designer. This chapter presents basic concepts about forms and discusses how you can use the technologies of the Acrobat SDK to manipulate forms. This chapter covers the following topics: ● Types of Forms ● Guidelines for Creating a New Form ● Acrobat Forms and the Acrobat SDK ● XML Forms and the Acrobat SDK ● Automatically Populating Forms ● Creating Web-Ready Forms ● Punchcard/Barcode Form Fields ● Collecting Data from Completed Forms ● XML Form Templates Types of Forms In previous versions of Acrobat, PDF forms were generally Acrobat forms. You could create and manipulate Acrobat forms and retrieve form data using Acrobat JavaScript or, using the Forms API, from plug-ins and external applications. In Acrobat 7.0, there is increased support for XML Forms, which are based on the XML Forms Architecture (XFA) specification. It is strongly recommended that new forms development be done using XML forms rather than Acrobat forms. XML Forms A form is derived from a form design that you create using Adobe LiveCycle Designer. The form design specifies a set of layout, presentation rules, and data capture rules, including calculating values based on user input. The rules are applied whenever a form is filled with data. How the form is filled with data depends on the type of form. For information about creating forms, see the Adobe LiveCycle Designer documentation. Using Adobe LiveCycle Designer, you can create the following types of forms: ● Acrobat SDK User’s Guide Interactive - An interactive form design produces a form that can be filled in online. Users can open the form in a browser or Adobe Reader and enter information into the form’s fields. An interactive form can include buttons or commands for common tasks, 79 9 Forms and the Acrobat SDK Types of Forms such as saving data to a file or printing. It can also include selection lists, calculations, and validations. ● Static - A static form design presents a fixed layout of text, graphics, and field areas. The resulting form retains its exact layout regardless of the amount of data merged into it. A static form design can also be designed to have interactive capabilities. ● Dynamic - A dynamic form design produces a form that has the ability to grow or shrink according to the amount of data being merged into it. A dynamic form design can also be designed to have interactive capabilities. XML forms can be understood in terms of two major components: templates and content. The templates define presentation, calculation, and interaction rules, and are based on XML. Content is the static or dynamic data, stored in the document, that is bound to the templates. For dynamic XML forms, the content is defined after binding to a template. This means that the following are possible: ● Fields can be moved or resized. ● Fields can automatically grow or shrink according to the amount of text added or removed. ● As a field grows, it can span multiple pages. ● Repeating subforms can be spawned as needed, and page contents will shift accordingly. ● Elements on the page are shown or hidden as needed. To take advantage of the rich forms functionality offered by the XFA plug-in, use Adobe Designer to create or edit the templates and save your forms in the XML Data Package format (XDP) or as a PDF document. Use XDP if the data is processed by server applications, and PDF if the data is processed by Acrobat. Acrobat Forms With Acrobat forms, you can author form fields and retrieve data from those form fields. For Adobe Reader, the Forms plug-in does not allow form authoring, but allows users to fill in data and print Acrobat forms. The Adobe Reader Forms plug-in also does not allow users to save data to the local hard disk. Both Acrobat and Adobe Reader allow Web designers to send data from the form back to a Web server. 80 Acrobat SDK User’s Guide Forms and the Acrobat SDK Forms Workflows 9 Fo r m s Wo r k f l ows There are three basic workflows for forms: Fill and Print Forms are filled in on the screen and then printed out. They are then returned by traditional methods such as fax or postal mail. Email Submit Forms contain a Submit button that enables the sending of an email message with an attached data file that contains only the form data. See “Collecting Data from Completed Forms” on page 85. Online Submit Forms submit form data to a web server much like forms on the Internet. The user must be online to submit your information. For more information, see “Collecting Data from Completed Forms” on page 85. Elements of Acrobat Forms Acrobat offers several form field types for building and creating forms: ● Button ● Check box ● Combo box ● Digital signature field ● Document message bar ● List box ● Radio button ● Text field To customize the utility and behavior of the form, you can define Acrobat JavaScript methods to respond to events. For more information about form field types, see the Acrobat JavaScript Scripting Guide. Acrobat SDK User’s Guide 81 9 Forms and the Acrobat SDK Guidelines for Creating a New Form G u i d e l i n e s fo r C re at i n g a N ew Fo r m Creating a new form, whether using Adobe LiveCycle Designer or programmatically using Acrobat JavaScript, requires you to consider specific issues. For guidelines, see the Acrobat JavaScript Scripting Guide. Your form design may have dynamically changing features such as the current date, as well as convenience options such as automatic generation of email messages. It may even have a dynamically changing appearance and layout which is responsive to user interactions. Acrobat Forms and the Acrobat SDK For Acrobat forms, there is a rich set of APIs that allows you to create and manipulate form fields, and to retrieve form data using Acrobat JavaScript, a plug-in or an external application. Though you can manipulate form fields and form data from a plug-in, it is much quicker to develop Acrobat forms using Acrobat JavaScript. Using the Acrobat SDK, you can: ● Create Adobe PDF forms from scratch or from a template ● Add or remove form fields ● Set form field properties ● Make forms web-ready (see “XML Form Templates” on page 86) ● Extract and export form data (see “Collecting Data from Completed Forms” on page 85) ● Make forms accessible (see Chapter 14, “Accessibility”) Acrobat JavaScript for Acrobat Forms You can extend the functionality of Acrobat forms through the application of Acrobat JavaScript. Acrobat JavaScript can be integrated into your forms to enhance their interactive capabilities. You can extend the capability of your forms by using Acrobat JavaScript to: ● Automate formatting, calculations, and data validation ● Develop customized actions assigned to user events ● Interact with databases and Web services Acrobat JavaScript provides a field object, which has properties that define the field’s type, appearance and data values. 82 Acrobat SDK User’s Guide Forms and the Acrobat SDK Acrobat Forms and the Acrobat SDK 9 The Forms API The Forms plug-in for Acrobat allows plug-in developers to author Acrobat form fields. For Adobe Reader, the Forms plug-in does not allow form authoring, but allows users to fill in data and print Acrobat forms. In general, the Adobe Reader Forms plug-in also does not allow users to save data to the local hard disk. However, if the PDF document has additional usage rights, then it may be able to save the document or perform other functions. For more information, see Chapter 10, “Rights-enabled PDF Documents”. Both Acrobat and Adobe Reader allow Web designers to send data from the form back to a Web server. The Forms API uses the PDField object, which is an opaque object representing a field in an Acrobat form. A PDF document that contains an Acrobat form has an AcroForm entry in the document catalog dictionary, which contains an array of references to each of the root fields in the document. The three most important properties of a field are its type, name, and value. Other properties specify the appearance of a field. Fields can be organized into a hierarchy, and other field properties associate it with its parent and children. OLE Automation for Acrobat Forms The Acrobat Forms plug-in has been enhanced to work as an Automation server in the Win32 environment. There is no equivalent support in a Mac environment. OLE Automation is particularly useful for creating custom forms from an external application. Methods and properties are provided that allow you to programmatically associate actions and Acrobat JavaScript scripts with form fields. You can also add document-level JavaScript scripts. A very important and useful feature of OLE Automation of Acrobat forms is the ExecuteThisJavaScript method of the AFormApp object. The JavaScript string passed to this method is immediately executed in the context of the current form. You can also use the ExecuteThisJavaScript method to execute JavaScript scripts from nonforms PDF documents. Since the automation capabilities have been added to a plug-in, rather than an executable that can be directly launched, there are several steps you must perform to be able to access them from an Automation controller. See the Acrobat and PDF Library API Reference for complete details. Acrobat SDK User’s Guide 83 9 Forms and the Acrobat SDK XML Forms and the Acrobat SDK XML Fo rms and the Acro bat SDK For XML forms, there are additional properties and methods available only from JavaScript that allow you to access XFA-specific objects. You cannot access these objects from a plugin or external application. In particular, Acrobat JavaScript provides access to the XFA appModel container, which provides properties and methods to query and manipulate the XML field hierarchy. For more information on XML Forms, see the Acrobat JavaScript Scripting Guide or the Acrobat JavaScript Scripting Reference. Automatically Populating Forms You can populate forms from a database or using a standards-based network protocol such as SOAP. For more information, see “Interacting with OBDC Databases” on page 54 and “SOAP and Web Services” on page 74. XML Forms are particularly well suited for populating forms from an external database. Creating Web-Ready Forms Both Acrobat and XML forms can be used in workflows that require the exchange of information over the Web. You can create forms that run in Web browsers, and can submit and retrieve information between the client and server by making a Submit button available in the form. The button can perform tasks similar to those of HTML scripting macros. For more information, see the Acrobat JavaScript Scripting Guide. Punchcard/Barcode Form Fields With Adobe LiveCycle Designer, you can add interactive barcode form fields for various identification purposes, such as product inventory. The bars and characters of interactive barcode fields change to encrypt the data that is entered into other associated form fields. Users filling out a form with a barcode cannot manually enter data into the barcode form field. You cannot read or modify barcode form fields using the Acrobat SDK. 84 Acrobat SDK User’s Guide Forms and the Acrobat SDK Collecting Data from Completed Forms 9 Collecting Data from Completed Forms XML and XDP Formats You can save your form data in pure XML format, or, to take advantage of the rich functionality offered by the XFA plug-in, you can save your forms in the XML Data Package format (XDP). The XDP format allow you to package units of PDF content within a surrounding XML container, and is thus considered an XML-based companion to PDF. The advantage of this format is that it provides XML parsers direct access to the XML form-data subassembly of the PDF document. For more information, see the Acrobat JavaScript Scripting Guide. FDF and XFDF Formats Using Acrobat JavaScript, form data can be saved in either FDF or XFDF format in a separate file which can subsequently be used in the next step within your workflow. This approach minimizes the file size to just the amount needed to store your data, thus decreasing network traffic and processing time for the next step in the workflow. For more information, see the Acrobat JavaScript Scripting Guide. Saving Data to a Microsoft Excel Spreadsheet Once you’ve collected PDF form data in FDF or XML format from multiple users, you can organize the form data into a comma-delimited spreadsheet file (CSV). After exporting the form data to a CSV file, you can work with the data in a spreadsheet application, such as Microsoft Excel. You can also save form data as a tab-delimited file. Tab-delimited files can also be imported using doc object methods. Submitting Data from Attachments Data from various attachments can be imported into an XML or XFA-based document, and submitted to a server for processing. Exporting Data as Images Since images are their own fields, they can be exported in any of the standard image types using the doc object’s exportDataObject method. If the image is to be used again, it can be imported as an icon in any of the standard formats: BMP, GIF, JPEG, PCX, PNG, or TIFF. Acrobat SDK User’s Guide 85 9 Forms and the Acrobat SDK XML Form Templates XML Form Templates Acrobat JavaScript defines a Template object that supports interactive form architectures. In this context, a Template is a named page within a PDF document that provides a convenient format to automatically generate and manipulate a large number of form fields. These pages contain visibility settings, and can be used to spawn new pages containing identical sets of form controls to those defined within the template. For more information, see the Acrobat JavaScript Scripting Guide. 86 Acrobat SDK User’s Guide 10 Rights-enabled PDF Documents When creating a PDF document, it is possible to assign it special rights that enable users of Adobe Reader to fill in forms, participate in online reviews, and attach files. Adobe LiveCycle Reader Extensions may be used to activate additional functionality within Adobe Reader for a particular document, thereby enabling the user to save, fill in, annotate, sign, certify, authenticate, and submit the document. This streamlines collaboration for document reviews and the automating of data capture with electronic forms. Users of Acrobat Professional can also Reader-enable collaboration. This chapter consists of the following sections: ● Additional Usage Rights ● Differences between Usage Rights and Reader Enabling ● Creating Rights-enabled Documents ● Accessing Additional Usage Rights ● Applying and Validating Additional Usage Rights ● Effects of Reader Extensions on Acrobat Standard and Acrobat Professional ● Applying and Validating Additional Usage Rights Additional Usage Rights Additional usage rights allow an Adobe Reader user to perform specific operations on a rights-enabled PDF document. The following additional usage rights can be enabled for a PDF document (see “Creating Rights-enabled Documents” on page 89): Acrobat SDK User’s Guide Form fill-in and document full-save Form import an export Form add and delete Form submit standalone Form spawn template Signature modify Annot create, delete, modify, and copy Annot import and export 87 10 Rights-enabled PDF Documents Differences between Usage Rights and Reader Enabling Form barcode plain text Annot online Form online Embedded File create, delete, modify, copy, and import Permissions enabled by usage rights may be disallowed if: ● the document is encrypted and the security handler is set to disallow any of these operations, or ● the document contains DocMDP settings that do not allow these operations. For more information, see the Acrobat JavaScript Scripting Guide. Differences between Usage Rights and Reader Enabling You may not develop an Adobe Reader plug-in without approval from Adobe. You must use Adobe’s web-based application to describe your plug-in and submit information to Adobe. Adobe reviews it and either approves or rejects the application. The application and the Adobe Reader Integration Key Licensing Agreement can only be submitted as a web form. Information can be found at: http://partners.adobe.com/asn Note that there is a fee to get the enabling key, and that your plug-in can only use a restricted set of APIs. As with all plug-ins, reader-enabled plug-ins must be installed on each user’s machine (either through an installer or by the user), and the plug-in is then available to all PDF documents used on that computer. PDF documents with additional usage rights contain rights-enabling information within each individual document, so no additional installation is needed. The APIs available to both plug-in and Acrobat JavaScript developers depends on which usage rights are set for each individual document; you cannot make APIs available to all documents as with Reader-enabled plug-ins. Using APIs available with additional usage rights requires no prior approval by Adobe. 88 Acrobat SDK User’s Guide Rights-enabled PDF Documents Creating Rights-enabled Documents 10 C re at i n g R i g h t s - en a b l e d D o c u m e nt s PDF documents can be “rights-enabled” using Adobe LiveCycle Reader Extensions . Developers cannot programmatically rights-enable a PDF file. During the design process, a PDF document may be created through the usage of Adobe LiveCycle Designer, Adobe LiveCycle Forms, or Adobe Document Server. The document creator can assign appropriate usage rights using Adobe LiveCycle Reader Extensions. The PDF document is made available on the Web, and users can complete the form on the web site, or save it locally and subsequently complete and annotate it, digitally sign it, add attachments, and return it. In effect, Adobe LiveCycle Reader Extensions enables additional functionality within Adobe Reader for a given document. After the user has finished working with the document, those functions are disabled until the user receives another rights-enabled PDF file. One major advantage of Adobe LiveCycle Reader Extensions is that it supports data automation through XML-based representation and transfer via SOAP, ensuring seamless integration with business logic and advanced data transport capabilities available within enterprise applications. For more information, see the Acrobat JavaScript Scripting Guide. Accessing Additional Usage Rights When a rights-enabled PDF is opened, Adobe Reader changes the user interface and enables additional features. Previously unavailable APIs, for both JavaScript and plug-ins, are then available to developers. To check whether a PDF document has rights enabled, plug-in developers can use the PDDocPermRequest methods. JavaScript developers cannot programmatically access or assign additional usage rights with a PDF file. For this reason, it is advised that try-catch blocks be used around methods which might violate the constraints related to the document’s rights. Acrobat SDK User’s Guide 89 10 Rights-enabled PDF Documents Applying and Validating Additional Usage Rights Ap p l y i n g a n d Va l i d at i n g Ad d i t i o n a l Us a g e R ig h t s The doc object provides two methods that rely upon its security model to apply and validate usage rights within a document: ● appRightsSign: Creates and embeds permission information for additional features in Adobe Reader, including a signature used to validate the permissions granted by Adobe Systems. ● appRightsValidate: Returns the validity of the application rights signature set by appRightsSign. The usage rights supported are listed in “Additional Usage Rights” on page 87. For more information, see the Acrobat JavaScript Scripting Guide and the Acrobat JavaScript Scripting Reference. Effects of Reader Extensions on Acrobat Standard and Acrobat Professional Certain editing features normally available within Acrobat Standard and Acrobat Professional are disabled for documents having Reader Extensions. This ensures that the user cannot inadvertently invalidate the additional usage rights in a document under managed review before passing the document on to an Adobe Reader user for further commenting. For complete details, see the Acrobat JavaScript Scripting Guide and the Acrobat SDK Plug-in Guide. Enabling Collaboration By using Really Simple Syndication (RSS), collaboration servers can provide customized XML-based user interfaces directly inside of Acrobat itself. This provides a more dynamic and personalized tool, as well as enabling JavaScript developers to extend collaboration, including full user interfaces. In addition, you can now migrate comments from one document to another, carry comments across multiple versions of a document, and anchor comments to content so that the annotations remain in the right place even if the content changes. This makes it possible to automate discovery of collaboration servers, initiation workflows, and RSS feeds that may be used to populate content inside Adobe Reader. Note that users of Adobe Acrobat Professional can enable collaboration; this enables them to invite users of Adobe Reader to participate in the review process. For more information, see the Acrobat JavaScript Scripting Guide and the Acrobat JavaScript Scripting Reference. 90 Acrobat SDK User’s Guide 11 Providing Document Security Acrobat security is similar to home security. Just as you lock your doors to prevent someone from entering your house without permission, you use Acrobat security features to lock a PDF document. For example, you can use passwords to restrict users from opening, printing, or editing PDF documents. You can use digital signatures to certify PDF documents, and you can encrypt PDF documents so that only an approved list of users can open them. To save security settings for later use, you can create a security policy that stores security settings. NOTE: This chapter focuses on how to use the Acrobat 7.0.5 SDK for security. For information on how to view or modify security using Acrobat 7.0 Professional or Acrobat 7.0 Standard, see the online help for each product. This chapter consists of the following sections: ● Acrobat Security Overview ● Encryption and Decryption ● Digital IDs and Certificates ● Security Handlers ● Digitally Signing Adobe PDF Documents ● Security Policies ● Using eEnvelopes to Send Secure Files ● Document Rights Acrobat Security Overview You can use the following methods to enhance document security: Acrobat SDK User’s Guide Password security Add passwords and set security options to restrict opening, editing, and printing PDF documents. Acrobat supports 128bit RC4 and 128-bit AES (Advanced Encryption Standard) security methods. You can choose which method to use when securing documents. Certification security Encrypt a document so that only a specified set of users have access to it. See “Encryption and Decryption” on page 92. 91 11 Providing Document Security Encryption and Decryption Adobe Policy Server Apply server-based security policies to PDF documents. Server-based security policies are especially useful if you want others to have access to PDF documents only for a limited time. See “Security Policies” on page 97. Document certification When an author digital signature is added, editing changes are restricted and detected. See “Certifying PDF Documents” on page 97. Encryption and Decryption Encryption is controlled by an encryption dictionary in the PDF file. Acrobat uses RC4 (a proprietary algorithm provided by RSA Data Security, Inc.) to encrypt document data, and a standard (proprietary) method to encrypt, decrypt, and verify user passwords to determine whether or not a user is authorized to open a document. See Section 3.5, “Encryption,” in the PDF Reference for more information on the encryption used in PDF files. Each stream or string object in a PDF file is individually encrypted. This level of encryption improves performance because objects can be individually decrypted as needed rather than decrypting an entire file. All objects, except for the encryption dictionary (which contains the security handler’s private data), are encrypted using the RC4 algorithm that Adobe licenses from RSA Data Security, Inc. Plug-ins may not substitute another encryption scheme for RC4. For digital signatures and document encryption, Acrobat supports public-key cryptography. Public-key cryptography uses two keys: a public key, which is stored inside a certificate that can be shared with other users, and a private key, called a digital ID, which is not shared with others. The public key certificate is used to encrypt (scramble) documents or to verify digital signatures, and the digital ID is used to decrypt (unscramble) encrypted documents or to create digital signatures. Digital IDs and Certificates A digital ID lets you create a digital signature or decrypt an encrypted PDF document. A digital ID is sometimes referred to as a private key, a credential, or a profile. When you sign or decrypt a document, you select which digital ID to use. A digital ID is usually password-protected and can be stored on your computer as a PKCS#12 file, on a smart card, or in the Windows Credential Store. You can get a digital ID from a third-party provider, or you can create a self-signed digital ID and share your signature information with others using a public key certificate. A certificate is a confirmation of your digital ID and contains information used to protect data. When a digital signature is applied, a unique fingerprint with encrypted numbers is embedded in the document. The recipient needs the signer’s certificate to validate that the 92 Acrobat SDK User’s Guide Providing Document Security Digital IDs and Certificates 11 digital signature and certificate match the signer’s digital ID. Adobe Acrobat includes one handler that has access to trusted certificates in a number of different locations. The locations include Microsoft’s cryptographic store used for Windows security, PKCS#12 encryption, which is a standard encryption format, and PKCS#11 encryption, which is used on smart cards. Obtaining a Digital ID from a Third Party In general, digital IDs are issued by a third party for use in any official capacity. Third-party providers, such as Entrust, include advanced security features. The provider of digital ID certificates is sometimes called a certificate authority or a signature handler. Third-party providers verify your identity, issue the private key, protect the public key, and maintain system integrity. You may want to obtain more than one digital ID if you sign documents in different roles or with different certification methods. See http://partners.adobe.com for information on using providers with advanced security features. Digital IDs and the Acrobat SDK You can work with digital IDs and certificates from Acrobat JavaScript and from a plug-in using the PubSec API (see “Security Handlers and Plug-ins” on page 94). Using the Acrobat SDK, you can: Acrobat SDK User’s Guide ● Create a digital ID (Default Certificate Security). ● Save a certificate file to disk. ● Use an existing certificate to create a digital ID. ● Manage digital IDs (Windows Certificate Security). ● Share digital ID certificates. ● Build a list of trusted identities. 93 11 Providing Document Security Security Handlers S ec u r i t y H a n d l e r s The code that performs user authorization and sets permissions is known as a security handler. The core API has one built-in security handler. This security handler supports two passwords: ● A user password that allows a user to open and read a protected document with whatever permissions the owner chooses ● An owner password that allows a document’s owner to change the permissions granted to users You can either use the built-in security handler, or write a plug-in to create your own security handlers to perform user authorization in other ways (for example, by the presence of a specific hardware key or file, or by reading a magnetic card reader). You cannot create a custom security handler using Acrobat JavaScript. A custom security handler can use Acrobat or Adobe Reader’s built-in dialog boxes for entering passwords and for changing permissions. Security handlers are responsible for: ● Setting permissions on a file. ● Authorizing access to a file. ● Setting up a file’s encryption and decryption keys. ● Maintaining the encryption dictionary of the PDF file containing the document. Security handlers are used when: ● A document is opened — the security handler must determine whether a user is authorized to open the file and set up the decryption key that is used to decrypt the PDF file. ● A document is saved — the security handler must set up the encryption key and write any necessary security-related information into the PDF file’s encryption dictionary. ● A user tries to change a document’s security settings — the security handler must determine whether the user is permitted to perform the operation. PPKLite and PPKMS Security Handlers In Acrobat 6, the built-in PPKLite signature handler only supported a single certificate chain for validation; broader support required the Microsofts Crypto API (MSCAPI) support of the PPKMS handler. In Acrobat 7, PPKLite supports RFC3280-based certificate chains natively. MSCAPI support has been rolled into PPKLite and is no longer a separate handler. Security Handlers and Plug-ins The PubSec layer, introduced in Acrobat 6.0, is an interface for Acrobat public-key security handlers. PubSec forms a high-level interface to the digital signature facility; the PubSec 94 Acrobat SDK User’s Guide Providing Document Security Security Handlers 11 code uses the DigSig API for digital signature operations, but provides many additional benefits. Developers are encouraged to use the PubSec HFT rather then DigSig HFT. PubSec provides functions to: ● Count and close encrypted documents. ● Validate a specific signature field. ● Access and create digests for data buffers. ● Import and export certificate data, and manage the certificates in the Acrobat Address Book (AAB). ● Manage signature appearances (DSAP files). ● Register and unregister handlers. Handlers can register as PubSec handlers to provide the following cryptographic services: – Perform private-key signing and signature validation – Act as a cryptographic source for decrypting using private keys – Act as a directory source for certificate-based identity authentication Handlers can call back into the PubSec HFT for various services. Most calls to PubSec pass an opaque state object called a PSEngine. You specify a default engine upon registering the handler, and the default engine can make use of the security user interface dialog boxes provided by PubSec and DigSig. For more information, see the Acrobat and PDF Library API Overview and the Acrobat and PDF Library API Reference. Security Handlers and Acrobat JavaScript SecurityHandler objects are used to access security handler capabilities such as signatures, encryption and directories. Different security handlers will have different properties and methods. Individual SecurityHandler objects may or may not implement these properties and methods. The JavaScript interface for Adobe.PPKLite signatures was introduced in Acrobat 5.0; additions to the JavaScript interface were introduced in Acrobat 6.0. Prior to Acrobat 6.0 there was no support in Acrobat to enable JavaScript in third party security handlers. Note that not all security handlers are JavaScript enabled, and not all JavaScript enabled handlers are enabled for all security operations. Third party public key security handlers may support JavaScript, but only if they use the new PubSec programming interface that was introduced in Acrobat 6.0. JavaScript enabled handlers provided by Adobe include: Acrobat SDK User’s Guide ● The Adobe.PPKLite security handler, supporting signature and encryption, on Windows, provides directory access through the Microsoft Active Directory Scripting Interface (ADSI). ● The Adobe.AAB security handler provides a local address book and support for directory operations. 95 11 Providing Document Security Digitally Signing Adobe PDF Documents Note that the Standard security handler, used for password encryption of documents, is not JavaScript enabled in general. In Acrobat 7.0, encryption using Standard security is possible using predefined policies. Also, in Acrobat 7.0, the Adobe.APS handler can be used for encryption via the encryptUsingPolicy method. This handler also makes a directory available via the directory services, but as no certificates are returned from this directory, it is of limited general use. For more information, see the Acrobat JavaScript Scripting Reference. Digitally Signing Adobe PDF Documents A digital signature, like a conventional handwritten signature, identifies the person signing a document. Unlike traditional signatures on paper, however, each digital signature stores information about the person signing a document. Signatures help prevent unwanted changes to a PDF document. For example, an author may not want a PDF document with company letterhead to be changed after it is signed. The first signature in a document is called the author signature. When you add the first signature to a document, you have the option of certifying the document. Certifying a document lets you attest to its contents and specify the types of changes allowed for the document to remain certified. Changes to the document are detected in the Signatures tab. Subsequent signatures to the document are called ordinary signatures. To sign a document, you must select a digital ID, which contains the signature information that you can share with other users in a certificate. You can create a self-signed digital ID, or you can obtain a digital ID from a third-party provider. Using certificates, other users can validate your signatures, and you should validate the signatures of others. Signing Adobe PDF Documents An author of a PDF document can simply add a signature to indicate approval. Alternatively, a PDF document can be signed more than once and by more than one person. For example, the author can save a PDF document containing form fields as a certified document, allowing only form fields to be filled in. When another user opens the PDF document, a message indicates whether the certification is still valid. This user can then fill out the form and sign the document when finished. To add a signature to a PDF document using Acrobat JavaScript: ● Create a signature field ● Choose a security handler ● Invoke the field’s signatureSign method From a plug-in, you can sign a PDF document using the PubSec and DigSig APIs. 96 Acrobat SDK User’s Guide Providing Document Security Security Policies 11 Certifying PDF Documents You can apply permissions to a PDF document, but some applications may not respect these permissions. In these cases, it is desirable to be able to detect unauthorized changes to the document. The author signature for a document makes Modification, Detection, and Prevention (MDP) possible. When this type of signature is applied, it is possible to certify the document, which means that you specify information about its contents and the types of changes that are allowed in order for the document to remain certified. You certify the document by applying an author signature to it. If necessary, you can create an author signature field using Acrobat JavaScript and then sign it as described in “Signing Adobe PDF Documents” on page 96. Validating Signatures When you validate a signature, you verify the signer’s identity and assess any changes made after the document was signed. For an identity to be valid, the signer’s certificate, or one of its parent certificates that was used to issue the signer’s certificate, must be in your list of trusted identities, and it must not have expired or been revoked. Using the Acrobat SDK, you can validate a signature from a plug-in, from Acrobat JavaScript, or from and external application using IAC. Security Policies In Adobe Acrobat 7.0, you can save security settings as policies that you can reuse. Security policies include the type of security encryption, the permission settings, and information about who can open the document or change security settings. There are two kinds of security policies: Acrobat SDK User’s Guide ● A user policy is developed and applied by an individual user. If you apply the same security settings to various documents, you can save time by creating a user policy and then reapplying the user policy to documents without having to specify the security settings each time. User policies for passwords and public key certificates are stored on your local computer. If you have access to Adobe Policy Server, you can also create a user policy that is stored on a policy server and is available only to the person who creates it. ● An organizational policy is created by an Adobe LiveCycle Policy Server administrator and is stored on a policy server to be shared by a group of users. Adobe Policy Server controls access to PDF documents and auditing events as defined by the security policy. You can use Adobe LiveCycle Policy Server only if your company has purchased rights and made it available to you. 97 11 Providing Document Security Using eEnvelopes to Send Secure Files Using Adobe Policy Server Adobe Policy Server is a web server-based security system that provides dynamic control over PDF documents. Adobe Policy Server can be configured to run with LDAP, Adobe Document Server, and other enterprise systems. Policies provided by Adobe Policy Server are stored on the server and can be refreshed from the server. You must log into Adobe Policy Server to use these server policies. Security policies are stored on a policy server, but the PDF documents are not. However, users may be required to connect to the policy server so that they can open or continue to use PDF documents to which a security policy has been applied. For information on configuring Adobe Policy Server, see the help system that appears when you start Adobe Policy Server Web Console in your browser. Encrypting PDF Documents Using Security Policies Acrobat JavaScript provides objects for working with security policies. There are no C APIs for manipulating security policies from a plug-in. For more information, see the Acrobat JavaScript Scripting Guide. Using eEnvelopes to Send Secure Files When adding security to a document, you can choose to encrypt only the attachments. The PDF document in which documents are embedded is called an eEnvelope. Encrypting only the document attachments is especially useful for sending secure file attachments without modifying the file attachments themselves. The eEnvelope is not otherwise encrypted or permission-restricted. When other users open the eEnvelope, they can extract the file attachments and save them to disk. The saved files are identical to the original file attachments and are no longer encrypted when saved. To create an eEnvelope using the Acrobat SDK, invoke the Acrobat JavaScript doc object’s addRecipientListCryptFilter method, which is used to encrypt data objects. For more information, see the Acrobat JavaScript Scripting Guide. 98 Acrobat SDK User’s Guide Providing Document Security Document Rights 11 Document R i ghts By including additional usage rights in a PDF document, you can invite Adobe Reader 7.0 users to participate in an email-based document review. Additional usage rights, such as commenting rights, are document-specific and can be added to any PDF document except forms when you initiate an email-based or browser-based review. For more information, see Chapter 10, “Rights-enabled PDF Documents. Acrobat SDK User’s Guide 99 11 100 Providing Document Security Document Rights Acrobat SDK User’s Guide 12 Working with Metadata A PDF document can include general information such as the document’s title, author, and creation and modification dates. Such global information about the document itself (as opposed to its content or structure) is called metadata, and is intended to assist in cataloguing and searching for documents in external databases. A PDF document can also contain object data. Object data is information associated with a particular object in a PDF document. This chapter includes the following sections: ● Types of Metadata ● Extensible Metadata Platform (XMP) ● The Adobe XMP Toolkit ● Searching Metadata ● Object Data Types of Metadata Metadata can be stored in a PDF document in either of the following ways: ● In a document information dictionary associated with the document ● In a metadata stream associated with the document or a component of the document Metadata properties and values are represented in the World Wide Web Consortium’s Resource Definition Format (RDF), which is a standard metadata format based on XML. The set of standard metadata items is organized into schemas, each of which represents a set of properties from a particular application or industry standard. The schemas, as well as the physical representation, are defined by Adobe’s Extensible Metadata Platform (XMP) (see “Extensible Metadata Platform (XMP)” on page 102). Acrobat SDK User’s Guide 101 12 Working with Metadata Extensible Metadata Platform (XMP) Document Information Dictionary The optional Info entry in the trailer of a PDF file can hold a document information dictionary containing metadata for the document, including: ● title ● author ● subject ● creation and modification dates ● keywords ● creator (the original source of the document, such as Microsoft Word) ● producer (the program that produced the PDF, such as Distiller) For more information, see the PDF 1.6 Reference. Metadata Streams Metadata, both for an entire document and for components within a document, can be stored in PDF streams called metadata streams. The advantages of metadata streams over the document information dictionary include the following: ● PDF-based workflows often embed metadata-bearing artwork as components within larger documents. Metadata streams provide a standard way of preserving the metadata of these components for examination downstream. PD-aware applications should be able to derive a list of all metadata-bearing document components from the PDF document itself. ● PDF documents are often made available on the World Wide Web or in other environments, where many tools routinely examine, catalog, and classify documents. These tools should be able to understand the self-contained description of the document even if they do not understand PDF. Besides the usual entries common to all stream dictionaries, the metadata stream dictionary contains other additional entries. See the PDF Reference for complete details. The contents of a metadata stream is the metadata represented in Extensible Markup Language (XML). This information will be visible as plain text to tools that are not PDFaware only if the metadata stream is both unfiltered and unencrypted. Extensible Metadata Platform (XMP) Adobe’s Extensible Metadata Platform (XMP) is a labeling technology that allows you to embed metadata into the file itself. With XMP, desktop applications and back-end publishing systems gain a common method for capturing, sharing, and leveraging this valuable metadata — opening the door for more efficient job processing, workflow automation, and rights management, among many other possibilities. 102 Acrobat SDK User’s Guide Working with Metadata The Adobe XMP Toolkit 12 Accessing XMP Metadata Using Acrobat JavaScript The metadata method of the Acrobat JavaScript doc object allows you to access the XMP metadata embedded in a PDF document. The method returns a string containing the XML text stored as metadata in a particular PDF document. Accessing XMP Metadata From a Plug-in You can access XMP metadata information using the Acrobat SDK. Plug-ins can get or set XMP metadata using the PDDocGetXAPMetadataProperty and PDDocSetXAPMetadataProperty APIs. Using these APIs, you can access all of the properties in a pdDoc's Info dictionary, as well as properties that are not in the Info dictionary. NOTE: The term “XAP” refers to an early internal code name for Adobe’s Extensible Metadata Platform (XMP). For more information on this protocol, see the Adobe XMP Specification. You can also get or set the XMP metadata associated with a Cos dictionary or stream, or with a PDEContainer. These APIs are all included in the PDMetaDataCalls.h header file. See the Acrobat API and PDF Library API Reference for more information on these APIs. Acrobat Distiller and XMP Metadata Acrobat Distiller supports embedding of XMP metadata in PDF files in two ways. First, it always generates document level metadata. This metadata is derived from the PostScript file and cannot be modified by the PostScript program. To change the document level metadata, you must change it in the authoring application that generates the PostScript stream. A second way of adding metadata is to create object data. See “Object Data” on page 104 for more information. The Adobe XMP Toolkit The XMP Toolkit is designed to help applications handle XMP operations such as the creation and manipulation of metadata. The Toolkit makes it easier for developers to support XMP metadata, and helps to standardize how the data is represented and interchanged. The XMP Toolkit can be licensed, royalty-free, from Adobe Systems. The XMP Toolkit features a C++ interface which uses some modern (ANSI) features, such as exceptions, STL strings, and bool. It uses conservative coding and interface design for maximum portability and to make it easier for developers to adopt. Acrobat SDK User’s Guide 103 12 Working with Metadata Searching Metadata NOTE: Many namespaces, keywords, and related names in this document are prefaced with the string “XAP”, which was an early internal code name for XMP metadata. These names are retained for compatibility. The XMP Toolkit consists of two parts: ● MetaXAP manages the metadata for a managed resource such as an application document file. It defines the objects that act as containers for properties relating to a specific document, and is the primary interface to the XMP Toolkit. MetaXAP provides the top level abstraction for metadata about a document. Nodes are accessed via string pathnames which use a simplified form of XPath strings (XML Path Language: http://www.w3.org/Tr/xpath) ● UtilityXAP provides a variety of special purpose utilities to simplify common uses of MetaXAP. For example, MetaXAP reads and writes property values as strings. UtilityXAP has services that include conversion between integers and other types. XMP metadata properties are organized by schemas. In RDF, the schema is defined by a namespace attribute. Within each schema, properties are named via a path string. This path string has a very simple syntax which is modelled on the XPath standard. The full XMP data model is supported, including values that are simple literals, nested descriptions, and structured containers. Applications should include only the XAPToolkit.h file, and optionally the UtilityXAP.h file. Searching Metadata You can search metadata both by using Acrobat JavaScript and from a plug-in. In Acrobat JavaScript, use the docInfo and docXMP properties of the Search object. In a plug-in, search metadata by setting the kSearchDocInfo, kSearchDocumentXMP, or kSearchEveryWhere search option flags. Object Data The PDF structure tree and marked content work in tandem to support object data. Object data is information associated with a particular object in a PDF document, such as a chair in an engineering drawing. 104 Acrobat SDK User’s Guide Working with Metadata Object Data 12 Creating Object Data Object data is generated by the authoring application, such as Microsoft Visio. You can also attach additional name/value pairs to a set of content objects. You can generate object data by inserting pdfmarks into the PostScript file to be processed by Distiller. Using pdfmarks requires that you know PostScript well enough to either modify the PostScript file directly, or modify the authoring application to generate the appropriate pdfmarks in the PostScript stream. For more information, see “Choosing an Adobe PDF Settings File” on page 41 , the pdfmark Reference Manual., and the PDF Reference. In an existing PDF document, you can use the PDSEdit APIs to create object data programatically from a plug-in. Searching and Accessing Object Data Beginning in Acrobat 7.0, you can access object data from a plug-in and from Acrobat JavaScript. From a plug-in, you use C APIs to: ● Enumerate the PDSElement objects in a document which have user properties associated with them ● Enumerate the object data associated with a PDSElement object as either ASText or CosObj objects ● Check whether a PDF document or specific PDSElement has any user properties associated with it ● Find the ancestor or child node in the structure tree of a PDSElement that has user properties ● Search for object data using the kSearchUserProperties flag to the Search plugin. You can search object data from Acrobat JavaScript by using the Search object’s objectmetadata property. There are no C APIs to search for object-level metadata from a plug-in. Acrobat SDK User’s Guide 105 12 106 Working with Metadata Object Data Acrobat SDK User’s Guide 13 Searching and Indexing Using Acrobat and the Acrobat SDK, you can: ● Search - locate an occurrence of a word in the document content, metadata, attachments or other objects. ● Catalog - create a full-text index of your PDF document or document collections. This chapter consists of the following sections: ● The Acrobat Search Plug-in ● Indexing PDF Documents The Acrobat Search Plug-in With Acrobat, Adobe provides a full-text search system. Using the Acrobat search system, you can: ● Initiate a search with options You can pass query expressions and search settings (for example, whole words only, word stemming, case sensitive, and so forth) to the Acrobat search plug-in and initiate the search. Search results will be presented to the user. ● Control the list of indexes to search The search interface allows searches to be performed on one or more of the available indexes. You can control the list of active indexes. The Acrobat Search plug-in allows users to perform text searches in PDF documents. It adds menus, menu items, toolbar buttons, and a Search panel to the Acrobat or Adobe Reader. You can communicate with the Search plug-in via its plug-in API, via IAC (DDE or Apple events) or via Acrobat JavaScript’s Search object. You can perform all search options from each of these development environments. Creating Custom Searches The Acrobat interface can be extended with new menus and toolbar icons. For example, buttons to invoke a search and to find the next or previous occurrences can be added to the toolbar. You can also add custom, repeatable searches to a menu to increase user efficiency. For more information about adding menu items and toolbar buttons, see “Adding or Removing Menus and Menu Items” on page 59 and “Modifying the Toolbar” on page 60. Acrobat SDK User’s Guide 107 13 Searching and Indexing The Acrobat Search Plug-in Search Options Using the Acrobat JavaScript Search object’s properties and using SearchWordOptions flags with the Search API methods from a plug-in, you can specify the scope and search options for your search. You can set the scope of the search to be one or more of the following: ● Document text ● Bookmarks ● Document metadata (XMP) ● Signatures ● DocInfo fields ● Object data ● Attachments ● EXIF data in associated JPEG images Matching Criteria You can also specify whether the search should match: ● an exact phrase ● all words without regard to order ● any of the words You can also specify whether case and diacritical marks are used or ignored in the search. Searching across Multiple Documents Using the Acrobat SDK, you can search any of the following: ● the active document ● a specified folder ● a specified index ● all active indices Replacing the Acrobat Search Plug-in The Acrobat Search plug-in provided with Acrobat is a true Acrobat plug-in. You can remove it from the system by simply removing it from the Plug-ins directory and restarting Acrobat. Full-text search developers can create a customsearch plug-in using the Acrobat core API. This search plug-in can be represented as one or more toolbar buttons or menu items, and it can use the capabilities provided in the API. 108 Acrobat SDK User’s Guide Searching and Indexing Indexing PDF Documents 13 When creating a replacement search plug-in for Acrobat, you must decide what indexes your search plug-in will use. You can either create your own indexes (see “Extracting and Highlighting Text”) or search the Lextek indexes created by the Acrobat 7 Catalog plug-in. Indexing PDF Documents You can use the Acrobat SDK to create a full-text index of a set of PDF documents. A full-text index is a searchable database of all the text in the documents. After building an index, you can use search the entire library quickly. You can build and manipulate indices from a plug-in, from Acrobat JavaScript or from an external application using IAC (DDE or Apple events) calls. Extracting and Highlighting Text For indexing PDF files, Acrobat provides text extraction APIs. Text extraction also supplies position information that can be used to highlight search hits in the original PDF file. The text extraction tools are provided as calls in the plug-in API on the Acrobat platforms (Mac OS and Windows). You can extract ASCII text from a PDF file using a plug-in or using Acrobat JavaScript. You can also save the PDF document as text or rich text. Indexing and Acrobat JavaScript It is possible to extend and customize indexes for multiple PDF documents using the Acrobat JavaScript Catalog, CatalogJob, and Index objects. These objects may be used to build, retrieve, or remove indexes. The Index object represents a Catalog-generated index and contains a build method that is used to create an index. For more information, see the Acrobat JavaScript Scripting Guide. The Acrobat Catalog Plug-in Acrobat Catalog is a plug-in that allows you to create a full-text index of a set of PDF documents. The Catalog plug-in has an HFT consisting of several methods that plug-in developers can import and use. In addition, Catalog supports DDE, and broadcasts several Windows messages. For more information, see the Acrobat and PDF Library API Overview. Acrobat SDK User’s Guide 109 13 110 Searching and Indexing Indexing PDF Documents Acrobat SDK User’s Guide 14 Accessibility Acrobat and the Acrobat SDK provide extensive support for accessibility of documents to visually-impaired users. This chapter consists of the following sections: ● Accessibility Overview ● Optimizing the Accessibility of PDF Documents ● Making Forms Accessible ● Annotations and Accessibility ● Accessibility and Security ● Microsoft’s Active Accessibility (MSAA) Interface Accessibility Overview To enable proper vocalization, either through a screen reader or by some more direct invocation of a text-to-speech engine, PDF supports the following features: ● Specifying the natural language used for text in a PDF document—for example, as English or Spanish ● Providing textual descriptions for images or other items that do not translate naturally into text, or replacement text for content that does translate into text but is represented in a nonstandard way (such as with a ligature or illuminated character) ● Specifying the expansion of abbreviations or acronyms The core of this support lies in the ability to determine the logical order of content in a PDF document, independently of the content’s appearance or layout, through logical structure and tagged PDF documents (see “Creating Tagged PDF Documents” on page 43). Tagged PDF documents are created using the Acrobat Professional user interface or using the Acrobat SDK. An accessibility application can extract the content of a document for presentation to a disabled user by traversing the structure hierarchy and presenting the contents of each node. For this reason, producers of PDF files must ensure that all information in a document is reachable via the structure hierarchy, and they are strongly encouraged to use the facilities described in this section. Additional guidelines for accessibility support of content published on the World Wide Web can be found in the World Wide Web Consortium document Web Content Accessibility Guidelines and its associated documents. For complete details on accessibility support in PDF files, see the PDF Reference. Acrobat SDK User’s Guide 111 14 Accessibility Optimizing the Accessibility of PDF Documents Optimizing the Accessibility of PDF Documents If a PDF document is untagged, you can convert it to a tagged PDF using Acrobat Professional. NOTE: Acrobat Standard provides only minimal support tagging and no way to review or repair accessibility problems. On the tagged PDF document, perform an accessibility Full Check to isolate problems with PDF accessibility. To help improve the accessibility of tagged PDF documents, you can use the Acrobat user interface or the Acrobat SDK to: ● Create document navigation by adding bookmarks to the document (see “Adding and Managing Bookmarks” on page 47) ● Add alt text to images ● Create hyperlinks, which enhances accessibility because it is easier to activate a hyperlink than to search for a specific reference point in the same or another document (see “Adding and Managing Links” on page 49) ● Add watermarks that optimize the accessibility of the PDF document (see “Manipulating Pages of a PDF File” on page 50) ● Manipulate the tag structure tree using the PDSEdit APIs from a plug-in (see the Acrobat and PDF Library API Overview) Making Forms Accessible The follwoing accessibility tips can make your forms more easily usable by all users. Field Descriptions Every field that is not hidden should contain a user-friendly name. This name is spoken when a user acquires the focus to that field and should give an indication of the field’s purpose. For example, if a field is named name.first, a good short description would be First Name. The name should not depend on the surrounding context. For instance, if a form asks for the first name of both a person and their spouse, the field in the spouse section might be named Spouse’s First Name. This description is also displayed as a tooltip when the user positions the mouse over the field. 112 Acrobat SDK User’s Guide Accessibility Annotations and Accessibility 14 Setting Tab Order Because most users use the tab key to traverse a form, the tab order of the fields should be set in a logical way. This is especially important for visually impaired users, as they cannot rely on mouse movements or visual clues. Pressing the tab (shift-tab) key when there is no form field that has the focus causes the first (last) field in the tab order on the current page to become active. If there are no form fields on the page, Acrobat alerts the user of this via a speech cue. Annotations and Accessibility In Acrobat 6.0, annotations in PDF documents were not fully and easily accessible. This presented a challenge to visually-impaired users who access Acrobat through assistive technologies, such as screen readers and screen magnifiers. The Acrobat 7.0.5 SDK adds a new annotation accessibility API for the generalized interface between annotations and accessibility so that new and custom annotation types can be supported more easily and reliably. A new callback function, AVAnnotHandlerGetAccessibilityString, has been added to the AVAnnotHandler record. Note that there is one annotation handler for each annotation type. For more information, see the Acrobat and PDF Library API Reference. Tagged Annotations Annotations can be dynamically associated with a new structure tree that is separate from the original content of the document. This supports accessibility without modifying the original content. Text-To-Speech Text-To-Speech engines can translate structured text in a PDF document into audible sound. To access the Text-To-Speech engine from Acrobat JavaScript, use the TTS object, which has methods to render text as digital audio and present it in spoken form to the user. Accessibility and Security It is not necessary to sacrifice security in order to make a document accessible: select the Enable Text Access for Screen Reader Devices for the Visually Impaired option in the Security section of Document Properties. Acrobat SDK User’s Guide 113 14 Accessibility Microsoft’s Active Accessibility (MSAA) Interface You can enable this option using Acrobat JavaScript’s doc object’s encryptForRecipients method. This method allows you to control whether content can be extracted for use by applications that, for example, read text aloud. For more information, see the Chapter 11, “Providing Document Security”. Microsoft’s Active Accessibility (MSAA) Interface Acrobat exports COM objects in order to make the content of a PDF file available to assistive technology. An accessibility application such as a screen reader can interface with Acrobat through Microsoft’s Active Accessibility (MSAA) interface, using MSAA objects that Acrobat exports, or directly through exported COM objects that allow access to the PDF’s internal structure, called the document object model, or DOM. Information about the underlying PDF structure is made available through direct COM objects that represent the PDF DOM. The DOM accessibility interfaces provide more extensive access. The DOM and MSAA models are related, and a developer can use either or both. Acrobat issues notifications to accessibility clients about signigicant events occurring in the PDF file window, and responds to requests from such clients. For more information, see Reading PDF Through COM Accessibility Interfaces. 114 Acrobat SDK User’s Guide 15 Working With PDF Layers Adobe PDF layers are components of content that may occupy the same physical space as other components. Multiple components may be visible or invisible depending on their settings, and may be used to support the display, navigation, and printing of layered PDF content by various applications. Using the Acrobat SDK, you can display, navigate and print layered PDF documents. This chapter consists of the following sections: ● About Adobe PDF layers ● Creating Layered PDF Files ● Navigating with Layers ● Working with Layers from Acrobat JavaScript ● Working with Layers from a Plug-in About Adobe PDF layers Acrobat supports the display, navigation, and printing of layered Adobe PDF content output by applications such as Adobe InDesign, AutoCAD, and Microsoft Visio. PDF layers are supported through the usage of PDF Optional Content Group (OCG) objects. Optional content refers to content in a PDF document that can be selectively viewed or hidden. Optional content became available in Acrobat 6. Note the following: Acrobat SDK User’s Guide ● You can rename and merge layers, change the properties of layers, and add actions to layers. You can also lock layers to prevent them from being hidden. ● You can control the display of layers using the default and initial state settings. For example, if your document contains a copyright notice, you can easily hide the layer whenever the document is displayed onscreen but ensure that the layer always prints. ● Acrobat does not allow you to author layers that change visibility according to the zoom level, but it does support this capability from other authoring applications. ● To direct users to a custom view using a particular layer set, you can add bookmarks to a PDF document that contains layers. Use this technique to highlight a portion of a layer that is especially important. You can add links so that users can click on a visible or invisible link to navigate to or zoom in on a layer. ● To create layers while exporting InDesign CS or later documents to PDF, make sure that Compatibility is set to Acrobat 6 (PDF 1.5) and that Create Acrobat Layers is selected in the Export PDF dialog box. 115 15 Working With PDF Layers Creating Layered PDF Files Creating Layered PDF Files The PDFMakers for several engineering applications, including Microsoft Visio and AutoCad, automatically generate the necessary ProcSets to create layered PDF documents. Third-party developers must insert OC ProcSet information into the PostScript stream. For more details, see “Creating PDF Documents from an Authoring Application” on page 39 and the Acrobat Distiller API Reference. You create layered PDF documents with the ProcSet used to build Optional Content (OC) into PDF through Acrobat Distiller. Navigating with Layers Since information can be stored in different layers of a PDF document, navigational controls can be customized within different layers, whose visibility settings may be dynamically customized so that they are tied to context and user interaction. For example, if the user selects a given option, a set of navigational links belonging to a corresponding optional content group can be shown. Working with Layers from Acrobat JavaScript Using Acrobat JavaScript, you can determine the order in which layers are displayed in the user interface. You can also use Acrobat JavaScript to: ● Merge layers in a PDF document ● Flatten layers in a PDF document ● Combine PDF layered documents For more information, see the Acrobat JavaScript Scripting Guide. 116 Acrobat SDK User’s Guide Working With PDF Layers Working with Layers from a Plug-in 15 Wo r k i n g w i t h L ayer s f ro m a P l u g - i n The PDOCG object represents an optional-content group. This corresponds to a PDF OCG dictionary representing a collection of graphic objects that can be made visible or invisible. Any graphic content of the PDF can be made optional, including page contents, XObjects, and annotations. The specific content objects in the group have an OC entry in the PDF. Using PDOCG methods from a plug-in, you can: ● Create a new OCG ● Get and set the current state of an OCG ● Get and set the initial OCG state ● Get and set document configurations For more information, see the Acrobat and PDF Library API Overview and the Acrobat and PDF Library API Reference. Acrobat SDK User’s Guide 117 15 118 Working With PDF Layers Working with Layers from a Plug-in Acrobat SDK User’s Guide Index A "about" box and splash screen 64 accessibility 111 forms 112 security 113 tagged PDF 111 Acrobat Capture 3.0.x 46 Acrobat Distiller 39 batch processing 42 parameters 42 settings file 41 XMP 103 acrobat forms 80 Acrobat JavaScript 19 contexts 20 cross-platform compatibility 32 distribution 32 forms 82 JSObject 27 objects 19 samples 35 scope 32 Acrobat SDK Unix 19 AcroForm 83 AcroPDF 26 actions 51 ADBC 56 Adobe Document Server 46, 89 Adobe LiveCycle Designer 79, 84, 89 Adobe LiveCycle Document Security 16 Adobe LiveCycle Forms 89 Adobe LiveCycle Reader Extensions 16, 87, 89 Adobe Policy Server 16, 92, 98 Adobe Reader enabling 88 Apple events Distiller 40 appModel 84 Acrobat SDK User’s Guide AS layer 24 attachments searching 108 author signature 97 Autodesk AutoCAD 37 AV layer 23 B barcode 84 bookmark 49 bookmarks searching 108 C Catalog 109 Catalog Plug-in 24, 109 CatalogJob 109 certificates 92 certified plug-in 21 collaboration 90 contexts 20 core API organization 22 core API organization AS layer 24 AV layer 23 Cos layer 24 PD layer 23 PDFEdit 23 PDSEdit 23 platform-specific methods 24 Cos layer 24 cross-platform compatibility 32 D DDE 27 PDF creation 39 119 Index dictionary 55 digital ID 92 digital signature 96 Digital Signature Plug-in 24 Distiller 39 Apple events 40 Distller OLE Automation 40 distribution 32 DNS-SD 75 doc addRecipientListCryptFilter 98 E embedded fonts 57 encryption 92 ExecuteThisJavaScript 83 ExecuteThisScript 31 extended APIs Catalog 24 digital signature 24 forms 24 PDF consultant 24 SaveAsXML 25 search 25 spelling 25 weblink 25 F FDF 68, 85 footers 54 forms acrobat 80 Acrobat JavaScript 82 barcode fields 84 FDF 85 field types 81 guidelines 82 Microsoft Excel 85 OLE automation 83 plug-in 83 populating 84 120 templates 86 web-ready 84 workflows 81 XDP 85 XFDF 85 Forms API 83 Forms Plug-in 24 H handlers security 94 Hanko stamp 71 headers 54 help files 64 Host Function Table (HFT) 24 hyperlinks 50 I IAC 30 DDE 27 JSObject 27 OLE support 26 PDF Browser Controls 30 PDF browser controls 26 samples 35 Index 109 Inkan stamp 71 installation 32 J JSObject 22, 27, 31 L Links 50 logical structure 53 M Mac OS X 22 Mach-O 22 Acrobat SDK User’s Guide Index MDP 97 menus and menu items 59 metadata searching 108 Microsoft Access 37 Microsoft Active Accessibility (MSAA) 114 Microsoft Excel 37, 85 Microsoft Internet Explorer 37 Microsoft Outlook 37 Microsoft PowerPoint 37 Microsoft Project 37 Microsoft Publisher 37 Microsoft Visio 37 Microsoft Word 37 MSCAPI 94 O OBDC 56 object data searching 108 OCG 54 OLE Automation Distiller API 40 OLE support 26 online collaboration 67 organization of core API 23 P page content 52 pages creating empty 51 deleting 51 inserting 51 moving 51 PD layer 23 PDDocCreate 45 PDDocPermRequest 89 PDF Browser Controls 30 PDF Consultant Plug-in 24 PDF documents creating 37 printing 56 Acrobat SDK User’s Guide tagged 43 PDF printer 38 PDFEdit 23, 52 samples 52 PDField 83 PDFMaker 37 pdfmark 39, 41, 44 pdfmarks 53 PDSEdit 23, 53, 112 Plug-in 19 plug-ins Adobe Reader-enabled 21 certified 21 cross-platform compatibility 32 installation 32 scope 32 PostScript 39 PPKLite 94 PPKMS 94 printing 56 PubSec layer 94 R Reader enabling 88 Reader extensions effects 90 Reader-enabled plug-ins 21 Really Simple Syndication (RSS) 90 rights-enabling 87 S samples 34 IAC 35 JavaScript 35 SaveAsXML XML conversion 76 SaveAsXML plugin 25 scope 32 Search Plug-in 25 Search plug-in 107 searching 121 Index attachments 108 custom 107 metadata 108 object data 108 XMP 108 security 91 accessibility 113 security handlers 94 Security Policies 97 snippets 52 SOAP 74, 84 Spelling 55 Spelling Plug-in 25 splash screen 64 stamps 71 T tagged PDF 53, 111 tagged PDF documents 43 template 74 templates 86 text extraction 109 text-to-speech (TTS) engines 113 thumbnails 50 toolbar 49 W watermarks 54 Weblink Plug-in 25 workflows forms 81 X XDP 85 XFDF 85 XML 73 architecture 73 templates 74 XML Forms forms XML 74 XMP 74 searching 108 XMP Toolkit 103 XSD 75 U Unix 19 usage rights 21, 87 effects 90 user interface "about" box and splash screen 64 help files 64 menus and menu items 59 toolbar 49 V Visual Studio . NET 2003 22 122 Acrobat SDK User’s Guide

Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Tagged PDF                      : Yes
Page Mode                       : UseNone
XMP Toolkit                     : 3.1-702
Producer                        : Acrobat Distiller 7.0 (Windows)
Creator Tool                    : FrameMaker 7.1
Modify Date                     : 2006:03:27 19:41:33+11:00
Create Date                     : 2005:07:27 10:18Z
Metadata Date                   : 2006:03:27 19:41:33+11:00
Format                          : application/pdf
Title                           : Acrobat SDK User’s Guide
Creator                         : Adobe Developer Support
Description                     : Adobe Systems Incorporated (2005)
Document ID                     : uuid:9a36bf6d-1724-487e-815d-622362c38d38
Instance ID                     : uuid:a42cc881-8dfd-4cf2-aee4-c1a7633feada
Page Count                      : 122
Page Layout                     : OneColumn
Subject                         : Adobe Systems Incorporated (2005)
Author                          : Adobe Developer Support
Warning                         : [Minor] Ignored duplicate Info dictionary
EXIF Metadata provided by EXIF.tools

Navigation menu