Adobe ACROBAT SDK 8.1 User manual

Adobe
Brand
Adobe
Model
ACROBAT SDK 8.1
Category
Desktop publishing software
Type
User manual
bbc
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.
3
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
Adobe Acrobat SDK Contents
Developing Plug-ins and Applications 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 Contents
Developing Plug-ins and Applications 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 Contents
Developing Plug-ins and Applications 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 Contents
Developing Plug-ins and Applications 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 Contents
Developing Plug-ins and Applications 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 Contents
Developing Plug-ins and Applications 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 Contents
Developing Plug-ins and Applications 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
11
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
Example 4.7 Inserting text into a PDF document..........................................................................................................................66
Example 4.8 Saving a PDF document................................................................................................................................................67
Example 4.9 Examining a PDF Library application source file .................................................................................................68
Example 5.1 Opening a PDF file...........................................................................................................................................................73
Example 5.2 Opening a PDF document in an external window ..............................................................................................80
Example 5.3 Creating a PDDoc object...............................................................................................................................................84
Example 5.4 Creating a PDDoc object based on an open PDF document...........................................................................85
Example 5.5 Accessing a non-PDF file...............................................................................................................................................85
Example 6.1 Adding a menu command to an existing menu ..................................................................................................91
Example 6.2 Adding a menu command to a new menu ............................................................................................................92
Example 6.3 Creating menu callback functions.............................................................................................................................94
Example 7.1 Retrieving a toolbar by name......................................................................................................................................99
Example 7.2 Creating a toolbar button.......................................................................................................................................... 100
Example 7.3 Setting a button’s help text ...................................................................................................................................... 101
Example 7.4 Setting a button’s label text...................................................................................................................................... 102
Example 7.5 Retrieving existing toolbar buttons....................................................................................................................... 103
Example 7.6 Attaching a button to a toolbar .............................................................................................................................. 104
Example 7.7 Exposing a button in a web browser..................................................................................................................... 104
Example 7.8 Removing a button from a toolbar ........................................................................................................................ 105
Example 7.9 Creating a toolbar button callback function ...................................................................................................... 106
Example 8.1 Creating text annotations.......................................................................................................................................... 109
Example 8.2 Retrieving existing annotations .............................................................................................................................. 110
Example 8.3 Modifying a text annotation..................................................................................................................................... 112
Example 9.1 Creating bookmarks .................................................................................................................................................... 114
Example 9.2 Assigning an action to a bookmark ....................................................................................................................... 116
Example 9.3 Opening a bookmark .................................................................................................................................................. 117
Example 9.4 Retrieving the root bookmark.................................................................................................................................. 118
Example 9.5 Retrieving a specific bookmark ............................................................................................................................... 118
Example 9.6 Retrieving existing bookmarks................................................................................................................................ 119
Example 9.7 Deleting a bookmark................................................................................................................................................... 121
Adobe Acrobat SDK List of Examples
Developing Plug-ins and Applications 12
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 .......................................................................................................................................... 129
Example 11.1 Creating a PDWordFinder object that is based on the current PDF document..................................... 133
Example 11.2 Extracting and displaying words............................................................................................................................. 135
Example 11.3 Highlighting a word in a PDF document ............................................................................................................. 137
Example 12.1 Creating an AVCommand handler ......................................................................................................................... 141
Example 12.2 Setting input parameters........................................................................................................................................... 142
Example 12.3 Setting configuration parameters .......................................................................................................................... 142
Example 12.4 Setting AVCommand parameters........................................................................................................................... 142
Example 12.5 Running an AVCommand.......................................................................................................................................... 143
Example 12.6 Exposing AVCommands to the batch framework ............................................................................................ 145
Example 13.1 Registering for an event notification..................................................................................................................... 152
Example 13.2 Unregistering an event notification....................................................................................................................... 153
Example 15.1 Creating an ASFileSys object.................................................................................................................................... 162
Example 15.2 Retrieving a host encoded platform path ........................................................................................................... 163
Example 15.3 Retrieving a Unicode platform path ...................................................................................................................... 163
Example 16.1 Creating an HFT callback function ......................................................................................................................... 168
Example 16.2 Creating new Host Table Functions....................................................................................................................... 170
Example 16.3 Examining an HFT header file .................................................................................................................................. 170
Example 16.4 Examining an HFT source file ................................................................................................................................... 171
Example 16.5 Importing an existing HFT......................................................................................................................................... 173
Example 16.6 Replacing an HFT method......................................................................................................................................... 175
Example 17.1 Creating a Cos string ................................................................................................................................................... 183
Example 17.2 Retrieving the string value from a CosDoc object............................................................................................ 184
Example 17.3 Creating a Cos array..................................................................................................................................................... 185
Example 17.4 Retrieving Cos array values ....................................................................................................................................... 186
Example 17.5 Creating a Cos dictionary........................................................................................................................................... 187
Example 17.6 Retrieving a value from a Cos dictionary ............................................................................................................. 188
Example 17.7 Querying a Cos dictionary for a key ....................................................................................................................... 188
Example 17.8 Creating a Cos name.................................................................................................................................................... 189
Example 17.9 Retrieving the value of a name object.................................................................................................................. 189
Example 17.10 Creating a stream dictionary .................................................................................................................................... 192
Example 17.11 Inserting a Cos stream into a PDF document page.......................................................................................... 193
Example 17.12 Creating a PDF document and populating it with a Cos content stream................................................ 197
Example 19.1 Creating an exception handler................................................................................................................................ 214
Adobe Acrobat SDK List of Examples
Developing Plug-ins and Applications 13
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..................................................................................................................................... 228
Example 20.6 Converting a page in a PDF document to Apple RGB..................................................................................... 243
14
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 See
A guide to the documentation in the Acrobat SDK. Acrobat SDK Documentation Roadmap
A guide to the sections of the Acrobat SDK that pertain to
Adobe
Reader.
Developing for Adobe Reader
A guide to the sample code included with the Acrobat SDK. Guide to SDK Samples
Prototyping code without the overhead of writing and
verifying
a complete plug-in or application.
Snippet Runner Cookbook
Detailed descriptions of DDE, OLE, Apple event, and
AppleScript
APIs for controlling Acrobat and Adobe Reader
or
for rendering PDF documents.
Interapplication Communication
API Reference
Using JavaScript™ to develop and enhance standard
workflows
in Acrobat and Adobe Reader.
Developing Acrobat Applications
Using JavaScript
Detailed descriptions of JavaScript APIs for developing and
enhancing workflows in Acrobat and Adobe
Reader.
JavaScript for Acrobat API Reference
Adobe Acrobat SDK Preface
Developing Plug-ins and Applications Related documentation 15
Detailed explanation of IAC concepts, describes many of
the objects and commands universally understood by
applications.
Developing Applications Using
Interapplication Communication
Detailed descriptions of the APIs for Acrobat and
Adobe
Reader plug-ins, as well as for PDF Library
applications.
Acrobat and PDF Library API Reference
For information about See
16
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.
Adobe Acrobat SDK Introduction
Developing Plug-ins and Applications 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 Solaris™, HP-UX, and AIX®.
The following diagram illustrates the hierarchy of the Acrobat core API.
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.
PDFEdit PDSEdit
COS layer
Acrobat Viewer
Portable Document
layer
layer
Acrobat
Support
layer
Adobe Acrobat SDK Introduction
Developing Plug-ins and Applications 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 Introduction
Developing Plug-ins and Applications 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 Introduction
Developing Plug-ins and Applications Acrobat core API methods 20
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).
object: identifies the object upon which the method acts (for example, menu).
verb: specifies an action that the method performs (for example, get or set). See the table that follows
this list for the most commonly used verbs in method names.
thing: specific to each method, usually an object of the operation. May not always be present.
The following table lists some common verbs that are used in method names and describes their meaning.
Verb Description
Acquire Obtains a shareable resource from a parent object or increments a reference counter
for an object. The shared object is not destroyed until all acquires have released it.
Example: AVMenuItemAcquire
Add Adds an object as a child to the current object.
Example: PDBookmarkAddChild
AddNew Creates a new object using the specified parameters and adds the new object to the
current object.
Example: PDBookmarkAddNewChild
Close Destroys an object that was opened and closes the underlying storage or stream.
Example: ASFileClose
Create Creates a new object of a given type.
Example: PDDocCreatePage.
Delete Removes the second object from the current object and destroys the second object.
Example: PDDocDeletePages
Destroy Destroys the specified object and releases its resources immediately.
Example: PDBookmarkDestroy
Enum Enumerates the specified descendant objects of the current object.
Example: PDDocEnumFonts
Get Retrieves a specific object attribute.
Example: AVWindowGetTitle
Is Retrieves a Boolean attribute of the object.
Example: PDBookmarkIsOpen
New Creates a new unattached object.
Example: AVMenuNew
Open Opens an object from storage or a stream.
Example: AVDocOpenFromFile
Release Releases a shared object.
Example: PDPageRelease
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
  • Page 1 1
  • Page 2 2
  • Page 3 3
  • Page 4 4
  • Page 5 5
  • Page 6 6
  • Page 7 7
  • Page 8 8
  • Page 9 9
  • Page 10 10
  • Page 11 11
  • Page 12 12
  • Page 13 13
  • Page 14 14
  • Page 15 15
  • Page 16 16
  • Page 17 17
  • Page 18 18
  • Page 19 19
  • Page 20 20
  • Page 21 21
  • Page 22 22
  • Page 23 23
  • Page 24 24
  • Page 25 25
  • Page 26 26
  • Page 27 27
  • Page 28 28
  • Page 29 29
  • Page 30 30
  • Page 31 31
  • Page 32 32
  • Page 33 33
  • Page 34 34
  • Page 35 35
  • Page 36 36
  • Page 37 37
  • Page 38 38
  • Page 39 39
  • Page 40 40
  • Page 41 41
  • Page 42 42
  • Page 43 43
  • Page 44 44
  • Page 45 45
  • Page 46 46
  • Page 47 47
  • Page 48 48
  • Page 49 49
  • Page 50 50
  • Page 51 51
  • Page 52 52
  • Page 53 53
  • Page 54 54
  • Page 55 55
  • Page 56 56
  • Page 57 57
  • Page 58 58
  • Page 59 59
  • Page 60 60
  • Page 61 61
  • Page 62 62
  • Page 63 63
  • Page 64 64
  • Page 65 65
  • Page 66 66
  • Page 67 67
  • Page 68 68
  • Page 69 69
  • Page 70 70
  • Page 71 71
  • Page 72 72
  • Page 73 73
  • Page 74 74
  • Page 75 75
  • Page 76 76
  • Page 77 77
  • Page 78 78
  • Page 79 79
  • Page 80 80
  • Page 81 81
  • Page 82 82
  • Page 83 83
  • Page 84 84
  • Page 85 85
  • Page 86 86
  • Page 87 87
  • Page 88 88
  • Page 89 89
  • Page 90 90
  • Page 91 91
  • Page 92 92
  • Page 93 93
  • Page 94 94
  • Page 95 95
  • Page 96 96
  • Page 97 97
  • Page 98 98
  • Page 99 99
  • Page 100 100
  • Page 101 101
  • Page 102 102
  • Page 103 103
  • Page 104 104
  • Page 105 105
  • Page 106 106
  • Page 107 107
  • Page 108 108
  • Page 109 109
  • Page 110 110
  • Page 111 111
  • Page 112 112
  • Page 113 113
  • Page 114 114
  • Page 115 115
  • Page 116 116
  • Page 117 117
  • Page 118 118
  • Page 119 119
  • Page 120 120
  • Page 121 121
  • Page 122 122
  • Page 123 123
  • Page 124 124
  • Page 125 125
  • Page 126 126
  • Page 127 127
  • Page 128 128
  • Page 129 129
  • Page 130 130
  • Page 131 131
  • Page 132 132
  • Page 133 133
  • Page 134 134
  • Page 135 135
  • Page 136 136
  • Page 137 137
  • Page 138 138
  • Page 139 139
  • Page 140 140
  • Page 141 141
  • Page 142 142
  • Page 143 143
  • Page 144 144
  • Page 145 145
  • Page 146 146
  • Page 147 147
  • Page 148 148
  • Page 149 149
  • Page 150 150
  • Page 151 151
  • Page 152 152
  • Page 153 153
  • Page 154 154
  • Page 155 155
  • Page 156 156
  • Page 157 157
  • Page 158 158
  • Page 159 159
  • Page 160 160
  • Page 161 161
  • Page 162 162
  • Page 163 163
  • Page 164 164
  • Page 165 165
  • Page 166 166
  • Page 167 167
  • Page 168 168
  • Page 169 169
  • Page 170 170
  • Page 171 171
  • Page 172 172
  • Page 173 173
  • Page 174 174
  • Page 175 175
  • Page 176 176
  • Page 177 177
  • Page 178 178
  • Page 179 179
  • Page 180 180
  • Page 181 181
  • Page 182 182
  • Page 183 183
  • Page 184 184
  • Page 185 185
  • Page 186 186
  • Page 187 187
  • Page 188 188
  • Page 189 189
  • Page 190 190
  • Page 191 191
  • Page 192 192
  • Page 193 193
  • Page 194 194
  • Page 195 195
  • Page 196 196
  • Page 197 197
  • Page 198 198
  • Page 199 199
  • Page 200 200
  • Page 201 201
  • Page 202 202
  • Page 203 203
  • Page 204 204
  • Page 205 205
  • Page 206 206
  • Page 207 207
  • Page 208 208
  • Page 209 209
  • Page 210 210
  • Page 211 211
  • Page 212 212
  • Page 213 213
  • Page 214 214
  • Page 215 215
  • Page 216 216
  • Page 217 217
  • Page 218 218
  • Page 219 219
  • Page 220 220
  • Page 221 221
  • Page 222 222
  • Page 223 223
  • Page 224 224
  • Page 225 225
  • Page 226 226
  • Page 227 227
  • Page 228 228
  • Page 229 229
  • Page 230 230
  • Page 231 231
  • Page 232 232
  • Page 233 233
  • Page 234 234
  • Page 235 235
  • Page 236 236
  • Page 237 237
  • Page 238 238
  • Page 239 239
  • Page 240 240
  • Page 241 241
  • Page 242 242
  • Page 243 243
  • Page 244 244
  • Page 245 245
  • Page 246 246
  • Page 247 247
  • Page 248 248
  • Page 249 249
  • Page 250 250
  • Page 251 251
  • Page 252 252
  • Page 253 253

Adobe ACROBAT SDK 8.1 User manual

Adobe
Brand
Adobe
Model
ACROBAT SDK 8.1
Category
Desktop publishing software
Type
User manual
Download PDF
report

Ask a question and I''ll find the answer in the document

Finding information in a document is now easier with AI

Related papers

Other documents