LayerPD_Layer
ObjectPDAnnotHandler

This is the abstract superclass for all annotations (see Section 8.4, Annotations, in the PDF Reference). Acrobat has two built-in annotation classes: PDTextAnnot and PDLinkAnnot. Plug-ins add movie, Widget (form field), and other annotation types. You can define new annotation subtypes by creating new annotation handlers (see Developing Plug-ins and Applications). There are no objects of type PDAnnot, but you can use PDAnnot methods on any subclass of PDAnnot.

The Acrobat SDK provides three useful macros to cast among PDAnnot and its text annotation and link annotation subclasses (see PDExpT.h). These are:



Typedef Summary
 Typedef
 PDAnnotHandler
A data structure containing callbacks that implement an annotation manager. The callbacks implement the annotation manager functions (for example, view, delete, or export the annotations of a document as a list, sorted by type, author, or date).
 PDAnnotHandlerClipboardData
Opaque data used by PDAnnotHandlers.
 PDAnnotHandlerRec
Structure Summary
 Structure
 _t_PDAnnotHandler
A data structure containing callbacks that implement an annotation manager. The callbacks implement the annotation manager functions (for example, view, delete, or export the annotations of a document as a list, sorted by type, author, or date).
Callback Summary
 Callback
 PDAnnotHandlerCanCopyProc
(Optional) A callback for PDAnnotHandler. It returns true if the copy operation is expected to succeed. It tests, for example, whether copying is allowed by document permissions.
 PDAnnotHandlerCanPasteProc
(Optional) A callback for PDAnnotHandler. It returns true if the paste operation is expected to succeed. It tests whether data from an annotation that has been copied to a clipboard can be pasted to a location on a page. Pasting can be disallowed by document permissions, or because the annotation cannot be accurately reproduced in the destination document.
 PDAnnotHandlerCopyProc
(Optional) A callback for PDAnnotHandler. It copies data from the annotation object to a new clipboard structure, and returns the clipboard structure.
 PDAnnotHandlerDeleteAnnotInfoProc
(Optional) A callback for PDAnnotHandler. It deletes information associated with an annotation. It frees all the memory associated with the annotation information.
 PDAnnotHandlerDestroyDataProc
(Optional) A callback for PDAnnotHandler. It destroys data from an annotation that has been copied to a clipboard. This callback may be executed regardless of how many times (if any) the annotation was pasted.
 PDAnnotHandlerDestroyProc
(Optional) A callback for PDAnnotHandler. It destroys the annotation handler structure when the application no longer requires it. The handler should destroy any dynamic memory stored in the userData field.
 PDAnnotHandlerGetAnnotInfoFlagsProc
A callback for PDAnnotHandler. It gets the annotation handler information flags, which indicate the operations allowed with annotations of this type.
 PDAnnotHandlerGetAnnotInfoProc
A callback for PDAnnotHandler. It gets the annotation information for an annotation.
 PDAnnotHandlerGetHeelPointProc
A callback for PDAnnotHandler. It gets the heel point (the focus or starting point) for the annotation. For a rectangular annotation, this is usually the top left corner.
 PDAnnotHandlerGetPrintAppearanceProc
A callback for PDAnnotHandler. It is called by the host application to obtain a print appearance (a Form XObject). If this callback is not implemented, the default appearance (if any) is used.
 PDAnnotHandlerGetTypeProc
A callback for PDAnnotHandler. It gets an ASAtom indicating the annotation type for which the handler is responsible. This corresponds to the annotation's Subtype key in the PDF file.
 PDAnnotHandlerPasteProc
(Optional) A callback for PDAnnotHandler. It creates a new annotation on the specified page using clipboard data generated by PDAnnotCopy().
Method Summary
 Method
 
Registers a handler for an annotation subtype, replacing any previous handler that had been registered for that subtype. The annotation handler is not registered if its PDAnnotHandlerGetTypeProc() returns NULL.

Typedefs Detail
PDAnnotHandler 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_PDAnnotHandler PDAnnotHandler;

A data structure containing callbacks that implement an annotation manager. The callbacks implement the annotation manager functions (for example, view, delete, or export the annotations of a document as a list, sorted by type, author, or date).

To fully use a PDAnnotHandler, the AVAnnotHandler associated with this annotation must have its AVAnnotHandlerGetInfoProc() and AVAnnotHandlerDeleteInfoProc() callbacks defined.

See Also


File: PDExpT.h
Line: 526
PDAnnotHandlerClipboardData 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef void* PDAnnotHandlerClipboardData;

Opaque data used by PDAnnotHandlers.


File: PDExpT.h
Line: 539
PDAnnotHandlerRec 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_PDAnnotHandler PDAnnotHandlerRec;

File: PDExpT.h
Line: 900


Structure Detail
_t_PDAnnotHandler
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

struct _t_PDAnnotHandler {
 ASSize_t size; 
 
 void* userData; 
 
 PDAnnotHandlerGetTypeProc GetType; 
 
 PDAnnotHandlerGetAnnotInfoProc GetAnnotInfo; 
 
 PDAnnotHandlerDeleteAnnotInfoProc DeleteAnnotInfo; 
 
 PDDocWillExportAnnotProc WillExportAnnot; 
 
 PDDocWillImportAnnotProc WillImportAnnot; 
 
 PDAnnotWillPrintProc WillPrintAnnot; 
 
 PDAnnotHandlerGetAnnotInfoFlagsProc GetAnnotInfoFlags; 
 
 PDAnnotHandlerCanCopyProc CanCopy; 
 
 PDAnnotHandlerCopyProc Copy; 
 
 PDAnnotHandlerCanPasteProc CanPaste; 
 
 PDAnnotHandlerPasteProc Paste; 
 
 PDAnnotHandlerDestroyDataProc DestroyData; 
 
 PDAnnotHandlerDestroyProc Destroy; 
 
 PDAnnotHandlerGetHeelPointProc GetHeelPoint; 
 
 PDAnnotHandlerGetPrintAppearanceProc GetPrintAppearance; 
}

A data structure containing callbacks that implement an annotation manager. The callbacks implement the annotation manager functions (for example, view, delete, or export the annotations of a document as a list, sorted by type, author, or date).

To fully use a PDAnnotHandler, the AVAnnotHandler associated with this annotation must have its AVAnnotHandlerGetInfoProc() and AVAnnotHandlerDeleteInfoProc() callbacks defined.

See Also


File: PDExpT.h
Line: 848

Elements
size  

The size of the data structure. It must be set to sizeof(PDAnnotHandlerRec).

 
userData  

A pointer to a block of user-supplied data.

 
Callbacks Detail
PDAnnotHandlerCanCopyProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*PDAnnotHandlerCanCopyProc)(PDAnnotHandler pdanh, PDPage sourcePage, PDAnnot pdan)

(Optional) A callback for PDAnnotHandler. It returns true if the copy operation is expected to succeed. It tests, for example, whether copying is allowed by document permissions.

See Also


File: PDExpT.h
Line: 697
PDAnnotHandlerCanPasteProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*PDAnnotHandlerCanPasteProc)(PDAnnotHandler pdanh, PDPage destPage, const ASFixedPoint *center, PDAnnotHandlerClipboardData data)

(Optional) A callback for PDAnnotHandler. It returns true if the paste operation is expected to succeed. It tests whether data from an annotation that has been copied to a clipboard can be pasted to a location on a page. Pasting can be disallowed by document permissions, or because the annotation cannot be accurately reproduced in the destination document.

See Also


File: PDExpT.h
Line: 745
PDAnnotHandlerCopyProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDAnnotHandlerClipboardData (*PDAnnotHandlerCopyProc)(PDAnnotHandler pdanh, PDPage sourcePage, PDAnnot pdan)

(Optional) A callback for PDAnnotHandler. It copies data from the annotation object to a new clipboard structure, and returns the clipboard structure.

See Also


File: PDExpT.h
Line: 718
PDAnnotHandlerDeleteAnnotInfoProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void (*PDAnnotHandlerDeleteAnnotInfoProc)(PDAnnotHandler pdanh, PDAnnotInfo info)

(Optional) A callback for PDAnnotHandler. It deletes information associated with an annotation. It frees all the memory associated with the annotation information.

See Also


File: PDExpT.h
Line: 589
PDAnnotHandlerDestroyDataProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void (*PDAnnotHandlerDestroyDataProc)(PDAnnotHandler pdanh, PDAnnotHandlerClipboardData data)

(Optional) A callback for PDAnnotHandler. It destroys data from an annotation that has been copied to a clipboard. This callback may be executed regardless of how many times (if any) the annotation was pasted.

See Also


File: PDExpT.h
Line: 787
PDAnnotHandlerDestroyProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void (*PDAnnotHandlerDestroyProc)(PDAnnotHandler pdanh)

(Optional) A callback for PDAnnotHandler. It destroys the annotation handler structure when the application no longer requires it. The handler should destroy any dynamic memory stored in the userData field.

See Also


File: PDExpT.h
Line: 798
PDAnnotHandlerGetAnnotInfoFlagsProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASFlagBits (*PDAnnotHandlerGetAnnotInfoFlagsProc)(PDAnnotHandler pdanh, PDAnnot pdan)

A callback for PDAnnotHandler. It gets the annotation handler information flags, which indicate the operations allowed with annotations of this type.

See Also


File: PDExpT.h
Line: 680
PDAnnotHandlerGetAnnotInfoProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDAnnotInfo (*PDAnnotHandlerGetAnnotInfoProc)(PDAnnotHandler pdanh, PDAnnot pdan, PDPage pdpage)

A callback for PDAnnotHandler. It gets the annotation information for an annotation.

See Also


File: PDExpT.h
Line: 574
PDAnnotHandlerGetHeelPointProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void (*PDAnnotHandlerGetHeelPointProc)(PDAnnotHandler pdanh, PDAnnot pdan, ASFixedPoint *point)

A callback for PDAnnotHandler. It gets the heel point (the focus or starting point) for the annotation. For a rectangular annotation, this is usually the top left corner.

See Also


File: PDExpT.h
Line: 812
PDAnnotHandlerGetPrintAppearanceProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

CosObj (*PDAnnotHandlerGetPrintAppearanceProc)(PDAnnotHandler pdanh, PDAnnot pdan, ASFixedRect *frAnnot, PDAnnotPrintOp op)

A callback for PDAnnotHandler. It is called by the host application to obtain a print appearance (a Form XObject). If this callback is not implemented, the default appearance (if any) is used.

See Also


File: PDExpT.h
Line: 834
PDAnnotHandlerGetTypeProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASAtom (*PDAnnotHandlerGetTypeProc)(PDAnnotHandler pdanh)

A callback for PDAnnotHandler. It gets an ASAtom indicating the annotation type for which the handler is responsible. This corresponds to the annotation's Subtype key in the PDF file.

See Also


File: PDExpT.h
Line: 603
PDAnnotHandlerPasteProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDAnnot (*PDAnnotHandlerPasteProc)(PDAnnotHandler pdanh, PDPage destPage, const ASFixedPoint *center, PDAnnotHandlerClipboardData data)

(Optional) A callback for PDAnnotHandler. It creates a new annotation on the specified page using clipboard data generated by PDAnnotCopy().

See Also


File: PDExpT.h
Line: 769

Method Detail
PDRegisterAnnotHandler()
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDRegisterAnnotHandler(PDAnnotHandler handler)

Registers a handler for an annotation subtype, replacing any previous handler that had been registered for that subtype. The annotation handler is not registered if its PDAnnotHandlerGetTypeProc() returns NULL.

To effectively use a PDAnnotHandler, the AVAnnotHandler associated with this annotation must have its AVAnnotHandlerGetInfoProc() and AVAnnotHandlerDeleteInfoProc() callbacks defined.

PDF Library applications can use this method to register their annotation handlers. Link and Watermark annotations have default handlers. For other annotation types, the applications should register their own handlers.

Parameters

handler — 

IN/OUT A pointer to a structure containing the annotation handler's callbacks. This structure must not be freed after this call, but must be retained.

See Also

PDGetAnnotHandlerByName
AVAppGetAnnotHandlerByName

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6738