® ® Adobe Acrobat 7.0.5 Acrobat SDK User’s Guide July 27, 2005 Adobe Solutions Network — http://partners.adobe.
© 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.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Resources and Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 How This Document Is Organized . .
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 . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents ADM Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Using ADM from Acrobat JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Using the ADM API from a Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Customizing Acrobat Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . .
Contents Signing Adobe PDF Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Certifying PDF Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Validating Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Security Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Using Adobe Policy Server . . . .
Contents Making Forms Accessible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112 Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112 Setting Tab Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113 Annotations and Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113 Tagged Annotations .
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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, ...
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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 a
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.
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.
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.
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.
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.
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.
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.
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.
5 Working with PDF Documents This chapter details how you can work with PDF documents using the Acrobat SDK.
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.
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.
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.
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.
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.
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.
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.
Working with PDF Documents Spell-Checking 5 Spell-Checking Acrobat provides a Spelling plug-in that can scan a document for spelling errors.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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”.
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.
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.
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.
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.
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 guidel
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 i
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 7
