PD_Layer.PDAnnotHandler (Acrobat)

	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
	_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
	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
	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.

Typedefs Detail

PDAnnotHandler

Product availability: All

Platform availability: All

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

PDRegisterAnnotHandler

File: PDExpT.h

Line: 527

PDAnnotHandlerClipboardData

Product availability: All

Platform availability: All

Syntax

typedef void* PDAnnotHandlerClipboardData;

Opaque data used by PDAnnotHandlers.

File: PDExpT.h

Line: 540

PDAnnotHandlerRec

Product availability: All

Platform availability: All

Syntax

typedef _t_PDAnnotHandler PDAnnotHandlerRec;

File: PDExpT.h

Line: 901

Structure Detail

_t_PDAnnotHandler

Product availability: All

Platform availability: All

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;  

}

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

See Also

PDRegisterAnnotHandler

File: PDExpT.h

Line: 849

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: All

Platform availability: All

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.

File: PDExpT.h

Line: 698

PDAnnotHandlerCanPasteProc

Product availability: All

Platform availability: All

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.

File: PDExpT.h

Line: 746

PDAnnotHandlerCopyProc

Product availability: All

Platform availability: All

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.

File: PDExpT.h

Line: 719

PDAnnotHandlerDeleteAnnotInfoProc

Product availability: All

Platform availability: All

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.

File: PDExpT.h

Line: 590

PDAnnotHandlerDestroyDataProc

Product availability: All

Platform availability: All

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.

File: PDExpT.h

Line: 788

PDAnnotHandlerDestroyProc

Product availability: All

Platform availability: All

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

PDRegisterAnnotHandler

File: PDExpT.h

Line: 799

PDAnnotHandlerGetAnnotInfoFlagsProc

Product availability: All

Platform availability: All

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.

File: PDExpT.h

Line: 681

PDAnnotHandlerGetAnnotInfoProc

Product availability: All

Platform availability: All

Syntax

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

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

File: PDExpT.h

Line: 575

PDAnnotHandlerGetHeelPointProc

Product availability: All

Platform availability: All

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

PDRegisterAnnotHandler

File: PDExpT.h

Line: 813

PDAnnotHandlerGetPrintAppearanceProc

Product availability: All

Platform availability: All

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

PDRegisterAnnotHandler

File: PDExpT.h

Line: 835

PDAnnotHandlerGetTypeProc

Product availability: All

Platform availability: All

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.

File: PDExpT.h

Line: 604

PDAnnotHandlerPasteProc

Product availability: All

Platform availability: All

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().

File: PDExpT.h

Line: 770

Method Detail

PDRegisterAnnotHandler

()

Product availability: Acrobat, 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.

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6741

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
PDAnnotHandler	Typedefs \| Structures \| Callbacks \| Methods

	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;

Layer	PD_Layer
Object	PDAnnotHandler