manualshive.com logo in svg

Adobe ACROBAT SDK 8.1, Руководство пользователя, Страница: 138 / 253

Поделиться
Скачать
Adobe ACROBAT SDK 8.1 Скачать руководство пользователя страница 138

     138

12

Creating Handlers

Adobe Reader and Acrobat plug-ins and PDF Library applications can add new types of tools, annotations, 
actions, file systems, and so on, thereby expanding the number of supported object types. To accomplish 
this task, the Acrobat core API provides a collection of callback routines called handlers that support 
objects. Handlers perform operations, such as creating and destroy objects, handling mouse clicks, 
handling keyboard events, and so on.

This chapter contains the following information.

About handlers

To add a new handler, you must write callback functions, create the appropriate data structure containing 
the callbacks and other data, and pass the structure to Acrobat by invoking the appropriate method. 
Subsequently, Acrobat automatically invokes the correct callback when it encounters an object of the type 
handled by the handler.

Topic

Description

See

About handlers

Describes the characteristics of handlers.

page 138

Action handlers

Describes the characteristics of action handlers.

page 139

 

Annotation handlers

Describes the characteristics of annotation handlers.

page 140

 

AVCommand handlers

Describes the characteristics of AVCommand handlers.

page 140

File format conversion 
handlers

Describes the characteristics of file format conversion 
handlers.

page 145

File specification handlers

Describes the characteristics of file specification handlers.

page 146

Selection servers

Describes the characteristics of selection server handlers. 

page 146

Tool callbacks

Describes the characteristics of tool callbacks.

page 147

Window handlers

Describes the characteristics of window handlers.

page 147

File systems

Describes the characteristics of file handlers.

page 148

Process monitors

Describes the characteristics of process monitors.

page 149

Transition handlers

Describes the characteristics of transition handlers.

page 149

Adding message handlers

Describes how to add Apple events and DDE messages.

page 150

Содержание ACROBAT SDK 8.1

Страница 1: ...bbc Developing Plug ins and Applications Adobe Acrobat SDK April 2007 Version 8 1...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 26: ...ithParamsInCosDoc PDEFormGetBBox PDEFormGetMatrix PDEImageCreateInCosDoc PDEScratchDocCleanup PDFileSpecAcquireASPathEx PDFileSpecGetDIPathEx PDFileSpecNewFromASPathEx PDFLibraryRegisterRNG PDOCRegist...

Страница 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...

Страница 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...

Страница 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...

Страница 30: ...backCreateProto ASCallbackCreateReplacement and ASCallbackCreateNotification methods to convert functions into callback functions and to perform type checking This enables the compiler to determine wh...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 65: ...e object and set its attributes PDEGraphicState gState PDEColorSpace pdeColorSpace PDEColorSpaceCreateFromName ASAtomFromString DeviceGray memset gState 0 sizeof PDEGraphicState gState strokeColorSpec...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 71: ...e pdDoc PDSaveFull PDSaveLinearized macPath NULL NULL NULL ASFileSysReleasePath NULL macPath endif Release all objects PDERelease PDEObject pdeFont PDERelease PDEObject pdeText i PDPageReleasePDEConte...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 78: ...ialogParamsRec dialogParams size sizeof AVOpenSaveDialogParamsRec dialogParams fileFilters filterRecP dialogParams numFileFilters 1 8 Set the AVFileFilterRec object s filterDescription attribute by in...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 84: ...s ASGetDefaultFileSysForPath pathType myPath ASPathName pathName ASFileSysCreatePathName fileSys pathType myPath NULL Create the authentication callback myAuthProcPtr ASCallbackCreateProto PDAuthProc...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 105: ...ar AVToolButton mySecureButton AVToolBarGetButtonByName myToolBar ASAtomFromString SecureTask if mySecureButton NULL AVAlertNote The button was not successfully retrieved return Remove the SecureTask...

Страница 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...

Страница 107: ...tonSetExecuteProc MyButton ExecProcPtr NULL Attach the button AVToolBarAddButton ToolBar MyButton FALSE NULL Release the callback function ASCallbackDestroy ExecProcPtr return true ACCB1 ASBool ACCB2...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 118: ...arkGetFirstChild returns NULL Example 9 4 Retrieving the root bookmark PDBookmark GetFirstBookmark PDDoc doc PDBookmark theroot childBookmark theroot PDDocGetBookmarkRoot doc childBookmark PDBookmarkG...

Страница 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...

Страница 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...

Страница 121: ...DocGetBookmarkRoot myPDDoc Retrieve a specific bookmark myBookmark PDBookmarkGetByTitle rootBookmark bookmarkTitle strlen bookmarkTitle 1 if PDBookmarkIsValid myBookmark AVAlertNote The bookmark was r...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 135: ...rConfigRec pConfig recSize sizeof PDWordFinderConfigRec pConfig ignoreCharGaps true pConfig ignoreLineGaps true pConfig noAnnots true pConfig noEncodingGuess true Create a PDWordFinder object PDWordFi...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 170: ...eplaceEntry gMyHFT BeepTwiceSEL ASCallbackCreateReplacement BeepTwiceSEL BeepTwice Implementation 0 HFTReplaceEntry gMyHFT BeepNTimesSEL ASCallbackCreateReplacement BeepNTimesSEL BeepNTimes Implementa...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 202: ...SetResourceForPage method result SetResourceForPage NewPage Invoke AddStreamToPage result AddStreamToPage NewPage StreamBuf StreamBufLen if result false ASRaise 0 PDPageRelease NewPage HANDLER AVAlert...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 212: ...the page s media box ASFixedRect boundingBox PDPageGetMediaBox pdPageImage boundingBox CosObj BBoxArray CosNewArray pdDocCos 4 false CosArrayPut BBoxArray 0 CosNewInteger pdDocCos false ASFixedRoundTo...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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_...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 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...

Страница 250: ...tSelection method 137 AVDocShowSelection method 137 AVMenu typedefs 89 AVMenubar typedef 89 AVOpenSaveDialogParamsRec typedef 76 AVPageView typedef 124 AVPageViewDrawNow method 124 AVPageViewDrawRectO...

Страница 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...

Страница 252: ...tNumAnnots 110 PDTextAnnotGetContents 111 PDTextAnnotSetContents 109 PDTextAnnotSetOpen 109 PDTextSelectCreateWordHilite 137 modal dialog boxes 43 modifying annotations 111 page contents 125 text elem...

Страница 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...

Отзывы:

Нет отзывов