Adobe ACROBAT SDK 8.1 Manual
  1. Manuals
  2. Brands
  3. Adobe Manuals
  4. Software
  5. ACROBAT SDK 8.1
  6. Manual
Adobe ACROBAT SDK 8.1 Manual

Adobe ACROBAT SDK 8.1 Manual

Developing plug-ins and applications
Hide thumbs
Table of Contents

Advertisement

Quick Links

Download this manual
b b
c
Developing Plug-ins and Applications
Adobe
Acrobat
SDK
®
®
April 2007
Version 8.1

Advertisement

Table of Contents
loading
Need help?

Need help?

Do you have a question about the ACROBAT SDK 8.1 and is the answer not in the manual?

Questions and answers

Related Manuals for Adobe ACROBAT SDK 8.1

Summary of Contents for Adobe ACROBAT SDK 8.1

  • Page 1 Developing Plug-ins and Applications Adobe Acrobat ® ® April 2007 Version 8.1...
  • Page 2 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.

  • Page 3: Table Of Contents

    Acrobat core API objects ..............................18 Acrobat core API methods..............................20 Data types....................................21 About PDF Library and plug-in applications ........................23 Manipulating Acrobat Professional, Acrobat Standard, and Adobe Reader ............23 Displaying a PDF document in an external window ....................23 Indexed searching .................................24 Modifying file access................................24 Creating new annotation types ............................24...
  • Page 4 Private data prefixes ...............................33 Action prefixes..................................33 Annotation prefixes ................................33 HFT prefixes ..................................33 Modifying the Acrobat or Adobe Reader user interface ....................33 Adding or removing menus and menu items ......................34 Modifying toolbars ................................34 Controlling the About box and splash screen......................34 Creating help files ..................................34 User interface guidelines..............................34...
  • Page 5 Compiling and building your plug-in..........................53 Creating a sample PDF Library application.........................54 Contents of the PDF Library SDK............................54 Including library files ..............................54 Sample code ..................................55 Developing applications with the Adobe PDF Library.....................56 Windows .....................................57 Mac OS....................................57 UNIX......................................57 Initialization and termination............................58 Multithreading ..................................59 Upgrading existing plug-ins..............................59...
  • Page 6 Adobe Acrobat SDK Contents Developing Plug-ins and Applications Creating Menus and Menu Commands..................88 About menus ....................................88 About AVmenubar typedefs ..............................89 About AVMenu typedefs..............................89 About AVMenuItem typedefs............................89 Adding menu commands to menus .............................90 Adding a menu command to an existing menu......................91 Adding a menu command to a new menu ........................92...
  • Page 7 Adobe Acrobat SDK Contents Developing Plug-ins and Applications 10 Working with Page Views and Contents................122 About page coordinates................................. 122 About page views ..................................124 Displaying page views................................124 Modifying page contents ............................... 125 Creating a PDEContent object ............................125 Accessing page contents ..............................126 Determining page element types..........................
  • Page 8 Adobe Acrobat SDK Contents Developing Plug-ins and Applications 14 Working with Document Security ..................154 About document security ..............................154 About security handlers................................154 Adding a security handler..............................155 Opening a secured file ..............................157 Saving a secured file ................................158 Setting security for a document ............................
  • Page 9 Adobe Acrobat SDK Contents Developing Plug-ins and Applications 17 Working with Cos Objects (Continued) Working with Cos names................................ 188 Creating Cos names ................................189 Retrieving the value of a name object ........................189 Working with Cos streams ..............................190 Creating Cos streams................................. 190 Creating a stream dictionary ............................
  • Page 10 Creating resource files on the UNIX platform......................248 Creating the public and private keys........................... 248 Enabling the plug-in for Adobe Reader........................249 Troubleshooting ..................................249 The plug-in appears to be ignored by Adobe Reader ................... 249 Adobe Reader error messages ............................249 Index ............................250...

  • Page 11: List Of Examples

    List of Examples Example 4.1 Creating a new PDF document...........................63 Example 4.2 Creating a new page...............................63 Example 4.3 Creating a PDEContent object ............................64 Example 4.4 Acquiring a font that is used to draw text on a page ..................64 Example 4.5 Creating a PDEGraphicState object ..........................65 Example 4.6 Creating an ASFixedMatrix object ..........................65...

  • Page 12: Developing Plug-Ins And Applications

    Adobe Acrobat SDK List of Examples Developing Plug-ins and Applications Example 10.1 Displaying a page view............................... 125 Example 10.2 Creating a PDEContent object ..........................126 Example 10.3 Accessing page contents ............................127 Example 10.4 Determining page element types .......................... 127 Example 10.5 Modifying page contents ............................

  • Page 13: Developing Plug-Ins And Applications

    Adobe Acrobat SDK List of Examples Developing Plug-ins and Applications Example 20.1 Importing consultant HFTs ............................223 Example 20.2 Registering an agent with a consultant........................ 225 Example 20.3 Using the consultant traversal stack........................226 Example 20.4 Creating an agent class .............................. 227 Example 20.5 Creating agent constructors.............................

  • Page 14: Preface

    Acrobat Professional, Acrobat Standard and Adobe Reader® user interface and the contents of underlying Adobe PDF documents. This guide also describes how to upgrade plug-ins from Acrobat 7 to Acrobat 8, provides platform-specific techniques for developing plug-ins, and lists the Acrobat SDK header files.
  • Page 15 Detailed explanation of IAC concepts, describes many of Developing Applications Using the objects and commands universally understood by Interapplication Communication applications. Detailed descriptions of the APIs for Acrobat and Acrobat and PDF Library API Reference Adobe Reader plug-ins, as well as for PDF Library applications.

  • Page 16: Introduction

    Acrobat security model. There is currently no way for third party plug-ins to be certified by Adobe. There is a check box in the product user interface that can be used to ensure that only certified plug-ins load (other plug-ins will not load). Certified plug-ins are reserved for...

  • Page 17: About The Acrobat Core Api

    Adobe Acrobat SDK Introduction Developing Plug-ins and Applications About the Acrobat core API About the Acrobat core API The Acrobat core API consists of methods that operate on objects located within PDF documents. The Acrobat core API is implemented as a standard ANSI C programming library where methods are C functions and objects are opaque data types that encapsulate their data.

  • Page 18: Acrobat Core Api Objects

    Adobe Acrobat SDK Introduction Developing Plug-ins and Applications Acrobat core API objects Acrobat Support layer The Acrobat Support (AS) layer provides a variety of utility methods, including platform-independent memory allocation and fixed-point math utilities. In addition, it allows plug-ins to replace low-level file system routines used by Acrobat (including read, write, reopen, remove file, rename file, and other directory operations).
  • Page 19 Adobe Acrobat SDK Introduction Developing Plug-ins and Applications Acrobat core API objects File object interrelationships The following diagram shows file object interrelationships and how certain objects can be obtained by using other objects. Document object interrelationships The following diagram shows document object interrelationships and how certain objects can be...

  • Page 20: Acrobat Core Api Methods

    Adobe Acrobat SDK Introduction Developing Plug-ins and Applications Acrobat core API methods Acrobat core API methods Acrobat core API method names typically conform to the following syntax: <layer><object><verb><thing> layer: identifies the method’s layer (for example, AV for Acrobat Viewer layer).

  • Page 21: Data Types

    Adobe Acrobat SDK Introduction Developing Plug-ins and Applications Data types Verb Description Remove Removes the second object from the current object but does not destroy it. Example: AVMenuRemove Sets an attribute of the object. Example: PDAnnotSetFlags Note: Cos methods uses the verb Put.
  • Page 22 Adobe Acrobat SDK Introduction Developing Plug-ins and Applications Data types The following table describes scalar types. Type Byte Size Description Boolean ASBool unsigned char ASUns8 unsigned short ASUns16 unsigned long ASUns32 char ASInt8 signed short ASInt16 signed long ASInt32 signed long...

  • Page 23: About Pdf Library And Plug-In Applications

    API or the PDF Library API and refer you to the corresponding sections located in this guide. Manipulating Acrobat Professional, Acrobat Standard, and Adobe Reader Plug-ins can control the Acrobat and Adobe Reader interface. For example, you can create and attach a new button to an existing toolbar. For information, see “Attaching a button to a toolbar”...

  • Page 24: Indexed Searching

    PDF files and exchange and review comments. Rights-enabled PDF documents PDF documents that are rights-enabled can access specific functionality in Adobe Reader. PDF files can be enabled for this additional functionality using Adobe LiveCycle® Reader Extensions. When a PDF document is rights-enabled, additional APIs become available for plug-in development.

  • Page 25: New Acrobat Core Apis

    For information, see the Acrobat and PDF Library API AVAlertNote Reference. If such a plug-in is loaded under Adobe Reader, it notify the user that it cannot function fully, then proceed in one of several ways: Not load. ●...
  • Page 26 Adobe Acrobat SDK Introduction Developing Plug-ins and Applications New Acrobat core APIs PDAnnotSetTitleASText PDBookmarkAddNewChildASText PDBookmarkAddNewSiblingASText PDBookmarkAddSubtreeASText PDBookmarkGetByTitleASText PDBookmarkGetTitleASText PDBookmarkSetTitleASText PDDocGetCryptHandler PDDocGetInfoASText PDDocSetInfoAsASText PDEColorSpaceCreateInCosDoc PDEFontCreateFromSysFontAndEncoding InCosDoc PDEFontCreateFromSysFontExInCosDoc PDEFontCreateFromSysFontInCosDoc PDEFontCreateInCosDoc PDEFontCreateWithParamsInCosDoc PDEFormGetBBox PDEFormGetMatrix PDEImageCreateInCosDoc PDEScratchDocCleanup PDFileSpecAcquireASPathEx PDFileSpecGetDIPathEx PDFileSpecNewFromASPathEx PDFLibraryRegisterRNG PDOCRegisterFindOutAutoStatePrefProc PDOCRegisterFindOutLanguageProc PDOCRegisterFindOutUserProc...

  • Page 27: Understanding Plug-Ins

    37 files Extracting data from PDF Describes exporting data from PDF document objects to page 37 document objects XML files. About plug-in initialization This section describes the operation sequence that Acrobat or Adobe Reader performs to initialize a plug-in.

  • Page 28: Plug-In Loading And Initialization

    As each plug-in is loaded, the progress message shows the plug-in name. No plug-ins are loaded if the Shift key is held down while Acrobat or Adobe Reader launch. Also, if Acrobat or Adobe Reader are running in certified mode, no third-party plug-ins are loaded.

  • Page 29: Exporting Hfts

    Exporting HFTs Exporting HFTs A Host Function Table (HFT) is the mechanism through which plug-ins invoke methods in Adobe Reader or Acrobat, as well as in other plug-ins. After Acrobat finishes handshaking with all the plug-ins, it invokes each plug-in’s callback procedure.

  • Page 30: Summarizing A Plug-In's Life Cycle

    1. At startup, Adobe Reader or Acrobat searches its plug-in directory for plug-in files. 2. For each plug-in file, Adobe Reader or Acrobat attempts to load the file. If the plug-in is successfully loaded, Adobe Reader or Acrobat invokes routines in PIMain.c which completes the handshaking process.

  • Page 31: Notifications

    Examples of prefixes are ADBE or Acro, both of which are used by Adobe. This chapter uses ADBE in the examples. You would replace it in your plug-in with the prefix assigned to you.

  • Page 32: Using A Developer Prefix

    Adobe Acrobat SDK Understanding Plug-ins Developing Plug-ins and Applications Using a developer prefix Register Acrobat plug-in prefixes at the Adobe Solutions Network site: http://www.adobe.com/go/acrobat_developer Note: Registering a prefix with Acrobat Developer Support ensures that no other developer is assigned the same prefix. It is up to you to ensure that names are unique among all plug-ins you or your company write (for example, you must ensure that two of your plug-ins do not both use ADBE_save as a menu item name).

  • Page 33: Private Data Prefixes

    Reader user interface. To modify the user interface, you must invoke methods that belong to the Acrobat Viewer Layer. As a result, you cannot modify the Acrobat or Adobe user interface by using the PDF Library API. For information, see...

  • Page 34: Adding Or Removing Menus And Menu Items

    You are encouraged to have your plug-in add its menu commands to the Tools menu. When it is launched, Acrobat or Adobe Reader automatically add this menu, as well as the About Plug-ins and Plug-in Help menus. After Acrobat or Adobe Reader loads all plug-ins, it checks these three menus and removes any that are empty.

  • Page 35: Acquiring And Releasing Objects

    Release Acquire must ultimately be released. If they are not released, Acrobat or Adobe Reader raise exceptions when a non-zero reference count is discovered. An exception can occur when Acrobat or Adobe Reader quits or when a document is closed.

  • Page 36: Page View Layers

    Developing Plug-ins and Applications Page view layers Page view layers Acrobat and Adobe Reader’s drawing and mouse click processing relies on the concept of page view layers, which are numbers of type that are associated with the document itself and each ASFixed annotation type.

  • Page 37: Storing Private Data In Pdf Files

    Plug-ins can store private data in PDF files, although private data must be stored in such a way that the file can still be drawn by Acrobat. Adobe maintains a registry of private PDF dictionary key names to reduce the possibility of a plug-in’s key names conflicting with names belonging to other plug-ins. For information about dictionaries, see “Working with Cos dictionaries”...
  • Page 38 Adobe Acrobat SDK Understanding Plug-ins Developing Plug-ins and Applications Exporting data from PDF document objects To retrieve data from a PDF document object, invoke the method and PDDocExportUserProperties pass the following arguments: object that represents a PDF document that contains the object from which data is extracted.

  • Page 39: Creating Plug-In And Pdf Library Applications

    Creating Plug-in and PDF Library Applications This chapter discusses how to use the Acrobat SDK and the PDFL SDK to create plug-in applications as well as standalone applications that interact with PDF documents. To develop a plug-in for the Windows platform, you can use Microsoft Visual Studio 2003 or Microsoft Visual Studio 2005.

  • Page 40: Working With Platform-Specific Techniques

    Working with platform-specific techniques The Acrobat API is almost completely platform-independent. By using the memory allocation and file system APIs provided by Acrobat or Adobe Reader, many parts of a plug-in can be highly portable across platforms. This chapter contains platform-specific development information for the Windows and Mac OS platforms and provides guidelines that can help make plug-ins more portable among the various supported platforms.

  • Page 41: Windows Techniques

    The plug-in’s filename extension was not changed from .dll to .api. ● Too many plug-ins are being loaded by either Acrobat or Adobe Reader. There is a limit to the number ● of plug-ins that can be loaded at any one time. The number is variable and dependent on the code generation settings of all loaded plug-ins.

  • Page 42: Macros And Project Settings

    .def file in the project for the plug-in or by including the line in the /EXPORT:PlugInMain project settings for the plug-in. If you are developing an Adobe Reader plug-in, you also must define a macro to access HFTs available to Adobe Reader. For information, see “Creating an Adobe Reader Plug-In”...

  • Page 43: Handling The Thread Local Storage (Tls) Limit

    Handling the thread local storage (TLS) limit There is a limit to the number of plug-ins that Acrobat or Adobe Reader can load at any given time. This is due to a limitation of the multi-threading model used by the Win32 API and is dependent on the code generation settings of the plug-ins being loaded.

  • Page 44: Mac Os Techniques

    Starter sample does nothing other than build a loadable plug-in. In addition, other plug-ins that could be useful as a starting point for developing plug-ins are available. The Info.plist file contains a list of properties used by the package. Adobe provides a common info.plist file. It uses project settings to define properties appropriately for each plug-in.
  • Page 45 Adobe Acrobat SDK Creating Plug-in and PDF Library Applications Developing Plug-ins and Applications Mac OS techniques Xcode configuration files Mac OS plug-in sample build settings are defined in SDK and project-level configuration files and not within the projects themselves. Xcode configuration files include lists of build settings definitions that can be applied to multiple projects and/or multiple targets.

  • Page 46: Locating And Loading Plug-Ins

    //Draw to the port here SetGWorld(oldGWorld, oldDevice); AVPageViewReleaseMachinePort(pageView, pagePort); Locating and loading plug-ins\ When Acrobat or Adobe Reader launches, it scans the plug-ins folder to locate and load plug-ins with the acroplugin file extension. PowerPC plug-ins must have creator (CFBundleSignature) and type CARO XTND (CFBundlePackageType).

  • Page 47: Mac Os-Only Methods

    Mac OS. Interapplication communication Plug-ins can add their own Apple events to those supported by Acrobat or Adobe Reader, by hooking into Acrobat or Adobe Reader’s Apple event handling loop. This is done by replacing the method in the API. If the plug-in receives an Apple event it does not want to...

  • Page 48: Including Acrobat Sdk Library Files

    Adobe Acrobat SDK Creating Plug-in and PDF Library Applications Developing Plug-ins and Applications Including Acrobat SDK library files plug-in, it is not necessary to perform some of the tasks discussed in this section. For example, you do not need to start a new project, include header files, or add the PIMain source file. However, you still have to add application logic, compile, and build your project.
  • Page 49 Adobe Acrobat SDK Creating Plug-in and PDF Library Applications Developing Plug-ins and Applications Including Acrobat SDK library files Header file Description Types, macros, and structures that are required to use the AcroColor Host AcroColorExpT.h Function Table. The Acrobat color HFT.
  • Page 50 Adobe Acrobat SDK Creating Plug-in and PDF Library Applications Developing Plug-ins and Applications Including Acrobat SDK library files Header file Description Data structures for PDF Consultant. ConsExpT.h Catalog of functions exported by PDF Consultant. ConsHFT.h PDFObjectType enumeration definition used by PDF Consultant.
  • Page 51 Adobe Acrobat SDK Creating Plug-in and PDF Library Applications Developing Plug-ins and Applications Including Acrobat SDK library files Header file Description Procedures for storing and accessing descriptive metadata associated PDMetadataProcs.h with a PDF document and with components within a PDF document.
  • Page 52 Header file Description The bare minimum prefix file required to compile a Mac OS plug-in for PIPrefix.h Acrobat or Adobe Reader. Used to determine which HFTs (and which versions of those HFTs) the PIRequir.h plug-in requires. Data structures, types, and other constructs related to plug-ins and PIVersn.h...

  • Page 53: Adding The Pimain Source File

    Windows DLLs; however, the file extension is .api, not .dll. Once you create an API file, you must add it to the following directory: \Program Files\Adobe\Acrobat\plug_ins After you add the plug-in to this directory, you must restart Adobe Reader or Acrobat in order for the plug-in to take affect.

  • Page 54: Creating A Sample Pdf Library Application

    C/C++ project with PDF Library files included. This section helps you get started with development using the Adobe PDF Library Software Developers Kit (SDK). It describes the contents of each directory in the PDF Library SDK installation, lists available code samples, and provides platform-specific information on how to set up the development environment.

  • Page 55: Sample Code

    Adobe Acrobat SDK Creating Plug-in and PDF Library Applications Developing Plug-ins and Applications Contents of the PDF Library SDK PDF Library SDK header files ● The PDF Library SDK include directory contains headers for accessing the API methods. You can link to these library files from within your development environment.

  • Page 56: Developing Applications With The Adobe Pdf Library

    Developing applications with the Adobe PDF Library This section details the compiler environment variables (macros) required to build applications against the Adobe PDF Library. On all platforms, you must define the PRODUCT macro for the preprocessor. PRODUCT=\"Library.h\" This macro is used as a trigger for conditional compilation and allows the same headers to be used for...

  • Page 57: Windows

    (AdobePDFL.dll). You should link the interface library into your application. The operating system must be able to access the Adobe PDF Library at runtime. It does so by searching the paths specified by the PATH environment variable, as well as the folder in which the application was launched.

  • Page 58: Initialization And Termination

    The paths can be either full paths or paths relative to the directory from which the executable linking in the Adobe PDF Library was launched. You can set the value kPDFLInitIgnoreDefaultDirectories in the flags field of the...

  • Page 59: Multithreading

    Therefore, for existing Mac OS plug-ins, a variety of code incompatibilities may exist. Detecting supported APIs Acrobat Professional supports the full set of APIs. For Acrobat Standard and Adobe Reader, if you try to use an API that is not supported, nothing will happen. The same HFT version numbers are used across products, so all APIs are callable on all products, but certain APIs simply will not work on certain products.

  • Page 60: Updates To Ascoord And Avrect

    Under Adobe Reader, when a rights-enabled PDF file is opened, a flag is set that allows a plug-in to use APIs that become enabled as a result of loading the rights-enabled PDF. Familiarize yourself with the features available on the different configurations of Acrobat to ensure that you install plug-in menus and toolbars appropriately at initialization.

  • Page 61: Upgrading Plug-Ins On Mac Os

    The PDFL 8 SDK samples have debug and release targets that are built against the MacOSX10.4u.sdk SDK. These are carbon applications that create universal binaries linked to universal Adobe libraries. For a complete list of compatible application build settings, please see the MacSDKConfiguration Xcode configuration files and ProjectConfigurations files included in the PDFL 8 SDK.

  • Page 62: Inserting Text Into Pdf Documents

    PDF documents. The PDF Library API is not used to create plug-ins for Adobe Reader or Acrobat nor is it used to modify the user interface of Adobe Reader or Acrobat such as adding a toolbar or menu item.

  • Page 63: Creating A New Pdf Document

    Adobe Acrobat SDK Inserting Text into PDF Documents Developing Plug-ins and Applications Creating a new PDF document Creating a new PDF document You can programmatically create a new PDF document by invoking the method. This PDDocCreate method returns a object that only contains one COS object, which is a Catalog. For information...

  • Page 64: Acquiring Fonts

    Adobe Acrobat SDK Inserting Text into PDF Documents Developing Plug-ins and Applications Acquiring fonts Example 4.3 Creating a PDEContent object PDEContent pdeContent; pdeContent = PDPageAcquirePDEContent(pdPage, NULL); Acquiring fonts You must acquire the font that you will use to insert text into a PDF document. You can reference a font...

  • Page 65: Creating A Pdegraphicstate Object

    Adobe Acrobat SDK Inserting Text into PDF Documents Developing Plug-ins and Applications Creating a PDEGraphicState object Creating a PDEGraphicState object You must create a object that is used to define attributes of the object. PDEGraphicState PDEText After you create a...

  • Page 66: Inserting Text Into A Pdf Document

    Adobe Acrobat SDK Inserting Text into PDF Documents Developing Plug-ins and Applications Inserting text 2. Invoke the method and pass the following arguments: PDETextAdd object that you created. PDEText ● value that specifies the type of text to add. Specify for a text run.

  • Page 67: Saving The Pdf Document

    Adobe Acrobat SDK Inserting Text into PDF Documents Developing Plug-ins and Applications Saving the PDF document HelloWorldStr, // Text to add strlen(HelloWorldStr),// Length of text pdeFont, // Font to apply to text &gState, //Address of PDEGraphicState object sizeof(gState), //Size of graphic state to apply to text NULL, &textMatrix,...

  • Page 68: Examining A Pdf Library Application Source File

    Adobe Acrobat SDK Inserting Text into PDF Documents Developing Plug-ins and Applications Examining a PDF Library application source file The following image shows the PDF that is created when this source file is executed. The following code example is a source file that inserts text into a PDF document.
  • Page 69 Adobe Acrobat SDK Inserting Text into PDF Documents Developing Plug-ins and Applications Examining a PDF Library application source file #include "PagePDECntCalls.h" #ifdef MAC_ENV #include "macUtils.h" #endif void MainProc(void) char buf[256]; ASInt32 i; ASBool b; PDDoc pdDoc; /* Reference to a PDF document */ PDPage pdPage;...
  • Page 70 Adobe Acrobat SDK Inserting Text into PDF Documents Developing Plug-ins and Applications Examining a PDF Library application source file pdeFontAttrs.type = ASAtomFromString("Type1"); sysFont = PDFindSysFont(&pdeFontAttrs, sizeof(PDEFontAttrs), 0); pdeFont = PDEFontCreateFromSysFont(sysFont, kPDEFontDoNotEmbed); /* The following code sets up the default graphics state. We do this so that * we can free the PDEColorSpace objects //PDEColorSpace pdeColorSpace;...
  • Page 71 Adobe Acrobat SDK Inserting Text into PDF Documents Developing Plug-ins and Applications Examining a PDF Library application source file /* Save document to a file */ #if !MAC_ENV PDDocSave(pdDoc, PDSaveFull | PDSaveLinearized ,ASPathFromPlatformPath ("out.pdf"), NULL, NULL, NULL); #else macPath = GetMacPath("out.pdf");...

  • Page 72: Working With Documents And Files

    ASPathName PDF file to open. As of Acrobat or Adobe Reader 8.0, you can open PDF documents that are based on Unicode-named files. For information, see “Working with Unicode Paths” on page 160.

  • Page 73: Opening A Pdf File

    ● “Creating an ASFileSys object” on page 162. object that specifies a string value to display in the Adobe Reader or Acrobat title bar. ASText ● The following code example opens a PDF document that is based on a file named PurchaseOrder.pdf.

  • Page 74: Opening A Pdf Document In An External Window

    You can use the Acrobat core API to open a PDF document in an external window. For example, from within Adobe Reader or Acrobat, you can enable a user to select a PDF file and then display the PDF document in an external window.

  • Page 75: Creating A Window

    Adobe Acrobat SDK Working with Documents and Files Developing Plug-ins and Applications Creating a Window Creating a Window You must programmatically create the external window in which to display a PDF document. To create a window, you invoke standard platform C functions and not the Acrobat core API. For example, if you are creating your plug-in in Windows, you can use the Win32 API to create a window.

  • Page 76: Creating A Handler For An External Window

    Adobe Acrobat SDK Working with Documents and Files Developing Plug-ins and Applications Creating a handler for an external window AVExternalView: Displays the page view of the document as well as scroll bars, toolbars, ● bookmarks, and the thumbnails pane. Annotations, such as links, are active.
  • Page 77 Adobe Acrobat SDK Working with Documents and Files Developing Plug-ins and Applications Displaying an open dialog box The Acrobat core API has a typedef named that you use to display an AVOpenSaveDialogParamsRec open dialog box. The typedef contains the following attributes that you...
  • Page 78 ● value that specifies an encoding type. ASHostEncoding ● filterRec.filterDescription = ASTextNew(); ASTextSetEncoded (filterRec.filterDescription, "Adobe PDF Files", ASScriptToHostEncoding(kASRomanScript)); 9. Set the object’s attribute by invoking the AVOpenSaveDialogParamsRec windowTitle method (see step 8 for a description of this method).

  • Page 79: Displaying A Pdf Document Within A Window

    Adobe Acrobat SDK Working with Documents and Files Developing Plug-ins and Applications Displaying a PDF document within a window The address of an object. This value can be NULL if AVArraySize kAVOpenSaveAllowMultiple ● is not set as the value. flags The address of an object.

  • Page 80: Opening A Pdf Document In An External Window

    Adobe Acrobat SDK Working with Documents and Files Developing Plug-ins and Applications Displaying a PDF document within a window This code example contains a user-defined method named that acts as a window procedure AVWndProc and another user-defined function named that registers the windows...
  • Page 81 Adobe Acrobat SDK Working with Documents and Files Developing Plug-ins and Applications Displaying a PDF document within a window //Set attributes that belong to the ExternalDocServerCreationDataRec object memset(&creationData, 0, sizeof(ExternalDocServerCreationDataRec)); creationData.size = sizeof(ExternalDocServerCreationDataRec); creationData.platformWindow = (ExternalDocWindowData)externHWnd; creationData.acrobatProc = NULL; creationData.crossDocLinkWithDestData = (void *)externHWnd;...
  • Page 82 = sizeof(AVOpenSaveDialogParamsRec); dialogParams.fileFilters = &filterRecP; dialogParams.numFileFilters = 1; DURING //Set the AVFileFilterRec object’s filterDescription attribute filterRec.filterDescription = ASTextNew(); ASTextSetEncoded (filterRec.filterDescription, "Adobe PDF Files", ASScriptToHostEncoding(kASRomanScript)); //Set the AVOpenSaveDialogParamsRec object's windowTitle attribute dialogParams.windowTitle = ASTextNew(); ASTextSetEncoded (dialogParams.windowTitle, "Select A PDF Document To Open",ASScriptToHostEncoding(kASRomanScript));...

  • Page 83: Bridging Core Api Layers

    PDDo Creating a PDDoc object You can access a PDF file’s contents without displaying the PDF file in Acrobat or Adobe Reader. To perform this task, create a PDDoc object by invoking the PDDocOpen method and passing the following arguments: object that specifies the PDF file on which the is based.

  • Page 84: Creating A Pddoc Object Based On An Open Pdf Document

    PDDoc following tasks: 1. Create an object by invoking the method. This method gets the AVDoc AVAppGetActiveDoc frontmost document located within Adobe Reader or Acrobat. 2. Create a object by invoking the method. This method requires an PDDoc AVDocGetPDDoc AVDoc object and returns a object.

  • Page 85: Creating A Pddoc Object Based On An Open Pdf Document

    Adobe Acrobat SDK Working with Documents and Files Developing Plug-ins and Applications Accessing non-PDF files The following code example creates a PDDoc object that is based on an open PDF document. Example 5.4 Creating a PDDoc object based on an open PDF document AVDoc avDoc = AVAppGetActiveDoc();...
  • Page 86 Adobe Acrobat SDK Working with Documents and Files Developing Plug-ins and Applications Accessing non-PDF files AVAlertNote ("Unable to open data file for writing."); return false; numBytes = ASFileWrite (TheFile, gDataBuf, strlen (gDataBuf)); if (numBytes != strlen (gDataBuf)) ASFileClose (TheFile); AVAlertNote ("Number of bytes written was not the expected number.");...

  • Page 87: Printing Documents

    Adobe Acrobat SDK Working with Documents and Files Developing Plug-ins and Applications Printing documents //Create a platform-independent path ASPathName MakeCrossPlatformASPathName (char* platformPathname) ASPathName ThePathName = NULL; ThePathName = ASFileSysCreatePathName (NULL,ASAtomFromString("Cstring"), platformPathname, 0); return ThePathName; Printing documents You can use the Acrobat core API to print documents by using one of the following methods: AVDocPrintPages ●...

  • Page 88: Creating Menus And Menu Commands

    About menus Adobe Reader and Acrobat have a standard menu bar and menu that enables user to invoke specific functionality. You can, for example, click the Open command that is located on the File menu to open an existing PDF file.

  • Page 89: About Avmenubar Typedefs

    Acrobat core API. About AVMenu typedefs typedef represents a menu in the Adobe Reader or Acrobat menu bar. You can create new AVMenu menus, add menu commands to a menu, and remove menu items. Deleting an...

  • Page 90: Adding Menu Commands To Menus

    ● the menu item is visible for both Full Menus and Short Menus modes (this value is ignored in Adobe Reader or Acrobat 3.0 or later). The key to use as a shortcut for the menu command (an ASCII character). Use...

  • Page 91: Adding A Menu Command To An Existing Menu

    //Declare menu variables AVMenubar Themenubar = NULL; AVMenu FileMenu = NULL; AVMenuItem NewMenuCommand = NULL; //Retrieve the menu bar in Adobe Reader or Acrobat Themenubar = AVAppGetMenubar(); //Retrieve the File menu FileMenu = AVMenubarAcquireMenuByName(Themenubar, "File"); //Create a new menu command NewMenuCommand = AVMenuItemNew("Show Message", "ADBE:ExternWin", NULL, true,...

  • Page 92: Adding A Menu Command To A New Menu

    //Declare menu variables AVMenubar Themenubar = NULL; AVMenu NewMenu = NULL; AVMenuItem NewMenuCommand = NULL; //Retrieve the menu bar in Adobe Reader or Acrobat Themenubar = AVAppGetMenubar(); //Create a new menu NewMenu = AVMenuNew("New Menu", "ADBE:NewMenu", gExtensionID); if (NewMenu == NULL) AVAlertNote ("Unable to create the menu");...

  • Page 93: Creating Menu Callback Functions

    AVExecuteProc ExecProcPtr = NULL; AVComputeEnabledProc CompEnabledProcPtr = NULL; AVComputeMarkedProc CompMarkedProcPtr = NULL; is a callback that you can create that is invoked by Acrobat or Adobe Reader when a user AVExecuteProc selects a menu item. is a callback that you can create that is invoked by Adobe AVComputeEnabledProc Reader or Acrobat when determining whether or not to enable the menu command.

  • Page 94: Creating Menu Callback Functions

    AVExecuteProc AVMenuItemSetExecuteProc associate a menu command with a callback. That is, when a user selects a specific menu command, Acrobat or Adobe Reader will invoke the user-defined function whose address was passed to the macro. The method requires the following...
  • Page 95 AVComputeMarkedProc CompMarkedProcPtr = NULL; //Declare menu variables AVMenu FileMenu = NULL; AVMenuItem NewItem = NULL; //Retrieve the menu bar in Adobe Reader or Acrobat AVMenubar Themenubar = AVAppGetMenubar (); //Create menu callbacks ExecProcPtr = ASCallbackCreateProto (AVExecuteProc, &ShowMessage); CompEnabledProcPtr = ASCallbackCreateProto (AVComputeEnabledProc, &ComputeEnabledProc);...

  • Page 96: Determining If A Menu Item Can Be Executed

    Determining if a menu item can be executed Determining if a menu item can be executed In previous versions of Adobe Reader and Acrobat, it was possible for a document to execute a menu item in the viewing application using a Named action or the JavaScript method.

  • Page 97: Creating Toolbars And Buttons

    105 functions buttons. About toolbars Adobe Reader and Acrobat consists of various toolbars that enable a user to invoke specific functionality. For example, you can click the button that is located on the toolbar to open an existing PDF...

  • Page 98: About Avtoolbar Typedefs

    Acrobat move groups of tool buttons around. Retrieving toolbars You can use the Acrobat core API to retrieve an existing toolbar that appears in Adobe Reader or Acrobat. After you retrieve a toolbar, you can perform additional tasks such as attaching a button. For information, “Attaching a button to a toolbar”...

  • Page 99: Retrieving A Toolbar By Name

    The following table lists toolbar names that appear in Acrobat and Adobe Reader (Adobe Reader does not contain all the toolbars that Acrobat does). The Display Name column specifies the toolbar name that appears in Acrobat or Adobe Reader. The Internal Name column specifies the value that you must pass to method to retrieve the toolbar.

  • Page 100: Creating Toolbar Buttons

    Adobe Acrobat SDK Creating Toolbars and Buttons Developing Plug-ins and Applications Creating toolbar buttons Creating toolbar buttons You can create a new button that you can attach to a new or existing toolbar. To create a new button, invoke the...

  • Page 101: Setting Help Text For A Button

    Adobe Acrobat SDK Creating Toolbars and Buttons Developing Plug-ins and Applications Setting help text for a button Setting help text for a button A button’s help text appears when the mouse scrolls over and pauses on a toolbar button. A small pop-up window appears with a text message.

  • Page 102: Creating A Sub-Menu For A Button

    Adobe Acrobat SDK Creating Toolbars and Buttons Developing Plug-ins and Applications Creating a sub-menu for a button The following code example sets a button’s label text. Example 7.4 Setting a button’s label text //Declare an AVToolButton object AVToolButton MyButton = NULL;...

  • Page 103: Retrieving Existing Toolbar Buttons

    After you create a new button, you must attach it to a toolbar. A button must be attached to a toolbar before it is visible within Adobe Reader or Acrobat. To attach a button to a toolbar, invoke the method and pass the following arguments: AVToolBarAddButton object that represents the toolbar to which the button is attached.

  • Page 104: Exposing A Button In A Web Browser

    For information about creating a button, see “Creating toolbar buttons” on page 100. Exposing a button in a web browser You can expose an Acrobat or Adobe Reader toolbar button within a web browser by invoking the method. Pass the following arguments to the AVToolButtonSetExternal method: AVToolButtonSetExternal object that represents the button to expose within a web browser.

  • Page 105: Removing A Button From A Toolbar

    AVToolButtonDestroy Creating toolbar button callback functions You can create a toolbar button callback function which is invoked by Adobe Reader or Acrobat when a user clicks a button. For the purposes of this discussion, a simplistic user-defined function named is introduced. This method displays a message box by invoking the...

  • Page 106: Creating A Toolbar Button Callback Function

    AVExecuteProc AVToolButtonSetExecuteProc method to associate a button with a callback. That is, when a user clicks a button, Acrobat or Adobe Reader will invoke the user-defined function whose address was passed to the ASCallbackCreateProto macro. The...
  • Page 107 Adobe Acrobat SDK Creating Toolbars and Buttons Developing Plug-ins and Applications Creating toolbar button callback functions AVToolBar ToolBar = AVAppGetToolBarByName(toolbarName); //Create toolbar button callback AVExecuteProc ExecProcPtr = ASCallbackCreateProto (AVExecuteProc, &ShowButtonMessage); AVToolButtonSetExecuteProc (MyButton, ExecProcPtr, NULL); //Attach the button AVToolBarAddButton(ToolBar, MyButton, FALSE, NULL);...

  • Page 108: Creating Annotations

    Adobe Reader or Acrobat, similar to the way people traditionally collaborate using paper by adding comments, highlights, sticky notes, and so on. For example, the note annotation enables Adobe Reader or Acrobat users to add notes within a PDF document that other viewers can read.

  • Page 109: Creating Text Annotations

    Adobe Acrobat SDK Creating Annotations Developing Plug-ins and Applications Creating text annotations 4. Create a object by invoking the method and passing the following PDAnnot PDPageCreateAnnot arguments: object that represents the page that will contain the new annotation. ASPage ●...

  • Page 110: Retrieving Existing Annotations

    Adobe Acrobat SDK Creating Annotations Developing Plug-ins and Applications Retrieving existing annotations //Create a PDAnnot object annot = PDPageCreateAnnot (page, ASAtomFromString("Text"),&fr); //Cast the PDAnnot object to a PDTextAnnot object textannot = CastToPDTextAnnot(annot); //Open the annotation, set the text, and add it to a page PDTextAnnotSetOpen (textannot, true);...

  • Page 111: Modifying Text Annotations

    Adobe Acrobat SDK Creating Annotations Developing Plug-ins and Applications Modifying text annotations //Iterate through the PDF document page by page for (i = 0; i < PDDocGetNumPages(myPDDoc); i ++){ //Get each page within the document page = PDDocAcquirePage(myPDDoc, i); //Get each annotation on the page for (i2 = 0;...

  • Page 112: Example 8.3 Modifying A Text Annotation

    Adobe Acrobat SDK Creating Annotations Developing Plug-ins and Applications Modifying text annotations The second time is invoked, the allocated character pointer is passed as PDTextAnnotGetContents well as the object named . The character pointer is populated with the annotation’s ASInt32 bufSize text.

  • Page 113: Working With Bookmarks

    Every document has a root bookmark. The root bookmark does not represent a physical bookmark that appears in Adobe Reader or Acrobat, but is the root from which all bookmarks in the tree are descended. Bookmarks are organized in a tree structure in which each bookmark has zero or more children that appear indented, and zero or more siblings that appear at the same indentation level.

  • Page 114: Creating Bookmarks

    PDDoc PDBookmark root bookmark. The document’s root bookmark does not appear in Adobe Reader or Acrobat. 2. Create another object that represents the bookmark to add to the document’s root PDBookmark bookmark by invoking the method.

  • Page 115: Defining Bookmark Actions

    Adobe Acrobat SDK Working with Bookmarks Developing Plug-ins and Applications Defining bookmark actions Defining bookmark actions After you create a new bookmark, you must define an action that occurs when a user clicks on the bookmark. Otherwise, nothing occurs when a user clicks on the bookmark.

  • Page 116: Creating A Avpageview Object

    Adobe Acrobat SDK Working with Bookmarks Developing Plug-ins and Applications Defining bookmark actions Value Description Fits the width of the bounding box into the window. FitBH Fits the height of the bounding box into the window. FitBV Creating a AVPageView object...

  • Page 117: Removing Bookmark Actions

    Adobe Acrobat SDK Working with Bookmarks Developing Plug-ins and Applications Removing bookmark actions PDAction myAction = PDActionNewFromDest(myPDDoc,pdvDes,myPDDoc); //Attach an action to the bookmark PDBookmarkSetAction(childBookmark,myAction); Caution: When running this code example, you must have the PDF document on which the object PDDoc is based open.

  • Page 118: Retrieving Bookmarks

    Adobe Acrobat SDK Working with Bookmarks Developing Plug-ins and Applications Retrieving bookmarks Retrieving bookmarks You can use the Acrobat core API to retrieve bookmarks located within a PDF document. You can retrieve the root bookmark, retrieve a specific bookmark, or retrieve all bookmarks that are located within a PDF document.

  • Page 119: Retrieving All Bookmarks

    Adobe Acrobat SDK Working with Bookmarks Developing Plug-ins and Applications Retrieving all bookmarks //Retrieve a specific bookmark myBookmark = PDBookmarkGetByTitle (rootBookmark, bookmarkTitle, strlen(bookmarkTitle), -1); if (PDBookmarkIsValid (myBookmark)) AVAlertNote("The bookmark was retrieved"); else AVAlertNote("The bookmark was not retrieved"); Note: In the previous code example, a...

  • Page 120: Deleting Bookmarks

    Adobe Acrobat SDK Working with Bookmarks Developing Plug-ins and Applications Deleting bookmarks if (!PDBookmarkIsValid(aBookmark)) E_RTRN_VOID //Get the title of the bookmark char * bmBuf; ASInt32 bufSize = PDBookmarkGetTitle(aBookmark, NULL, 0) +1; //Allocate the size of bufSize to the character pointer bmBuf = (char*)ASmalloc((os_size_t)bufSize);...

  • Page 121: Example 9.7 Deleting A Bookmark

    Adobe Acrobat SDK Working with Bookmarks Developing Plug-ins and Applications Deleting bookmarks Example 9.7 Deleting a bookmark //Retrieve a bookmark whose title is Samples PDBookmark rootBookmark, myBookmark; char* bookmarkTitle = "Copying LiveCycle Print files"; //Get the root bookmark rootBookmark = PDDocGetBookmarkRoot(myPDDoc);...

  • Page 122: Working With Page Views And Contents

    This chapter explains how to display page views and modify page contents. A page view is the area of the Acrobat or Adobe Reader window that displays the visible content of a document page. An example of a page view is a PDF document page displayed within Adobe Reader or Acrobat at a 120% magnification.
  • Page 123 Adobe Acrobat SDK Working with Page Views and Contents Developing Plug-ins and Applications About page coordinates The following diagram shows a user space coordinate system. Media Box Crop Box (0,0) Device space specifies coordinates in screen pixels and is used in the AV layer to specify screen coordinates of windows.

  • Page 124: About Page Views

    Adobe Acrobat SDK Working with Page Views and Contents Developing Plug-ins and Applications About page views About page views A page view is represented by an object. To create an object, invoke the AVPageView AVPageView method. For information, see Displaying page views.

  • Page 125: Modifying Page Contents

    PDEText PDEPath PDEImage PDEContent modify objects that it contains. Create a object by performing the following tasks: PDEContent 1. Create an object by invoking the method. This method gets the AVDoc AVAppGetActiveDoc frontmost document located within Adobe Reader or Acrobat.

  • Page 126: Accessing Page Contents

    Adobe Acrobat SDK Working with Page Views and Contents Developing Plug-ins and Applications Accessing page contents 2. Create an object by invoking the method. This method requires AVPageView AVDocGetPageView object and returns an object. AVDoc AVPageView 3. Get the current page number of the PDF document by invoking the AVPageViewGetPageNum method.

  • Page 127: Determining Page Element Types

    Adobe Acrobat SDK Working with Page Views and Contents Developing Plug-ins and Applications Determining page element types The following code example accesses each element located in a object. PDEContent Example 10.3 Accessing page contents //Declare a PDEElement object PDEElement pdeElement;...

  • Page 128: Modifying Text Elements

    Adobe Acrobat SDK Working with Page Views and Contents Developing Plug-ins and Applications Modifying text elements Modifying text elements You can modify elements located within a object. This section discusses modifying text PDEContent elements by placing a red border around them. To place a red border around a text element, you must create a object and define its attributes.

  • Page 129: Example 10.5 Modifying Page Contents

    Adobe Acrobat SDK Working with Page Views and Contents Developing Plug-ins and Applications Modifying text elements The address of an object whose elements specify the length of dashes and gaps. You can ASFixed ● specify to draw a solid outline.
  • Page 130 Adobe Acrobat SDK Working with Page Views and Contents Developing Plug-ins and Applications Modifying text elements for (int i = 0; i < numTextRuns; i++){ //Get the bounding box of the text run PDETextGetBBox ((PDEText) pdeElement, kPDETextRun, i, &bbox); //Convert from user space bbox to device space rect AVPageViewRectToDevice (pageView, &bbox, &rect);...

  • Page 131: Working With Words

    Offsets between characters. (While character offsets are well-defined quantities in a PDF file, word ● numbers are calculated by the Acrobat or Adobe Reader word finder algorithm). About PDWord typedefs object represents a word in a PDF file. Each word contains a sequence of characters in one or PDWord more styles.

  • Page 132: About Pdwordfinder Typedefs

    To perform word operations, such as extracting and displaying words located in a PDF document, you must create a object. You can create a object by getting the active PDWordFinder PDWordFinder document (the frontmost document in Acrobat or Adobe Reader). Optionally, you can create a object when creating a object. PDWordFinderConfigRec PDWordFinder object enables you to customize how text is extracted.

  • Page 133: Example 11.1 Creating A Pdwordfinder Object That Is Based On The Current Pdf Document

    Adobe Acrobat SDK Working with Words Developing Plug-ins and Applications Creating a PDWordFinder object ignoreLineGaps: If true, this attribute disables the handling of vertical movements as line breaks, so that the word finder determines a line break only when a line break character or special tag information appears in the PDF content.

  • Page 134: Extracting And Displaying Words

    Adobe Acrobat SDK Working with Words Developing Plug-ins and Applications Extracting and displaying words pConfig.ignoreCharGaps = true; pConfig.ignoreLineGaps = true; pConfig.noAnnots = true; pConfig.noEncodingGuess = true; //Create a PDWordFinder object PDWordFinder pdWordFinder = PDDocCreateWordFinderEx(currentPDDoc, WF_LATEST_VERSION, false, &pConfig); Extracting and displaying words...

  • Page 135: Example 11.2 Extracting And Displaying Words

    Adobe Acrobat SDK Working with Words Developing Plug-ins and Applications Extracting and displaying words The following code example extracts and displays all words that are located on the current PDF document page. Included in this code example is application logic that creates a object.

  • Page 136: Highlighting Words

    You can use the Acrobat core API to highlight a word or a group of words located within a PDF document. By highlighting a word, you can make a specific word or group of words stand out. The following illustration shows the word Adobe highlighted. To highlight a word you must create a...

  • Page 137: Example 11.3 Highlighting A Word In A Pdf Document

    Adobe Acrobat SDK Working with Words Developing Plug-ins and Applications Highlighting words 6. Create a object by invoking the method and passing the following PDPage PDDocAcquirePage arguments: object. PDDoc ● The page number of the current page view. ● method returns a object.

  • Page 138: Creating Handlers

    Creating Handlers Adobe Reader and Acrobat plug-ins and PDF Library applications can add new types of tools, annotations, actions, file systems, and so on, thereby expanding the number of supported object types. To accomplish this task, the Acrobat core API provides a collection of callback routines called handlers that support objects.

  • Page 139: Action Handlers

    Adobe Acrobat SDK Creating Handlers Developing Plug-ins and Applications Action handlers It is possible to subclass existing handlers or to create entirely new handler types. For example, a plug-in can subclass the built-in text annotation handler by adding the ability to hide annotations. To accomplish this task, perform the following tasks: 1.

  • Page 140: Annotation Handlers

    AVCommand selection in the current document. are exposed to Adobe Reader or Acrobat through AVCommands handlers. You can add new command types by defining and registering an...

  • Page 141: Invoking Avcommands

    Adobe Acrobat SDK Creating Handlers Developing Plug-ins and Applications Invoking AVCommands The following code example creates an handler. AVCommand Example 12.1 Creating an AVCommand handler static AVCommandHandlerRec gAVCmdHandler; const char *kCmdName = "MinimalCommand"; static ACCB1 AVCommandStatus ACCB2 DoWorkImpl (AVCommand cmd) AVAlertNote("The DoWorkImpl method was invoked");...

  • Page 142: Setting Configuration Parameters

    Adobe Acrobat SDK Creating Handlers Developing Plug-ins and Applications Configuring AVCommands Example 12.2 Setting input parameters //Create a PDDoc object based on the current PDF document AVDoc avDoc = AVAppGetActiveDoc(); AVPageView pageView = AVDocGetPageView(avDoc); PDPageNumber pageNum = AVPageViewGetPageNum(pageView); PDDoc pdDoc = AVDocGetPDDoc(avDoc);...

  • Page 143: Running Commands

    Adobe Acrobat SDK Creating Handlers Developing Plug-ins and Applications Running commands //Create an ASCab object to hold command parameters ASCab params = ASCabNew(); ASText text = ASTextNew(); ASTextSetEncoded(text, docTitleValue,(ASHostEncoding)PDGetHostEncoding()); ASCabPutText (params, docTitleValue, text); //Clear the ASText object text = ASTextNew();...

  • Page 144: Exposing Avcommands To The Batch Framework

    (of the AVCommandRegisterCommandsProc structure). AVCommandHandlerRec Supporting properties When building a list of batchable commands, Adobe Reader or Acrobat iterates through its internal command list, querying each command for the properties. To be exposed CanBatch GroupTitle through the batch framework user interface, a command must support these properties (that is, return and a valid object, respectively).

  • Page 145: File Format Conversion Handlers

    “Running an AVCommand” on page 143. params File format conversion handlers A plug-in can add file conversion handlers to Acrobat (but not Adobe Reader) for performing the following file conversion operations: To import a PDF document from another file format. ●...

  • Page 146: File Specification Handlers

    Adobe Acrobat SDK Creating Handlers Developing Plug-ins and Applications File specification handlers By using a file format conversion handler, you can perform the following tasks: Provide default settings for the conversion by using the AVConversionDefaultSettingsProc ● callback method. Provide conversion parameter information by using the...

  • Page 147: Tool Callbacks

    When a plug-in creates a window, it can register the window, so that it behaves like other windows in Acrobat; for example, when Adobe Reader or Acrobat is minimized or hidden. For each window that a plug-in provides, a window handler must be provided. Window handlers are used only in the Mac OS version of Adobe Reader or Acrobat.

  • Page 148: File Systems

    Acrobat and PDF Library API Reference. File systems Plug-ins can add new file systems to Acrobat or Adobe Reader, to access files on a device that cannot be accessed as a local hard disk, such as a socket or a modem line.

  • Page 149: Progress Monitors

    Adobe Acrobat SDK Creating Handlers Developing Plug-ins and Applications Progress monitors Dispose of a path (not the underlying file) by using the callback ASFileSysDisposePathNameProc ● method. Flush data on a volume by using the callback method. ASFileSysFlushVolumeProc ● Handle asynchronous I/O operations by using the following callback methods: ●...

  • Page 150: Adding Message Handling

    AVTransHandlerGetUINameProc Adding message handling Plug-ins can add their own DDE messages and Apple events to those supported by Acrobat and Adobe Reader. On Windows, plug-ins can register to receive DDE messages directly. On Mac OS, plug-ins must hook into Acrobat or Adobe Reader’s Apple event handling loop to handle Apple events. To do this, replace the API’s AVAppHandleAppleEvent method.

  • Page 151: Registering For Event Notifications

    Notifications enable plug-ins to indicate that they are interested in a specified event (such as the initialization of Adobe Reader or Acrobat) and to provide a callback function that is invoked by Adobe Reader or Acrobat each time an event occurs.

  • Page 152: Example 13.1 Registering For An Event Notification

    NULL ● The following code example registers for the event that occurs when Adobe Reader or Acrobat is finished initializing. The name of the callback function is . This function simply myNotificationCallback displays an alert box.

  • Page 153: Unregistering Event Notifications

    The name of the Acrobat core API method that corresponds to the event notification. For example, ● to register for the event that occurs when Adobe Reader or Acrobat has initialized, pass . Append the value to the end of the method name.

  • Page 154: Working With Document Security

    All objects, except for the encryption dictionary (which contains the security handler’s private data), are encrypted using the RC4 algorithm Adobe licenses from RSA Data Security, Inc. A plug-in may not substitute another encryption scheme for RC4.

  • Page 155: Adding A Security Handler

    Adobe Acrobat SDK Working with Document Security Developing Plug-ins and Applications Adding a security handler A security handler supports two passwords: A user password that enables a user to open and read a protected document with whatever ● permissions the owner chose An owner password that allows a document’s owner to also change the permissions granted to users...
  • Page 156 Adobe Acrobat SDK Working with Document Security Developing Plug-ins and Applications Adding a security handler Security handlers data The following list describes three types of data used by security handlers: Authorization data is the data the security handler needs to determine the user’s authorization level for ●...

  • Page 157: Opening A Secured File

    Adobe Acrobat SDK Working with Document Security Developing Plug-ins and Applications Opening a secured file Acrobat’s authorization procedure Acrobat’s built-in authorization procedure works as follows: 1. Acrobat invokes the security handler’s authorize callback (which is either , introduced with Acrobat 5.0, or the older...

  • Page 158: Saving A Secured File

    Adobe Acrobat SDK Working with Document Security Developing Plug-ins and Applications Saving a secured file 3. If Acrobat finds no match, indicating that the necessary handler could not be found, it does not open the document. If it finds a matching security handler, it invokes that handler’s callback to extract and decrypt information from the PDF file’s...

  • Page 159: Setting Security For A Document

    Adobe Acrobat SDK Working with Document Security Developing Plug-ins and Applications Setting security for a document Setting security for a document Acrobat calls the new security handler’s callback to present PDCryptUpdateSecurityDataProc whatever user interface the security handler has for allowing the user to set security, passwords, and so forth.

  • Page 160: Working With Unicode Paths

    Working with Unicode Paths This chapter explains how to work with Acrobat or Adobe Reader’s support of Unicode paths. Using this feature, you can programmatically open and save Unicode-named files and select Unicode-named folders. You can, for example, enable a user to open a Unicode-named file and view the corresponding PDF document in Acrobat or Adobe Reader.

  • Page 161: Retrieving Unicode Path Values

    Adobe Acrobat SDK Working with Unicode Paths Developing Plug-ins and Applications Retrieving Unicode path values The following table lists Acrobat core API methods that should be replaced by newer methods in order to work with Unicode paths. Old method New method...

  • Page 162: Creating An Asfilesys Object

    Adobe Acrobat SDK Working with Unicode Paths Developing Plug-ins and Applications Creating an ASFileSys object Creating an ASFileSys object Regardless whether you are working with Unicode paths or non-Unicode paths, you must create an object when performing tasks that manipulate files, such as opening a PDF file. An ASFileSys object represents the file system in which the file that you are manipulating is located.

  • Page 163: Creating An Asfilesys Object That Supports Unicode Paths

    Adobe Acrobat SDK Working with Unicode Paths Developing Plug-ins and Applications Creating an ASFileSys object that supports Unicode paths Creating an ASFileSys object that supports Unicode paths You can invoke the method to create an object that ASGetDefaultUnicodeFileSys ASFileSys represents a file system that supports Unicode paths. On Windows, this method returns an ASFileSys object that uses Unicode paths.

  • Page 164: Working With Host Function Tables

    Each entry represents a single method that a plug-in can invoke, and is defined as a linked list of function pointers. Adobe Reader or Acrobat uses linked lists because some HFT entries may be marked so that they can be replaced by a plug-in. Also, it is useful to keep a list of each implementation of a method that has...

  • Page 165: Exporting Host Function Tables

    “Importing HFTs and registering for notifications” on page When a plug-in invokes a method in Adobe Reader, Acrobat, or another plug-in, the function pointer at the appropriate location in the appropriate HFT is dereferenced and executed. Macros in the Acrobat SDK’s header files hide this functionality, so that plug-ins contain only what appear to be normal function calls.

  • Page 166: Creating Hft Methods

    Adobe Acrobat SDK Working with Host Function Tables Developing Plug-ins and Applications Creating HFT methods Creating HFT methods The first step in exporting HFTs is to create the methods that will be exported and made available to other plug-ins. For the purpose of this discussion, assume that the following three methods exist: ACCB1 void ACCB2 BeepOnceImplementation() AVSysBeep (0);...
  • Page 167 Adobe Acrobat SDK Working with Host Function Tables Developing Plug-ins and Applications Creating HFT method definitions Defining function prototypes After you define an enumeration and an HFT object, you can define a function pointer for each method by using the following syntax: typdef ACCBPROTO1 return_type (ACCBPROTO2 *function_nameSELPROTO)(parameters);...

  • Page 168: Creating Hft Callback Functions

    Adobe Acrobat SDK Working with Host Function Tables Developing Plug-ins and Applications Creating HFT callback functions Creating HFT callback functions You must create an HFT callback function in order to successfully export an HFT. It is recommended that you place the application logic to create an HFT callback in the method.

  • Page 169: Creating New Host Function Tables

    Adobe Acrobat SDK Working with Host Function Tables Developing Plug-ins and Applications Creating new Host Function Tables DURING //Create an HFT callback function provideMyHFTCallback = ASCallbackCreateProto(HFTServerProvideHFTProc, &ProvideMyHFT); //Create an HFT server gMyHFTServer = HFTServerNew("MyHFT", provideMyHFTCallback, NULL, NULL); HANDLER gSomethingWentWrong=1; return false;...

  • Page 170: Examining Hft Header And Source Files

    Adobe Acrobat SDK Working with Host Function Tables Developing Plug-ins and Applications Examining HFT header and source files Example 16.2 Creating new Host Table Functions ACCB1 HFT ACCB2 ProvideMyHFT(HFTServer server, ASUns32 version,void *rock) //Ensure version is 1 if (version != 1) return NULL;...

  • Page 171: Examining An Hft Source File

    Adobe Acrobat SDK Working with Host Function Tables Developing Plug-ins and Applications Examining HFT header and source files enum DUMMYBLANKSELECTOR, BeepOnceSEL, BeepTwiceSEL, BeepNTimesSEL, NUMSELECTORSPlusOne extern HFT gMyHFT; #define NUMSELECTORS (NUMSELECTORSPlusOne - 1) typedef ACCBPROTO1 void (ACCBPROTO2 *BeepOnceSELPROTO)(void); #define BeepOnce (*((BeepOnceSELPROTO)(gMyHFT[BeepOnceSEL]))) typedef ACCBPROTO1 void (ACCBPROTO2 *BeepTwiceSELPROTO)(void);...
  • Page 172 Adobe Acrobat SDK Working with Host Function Tables Developing Plug-ins and Applications Examining HFT header and source files AVSysBeep (0); AVAlertNote ("In BeepOnceImplementation function."); /* The implementation for the BeepTwice() function. Note it has a ** different name than the #define for the function in MyHFT.h ACCB1 void ACCB2 BeepTwiceImplementation() AVSysBeep (0);...

  • Page 173: Importing An Existing Hft

    = ASExtensionMgrGetHFT(ASAtomFromString("MyHFT"), 1); return (gMyHFT != NULL); Note: Both the exporting and importing plug-ins must be located in Acrobat or Adobe Reader’s plug-ins directory. If the exporting plug-in is not located in this directory, the importing plug-in cannot successfully import an HFT.

  • Page 174: Invoking Hft Methods

    You can use the Acrobat core API to replace methods that are located in existing HFTs. For example, a plug-in could use this mechanism to change the appearance of all alert boxes displayed by Acrobat or Adobe Reader, or to override file opening behavior. The following table lists all the replaceable Acrobat and Adobe Reader methods. AVAlert AVAppCanQuit...

  • Page 175: Example 16.6 Replacing An Hft Method

    Adobe Acrobat SDK Working with Host Function Tables Developing Plug-ins and Applications Replacing HFT methods When an HFT entry is replaced, the entry’s linked list is updated so that the newly-added implementation is at the head of the linked list. Previous implementations, if any, follow in order, as shown in the following diagram.

  • Page 176: Migrating Non-Hft Pdf Library Applications To Hft Applications

    Adobe Acrobat SDK Working with Host Function Tables Developing Plug-ins and Applications Migrating non-HFT PDF Library applications to HFT applications void ReplaceAVAppCanQuit () DURING //Create the callback gMyAVAppCanQuitPtr = ASCallbackCreateReplacement (AVAppCanQuitSEL, &MyAVAppCanQuit); //Invoke the Replace macro REPLACE (gMyHFT, AVAppCanQuitSEL, gMyAVAppCanQuitPtr);...
  • Page 177 Adobe Acrobat SDK Working with Host Function Tables Developing Plug-ins and Applications Migrating non-HFT PDF Library applications to HFT applications The following table lists PDF Library API methods that should be changed to newer methods when working with HFTs. Old method...

  • Page 178: Working With Cos Objects

    Working with Cos Objects A PDF file is structured as a tree of low-level objects, called Cos objects. Cos objects form all PDF document components, such as bookmarks, pages, fonts, images, and annotations. The Acrobat core API contains methods (the Cos layer) that enable you to operate directly on these low-level objects. You may encounter a situation where you want to perform a task that is not supported by using AV and PD layer methods.

  • Page 179: About Direct And Indirect Objects

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications About direct and indirect objects About direct and indirect objects You can create Cos objects as either direct or indirect objects; the choice is specified as a parameter to the method that creates the object.
  • Page 180 Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications About Cos object types Literal strings A literal string is written as an arbitrary number of characters enclosed in parentheses. Any characters may appear in a string except unbalanced parentheses and the backslashes, which must be treated specially.

  • Page 181: Cos Arrays

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications About Cos object types Hexadecimal strings Strings may also be written in hexadecimal form, which is useful for including arbitrary binary data in a PDF file. A hexadecimal string is written as a sequence of hexadecimal digits (0–9 and either A–F or a–f ) enclosed within angle brackets (<...

  • Page 182: Cos Dictionaries

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications About Cos object types Beginning with PDF 1.2, any character except null (character code 0) may be included in a name by writing its 2-digit hexadecimal code, preceded by the number sign character (#). This syntax is required to represent any of the delimiter or white-space characters or the number sign character itself;...

  • Page 183: Cos Streams

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Working with Cos strings Cos streams A stream is a sequence of bytes that can be read a portion at a time. For this reason, objects with potentially large amounts of data, such as images and page descriptions, are represented as streams. A...

  • Page 184: Retrieving The String Value

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Retrieving the string value Retrieving the string value You can retrieve the string value from a that is based on a Cos string. To retrieve the string value, CosObj...

  • Page 185: Retrieving Cos Array Values

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Retrieving Cos array values 3. Create a object that stores a value to add to the Cos array. For example, to create a CosObj CosObj object that is based on an integer value, invoke the...

  • Page 186: Working With Cos Dictionaries

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Working with Cos dictionaries The following code illustrates a user-defined function named that retrieves the value GetArrayValues of each element and displays it in an alert box. Notice that a...

  • Page 187: Retrieving Values From A Cos Dictionary

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Retrieving values from a Cos dictionary 3. Create a object that represents a dictionary value. You must invoke a method that corresponds CosObj to the value’s data type. For example, to add an integer value, invoke the...

  • Page 188: Querying A Cos Dictionary For A Key

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Querying a Cos dictionary for a key 2. Get the element value. However, you must invoke the method that corresponds to the object’s CosObj data type. If, for example, the Cos array stores integer values, invoke the...

  • Page 189: Creating Cos Names

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Creating Cos names Creating Cos names You can use the Acrobat core API to create a object that is based on a Cos name. To create a Cos CosObj name, perform the following tasks: 1.

  • Page 190: Working With Cos Streams

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Working with Cos streams Working with Cos streams This section discusses ways in which you can work with Cos streams. For information, see “Cos streams” on page 183. A stream is represented by an object definition.
  • Page 191 Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Creating Cos streams In addition, most filters are defined so that the data is self-limiting; that is, they use an encoding scheme in which an explicit end-of-data (EOD) marker delimits the extent of the data. Finally, streams are used to represent many objects from whose length attributes can be inferred.

  • Page 192: Inserting A Cos Stream Into A Pdf Document

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Creating Cos streams Example 17.10 Creating a stream dictionary //Create a PDPage object using the current page AVDoc avDoc = AVAppGetActiveDoc(); AVPageView pageView = AVDocGetPageView(avDoc); PDPageNumber pageNum = AVPageViewGetPageNum(pageView);...

  • Page 193: Example 17.11 Inserting A Cos Stream Into A Pdf Document Page

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Creating Cos streams 5. Create a object that represents the stream dictionary. For information, see “Creating a stream CosObj dictionary” on page 190. 6. Read the stream into memory by invoking the...
  • Page 194 Caution: If you execute this code example without having a PDF document open, you will cause an Adobe Reader or Acrobat run-time error. The run-time error occurs because this code example creates a object that is based on the current PDF document page.

  • Page 195: Populating A Pdf Document With A Content Stream

    Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Populating a PDF document with a content stream Populating a PDF document with a content stream This section explains how to use the Acrobat core API to create a new PDF document, insert a page into the document, and populate the page with a Cos content stream that inserts the text .
  • Page 196 PDDoc PDDocCreate After the document is created, at least one page must be added before Acrobat or Adobe Reader can display the document. PDDoc NewDoc = PDDocCreate (); 4. Create a...

  • Page 197: Example 17.12 Creating A Pdf Document And Populating It With A Cos Content Stream

    7. Add a Cos stream to the page. In the following code example, a Cos stream is added to the page in a user-defined function named AddStreamToPage 8. Open the PDF document in Adobe Reader or Acrobat. In the following code example, this task occurs in the user-defined function named MakeTheFile 9.
  • Page 198 Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Populating a PDF document with a content stream //Make sure that the page is valid if (!page) return false; DURING //Get a CosDoc object by using the PDPage page passed to this object PageCosObj = PDPageGetCosObj(page);...
  • Page 199 Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Populating a PDF document with a content stream CosDictPut (FontDictObj, ASAtomFromString ("Subtype"), CosNewName (cd, false, ASAtomFromString ("Type1"))); CosDictPut (FontDictObj, ASAtomFromString ("Name"), CosNewName (cd, false, ASAtomFromString ("F0"))); CosDictPut (FontDictObj, ASAtomFromString ("BaseFont"), CosNewName (cd,false, ASAtomFromString ("Courier")));...
  • Page 200 Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Populating a PDF document with a content stream CosArrayPut (procArray, 1, CosNewName (cd, false, ASAtomFromString ("Text"))); ** Place the proc set key-value pair into the page’s resource dictionary. CosDictPut (ResDict, ASAtomFromString ("ProcSet"), procArray);...
  • Page 201 Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Populating a PDF document with a content stream return false; //Read the stream into memory by invoking the ASMemStmRdOpen method Stm = ASMemStmRdOpen (StreamBuf, StreamBufLen); if (!Stm){ AVAlertNote ("Unable to open data stream to create content stream.");...
  • Page 202 Adobe Acrobat SDK Working with Cos Objects Developing Plug-ins and Applications Populating a PDF document with a content stream DURING //Create a PDDoc object NewDoc = PDDocCreate(); if (NewDoc){ //Invoke the PDDocCreatePage method NewPage = PDDocCreatePage(NewDoc, PDBeforeFirstPage, MedBox); if (!NewPage) ASRaise (0);...

  • Page 203: Creating 3D Annotations

    Creating 3D Annotations Three-dimensional annotations can be viewed in a PDF document by means of 3D annotations. This chapter explains how to create 3D annotations and modify existing ones by using Cos objects. Before you read this chapter, it is strongly recommended that you become familiar with Cos objects. For information, “Working with Cos Objects”...

  • Page 204: Adding 3D Data To An Annotation

    Adobe Acrobat SDK Creating 3D Annotations Developing Plug-ins and Applications Adding 3D data to an annotation The type of the annotation, which in this case is . This sets the value of the annotation dictionary’s ● entry. It is important to note that in PDF this is a name object, not a string. In the API, the Subtype type is frequently used to represent names;...

  • Page 205: Creating The 3D Annotation Dictionary Entries

    Adobe Acrobat SDK Creating 3D Annotations Developing Plug-ins and Applications Creating the 3D annotation dictionary entries Most of the code described here involves setting the entries of dictionaries ( of type CosObjs CosDict Dictionaries contain a number of key-value pairs, where the key is a name object and the value is any type CosObj There are several common methods that can be used, which differ only in how the keys are specified.

  • Page 206: Creating The Stream Object

    Adobe Acrobat SDK Creating 3D Annotations Developing Plug-ins and Applications Specifying the 3D stream Other entries are unique to 3D streams (see Table 9.35 in the PDF Reference). They include: (optional): Must be if present. Type ● (required): Must be Subtype ●...

  • Page 207: Adding The Cos Stream To The Annotation Dictionary

    Adobe Acrobat SDK Creating 3D Annotations Developing Plug-ins and Applications Specifying the 3D stream object that represents the stream dictionary. You can invoke the method. CosObj CosNewNull ● object that represents the parameters that are used by the encoding filter if the source CosObj ●...

  • Page 208: Specifying Javascript Code

    Adobe Acrobat SDK Creating 3D Annotations Developing Plug-ins and Applications Specifying the 3D stream Specifying JavaScript code You can create JavaScript that manipulates the 3D annotation. JavaScript is optional and if you do not specify it, then the 3D annotation is still inserted into the PDF document; however, it remains a static graphic.

  • Page 209: Setting The Default View

    Adobe Acrobat SDK Creating 3D Annotations Developing Plug-ins and Applications Setting the default view Set it as the value of the entry of the 3D stream dictionary. The following code example OnInstantiate specifies a JavaScript script as the value of the entry of the 3D stream dictionary.

  • Page 210: Setting The Annotation Appearance

    Adobe Acrobat SDK Creating 3D Annotations Developing Plug-ins and Applications Setting the annotation appearance externalViewName, strlen(externalViewName))); CosDictPutKeyString(cosView, "IN", CosNewString(cosDoc, false, internalViewName, strlen(internalViewName))); CosDictPutKeyString(cosView, "MS", CosNewNameFromString(cosDoc, false, "M")); CosDictPutKeyString(cosView, "CO", CosNewFixed(cosDoc, false, FloatToASFixed(gCOvalue))); Here the matrix is populated with the appropriate values: CosObj matrixArray = CosNewArray(cosDoc, false, 12);...
  • Page 211 Adobe Acrobat SDK Creating 3D Annotations Developing Plug-ins and Applications Setting the annotation appearance The following is the function: GetFormXObjectFromFile CosObj GetFormXObjectFromFile (char* pdfImageFilePath, //Path of image PDF file PDDoc TargetPdDoc)// The current document PDDoc posterPDFDoc = NULL;//Initialization code PDPage pdPageImage = NULL;...
  • Page 212 Adobe Acrobat SDK Creating 3D Annotations Developing Plug-ins and Applications Setting the annotation appearance The parameters to this method are: object. PDEContent ● A flag indicating what type of Cos object should be created; in this case, a form XObject.

  • Page 213: Setting The Activation Dictionary

    Adobe Acrobat SDK Creating 3D Annotations Developing Plug-ins and Applications Setting the activation dictionary CosDictPutKeyString(contentFormXObject, "Matrix", MatrixArray); Finally, the method is used to copy the Cos object into the current CosObjCopy contentFormXObject PDF document. The parameters to this method are: to copy.

  • Page 214: Handling Exceptions

    Handling Exceptions This chapter explains how to handle exceptions that are raised by Acrobat core API methods. Acrobat core API methods generally do not return error codes; instead, they raise exceptions when errors occur. Exceptions are handled by exception handlers. It is recommended that you create your own exception handlers to trap and handle exceptions.

  • Page 215: Returning A Value From An Exception Handler

    Adobe Acrobat SDK Handling Exceptions Developing Plug-ins and Applications Returning a value from an exception handler Returning a value from an exception handler To return a value from a block, do not use a return statement. Instead, use the DURING HANDLER macros.

  • Page 216: Using Nested Exception Handlers

    Adobe Acrobat SDK Handling Exceptions Developing Plug-ins and Applications Using nested exception handlers This action leads to unpredictable results because the top stack frame has not been removed. As a result, the frame is incorrect. Instead, use the method and then use the...

  • Page 217: Using Register Variables

    Adobe Acrobat SDK Handling Exceptions Developing Plug-ins and Applications Using register variables exception handler will restore the incorrect calling environment and lead to unpredictable results, as shown in the following example: DURING /* Places one frame on the exception stack */ pdoc = AVDocGetPDDoc(avdoc);...

  • Page 218: Working With Acrobat Extended Apis

    Working with Acrobat Extended APIs Some of Acrobat’s default plug-ins expose their APIs for use by third parties. These are Acrobat’s extended APIs. The AcroColor extended API is the only extended API that is not in a plug-in: it is part of the Acrobat core, but is considered an extended API because it does not cleanly fit into the layered structure of the core.

  • Page 219: Search Extended Api

    Search extended API Search extended API The Adobe Acrobat Search plug-in allows users to perform text searches in PDF documents. It adds menus, menu items, a toolbar button, and a Search panel to the Acrobat viewer. The Search plug-in exports a host function table (HFT) that contains methods that can be used by other plug-ins.
  • Page 220 Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications PDF Consultant and Accessibility Checker extended API As the consultant traverses a PDF document, gathering objects of interest, it can perform the following tasks: Walk a given hierarchy ●...

  • Page 221: How The Consultant Works

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications How the consultant works How the consultant works The consultant completes a full, non-recursive traversal of the Cos graph that comprises a PDF document, keeping track of cycles as it goes. Note that there is no guarantee that objects will be visited in any...

  • Page 222: Important Issues For Consultant Development

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Important issues for consultant development 10. The consultant unregisters all agents. 11. You release the agent object. 12. You release the consultant object. Important issues for consultant development First, you must decide if you actually do want to use a consultant.

  • Page 223: Importing The Consultant Hfts Into A Plug-In

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Importing the consultant HFTs into a plug-in Avoiding agent collisions When running multiple agents on a document, the order in which you register your agents is the order in which the consultant will hand them objects.

  • Page 224: Creating And Destroying Consultants

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Creating and destroying consultants The consultant defines the following methods for HFT usage: ConsultantCreate ● ConsultantDestroy ● ConsultantTraverseFrom ● ConsultantRegisterAgent ● ConsultantSetStart ● ConsultantNextObj ● ConsultantGetPercentDone ● ConsultantGetNumDirectVisited ●...

  • Page 225: Registering Agents With Consultants

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Registering agents with consultants Registering agents with consultants In order to modify or analyze documents, you must register your agent with the consultant by invoking method. ConsultantRegisterAgent Once the agent is registered with the consultant, it remains registered until a call to is made.

  • Page 226: Starting The Consultant

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Starting the consultant Starting the consultant method instructs the consultant to begin traversing a document, ConsultantTraverseFrom starting at a specific Cos object. The Cos object should be the catalog of a currently open document. The...

  • Page 227: Creating An Agent Class

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Creating an agent class Each Cos object has a simple Cos type and attributes, in the scheme of the document as a whole each object serves a particular purpose. The PDF object type assigned to each object represents that object's role in the PDF document.

  • Page 228: Creating Agent Constructors

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Creating agent constructors //Constructor / destructor DumpAllObjectsAgent(PDDoc hPDDoc); virtual ~DumpAllObjectsAgent(void); //Required methods virtual void ConsAgentPostProcess(void); virtual ASInt32 ObjFound(CosObj Obj, const PDFObjType* pObjTypeHierarchy, const ASUns32 SizeObjHierarchy, TraversalStack Stack,CosObj* pObjToReturn);...

  • Page 229: Post Processing Stage

    Acrobat, and draws heavily on the PDF file design for an appended save. Adobe Acrobat implements digital signatures using plug-ins that can handle both generic functions common to all digital signatures, and also specific kinds of signatures (signing methods), such as...

  • Page 230: The Pubsec Layer

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications The PubSec layer The following diagram shows the security plug-in relationships. Note: For information about the APIs that make up the Digital signature extended API, see the Acrobat and PDF Library API Reference.

  • Page 231: Digital Signature Components

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Digital signature components To register a handler with PubSec, perform the following tasks: 1. Implement the callbacks you need to provide customized functionality. Many of the callbacks for PubSec can be specified as NULL, in which case PubSec provides default behavior.

  • Page 232: Initializing The Digital Signature Plug-In

    Auto-validation may produce significant delays if it must read all of a large document from a CD-ROM or over a network, or if it must access a signature registry or authority over a network. Therefore, Adobe software only accesses signatures at user request.
  • Page 233 Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Understanding the process Saving a document The following steps describe how the digital signature plug-in saves a document: 1. The digital signature plug-in invokes your callback method to update the DSCommitSignProc document with the actual signature.
  • Page 234 Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Understanding the process Revalidating signatures If the user reopens the file, the signatures must be validated. If the user asks to validate one or more signature fields, the digital signature plug-in sequences through them one at a time. Your...

  • Page 235: Forms Extended Api

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Forms extended API The AcroForms Widget Annot handler calls into DigSig using four entries. These calls all reflect user actions taken in the document view, not the Signatures panel view.

  • Page 236: Weblink Extended Api

    Basic progress status services (progress monitor, wait cursor, and so on) ● The Weblink plug-in includes a standard driver, known as the Adobe Standard Web Driver. It allows support for transport mechanisms or web browsers to be added at a later time.

  • Page 237: Spelling Extended Api

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications Spelling extended API A driver is responsible for performing the following tasks: Connecting with external services (either directly or through an external application) ● Communicating with external services ●...

  • Page 238: Acrocolor Extended Api

    AcroColor extended API AcroColor is an HFT that allows you to access the AcroColor engine (ACE), which controls color profile management for Adobe Acrobat. Plug-ins can import the AcroColor HFT to use the color management methods. While not, strictly speaking, an “extended API” (since the API is not exposed from a plug-in) the AcroColor API is included here with the extended APIs since it doesn’t fit into the “layered”...
  • Page 239 Color settings, as listed in the Acrobat Preferences. Color settings files contain, for instance, references ● to color profiles, and apply across Adobe products. Additional support objects include a string object and preset lists of settings. You can create an ICC color profile from available data (...
  • Page 240 Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications AcroColor extended API Color conversion operations The Color Conversion API has been extended in Acrobat 8.0 to include new APIs that enable you to add color conversion operations to your plug-in or PDF Library applications. By using this extended API, you can convert a page based on a list of conversion actions.
  • Page 241 Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications AcroColor extended API Action modifiers The following action modifiers apply if the action converts the object: Render Intent: ● Override the color conversion with one of the ICC intents ●...
  • Page 242 Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications AcroColor extended API Converting a document to RGB You can use the AcroColor extended API to convert a document to RGB by performing the following tasks: 1. Create an instance of the data structure.

  • Page 243: Example 20.6 Converting A Page In A Pdf Document To Apple Rgb

    Adobe Acrobat SDK Working with Acrobat Extended APIs Developing Plug-ins and Applications AcroColor extended API The data element to pass to the progress monitor callback. You can pass if you do not want to NULL ● provide a progress monitor callback.

  • Page 244: Pdf Optimizer Api

    The PDF Optimizer API is available with the PDDocSaveWithParams Professional version of Acrobat, but not with the Standard version or with Adobe Reader. Using this API, you can reduce the size of bulky PDF files and run Distiller optimizations on PDF files without having to print them.

  • Page 245: Creating An Adobe Reader Plug-In

    Acrobat viewer (Standard or Professional) before trying to Reader-enable it. 2. Visit the Adobe web site and fill out an Adobe Reader Integration Key License Agreement. There is a fee involved. The Adobe Reader Integration Key Licensing Agreement can only be submitted as a web form.

  • Page 246: Creating Resource Files On The Mac Os Platform

    Creating resource files on the Mac OS platform 4. Return to the Adobe web site (the exact URL will be provided to you in your contract package), and upload only the public key as a ZIP, HQX, or TAR archive. You must submit your public key via the Internet.

  • Page 247: Enabling The Plug-In For Adobe Reader

    Creating resource files on the Windows platform This section discusses creating a resource file for an Adobe Reader plug-in on the Windows platform. When prompted for a path by either of the enabling tools, the filename is limited to 8:3 format. The path may be specified in relative or absolute form.

  • Page 248: Creating Resource Files On The Unix Platform

    Creating resource files on the UNIX platform This section discusses creating a resource file for an Adobe Reader plug-in on the UNIX platform. When prompted for a path by either of the enabling tools, the filename is limited to 8:3 format. The path may be specified in relative or absolute form.

  • Page 249: Enabling The Plug-In For Adobe Reader

    249. Troubleshooting There are a number of issues that can cause a plug-in not to load in Adobe Reader. The most common issues are documented here. If the problem persists, contact Acrobat Developer Support. The plug-in appears to be ignored by Adobe Reader There are a few possible causes of this issue.

  • Page 250: Index

    Index AVPageViewGetPageNum method 126, 136 AVPageViewGoTo method 124 About box 34 AVPageViewRectToDevice method 123, 128 accessing AVPageViewSetColor method 128 non-PDF files 85 AVPageViewToViewDest method 115 page contents 126 AVToolBar typedefs 98 acquiring AVToolButton typedefs 98 fonts 64 AVToolButtonNew method 100 objects 35 Acrobat agents 220 Acrobat Support layer 18...
  • Page 251 19 literal strings 180 drawing 36 loading plug-ins 29 DURING HANDLER block 214 memory usage 46 enabling for Adobe Reader 25 menus and menu items 34 errorcode macro 214 methods event handling 31 ASAtomGetString 110 events 31...
  • Page 252 Adobe Acrobat SDK Index Developing Plug-ins and Applications AVDocGetPageView 116, 124, 126, 136 modifying AVDocGetPDDoc 84, 124, 125, 126, 136 annotations 111 AVDocOpenFromFile 72 page contents 125 AVDocSetSelection 137 text elements 128 AVDocShowSelection 137 modifying user interface 33 AVPageViewDrawNow 124...
  • Page 253 Adobe Acrobat SDK Index Developing Plug-ins and Applications PDF documents (Continued) simple data type 22 inserting text 62 SnippetRunner application 56 modifying annotations 111 splash screen 34 opening 72, 74 StartInit.cpp file 53 optimizing 244 supported environments 39 printing 87...

Table of Contents