bb
c
Developing Plug-ins and Applications
Adobe
®
Acrobat
SDK
April 2007
Version 8.1
Page 1: ...bbc Developing Plug ins and Applications Adobe Acrobat SDK April 2007 Version 8 1...
Page 2: ...red 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 i...
Page 3: ...t 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 Acrob...
Page 4: ...ng 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 Libra...
Page 5: ...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...
Page 6: ...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 Cr...
Page 7: ...dlers 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 param...
Page 8: ...ing 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...
Page 9: ...fault 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 Ra...
Page 10: ...r 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...
Page 11: ...ple 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...
Page 12: ...ing 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...
Page 13: ...porting 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...
Page 14: ...at 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...
Page 15: ...ts describes many of the objects and commands universally understood by applications Developing Applications Using Interapplication Communication Detailed descriptions of the APIs for Acrobat and Adob...
Page 16: ...amically 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...
Page 17: ...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 physi...
Page 18: ...des 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...
Page 19: ...ct 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...
Page 20: ...ntil 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 a...
Page 21: ...ays paired with a corresponding Release method and have the additional side effect of incrementing or decrementing a reference count The Acrobat core API uses Acquire and Release methods to perform va...
Page 22: ...y filling out a complex structure PDFontMetrics To define a data handler or server For example your plug in must provide a complex structure populated with callback methods AVAnnotHandlerRec when it r...
Page 23: ...eating Plug in and PDF Library Applications on page 39 Note The remaining parts of this section describe tasks that you can perform by using either the Acrobat core API or the PDF Library API and refe...
Page 24: ...pe in an annotation it can provide support for multiple fonts or text styles or it can support annotations that can only be viewed by specific users For example you can use the Acrobat core API to cre...
Page 25: ...lbar buttons and menu items that enable editing Plug ins that need to check whether or not they are running under Adobe Reader should do so as early in initialization as possible Plug ins that create...
Page 26: ...ithParamsInCosDoc PDEFormGetBBox PDEFormGetMatrix PDEImageCreateInCosDoc PDEScratchDocCleanup PDFileSpecAcquireASPathEx PDFileSpecGetDIPathEx PDFileSpecNewFromASPathEx PDFLibraryRegisterRNG PDOCRegist...
Page 27: ...ted to plug ins page 31 Handling events Describes event handling and the different event types such as mouse clicks page 31 Using plug in prefixes Describes how to use plug in prefixes when creating p...
Page 28: ...haking and Initialization Acrobat and Adobe Reader perform a handshake with each plug in as it is opened and loaded During handshaking the plug in specifies its name several initialization procedures...
Page 29: ...if another plug in initializes first and performs an operation such as creating a PDF document which causes a notification to be sent Plug ins must be prepared to correctly handle notifications as so...
Page 30: ...backCreateProto ASCallbackCreateReplacement and ASCallbackCreateNotification methods to convert functions into callback functions and to perform type checking This enables the compiler to determine wh...
Page 31: ...method If all of those procedures return false the event is passed to the active tool If that returns false the event is passed to any annotation at the current location Key presses Key presses are fi...
Page 32: ...used in plug in handshaking must use the following syntax Prefix_PluginName hsData extensionName ASAtomFromString ADBE_SuperCrop Menu prefixes Menu names must use the following syntax Prefix MenuName...
Page 33: ...g similar data can be assured that their plug ins can exchange data For more information regarding private data in PDF files see the PDF Reference Note For information about Cos dictionaries such as t...
Page 34: ...splaying the first document These changes take effect the next time Acrobat or Adobe Reader is started About Adobe Plug ins is a standard menu command in the Help menu This menu command contains a sub...
Page 35: ...classes derive from a base class which overrides new such as the class CSafeAlloc found in SafeAlloc h If you use an Acquire method to obtain an object you must subsequently use a Release method to co...
Page 36: ...lers provided by plug ins can reside in any layer For example a plug in could choose for its annotations to be between the page contents and links such as in layer 0 5 because layers are numbers of ty...
Page 37: ...e names Keys registered by third parties as well as keys whose prefix is registered that are applicable only to a limited set of users Adobe maintains a registry of these names and prefixes Keys that...
Page 38: ...PDDoc object on page 83 A PDSElement instance that represents PDF structural elements An ASStm object that represents XML content converted from information from labels An ASBool value that specifies...
Page 39: ...isted compiler versions Topic Description See Supported environments Describes supported environments for plug in and PDF Library application development page 39 Working with platform specific techniq...
Page 40: ...value Constants that indicate for example that a file could not be opened because it was not found The following are platform specific data types that do not appear explicitly in the API but are used...
Page 41: ...sed It s possible for a developer to run some initialization code in DLLMain such as allocating memory before its PluginMain procedure is called by Acrobat or Adobe Reader If you do this it s importan...
Page 42: ...its OLE automation and there cannot be two MFC based OLE automation servers in the same process OLE or ActiveX server plug ins must be implemented using the ActiveX Template Library Plug ins should us...
Page 43: ...multi threaded DLL runtime library Both the DLL and static versions of the runtime libraries occupy a TLS slot However many plug ins shipped with Acrobat or Adobe Reader use the DLL version so the ru...
Page 44: ...eloper tools contains the correct frameworks and libraries as well as extensive documentation on making plug ins and applications Mach O and Carbon compliant Note Acrobat SDK samples are built against...
Page 45: ...s related parent SDK configuration file for example ProjectDefault xconfig includes Default xcconfig and ProjectResources xcconfig includes Resources xcconfig Generally SDK level setting definitions a...
Page 46: ...e system and not from the application s memory partition For information see Acquiring and releasing objects on page 35 Memory allocation guidelines are particularly important in Mac OS to insure that...
Page 47: ...y for the platform and development environment by the header file PIPrefix h You are encouraged to use this header file Mac OS only methods Plug ins should not use the ASPathFromPlatformPath method in...
Page 48: ...rmation about linking to library files The Acrobat SDK library files are separated into the following categories SDK Header files that are common to most plug ins and that are generally referenced fro...
Page 49: ...ros and structures that are required to use the ASExtra HFT ASExtraProcs h Catalog of functions exported by the ASExtra HFT ASExtraVers h ASExtra HFT name and version ASKey h Definition of standard ke...
Page 50: ...for the Acrobat Form plug in HFTLibrary h Product file for the Acrobat HFT library definition Library h Product file for the Acrobat library definition MacCalls h HFT for the Mac OS platform MacPlatf...
Page 51: ...DF Edit error codes used with ASRaise PEExpT h Types macros structures etc required to use the PDFEdit HFTs PERCalls h Types macros structures etc required to use the PDFEditRead HFT PERProcs h Catalo...
Page 52: ...ug in s resource file on top of the resource chain before calling the real implementation SafeResources h Interface definitions for SafeResources cpp SmartPDPage h Class containing a thin wrapper for...
Page 53: ...n the Starter plug in and paste it For information about these methods see About plug in initialization on page 27 The entry point to a plug in is the PluginInit method For example if you add the foll...
Page 54: ...ibraries Fonts used in the library s basic operations Sample applications and code snippets showing how to use the library for a variety of purposes Documentation discussing development techniques and...
Page 55: ...e Mac OS samples are provided as application packages This format is normal for double clickable applications but they can also be run from the command line To run them from the command line you can e...
Page 56: ...cations with the Adobe PDF Library This section details the compiler environment variables macros required to build applications against the Adobe PDF Library On all platforms you must define the PROD...
Page 57: ...by searching the paths specified by the PATH environment variable as well as the folder in which the application was launched Mac OS The Mac OS libraries use a precompiled header and prefix file to de...
Page 58: ...e structure before passing it to PDFLInit size denotes the size of the structure and can be obtained with sizeof PDFLDataRec listLen is the number of directories listed in dirList dirList is an array...
Page 59: ...r for your plug in to use new functionality that is available with the Acrobat 8 SDK such as the ability to work with Unicode named files you must update the directory that stores header and library f...
Page 60: ...change them accordingly If you are currently using ASCoord for any coordinates other than those listed above then you may be using ASCoord inappropriately and it should be changed You should also repl...
Page 61: ...KConfiguration Xcode configuration files and ProjectConfigurations files included in the Acrobat 8 SDK Note As of Acrobat 8 0 SDK CodeWarrior is no longer supported Migrating a PDF Library application...
Page 62: ...ument This functionality is useful for dynamically updating a PDF document with information obtained during run time You can insert text into a PDF document by performing the following tasks 1 Create...
Page 63: ...specifies the page number after which the new page is inserted Specify PDBeforeFirstPage to insert the new page at the beginning of the PDF document An ASFixedRect object that specifies the page size...
Page 64: ...voking the PDFindSysFont method and passing the following arguments The address of the PDEFontAttrs object Size of the PDEFontAttrs object in bytes A value that specifies a PDSysFontMatchFlags value F...
Page 65: ...e object and set its attributes PDEGraphicState gState PDEColorSpace pdeColorSpace PDEColorSpaceCreateFromName ASAtomFromString DeviceGray memset gState 0 sizeof PDEGraphicState gState strokeColorSpec...
Page 66: ...x object on page 65 The address of the ASFixedMatrix object that holds the matrix for the line width when stroking text It is recommended that you pass NULL 3 Insert text into the page content by invo...
Page 67: ...file is saved An ASFileSys object that represents the file system For information see Creating an ASFileSys object on page 162 A progress monitor value Invoke the AVAppGetDocProgressMonitor method to...
Page 68: ...xample is a source file that inserts text into a PDF document Example 4 9 Examining a PDF Library application source file ifdef MAC_ENV include Carbon Carbon h else include sys types h include sys sta...
Page 69: ...PDEColorSpace pdeColorSpace ColorSpace PDEGraphicState gState Graphic state to apply to operation char HelloWorldStr Hello There Text to write to the PDF ifdef MAC_ENV ASPathName macPath endif Create...
Page 70: ...Ten gState flatness fixedOne gState lineWidth fixedOne Create an ASFixedMatrix object memset textMatrix 0 sizeof textMatrix Set the buffer size textMatrix a Int16ToFixed 24 Set font width and height t...
Page 71: ...e pdDoc PDSaveFull PDSaveLinearized macPath NULL NULL NULL ASFileSysReleasePath NULL macPath endif Release all objects PDERelease PDEObject pdeFont PDERelease PDEObject pdeText i PDPageReleasePDEConte...
Page 72: ...is AVDocOpenFromFile Before you invoke this method you must create an ASPathName object which is a platform independent path value that specifies the PDF file to open As of Acrobat or Adobe Reader 8...
Page 73: ...me object by displaying an open dialog box For information see Displaying an open dialog box on page 76 To programmatically open a PDF file in Acrobat or Adobe Reader invoke the AVDocOpenFromFile meth...
Page 74: ...chapter you must also use the following typedefs to open a PDF document in an external window AVDocOpenParamsRec defines required parameters for opening a PDF document in a window This typedef enable...
Page 75: ...played In the Windows operating system the coordinates are MDI client coordinates In Mac OS the coordinates are global screen coordinates This attribute is ignored if the useFrame attribute is false u...
Page 76: ...tains callback functions that implement a window handler After you create an ExternalDocServerCreationDataRec object allocate its buffer size and set the following attributes size The size of the data...
Page 77: ...le An ASText object that specifies the title for the dialog box This attribute can be NULL in which case the default title is used actionButtonTitle An ASText object that specifies the title of the ac...
Page 78: ...ialogParamsRec dialogParams size sizeof AVOpenSaveDialogParamsRec dialogParams fileFilters filterRecP dialogParams numFileFilters 1 8 Set the AVFileFilterRec object s filterDescription attribute by in...
Page 79: ...ystem in which the PDF file is located For information see Creating an ASFileSys object on page 162 An ASPathName object that represents the path in which the PDF file is located An ASFileMode object...
Page 80: ...ion that opens a PDF document in an external window ACCB1 void ACCB2 OpenExternalWindow void data Declare local variables ASPathName pathName ASInt32 retVal ASFileSys myFileSys bool bWindowIsOpen fals...
Page 81: ...E_READ gDocInfo file if retVal 0 Create a ASText object used to display in the new window ASText title ASTextFromScriptText PDF Viewer kASRomanScript Opens and displays a document from a file using th...
Page 82: ...tes that belong to the AVFileFilterRec object memset filterRec 0 sizeof AVFileFilterRec filterRec fileDescs descRec filterRec numFileDescs 1 filterRecP filterRec Set attributes that belong to the AVOp...
Page 83: ...to access other layers from the AV layer There are several bridge methods which connect the different API layers AV PD and Cos All AVDoc objects have an underlying PDDoc object Operations on an AVDoc...
Page 84: ...s ASGetDefaultFileSysForPath pathType myPath ASPathName pathName ASFileSysCreatePathName fileSys pathType myPath NULL Create the authentication callback myAuthProcPtr ASCallbackCreateProto PDAuthProc...
Page 85: ...rror message if something goes wrong ASFileSysOpenFile opens a file using the modes specified ASFileWrite writes data to the file ASFileClose closes the file ASFileRead reads data from the file ASFile...
Page 86: ...thname ASPathName path NULL ASFile TheFile NULL ASInt32 err 0 ASInt32 mode ASFILE_READ char Data 500 char buf 500 path MakeCrossPlatformASPathName pathname if path NULL AVAlertNote Unable to gain acce...
Page 87: ...job settings are used Printing is complete when this method returns The AVDocPrintPagesWithParams method prints a document with a full range of options Printing is complete when this method returns I...
Page 88: ...that enables user to invoke specific functionality You can for example click the Open command that is located on the File menu to open an existing PDF file Using the Acrobat core API you can programma...
Page 89: ...e Using plug in prefixes on page 31 About AVMenuItem typedefs An AVMenuItem is a menu command within a menu It contains the following attributes A name A keyboard shortcut A callback function to execu...
Page 90: ...pendent name of the menu to create For information see Using plug in prefixes on page 31 An ASExtension value that registers the menu For information about an ASExtension value see the Acrobat and PDF...
Page 91: ...to which a menu command is attached An AVMenuItem object that is attached The location in the menu that specifies where the command is added You can specify APPEND_MENUITEM to append the menu command...
Page 92: ...lared see the plug in samples that accompany the Acrobat SDK Adding a menu command to a new menu The following code example creates a new menu command that displays the text Show Message and attaches...
Page 93: ...hecked For the purpose of this discussion a simplistic user defined function named ShowMessage is introduced This method displays a message box by invoking the AVAlertNote method The following code ex...
Page 94: ...After you create an AVExecuteProc callback invoke the AVMenuItemSetExecuteProc method to associate a menu command with a callback That is when a user selects a specific menu command Acrobat or Adobe R...
Page 95: ...AVmenubarAcquireMenuByName Themenubar File if FileMenu Create a new menu item NewItem AVMenuItemNew Show Message ADBE ExternWin NULL true NO_SHORTCUT 0 NULL gExtensionID if NewItem NULL AVAlertNote Un...
Page 96: ...promise a user s privacy or system For example it was possible to use the app execMenuItem JavaScript method to obtain data from a document by creating the equivalent to a user selecting the menu sequ...
Page 97: ...ment The following illustration shows two toolbars located in Acrobat Topic Description See About toolbars Describes the characteristics of a form based application page 97 Retrieving toolbars Describ...
Page 98: ...olbar Like menu items a callback function that is executed when the button is clicked must be defined For information see Creating toolbar button callback functions on page 105 A plug in can invoke a...
Page 99: ...the Hand tool Commenting Commenting Contains buttons that enable you to perform commenting operations such as using the Notes tool Drawing Markups AdvCommenting Contains buttons that enable you to per...
Page 100: ...hing a button to a toolbar on page 103 It is strongly recommended that you create an AVIcon object when creating a new button To create an AVIcon object you must invoke platform specific APIs That is...
Page 101: ...SE FALSE Set a button s help text const char helpText Open PDF in external window AVToolButtonSetHelpText MyButton helpText Setting label text A button s label text is the text that is displayed besid...
Page 102: ...An AVToolButton object that specifies a button to which the menu is attached An AVMenu object that represents the menu For information see Creating Menus and Menu Commands on page 88 Tip To view an ex...
Page 103: ...Acrobat To attach a button to a toolbar invoke the AVToolBarAddButton method and pass the following arguments An AVToolBar object that represents the toolbar to which the button is attached An AVToolB...
Page 104: ...wser by invoking the AVToolButtonSetExternal method Pass the following arguments to the AVToolButtonSetExternal method An AVToolButton object that represents the button to expose within a web browser...
Page 105: ...ar AVToolButton mySecureButton AVToolBarGetButtonByName myToolBar ASAtomFromString SecureTask if mySecureButton NULL AVAlertNote The button was not successfully retrieved return Remove the SecureTask...
Page 106: ...owButtonMessage After you create an AVExecuteProc callback you can invoke the AVToolButtonSetExecuteProc method to associate a button with a callback That is when a user clicks a button Acrobat or Ado...
Page 107: ...tonSetExecuteProc MyButton ExecProcPtr NULL Attach the button AVToolBarAddButton ToolBar MyButton FALSE NULL Release the callback function ASCallbackDestroy ExecProcPtr return true ACCB1 ASBool ACCB2...
Page 108: ...nnot object corresponds to a link annotation You can use PDAnnot methods to get and set various annotation properties such as color date title location and subtype For example you can invoke the PDAnn...
Page 109: ...ts A PDTextAnnot object that represents the annotation for which text is set A character pointer that specifies the text to set An ASInt32 object that specifies the length of the character pointer 8 A...
Page 110: ...e method and passing the following arguments A PDDoc object that represents the PDF document that contains the page An ASInt32 object that represents the page number 4 After you obtain a PDPage object...
Page 111: ...he correct subtype by invoking the PDAnnotGetSubtype method This method requires a PDAnnot object and returns an ASAtom object that specifies the annotation s subtype When modifying a text annotation...
Page 112: ...ument page PDDocAcquirePage myPDDoc i Get each annotation on the page for i2 0 i2 PDPageGetNumAnnots page i2 Get a specific annotation annot PDPageGetAnnot page i2 if PDAnnotIsValid annot Determine if...
Page 113: ...location in the current document although other actions can be specified Every document has a root bookmark The root bookmark does not represent a physical bookmark that appears in Adobe Reader or Ac...
Page 114: ...mark object that represents the parent bookmark in this case the parent bookmark is also the document s root bookmark and an ASAtom object that represents the bookmark s title 3 Create a PDBookmark ob...
Page 115: ...hat represents the destination document This object is the same object that is specified as the first parameter The PDActionNewFromDest method returns a PDAction method Creating a PDViewDestination ob...
Page 116: ...ion to a bookmark After you create both an AVPageView object and an PDViewDestination object you can create a PDAction object and assign it to a specific bookmark by invoking the PDBookmarkSetAction m...
Page 117: ...to open or close An ASBool value that specifies whether to open or close the bookmark The value true specifies to open the bookmark and the value false specifies to close the bookmark Before you invok...
Page 118: ...arkGetFirstChild returns NULL Example 9 4 Retrieving the root bookmark PDBookmark GetFirstBookmark PDDoc doc PDBookmark theroot childBookmark theroot PDDocGetBookmarkRoot doc childBookmark PDBookmarkG...
Page 119: ...character pointer Because the size of the bookmark s title is unknown the PDBookmarkGetTitle is invoked twice The first time it is invoked NULL is passed as the buffer address second argument and 0 i...
Page 120: ...treeBookmark HANDLER END_HANDLER Deleting bookmarks You can use the Acrobat core API to delete an existing bookmark Deleting a bookmark deletes child bookmarks however PDF document content is not aff...
Page 121: ...DocGetBookmarkRoot myPDDoc Retrieve a specific bookmark myBookmark PDBookmarkGetByTitle rootBookmark bookmarkTitle strlen bookmarkTitle 1 if PDBookmarkIsValid myBookmark AVAlertNote The bookmark was r...
Page 122: ...te system used within PDF documents It specifies coordinates for most objects in the PD layer For information see Portable Document layer on page 17 When working with the user space coordinate system...
Page 123: ...ect object to represent a specific coordinate The following diagram shows a device space coordinate system The AVPageViewRectToDevice method can transform a rectangle s coordinates from user space to...
Page 124: ...the document Convert the AVDoc object to a PDDoc object by invoking the AVDocGetPDDoc method This method requires an AVDoc and returns a PDDoc object Get the total number of pages located within the...
Page 125: ...the PDDocAcquirePage method to acquire the page the PDPage object To access the contents of PDF pages you use PD layer methods In addition the Acrobat core API provides the PDFEdit typedef which prov...
Page 126: ...ct AVDoc avDoc AVAppGetActiveDoc AVPageView pageView AVDocGetPageView avDoc PDPageNumber pageNum AVPageViewGetPageNum pageView Bridge method to PD doc PDDoc pdDoc AVDocGetPDDoc avDoc Acquire current p...
Page 127: ...r you can pass a PDEElement object and cast it to a PDEObject This method returns an ASInt32 object that specifies the element type For example if the element is a text element then this method return...
Page 128: ...llowing arguments A PDEText object that represents the text element whose bounding box is obtained A PDETextFlags value that specifies whether index refers to the character offset from the beginning o...
Page 129: ...olorValueRec red blue Define red red space PDDeviceRGB red value 0 ASInt32ToFixed 1 red value 1 0 red value 2 0 Define blue blue space PDDeviceRGB blue value 0 0 blue value 1 0 blue value 2 ASInt32ToF...
Page 130: ...AVPageViewRectToDevice pageView bbox rect Draw the rect AVPageViewDrawRectOutline pageView rect 1 NULL 0 else Assign blue to the page view AVPageViewSetColor pageView blue Get the bounding box of the...
Page 131: ...yphenated across line breaks on a page Each character in a word has a character type Character types include control code lowercase letter uppercase letter digit punctuation mark hyphen soft hyphen li...
Page 132: ...ary methods of working with word finders are Invoking the PDWordFinderEnumWords method which invokes a user defined callback function each time a word is recognized on a page For information see Extra...
Page 133: ...formation see Opening PDF documents on page 72 2 Create a PDDoc object by invoking the AVDocGetPDDoc method and passing the AVDoc object 3 If desired create a PDWordFinderConfigRec object If you do no...
Page 134: ...pe that invokes the user defined function whose address was passed as the second argument The following lines of code shows the ASCallbackCreateProto macro converting the wordEnumerator user defined f...
Page 135: ...rConfigRec pConfig recSize sizeof PDWordFinderConfigRec pConfig ignoreCharGaps true pConfig ignoreLineGaps true pConfig noAnnots true pConfig noEncodingGuess true Create a PDWordFinder object PDWordFi...
Page 136: ...inning of the document For example if you specify 1 then the second word in the document is highlighted this value is a 0 based index The length attribute specifies the number of words that are highli...
Page 137: ...epresents the text selection Cast the PDTextSelect object as a void pointer An ASBool object that specifies whether to highlight the selection Pass the value true to highlight the specified word s 9 D...
Page 138: ...cription See About handlers Describes the characteristics of handlers page 138 Action handlers Describes the characteristics of action handlers page 139 Annotation handlers Describes the characteristi...
Page 139: ...handler data structure contains a size field which specifies the structure s size This field provides future compatibility Different versions of the structure have different sizes allowing Acrobat to...
Page 140: ...ewBBoxProc callback method Highlight unhighlight the annotation when it is added to removed from the selection by using the following callback methods AVAnnotHandlerNotifyAnnotAddedToSelectionProc or...
Page 141: ...programmatically invoke AVCommands using AVCommand methods perform the following tasks 1 Instantiate the command by invoking the AVCommandNew method providing the registered name of the command ASAtom...
Page 142: ...ive To invoke the command programmatically create an ASCab object and populate it with the appropriate parameters as shown in the following example Example 12 3 Setting configuration parameters Create...
Page 143: ...ocTitleValue Document Title const char docSubjectValue Document Subject Create a PDDoc object based on the current PDF document AVDoc avDoc AVAppGetActiveDoc AVPageView pageView AVDocGetPageView avDoc...
Page 144: ...list by invoking the AVAppRegisterGlobalCommand method AVCommand cmd AVCommandNew ASAtomFromString kCmdName AVAppRegisterGlobalCommand cmd Although this step can be performed at any time once the comm...
Page 145: ...tle text if doItAll ASCabKnown params kAVCommandKeyTitle Create another text object and insert it into the ASCab text ASTextNew ASTextSetEncoded text kCmdTitle ASHostEncoding PDGetHostEncoding ASCabPu...
Page 146: ...o enable the selection of data types not already supported To add a new selection server you must provide a set of callbacks specify them in the AVDocSelectionServer data structure and register them u...
Page 147: ...ut there are no documents open it does not make sense to activate the tool Note For a complete list of callbacks see the description of AVTool in the Acrobat and PDF Library API Reference Window handl...
Page 148: ...e a file system A file system handler does not require explicit registration By using a file system handler you can perform the following tasks Open a file by using the ASFileSysOpenProc callback meth...
Page 149: ...itor there is no explicit registration method Using a progress monitor you can perform the following tasks Initialize the progress monitor and display it with a current value of zero by invoking the P...
Page 150: ...ister to receive DDE messages directly On Mac OS plug ins must hook into Acrobat or Adobe Reader s Apple event handling loop to handle Apple events To do this replace the API s AVAppHandleAppleEvent m...
Page 151: ...VPageViewDidChange In contrast after opening a PDF document in Mac OS notifications occur in this order 1 AVPageViewDidChange 2 AVDocDidActivate 3 AVPageViewDidChange 4 AVDocDidOpen This chapter conta...
Page 152: ...e Acrobat core API method that corresponds to the event notification Do not append a value to the method name The address of the user defined function that is invoked when the event occurs A pointer t...
Page 153: ...this is defined in the PIMain c file The callback function that is invoked when the event occurs You can invoke the ASCallbackCreateNotification macro and pass the following arguments The name of the...
Page 154: ...the values it places into the encryption dictionary the values are in plain text The core API provides two Cos layer methods to encrypt and decrypt data using the RC4 algorithm These methods are CosE...
Page 155: ...associated with it A document has zero security handlers if no security is used on the file When security is applied to a file or the user selects a different security handler for a secured file the...
Page 156: ...yDataProc Extracts security information from the security data structure PDCryptGetSecurityInfoProc Allows the user to request different security settings usually by displaying a dialog box PDCryptDis...
Page 157: ...hich other documents use the same password The authorize callback can return permissions that depend on the password as well as the permissions specified when encryption was set up This allows for exa...
Page 158: ...lculation based on the contents of the security data structure filled previously by the handler s PDCryptNewSecurityDataProc callback Saving a secured file When saving a file it is important to rememb...
Page 159: ...ecurity data structure was seeded with information from encryptDict an internal authorize procedure is called This procedure decrypts and examines the data fields in the security data structure copy t...
Page 160: ...tFileSysByName method and passing either ASAtomFromString Win Creating Unicode file path application logic When creating application logic that requires a file system argument either a Unicode file sy...
Page 161: ...ieve a Unicode path value The Unicode file system is essentially the same as the classic Windows file system except that its ASPathName object supports a few additional calls through the file system c...
Page 162: ...fied path values and decides if the classic default file system is used works or if the Unicode file system is used On Mac OS and UNIX the default file system is always returned because neither has a...
Page 163: ...ws Note The classic Windows file system supports both Cstring and WinUnicodePath in its implementation of the ASFileSysAcquirePlatformPath and ASPlatformPathGetCstringPtr methods The following code ex...
Page 164: ...ke and is defined as a linked list of function pointers Adobe Reader or Acrobat uses linked lists because some HFT entries may be marked so that they can be replaced by a plug in Also it is useful to...
Page 165: ...handling requests to obtain or destroy its HFT As part of its responsibility to handle requests an HFT server can choose to support multiple versions of the HFT These versions generally correspond to...
Page 166: ...the methods are accessed through a function pointer Part of the process of defining a function pointer through which HFT methods are accessed is to create an enumeration that specifies the index of e...
Page 167: ...r each method that is used to invoke the HFT method from other plug ins You can define an HFT method name by using the following syntax define method_name method_nameSELPROTO HFTname method_nameSEL Th...
Page 168: ...ction whose address was passed as the second argument The following lines of code show the ASCallbackCreateProto macro converting the ProvideMyHFT user defined function to a PDWordProc callback HFTSer...
Page 169: ...2 Invoke the HFTReplaceEntry method to populate the entries in the HFT object with pointers to the HFT methods This method requires the following arguments An HFT object that you want to populate The...
Page 170: ...eplaceEntry gMyHFT BeepTwiceSEL ASCallbackCreateReplacement BeepTwiceSEL BeepTwice Implementation 0 HFTReplaceEntry gMyHFT BeepNTimesSEL ASCallbackCreateReplacement BeepNTimesSEL BeepNTimes Implementa...
Page 171: ...L End of MyHFT h Examining an HFT source file The following code example shows the syntax of a source file used to create an HFT Notice that the methods BeepOnceImplementation BeepTwiceImplementation...
Page 172: ...es i AVSysBeep 0 AVAlertNote In BeepNTimesImplementation function Create a new HFT of NUMSELECTORS entries Then put the methods into the table via HFTReplaceEntry ACCB1 HFT ACCB2 ProvideMyHFT HFTServe...
Page 173: ...mport an existing HFT you must invoke the ASExtensionMgrGetHFT method within the PluginImportReplaceAndRegister handshaking method The ASExtensionMgrGetHFT method requires the following arguments An A...
Page 174: ...ble lists all the replaceable Acrobat and Adobe Reader methods To replace one of these methods a plug in invokes the HFTReplaceEntry method In some cases when the replacement method is finished execut...
Page 175: ...uit method with a custom method named MyAvAppCanQuit The MyAVAppCanQuit method s arguments and return value are identical to those of the AVAppCanQuit method Replaceable methods must be replaced with...
Page 176: ...T PDF Library applications by performing the following tasks 1 Change your project settings from PRODUCT Library h to PRODUCT HFTLibrary h the header files include the necessary code to translate from...
Page 177: ...wing table lists PDF Library API methods that should be changed to newer methods when working with HFTs Note Other PDF Library API methods will work as is without any code change Old method New method...
Page 178: ...For information see Creating 3D Annotations on page 203 This chapter contains the following information Caution Care is required when working with Cos objects Unlike using AV and PD objects Cos object...
Page 179: ...a reference to it in indirect object 7 6 0 obj This is a string endobj 7 0 obj 6 0 R An array with one element that is indirect object 6 endobj If you were to retrieve the zeroth element in the array...
Page 180: ...ASCII characters unbalanced parentheses or the backslash character itself in the string The character immediately following the backslash determines its precise interpretation If the character follow...
Page 181: ...by a numeric index Array indexes are zero based and may be any combination of the Cos data types The following array has seven elements three integers a string a Boolean value a dictionary containing...
Page 182: ...s in ASCII This enables a name object to represent text in any natural language subject to the implementation limit on the length of a name Cos dictionaries A dictionary object is an associative table...
Page 183: ...section discusses ways in which you can work with Cos strings For information see Cos strings on page 179 Creating Cos strings You can use the Acrobat core API to create a CosObjobject that is based o...
Page 184: ...alue Working with Cos arrays This section discusses ways in which you can work with Cos arrays Creating Cos arrays You can use the Acrobat core API to create a CosObj object that is based on a Cos arr...
Page 185: ...Example 17 3 Creating a Cos array Create a new Cos array CosObj ArrayObj IntObj CosDoc cd PDDocGetCosDoc myPDDoc ArrayObj CosNewArray cd false 5 for int i 1 i 5 i Create a new CosObj representing the...
Page 186: ...is section discusses ways in which you can work with Cos dictionaries For information see Cos dictionaries on page 182 Creating Cos dictionaries You can create a CosObj object that is based on a Cos d...
Page 187: ...5 Repeat steps 3 and 4 for each dictionary entry that you want to add The following code example creates a Cos dictionary with the following entries Key1 1 Key2 A PDDoc object named myPDDoc is passed...
Page 188: ...ue of the dictionary element sprintf buf The value of the dictionary element is d dicValue AVAlertNote buf Note The Dict object is a CosObj that represents the dictionary For information see Creating...
Page 189: ...e CosObj nameObj CosDoc cd PDDocGetCosDoc myPDDoc nameObj CosNewName cd false ASAtomFromString Name1 Retrieving the value of a name object You can retrieve the value of a name object by using the Acro...
Page 190: ...document page The following diagram shows the result of a data stream that creates a thin black line segment being inserted into a PDF document The following example shows the syntax of a stream that...
Page 191: ...gth entry defined perform the following tasks 1 Create a CosDoc object that represents a PDF file by invoking the PDDocGetCosDoc method 2 Create an ASUns32 object that represents the stream length 3 C...
Page 192: ...CosDictPutKeyString AttrDict Length_KStr LengthEntry Determine if the stream dictionary is valid if CosObjEqual AttrDict CosNewNull true AVAlertNote The attributes dictionary could not be created retu...
Page 193: ...ecified in the stream dictionary before it is written to the Cos stream A CosObj object that represents the stream dictionary pass the CosObj object created in step 5 A CosObj object that represents t...
Page 194: ...stream dictionary is valid if CosObjEqual AttrDict CosNewNull true AVAlertNote The stream dictionary could not be created return Read the stream into memory by invoking the ASMemStmRdOpen method Open...
Page 195: ...the font that a content stream uses and a page dictionary defines attributes such as the page s height and width For information about these dictionaries see the PDF Reference The following example s...
Page 196: ...1 Tf 24 0 0 24 36 756 Tm 0 Tr 0 g 0 Tc 0 Tw Hello There Tj ET 3 Create a PDDoc object that represents the new document by invoking the PDDocCreate method After the document is created at least one pag...
Page 197: ...le is made up by various user defined functions To make it easier to view these functions all function signatures are bolded The entry point to this source file is the MakeTheFile function You can inv...
Page 198: ...alse END_HANDLER return true end of SetResourceForPage Create the font s resources Return true if all is valid else false Creates the required font and proc set dictionaries then creates the global re...
Page 199: ...CosNewDict cd false 2 HANDLER AVAlertNote Trying to create page s resource dictionary CosObjDestroy FontDictObj return false END_HANDLER Add entries to the page s resource dictionary Font F0 5 0 R Pr...
Page 200: ...newly created dictionary ASAtom Key Key used to retrieve CosObj in dictionary CosObj Value Assigned then added to dictionary CosObj DecodeArray Create the stream dictionary Dict CosNewDict Doc false 1...
Page 201: ...y AttrDict ASStmClose Stm return false END_HANDLER Add the content stream to the page PDPageAddCosContents page PageStrm return true end of AddStreamToPage Create the new PDF document void MakeTheFile...
Page 202: ...SetResourceForPage method result SetResourceForPage NewPage Invoke AddStreamToPage result AddStreamToPage NewPage StreamBuf StreamBufLen if result false ASRaise 0 PDPageRelease NewPage HANDLER AVAlert...
Page 203: ...es If the value is a dictionary that dictionary has its own key value pairs Therefore dictionaries can be nested within other dictionaries as you will see with the 3D structures General annotation dic...
Page 204: ...ng values as well as complex types such as dictionaries arrays and streams The API provides methods for creating and working with different object types The creation methods are of the form CosNewObje...
Page 205: ...he CosObj object as shown in the following example CosDoc cosDoc CosObjGetDoc cosAnnot Two additional dictionary entries which are not specific to 3D annotations the P page and Contents entries can be...
Page 206: ...PDF file is located Invoke the ASGetDefaultFileSys method to get the default file system An ASPathName object that represents the path in which the file containing the U3D data is located pass the AS...
Page 207: ...asFile ASFileSysReleasePath ASGetDefaultFileSys u3DPathName if asFile NULL AVAlertNote Error opening 3D data file Read data stream from the file ASStm fileStm ASFileStmRdOpen asFile 0 if fileStm NULL...
Page 208: ...t32 err1 ASFileSysOpenFile ASGetDefaultFileSys JsPathName ASFILE_READ jsFile Next the data from the file is read into a stream ASStm JsFileStm ASFileStmRdOpen jsFile 0 In the following code an entry i...
Page 209: ...g code creates a view dictionary and specifies its entries The code assumes the Cos objects cosAnnot for the annotation and cosDoc for the document have already been obtained First a view dictionary i...
Page 210: ...of the annotation dictionary specifies an appearance dictionary This dictionary contains one or more appearance streams see section 8 4 4 of the PDF Reference that are PDF content streams form XObjec...
Page 211: ...sterPDFDoc 0 The code then uses PDE layer PDFEdit methods that work with the content streams on the PDF page See the Overview guide for more information on how these methods work The PDPageAcquirePDEC...
Page 212: ...the page s media box ASFixedRect boundingBox PDPageGetMediaBox pdPageImage boundingBox CosObj BBoxArray CosNewArray pdDocCos 4 false CosArrayPut BBoxArray 0 CosNewInteger pdDocCos false ASFixedRoundTo...
Page 213: ...nnotation is inactive it displays its normal appearance See Setting the annotation appearance on page 210 When it is activated one of its views specified by the 3DV entry is displayed First the dictio...
Page 214: ...r can access the exception error code by using the ERRORCODE macro The value returned by the ERRORCODE macro does not change until another exception is raised For information about the ERRORCODE macro...
Page 215: ...t Now if myfn raises an exception your handler will be executed Raising exceptions Although many Acrobat core API methods raise exceptions some methods do return error codes or NULL if something goes...
Page 216: ...ference Using nested exception handlers Avoid using nested exception handlers within a single function The exception handling macros change the call stack and nesting them can disrupt the stack Your p...
Page 217: ...variables The DURING and HANDLER macros use the standard C setjmp longjmp mechanism The DURING macro calls setjmp An exception results in a longjmp to the context that was saved by the most recent se...
Page 218: ...ded API Digital Signature DigSig Extended API Forms Extended API Weblink Extended API Spelling Extended API AcroColor Extended API Topic Description See About Acrobat extended APIs Describes the chara...
Page 219: ...on about the methods included in the Search extended API see the Acrobat and PDF Library API Reference Catalog extended API Acrobat Catalog is a plug in that allows you to create a full text index of...
Page 220: ...nd obtaining instructions from the agent as to an object s visitation status Agents can perform their own repairs and modifications to the PDF document and can return a corrected object to serve as a...
Page 221: ...behavior in the revisit upon reclassification mode is to revisit objects when they are reclassified new objects added in this mode will actually be visited again if they are reclassified as the trave...
Page 222: ...ck of the objects it has visited in the PDF document in the traversal stack If an agent modifies an object such that it affected the traversal stack the entire process is derailed The consultant may n...
Page 223: ...Objects that have multiple classifications can be reached from multiple paths In such cases you might allow the consultant to revisit such objects if and only if they have been reclassified on a new...
Page 224: ...your agent class Use a plug in as the owner for both the consultant and your agent object Because there is some memory overhead in creating a consultant you should only create a Consultant object whe...
Page 225: ...th a consultant Example 20 2 Registering an agent with a consultant Declare volatile consultant because it is inside a DURING bloc Consultant volatile hConsultant Consultant NULL DURING AVDoc hAVDoc A...
Page 226: ...mItems ConsStackGetCount stack for Index 0 Index NumItems CurStrLen strLen Index if CurStrLen strlen TRAVERSAL_SEP strLen strcat traversalString TRAVERSAL_SEP Add the parent key if this stack entry ha...
Page 227: ...type subclasses and superclasses Certain PDF object types are members of more generic classes of PDF object type Agents can often make use of this information so the consultant assigns object types th...
Page 228: ...members of the Agent class In larger scale systems it is better to create a host object for the agent that is responsible for determining the proper objects to include in the array and for passing the...
Page 229: ...involves the most common Cos objects CosString CosDict CosArray and CosStream Post processing stage The second and final required function definition in any ConsultantAgentObj derived class is the Pos...
Page 230: ...le you to perform the following tasks Count and close encrypted documents Validate a specific signature field Access and create digests for data buffers Import and export certificate data and manage t...
Page 231: ...arently Digital signature scenarios Acrobat supports three digital signature scenarios Acrobat s Digital Signature plug in handles the first case and allows other plug ins to further handle the second...
Page 232: ...it must access a signature registry or authority over a network Therefore Adobe software only accesses signatures at user request When the user closes a document the digital signature plug in invokes...
Page 233: ...igital signature plug in may rename the file and may invoke the Optimizer Linearizer and Garbage Collector Upon return from the save all Cos objects are invalid including those in the marked array All...
Page 234: ...s a doublechecked pass fail unknown blank icon and a line of text for each signature field in the document The default text is the name of the person signing and the date and time of signing displayed...
Page 235: ...ture that is it must equal offset 1 of the F in the EOF at the end of the file In addition the following constraints also apply All offsets must be in the range 0 2147483647 All lengths must be in the...
Page 236: ...iver uses DDE messages and Apple events to communicate with a web browser It supports a protocol that consists of a suite of verbs some going to and some coming from the web browser These verb definit...
Page 237: ...wser launching the browser application if necessary The external web browser brings itself to the foreground unless the URL s MIME type is application pdf 3 The web browser retrieves the document and...
Page 238: ...ase a string is expected to have the appropriate null termination If a string is UCS 2 it may have embedded language and country information Output text is in big endian UCS 2 format with the bytes 0x...
Page 239: ...a string object and preset lists of settings You can create an ICC color profile from available data ACMakeBufferProfile or use profiles that are installed on the system ACGetWorkingSpaceProfile or st...
Page 240: ...ample a list could contain the following actions 1 Convert JPEG images to CMYK 2 Convert all images to CMYK 3 Convert line art using saturation intent Object attributes An object located within a PDF...
Page 241: ...e particular object if a match is located The ink list defines ink aliasing or conversion to process for particular named colorants The following list specifies the data structures that you use to wor...
Page 242: ...e of the PDColorConvertAction data structure and assign the following values to its data members mMatchAttributesAny Assign 1 mMatchSpaceTypeAny Assign 1 mMatchIntent Assign AC_UseProfileIntent an AC_...
Page 243: ...ne the color actions PDColorConvertAction myAction Declare an AC_Profile object AC_Profile prof Define AppleRGB as the profile to use ACProfileFromCode prof AC_Profile_AppleRGB Declare a PDColorConver...
Page 244: ...DocSaveOptimized method to run the PDF Optimizer tool on a specified PDF document An optimized document is created using the settings specified in the PDFOptParams structure The optimized document is...
Page 245: ...obe Reader perform the following tasks 1 Write the code for your plug in When possible ensure that the plug in works correctly in the full Acrobat viewer Standard or Professional before trying to Read...
Page 246: ...letely new plug in that is not backwards compatible with earlier versions of Acrobat Therefore if you want your plug in to run on both Acrobat 7 or later and on earlier versions of Acrobat you must ma...
Page 247: ...ows platform This section discusses creating a resource file for an Adobe Reader plug in on the Windows platform When prompted for a path by either of the enabling tools the filename is limited to 8 3...
Page 248: ...l This will create a plug in that has the correct API_DIGITAL_CERTIFICATE and API_ENCRYPTED_DIGEST resources The plug in can now be loaded by Adobe Reader If you encounter any difficulties refer to Tr...
Page 249: ...re the Certified Plug ins Only box is not checked in the Options preferences dialog box The plug in was not correctly enabled The resources file sent by Adobe may have been corrupted during delivery V...
Page 250: ...tSelection method 137 AVDocShowSelection method 137 AVMenu typedefs 89 AVMenubar typedef 89 AVOpenSaveDialogParamsRec typedef 76 AVPageView typedef 124 AVPageViewDrawNow method 124 AVPageViewDrawRectO...
Page 251: ...xporting host function tables 165 exporting HFTs 29 external window creating 75 creating handler 76 defining parameters 75 displaying a PDF document 74 ExternalDocServerCreationDataRec typedef 74 extr...
Page 252: ...tNumAnnots 110 PDTextAnnotGetContents 111 PDTextAnnotSetContents 109 PDTextAnnotSetOpen 109 PDTextSelectCreateWordHilite 137 modal dialog boxes 43 modifying annotations 111 page contents 125 text elem...
Page 253: ...46 retrieving annotations 110 bookmarks 118 cos arrays values 185 cos dictionary values 187 cos name value 189 page elements 126 toolbars 98 returning values 215 S scalar data type 21 screen redrawin...
