User manual ADOBE ACROBAT SDK 8.1

bc Developing Plug-ins and Applications Adobe® Acrobat® SDK April 2007 Version 8.1 © 2007 Adobe Systems Incorporated. All rights reserved. Adobe® Acrobat® SDK 8.1 Developing Plug-ins and Applications for Microsoft® Windows®, Mac OS®, Linux® and UNIX® Edition 2.0, April 2007 If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner. Any references to company names and company logos in sample material are for demonstration purposes only and are not intended to refer to any actual organization. Adobe, the Adobe logo, Acrobat, LiveCycle, PostScript, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. AIX is a trademark of International Business Machines Corporation in the United States and/or other countries. Apple and Mac OS are trademarks of Apple Computer, Inc., registered in the United States and other countries. HP-UX is a registered trademark of Hewlett-Packard Company. Intel is a registered trademark of Intel Corporation in the U.S. and other countries. JavaScript is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries. Linux is a registered trademark of Linus Torvalds. Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Red Hat is a trademark or registered trademark of Red Hat, Inc. in the United States and other countries. Solaris is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group in the U.S. and other countries. All other trademarks are the property of their respective owners. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Notice to U.S. Government End Users. The Software and Documentation are "Commercial Items," as that term is defined at 48 C.F.R. §2.101, consisting of "Commercial Computer Software" and "Commercial Computer Software Documentation," as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference. Contents List of Examples ......................................................................................................................... 11 Preface ........................................................................................................................................ 14 What's in this guide .....................................................................................................................................................................14 Who should read this guide? ...................................................................................................................................................14 Related documentation .............................................................................................................................................................14 1 Introduction ............................................................................................................................... 16 About plug-ins...............................................................................................................................................................................16 About the Acrobat core API......................................................................................................................................................17 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 Dynamically adding text to PDF documents ...............................................................................................................24 Understanding your target application ...............................................................................................................................24 New Acrobat core APIs ...............................................................................................................................................................25 2 Understanding Plug-ins ............................................................................................................ 27 About plug-in initialization.......................................................................................................................................................27 Plug-in loading and initialization .....................................................................................................................................28 Handshaking and Initialization .........................................................................................................................................28 Exporting HFTs........................................................................................................................................................................29 Importing HFTs and registering for notifications.......................................................................................................29 Initialization..............................................................................................................................................................................29 Unloading .................................................................................................................................................................................29 Summarizing a plug-in's life cycle ...................................................................................................................................30 Using callback functions............................................................................................................................................................30 Notifications ...................................................................................................................................................................................31 Handling events............................................................................................................................................................................31 Mouse clicks .............................................................................................................................................................................31 Adjust cursor............................................................................................................................................................................31 Key presses ...............................................................................................................................................................................31 3 Adobe Acrobat SDK Developing Plug-ins and Applications Contents 4 2 Understanding Plug-ins (Continued) Using plug-in prefixes.................................................................................................................................................................31 Obtaining a developer prefix.............................................................................................................................................31 Using a developer prefix .....................................................................................................................................................32 Plug-in name .....................................................................................................................................................................32 Menu prefixes ...................................................................................................................................................................32 Menu items prefixes .......................................................................................................................................................32 Tool prefixes ......................................................................................................................................................................32 Toolbar button prefixes.................................................................................................................................................32 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 Acquiring and releasing objects .............................................................................................................................................35 Debugging plug-ins ....................................................................................................................................................................35 Page view layers............................................................................................................................................................................36 Minimizing screen redrawing ..................................................................................................................................................36 Storing private data in PDF files..............................................................................................................................................37 Exporting data from PDF document objects .....................................................................................................................37 3 Creating Plug-in and PDF Library Applications ...................................................................... 39 Supported environments ..........................................................................................................................................................39 Working with platform-specific techniques .......................................................................................................................40 About platform-dependent data .....................................................................................................................................40 Portability techniques ..........................................................................................................................................................40 Windows techniques ............................................................................................................................................................41 Developing a Windows plug-in..................................................................................................................................41 Locating and loading plug-ins....................................................................................................................................41 Why a plug-in might not load .....................................................................................................................................41 Macros and project settings ........................................................................................................................................42 Interapplication communication ...............................................................................................................................42 Debugging .........................................................................................................................................................................42 Handling the thread local storage (TLS) limit........................................................................................................43 Using modal dialog boxes............................................................................................................................................43 Mac OS techniques................................................................................................................................................................44 Developing a Mac OS plug-in......................................................................................................................................44 Locating and loading plug-ins\ ..................................................................................................................................46 Using memory ..................................................................................................................................................................46 Resource file considerations........................................................................................................................................46 Mac OS-only methods....................................................................................................................................................47 Interapplication communication ...............................................................................................................................47 Adobe Acrobat SDK Developing Plug-ins and Applications Contents 5 3 Creating Plug-in and PDF Library Applications (Continued) Creating a sample plug-in.........................................................................................................................................................47 Including Acrobat SDK library files ..................................................................................................................................48 Adding the PIMain source file ...........................................................................................................................................53 Adding application logic.....................................................................................................................................................53 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 Detecting supported APIs...................................................................................................................................................59 Updates to ASCoord and AVRect .....................................................................................................................................60 Upgrading plug-ins in Windows.......................................................................................................................................60 Upgrading plug-ins on Mac OS.........................................................................................................................................61 Migrating a PDF Library application from CodeWarrior to Xcode..............................................................................61 4 Inserting Text into PDF Documents ......................................................................................... 62 About inserting text into a PDF document.........................................................................................................................62 Creating a new PDF document.........................................................................................................................................63 Creating a new page.............................................................................................................................................................63 Creating a container .............................................................................................................................................................63 Acquiring fonts .......................................................................................................................................................................64 Creating a PDEGraphicState object.................................................................................................................................65 Creating an ASFixedMatrix object ...................................................................................................................................65 Inserting text............................................................................................................................................................................65 Saving the PDF document..................................................................................................................................................67 Examining a PDF Library application source file...............................................................................................................67 5 Working with Documents and Files ......................................................................................... 72 Opening PDF documents..........................................................................................................................................................72 Opening a PDF document in an external window...........................................................................................................74 Creating a Window................................................................................................................................................................75 Defining the parameters for an external window......................................................................................................75 Creating a handler for an external window..................................................................................................................76 Displaying an open dialog box .........................................................................................................................................76 Displaying a PDF document within a window ............................................................................................................79 Bridging core API layers .............................................................................................................................................................83 Creating a PDDoc object .....................................................................................................................................................83 Creating a PDDoc object based on an open PDF document.................................................................................84 Accessing non-PDF files.......................................................................................................................................................85 Printing documents.....................................................................................................................................................................87 Adobe Acrobat SDK Developing Plug-ins and Applications Contents 6 6 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 Creating menu callback functions .........................................................................................................................................93 Determining if a menu item can be executed ...................................................................................................................96 7 Creating Toolbars and Buttons ................................................................................................ 97 About toolbars ..............................................................................................................................................................................97 About AVToolBar typedefs .................................................................................................................................................98 About AVToolButton typedefs..........................................................................................................................................98 Retrieving toolbars ......................................................................................................................................................................98 Creating toolbar buttons........................................................................................................................................................ 100 Setting help text for a button......................................................................................................................................... 101 Setting label text ................................................................................................................................................................. 101 Creating a sub-menu for a button ................................................................................................................................ 102 Retrieving existing toolbar buttons.................................................................................................................................... 102 Attaching a button to a toolbar ........................................................................................................................................... 103 Exposing a button in a web browser.................................................................................................................................. 104 Removing a button from a toolbar ..................................................................................................................................... 105 Creating toolbar button callback functions..................................................................................................................... 105 8 Creating Annotations ..............................................................................................................108 About annotations.................................................................................................................................................................... 108 Creating text annotations ...................................................................................................................................................... 108 Retrieving existing annotations........................................................................................................................................... 110 Modifying text annotations................................................................................................................................................... 111 9 Working with Bookmarks .......................................................................................................113 About bookmarks...................................................................................................................................................................... 113 Creating bookmarks ................................................................................................................................................................. 114 Defining bookmark actions............................................................................................................................................. 115 Creating a PDViewDestination object................................................................................................................... 115 Creating a AVPageView object ................................................................................................................................ 116 Assigning an action to a bookmark ....................................................................................................................... 116 Removing bookmark actions.......................................................................................................................................... 117 Opening and closing bookmarks .................................................................................................................................. 117 Retrieving bookmarks.............................................................................................................................................................. 118 Retrieving the root bookmark........................................................................................................................................ 118 Retrieving a specific bookmark...................................................................................................................................... 118 Retrieving all bookmarks.................................................................................................................................................. 119 Deleting bookmarks................................................................................................................................................................. 120 Adobe Acrobat SDK Developing Plug-ins and Applications Contents 7 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................................................................................................................................. 127 Modifying text elements .................................................................................................................................................. 128 11 Working with Words................................................................................................................131 About searching for words .................................................................................................................................................... 131 About PDWord typedefs .................................................................................................................................................. 131 About PDWordFinder typedefs ..................................................................................................................................... 132 Creating a PDWordFinder object......................................................................................................................................... 132 Extracting and displaying words ......................................................................................................................................... 134 Highlighting words................................................................................................................................................................... 136 12 Creating Handlers....................................................................................................................138 About handlers........................................................................................................................................................................... 138 Action handlers .......................................................................................................................................................................... 139 Annotation handlers ................................................................................................................................................................ 140 AVCommand handlers ............................................................................................................................................................ 140 Creating an AVCommand handler................................................................................................................................ 140 Invoking AVCommands.................................................................................................................................................... 141 Configuring AVCommands ............................................................................................................................................. 141 Setting input parameters........................................................................................................................................... 141 Setting configuration parameters .......................................................................................................................... 142 Setting AVCommand parameters........................................................................................................................... 142 Running commands........................................................................................................................................................... 143 Exposing AVCommands to the batch framework................................................................................................... 144 Adding a handler to the global command list ................................................................................................... 144 Supporting properties ................................................................................................................................................ 144 File format conversion handlers .......................................................................................................................................... 145 File specification handlers...................................................................................................................................................... 146 Selection servers........................................................................................................................................................................ 146 Tool callbacks.............................................................................................................................................................................. 147 Window handlers ...................................................................................................................................................................... 147 File systems.................................................................................................................................................................................. 148 Progress monitors ..................................................................................................................................................................... 149 Transition handlers ................................................................................................................................................................... 149 Adding message handling..................................................................................................................................................... 150 13 Registering for Event Notifications........................................................................................151 Registering event notifications ............................................................................................................................................ 151 Unregistering event notifications ....................................................................................................................................... 153 Adobe Acrobat SDK Developing Plug-ins and Applications Contents 8 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 .......................................................................................................................................... 159 Saving a file with an encryption dictionary ............................................................................................................... 159 Opening an encrypted file............................................................................................................................................... 159 15 Working with Unicode Paths ..................................................................................................160 About Unicode paths............................................................................................................................................................... 160 Creating Unicode file path application logic................................................................................................................... 160 Retrieving Unicode path values........................................................................................................................................... 161 Creating an ASFileSys object .......................................................................................................................................... 162 Creating an ASFileSys object that supports Unicode paths ................................................................................ 163 16 Working with Host Function Tables .......................................................................................164 About host function tables .................................................................................................................................................... 164 Exporting host function tables............................................................................................................................................. 165 Creating HFT methods ...................................................................................................................................................... 166 Creating HFT method definitions.................................................................................................................................. 166 Creating HFT callback functions.................................................................................................................................... 168 Creating new Host Function Tables ............................................................................................................................. 169 Examining HFT header and source files...................................................................................................................... 170 Examining an HFT header file .................................................................................................................................. 170 Examining an HFT source file ................................................................................................................................... 171 Importing an existing HFT...................................................................................................................................................... 173 Invoking HFT methods ............................................................................................................................................................ 174 Replacing HFT methods.......................................................................................................................................................... 174 Migrating non-HFT PDF Library applications to HFT applications .......................................................................... 176 17 Working with Cos Objects.......................................................................................................178 About Cos objects..................................................................................................................................................................... 178 About direct and indirect objects ................................................................................................................................. 179 About Cos object types..................................................................................................................................................... 179 Cos strings ....................................................................................................................................................................... 179 Cos arrays......................................................................................................................................................................... 181 Cos names ....................................................................................................................................................................... 181 Cos dictionaries ............................................................................................................................................................. 182 Cos streams..................................................................................................................................................................... 183 Working with Cos strings........................................................................................................................................................ 183 Creating Cos strings ........................................................................................................................................................... 183 Retrieving the string value............................................................................................................................................... 184 Working with Cos arrays ......................................................................................................................................................... 184 Creating Cos arrays............................................................................................................................................................. 184 Retrieving Cos array values ............................................................................................................................................. 185 Working with Cos dictionaries.............................................................................................................................................. 186 Creating Cos dictionaries ................................................................................................................................................. 186 Retrieving values from a Cos dictionary ..................................................................................................................... 187 Querying a Cos dictionary for a key.............................................................................................................................. 188 Adobe Acrobat SDK Developing Plug-ins and Applications Contents 9 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 .................................................................................................................................... 190 Inserting a Cos stream into a PDF document..................................................................................................... 192 Populating a PDF document with a content stream.............................................................................................. 195 18 Creating 3D Annotations ........................................................................................................203 Creating annotations ............................................................................................................................................................... 203 Adding 3D data to an annotation ....................................................................................................................................... 204 Creating the 3D annotation dictionary entries ........................................................................................................ 205 Specifying the 3D stream................................................................................................................................................. 205 Creating the stream object ....................................................................................................................................... 206 Adding the Cos stream to the annotation dictionary ..................................................................................... 207 Creating the attributes dictionary .......................................................................................................................... 207 Specifying JavaScript code........................................................................................................................................ 208 Setting the default view ................................................................................................................................................... 209 Setting the annotation appearance ............................................................................................................................. 210 Setting the activation dictionary................................................................................................................................... 213 19 Handling Exceptions ...............................................................................................................214 Creating exception handlers................................................................................................................................................. 214 Returning a value from an exception handler................................................................................................................ 215 Raising exceptions .................................................................................................................................................................... 215 Exception handling scenarios............................................................................................................................................... 215 Using goto statements...................................................................................................................................................... 215 Using nested exception handlers ................................................................................................................................. 216 Using register variables .................................................................................................................................................... 217 20 Working with Acrobat Extended APIs....................................................................................218 About Acrobat extended APIs .............................................................................................................................................. 218 Search extended API ................................................................................................................................................................ 219 Catalog extended API .............................................................................................................................................................. 219 PDF Consultant and Accessibility Checker extended API........................................................................................... 219 How the consultant works............................................................................................................................................... 221 Important issues for consultant development......................................................................................................... 222 Importing the consultant HFTs into a plug-in .......................................................................................................... 223 Creating and destroying consultants .......................................................................................................................... 224 Registering agents with consultants ........................................................................................................................... 225 Starting the consultant ..................................................................................................................................................... 226 Consultant object type identification.......................................................................................................................... 226 Creating an agent class..................................................................................................................................................... 227 Creating agent constructors ........................................................................................................................................... 228 Recognizing objects of interest ..................................................................................................................................... 228 Post processing stage........................................................................................................................................................ 229 Adobe Acrobat SDK Developing Plug-ins and Applications Contents 10 20 Working with Acrobat Extended APIs (Continued) Digital signature extended API ............................................................................................................................................ 229 The PubSec layer ................................................................................................................................................................. 230 Digital signature components ....................................................................................................................................... 231 Digital signature scenarios .............................................................................................................................................. 231 Initializing the digital signature plug-in ..................................................................................................................... 232 Understanding the process............................................................................................................................................. 232 Forms extended API ................................................................................................................................................................. 235 Weblink extended API ............................................................................................................................................................. 236 Weblink services .................................................................................................................................................................. 236 Writing a custom driver .................................................................................................................................................... 236 Spelling extended API ............................................................................................................................................................. 237 AcroColor extended API.......................................................................................................................................................... 238 PDF Optimizer API..................................................................................................................................................................... 244 21 Creating an Adobe Reader Plug-In.........................................................................................245 Enabling an Adobe Reader plug-in..................................................................................................................................... 245 Creating resource files on the Mac OS platform ............................................................................................................ 246 Creating the public and private key pairs .................................................................................................................. 246 Enabling the plug-in for Adobe Reader...................................................................................................................... 247 Creating resource files on the Windows platform......................................................................................................... 247 Creating the public and private key pairs .................................................................................................................. 247 Enabling the plug-in for Adobe Reader...................................................................................................................... 247 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 List of Examples Example 4.1 Example 4.2 Example 4.3 Example 4.4 Example 4.5 Example 4.6 Example 4.7 Example 4.8 Example 4.9 Example 5.1 Example 5.2 Example 5.3 Example 5.4 Example 5.5 Example 6.1 Example 6.2 Example 6.3 Example 7.1 Example 7.2 Example 7.3 Example 7.4 Example 7.5 Example 7.6 Example 7.7 Example 7.8 Example 7.9 Example 8.1 Example 8.2 Example 8.3 Example 9.1 Example 9.2 Example 9.3 Example 9.4 Example 9.5 Example 9.6 Example 9.7 Creating a new PDF document...................................................................................................................................63 Creating a new page.......................................................................................................................................................63 Creating a PDEContent object ....................................................................................................................................64 Acquiring a font that is used to draw text on a page .........................................................................................64 Creating a PDEGraphicState object ..........................................................................................................................65 Creating an ASFixedMatrix object .............................................................................................................................65 Inserting text into a PDF document..........................................................................................................................66 Saving a PDF document ................................................................................................................................................67 Examining a PDF Library application source file .................................................................................................68 Opening a PDF file...........................................................................................................................................................73 Opening a PDF document in an external window ..............................................................................................80 Creating a PDDoc object...............................................................................................................................................84 Creating a PDDoc object based on an open PDF document...........................................................................85 Accessing a non-PDF file...............................................................................................................................................85 Adding a menu command to an existing menu ..................................................................................................91 Adding a menu command to a new menu ............................................................................................................92 Creating menu callback functions.............................................................................................................................94 Retrieving a toolbar by name......................................................................................................................................99 Creating a toolbar button.......................................................................................................................................... 100 Setting a button's help text ...................................................................................................................................... 101 Setting a button's label text...................................................................................................................................... 102 Retrieving existing toolbar buttons ....................................................................................................................... 103 Attaching a button to a toolbar .............................................................................................................................. 104 Exposing a button in a web browser..................................................................................................................... 104 Removing a button from a toolbar ........................................................................................................................ 105 Creating a toolbar button callback function ...................................................................................................... 106 Creating text annotations.......................................................................................................................................... 109 Retrieving existing annotations .............................................................................................................................. 110 Modifying a text annotation..................................................................................................................................... 112 Creating bookmarks .................................................................................................................................................... 114 Assigning an action to a bookmark ....................................................................................................................... 116 Opening a bookmark .................................................................................................................................................. 117 Retrieving the root bookmark.................................................................................................................................. 118 Retrieving a specific bookmark ............................................................................................................................... 118 Retrieving existing bookmarks ................................................................................................................................ 119 Deleting a bookmark................................................................................................................................................... 121 11 Adobe Acrobat SDK Developing Plug-ins and Applications List of Examples 12 Example 10.1 Example 10.2 Example 10.3 Example 10.4 Example 10.5 Example 11.1 Example 11.2 Example 11.3 Example 12.1 Example 12.2 Example 12.3 Example 12.4 Example 12.5 Example 12.6 Example 13.1 Example 13.2 Example 15.1 Example 15.2 Example 15.3 Example 16.1 Example 16.2 Example 16.3 Example 16.4 Example 16.5 Example 16.6 Example 17.1 Example 17.2 Example 17.3 Example 17.4 Example 17.5 Example 17.6 Example 17.7 Example 17.8 Example 17.9 Example 17.10 Example 17.11 Example 17.12 Example 19.1 Displaying a page view............................................................................................................................................... 125 Creating a PDEContent object ................................................................................................................................. 126 Accessing page contents ........................................................................................................................................... 127 Determining page element types .......................................................................................................................... 127 Modifying page contents .......................................................................................................................................... 129 Creating a PDWordFinder object that is based on the current PDF document..................................... 133 Extracting and displaying words............................................................................................................................. 135 Highlighting a word in a PDF document ............................................................................................................. 137 Creating an AVCommand handler ......................................................................................................................... 141 Setting input parameters........................................................................................................................................... 142 Setting configuration parameters .......................................................................................................................... 142 Setting AVCommand parameters........................................................................................................................... 142 Running an AVCommand.......................................................................................................................................... 143 Exposing AVCommands to the batch framework ............................................................................................ 145 Registering for an event notification..................................................................................................................... 152 Unregistering an event notification....................................................................................................................... 153 Creating an ASFileSys object .................................................................................................................................... 162 Retrieving a host encoded platform path ........................................................................................................... 163 Retrieving a Unicode platform path ...................................................................................................................... 163 Creating an HFT callback function ......................................................................................................................... 168 Creating new Host Table Functions....................................................................................................................... 170 Examining an HFT header file .................................................................................................................................. 170 Examining an HFT source file ................................................................................................................................... 171 Importing an existing HFT......................................................................................................................................... 173 Replacing an HFT method ......................................................................................................................................... 175 Creating a Cos string ................................................................................................................................................... 183 Retrieving the string value from a CosDoc object............................................................................................ 184 Creating a Cos array..................................................................................................................................................... 185 Retrieving Cos array values ....................................................................................................................................... 186 Creating a Cos dictionary........................................................................................................................................... 187 Retrieving a value from a Cos dictionary ............................................................................................................. 188 Querying a Cos dictionary for a key ....................................................................................................................... 188 Creating a Cos name.................................................................................................................................................... 189 Retrieving the value of a name object .................................................................................................................. 189 Creating a stream dictionary .................................................................................................................................... 192 Inserting a Cos stream into a PDF document page.......................................................................................... 193 Creating a PDF document and populating it with a Cos content stream................................................ 197 Creating an exception handler ................................................................................................................................ 214 Adobe Acrobat SDK Developing Plug-ins and Applications List of Examples 13 Example 20.1 Example 20.2 Example 20.3 Example 20.4 Example 20.5 Example 20.6 Importing consultant HFTs ....................................................................................................................................... 223 Registering an agent with a consultant................................................................................................................ 225 Using the consultant traversal stack...................................................................................................................... 226 Creating an agent class .............................................................................................................................................. 227 Creating agent constructors..................................................................................................................................... 228 Converting a page in a PDF document to Apple RGB..................................................................................... 243 Preface Developing Plug-ins and Applications is one of several resources available to help you learn about Adobe® Acrobat® plug-in and Adobe® PDF Library application development. What's in this guide This guide describes Acrobat plug-in and PDF Library application development concepts and how to develop Acrobat plug-ins and PDF Library applications. It shows how your plug-in can manipulate and enhance the 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. Who should read this guide? This guide is intended for C/C++ developers responsible for developing Acrobat or Adobe Reader plug-ins or PDF Library applications. This document assumes that you are familiar with the Acrobat product family and are an experienced user of Acrobat products. Related documentation In addition to this guide, the resources in the table provide information about the Acrobat SDK. For information about A guide to the documentation in the Acrobat SDK. A guide to the sections of the Acrobat SDK that pertain to Adobe Reader. A guide to the sample code included with the Acrobat SDK. Prototyping code without the overhead of writing and verifying a complete plug-in or application. Detailed descriptions of DDE, OLE, Apple event, and AppleScript APIs for controlling Acrobat and Adobe Reader or for rendering PDF documents. Using JavaScriptTM to develop and enhance standard workflows in Acrobat and Adobe Reader. Detailed descriptions of JavaScript APIs for developing and enhancing workflows in Acrobat and Adobe Reader. See Acrobat SDK Documentation Roadmap Developing for Adobe Reader Guide to SDK Samples Snippet Runner Cookbook Interapplication Communication API Reference Developing Acrobat Applications Using JavaScript JavaScript for Acrobat API Reference 14 Adobe Acrobat SDK Developing Plug-ins and Applications Preface Related documentation 15 For information about Detailed explanation of IAC concepts, describes many of the objects and commands universally understood by applications. Detailed descriptions of the APIs for Acrobat and Adobe Reader plug-ins, as well as for PDF Library applications. See Developing Applications Using Interapplication Communication Acrobat and PDF Library API Reference 1 Introduction You can use the Acrobat SDK to create plug-ins for Adobe Reader and Acrobat as well as standalone applications that interact with and manipulate PDF documents. The Acrobat SDK contains two libraries: the Acrobat core API and the PDF Library API. The Acrobat core API contains a set of interfaces that enable you to develop plug-ins that integrate with Acrobat and Adobe Reader. The PDF Library API enables you to develop applications that interact with and manipulate PDF documents. It overlaps with the Acrobat core API (with the important exception of the AV-layer, which is only part of the Acrobat core API); however, the PDF Library API also extends the Acrobat core API with a small number of interfaces specific to the PDF Library API. This chapter introduces the Acrobat core API and PDF Library API. About plug-ins A plug-in is an application that uses the resources of Acrobat or Adobe Reader as a host environment. This means that a plug-in does not require complex user interface elements. However, it must perform certain basic functions to let Adobe Reader or Acrobat know of its presence. Plug-ins are dynamically-linked extensions to Acrobat or Adobe Reader and are written using the Acrobat core API, which is an ANSI C/C++ library. Plug-ins add custom functionality and are equivalent to dynamically-linked libraries (DLLs) on the Microsoft® Windows® platform; however, the plug-in file name extension is .api, not .dll. On Mac OS, the file name extension of a plug-in is acroplugin. After you develop a plug-in, you place it into the following directory: \Program Files\Adobe\Acrobat\plug_ins Acrobat or Adobe Reader must be restarted in order for the plug-in to be recognized. Three types of plug-ins exist: 1. Regular plug-ins. Most plug-ins fall under this category. 2. Reader-enabled plug-ins. Reader-enabled plug-ins access a limited set of APIs. These plug-ins are developed with permission from Adobe and require special processing to load under Adobe Reader. For information, see "Creating an Adobe Reader Plug-In" on page 245. 3. Certified plug-ins. Certified plug-ins have undergone extensive testing to ensure that they do not compromise the integrity of the 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 Adobe only. 16 Adobe Acrobat SDK Developing Plug-ins and Applications Introduction About the Acrobat core API 17 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. The Acrobat core API is supported on Windows (32 bit), Mac OS, Linux®, and some UNIX® platforms like SolarisTM, HP-UX, and AIX®. The following diagram illustrates the hierarchy of the Acrobat core API. Acrobat Viewer layer Portable Document layer Acrobat Support layer PDSEdit PDFEdit COS layer Acrobat Viewer layer The Acrobat Viewer (AV) layer enables plug-ins to control Acrobat and modify its user interface. Using AV methods, you can, for example, add menus and menu commands, add buttons to toolbars, open and close files, display simple dialog boxes, and perform many other application-level tasks. Note: AV layer methods are not available through the PDF Library API. Portable Document layer The Portable Document (PD) layer provides access to PDF document components such as pages and annotations. Closely related to the PD layer are two method groups, each of which controls a different aspect of a PDF document: PDFEdit methods deal with the physical representation of a PDF document. More specifically, PDFEdit methods handle page content as a list of objects whose values and attributes are modifiable. These methods allow your plug-in or PDF Library application to read, write, edit, and create page contents and page resources, which may contain fonts, images, and so on. PDSEdit methods deal with the logical structure of a PDF document. A PDF document's logical structure is built independently of its physical representation, with pointers from the logical structure to the physical representation, and the reverse. PDSEdit methods store the logical structure information. They enable your plug-in or PDF Library application to access PDF files by means of a structure tree. Having logical structure in PDF files facilitates navigating, searching, and extracting data from PDF documents. For example, PDSEdit methods can obtain logically-ordered content, independently of the drawing order. Adobe Acrobat SDK Developing Plug-ins and Applications Introduction Acrobat core API objects 18 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). This enables Acrobat to be used with other file systems, such as on-line systems. Cos layer The Cos Object System (Cos) layer provides access to the building blocks used to construct PDF documents. Cos methods allow plug-ins and PDF Library applications to manipulate low-level data in a PDF file, such as dictionary and data streams. For information, see "Working with Cos Objects" on page 178. Platform-specific methods In addition to the method groups represented in the previous diagram, the Acrobat core API includes platform-specific plug-in utilities to handle issues that are unique to Windows, Mac OS and Linux platforms. For information about these methods, see the Acrobat and PDF Library API Reference. Acrobat core API objects Most objects accessible through AV and PD layer methods are opaque. That is, they are neither pointers nor pointers to pointers. They provide equivalent functionality in that they reference an object's data rather than storing it. If you assign one object to another variable, both variables affect the same internal object. Objects are typically named using the following conventions: The name of the concrete definition for a complex type ends in Rec (for record). A pointer to a simple or complex type ends in P (for pointer). Opaque types do not contain a P suffix. For example, a PDDoc object references a PDF document. Three names identify complex types that provide callback methods: Monitor: A set of callbacks for an enumeration method. Server: An implementation of a service added by a plug-in. Handler: An implementation for a subtype of object handled by a plug-in Callback method names typically contain the suffix Proc (for procedure). Adobe Acrobat SDK Developing Plug-ins and Applications Introduction Acrobat core API objects 19 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 obtained by using other objects. Adobe Acrobat SDK Developing Plug-ins and Applications Introduction Acrobat core API methods 20 Acrobat core API methods Acrobat core API method names typically conform to the following syntax: