AV_Layer.AVAnnotHandler (Acrobat)

	Define
	AVAnnotHandlerInfoInit

	Typedef
	AVAnnotAppearanceDataRec
	AVAnnotHandler A data structure containing callbacks that implement an annotation handler. The callbacks implement the annotation handler functions. For example, they can be used to draw the annotation and highlight the annotation when it is selected. The data specifies properties of the annotation, such as text selection behavior.
	AVAnnotHandlerInfo
	AVAnnotHandlerInfoRec
	AVAnnotHandlerRec
	AVAnnotOpData
	AVAnnotOpDataRec

	Enumeration
	`AVAnnotAccStrType` The type of accessibility string to be obtained
	`AVAnnotOp` An enumeration detailing operations to which the annotation can be requested to respond.
	`AVAnnotOpReason` Constants that specify how an annotation operation request was triggered.

	Structure
	_AVAnnotHandlerInfoRec A structure used to describe information for a particular annotation type.
	_t_AVAnnotAppearanceData
	_t_AVAnnotHandler A data structure containing callbacks that implement an annotation handler. The callbacks implement the annotation handler functions. For example, they can draw the annotation or highlight the annotation when it is selected. The data specifies properties of the annotation (for example, text selection behavior).
	_t_AVAnnotOpData Additional information passed to the annotation when performing an operation. For some operations a NULL will be passed; in others a pointer to an AVAnnotOpData structure will be passed.

	Callback
	AVAnnotHandlerAdjustCursorExProc (Optional) A callback for AVAnnotHandler. It controls the cursor shape when the cursor is within the annotation. If NULL, the annotation behaves as if the AdjustCursor() callback returned false.
	AVAnnotHandlerAdjustCursorProc Deprecated in Acrobat 6.0. Use AVAnnotHandlerAdjustCursorExProc().
	AVAnnotHandlerAppearanceDrawingProc A callback for AVAnnotHandler that draws the appearance of the annotation for the given page view. Use this prototype for three callbacks: BeginAppearanceDrawing(), FinishAppearanceDrawing(), and CancelAppearanceDrawing().
	AVAnnotHandlerCanPerformOpProc Called to determine if this annotation can perform the specified operation.
	AVAnnotHandlerCopyProc (Optional) A callback for AVAnnotHandler. It is called upon to copy an annotation, possibly to another document. Annotation handlers should provide this callback to allow for copying their annotations. It is called by AVDocCopyAnnot().
	AVAnnotHandlerCursorEnterProc (Optional) A callback for AVAnnotHandler. It is called whenever the cursor moves over an annotation handled by this annotation handler.
	AVAnnotHandlerCursorExitProc (Optional) A callback for AVAnnotHandler. It is called whenever the cursor moves off an annotation handled by this annotation handler.
	AVAnnotHandlerDeleteInfoProc (Optional) A callback for AVAnnotHandler. It deletes information associated with an annotation.
	AVAnnotHandlerDoClickExProc (Optional) A callback for AVAnnotHandler. It handles both left and right mouse button clicks within the annotation. If NULL, the annotation behaves as if the callback returned false.
	AVAnnotHandlerDoClickProc Deprecated in Acrobat 6.0. Use AVAnnotHandlerDoClickExProc().
	AVAnnotHandlerDoKeyDownExProc Called for each keystroke received when an annotation has focus.
	AVAnnotHandlerDoKeyDownProc Deprecated in Acrobat 6.0. Use AVAnnotHandlerDoKeyDownExProc().
	AVAnnotHandlerDoPropertiesExProc (Optional) A callback for AVAnnotHandler. It displays whatever user interface it wishes to allow a user to change an annotation's properties. Set it to NULL if the annotation type has no user-specified properties.
	AVAnnotHandlerDoPropertiesProc Deprecated in Acrobat 6.0. Use AVAnnotHandlerDoPropertiesExProc().
	AVAnnotHandlerDrawExProc Called to request that the annotation appearance be drawn.
	AVAnnotHandlerDrawProc Deprecated in Acrobat 6.0. Use AVAnnotHandlerDrawExProc().
	AVAnnotHandlerEnumProc A callback for AVAppEnumAnnotHandlers(). It is called once for each annotation handler currently registered with the Acrobat viewer (see AVAppRegisterAnnotHandler()).
	AVAnnotHandlerGetAccessibilityStringProc A callback for AVAnnotHandler. It gets the accessibility string associated with an annotation.
	AVAnnotHandlerGetAnnotInTabOrderProc A callback for AVAnnotHandler. It allows the annotation handler to determine which annot is next in the tab order.
	AVAnnotHandlerGetAnnotViewBBoxProc A callback for AVAnnotHandler. It returns the rectangle enclosing the annotation on the screen.
	AVAnnotHandlerGetAppearanceExProc A callback for AVAnnotHandler. It fills in a structure representing an annotation's appearance. Upon return, the annotation appearance is drawn according to the returned flag values
	AVAnnotHandlerGetAppearanceProc A callback for AVAnnotHandler. It fills in a CosObj representing a Form field. Upon return, the annotation appearance is drawn according to the returned flag values
	AVAnnotHandlerGetAuxIconCountProc A callback for AVAnnotHandler. It returns information about auxiliary icons for the annotation on the screen.
	AVAnnotHandlerGetAuxIconsProc A callback for AVAnnotHandler. It returns information about auxiliary icons for the annotation on the screen.
	AVAnnotHandlerGetFlagsProc A callback for AVAnnotHandler. It returns the flags value for the annotation on the screen.
	AVAnnotHandlerGetInfoProc (Optional) A callback for AVAnnotHandler. It gets information associated with an annotation.
	AVAnnotHandlerGetLayerExProc A callback for AVAnnotHandler. It returns the annotation's layer. The layer need not be a constant. For example, the Acrobat viewer's built-in text annotations have a different layer depending on whether they are opened or closed. This ensures that a closed text annotation never appears on top of an open text annotation.
	AVAnnotHandlerGetLayerProc Deprecated in Acrobat 6.0. Use AVAnnotHandlerGetLayerExProc().
	AVAnnotHandlerGetTypeProc (Required) A callback for AVAnnotHandler. It returns an ASAtom indicating the annotation type for which the handler is responsible. This corresponds to the annotation's Subtype key in the PDF file.
	AVAnnotHandlerNewProc (Unused) A callback for AVAnnotHandler. It allows the annotation handler to add any attributes to the annotation object to make sure the new annotation is in a valid initial state for its subclass.
	AVAnnotHandlerNotifyAnnotAddedToSelectionProc (Optional) A callback for AVAnnotHandler. It is called when an annotation is added to the selection, and should highlight the annotation. Set it to NULL if it is omitted.
	AVAnnotHandlerNotifyAnnotRemovedFromSelectionProc (Optional) A callback for AVAnnotHandler. It is called when an annotation is removed from the selection, and should un-highlight the annotation. Set it to NULL if omitted.
	AVAnnotHandlerNotifyDestroyProc Currently unused.
	AVAnnotHandlerPerformOpProc Called to initiate the operation.
	AVAnnotHandlerPostDrawProc Called to request that additional drawing is performed after the annotation appearance is drawn.
	AVAnnotHandlerPtInAnnotViewBBoxProc A callback for AVAnnotHandler. It is called by AVPageViewIsAnnotAtPoint() to determine whether a point is within an annotation. The annotation handler is free to determine what it means for the point to be in the annotation. For example, if the annotation appears only as the outline of a circle, the point may be in the annotation only when it is near the border of the circle, but not when it is elsewhere within the circle.

	Method
	void AVAnnotHandlerDeleteInfo(AVAnnotHandler avanh, AVAnnotHandlerInfo info) Deletes the AVAnnotHandlerInfo associated with an annotation handler.
	AVAnnotHandlerInfo AVAnnotHandlerGetInfo(AVAnnotHandler avanh) Gets the information structure associated with an annotation handler.

Defines Detail

AVAnnotHandlerInfoInit

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define AVAnnotHandlerInfoInit do { \ memset(x, 0, sizeof(AVAnnotHandlerInfoRec)); \ x->size = sizeof(AVAnnotHandlerInfoRec); \ }while(0)

File: AVExpT.h

Line: 3015

Typedefs Detail

AVAnnotAppearanceDataRec

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_AVAnnotAppearanceData AVAnnotAppearanceDataRec;

File: AVExpT.h

Line: 3931

AVAnnotHandler

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_AVAnnotHandler AVAnnotHandler;

A data structure containing callbacks that implement an annotation handler. The callbacks implement the annotation handler functions. For example, they can be used to draw the annotation and highlight the annotation when it is selected. The data specifies properties of the annotation, such as text selection behavior.

Appearance drawing is new as of Acrobat 6.0. If the handler implements the GetAppearance() or GetAppearanceEx() callback, the new drawing style is used. If the GetAppearance() callback returns false or is not implemented, the viewer calls the drawing procedure (DrawEx() if present, Draw() otherwise) to draw the annotation using Acrobat 5.0-style drawing.

For the new style of appearance drawing, the viewer calls the handler's BeginAppearanceDrawing() callback, then draws the appearance object. If the drawing operation completes without errors, it call the the handler's BeginAppearanceDrawing() callback; if an error occurs or the operation is cancelled, it calls the CancelAppearanceDrawing() callback. This can happen if, for example, the user switches to another page before the drawing is completed.

The handler must not destroy or modify the appearance object while it is being drawn. It can do so only after the EndAppearanceDrawing() or CancelAppearanceDrawing() callback is exercised.

File: AVExpT.h

Line: 3150

AVAnnotHandlerInfo

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _AVAnnotHandlerInfoRec AVAnnotHandlerInfo;

File: AVExpT.h

Line: 3007

AVAnnotHandlerInfoRec

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _AVAnnotHandlerInfoRec AVAnnotHandlerInfoRec;

File: AVExpT.h

Line: 3007

AVAnnotHandlerRec

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_AVAnnotHandler AVAnnotHandlerRec;

File: AVExpT.h

Line: 4178

AVAnnotOpData

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_AVAnnotOpData AVAnnotOpData;

File: AVExpT.h

Line: 3099

AVAnnotOpDataRec

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_AVAnnotOpData AVAnnotOpDataRec;

File: AVExpT.h

Line: 3099

Enumeration Detail

AVAnnotAccStrType

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

enum AVAnnotAccStrType {

  kAVAnnotAccName,


 


  kAVAnnotAccValue,


 


  kAVAnnotAccDefaultAction

}

File: AVExpT.h

Line: 3831

Elements

	kAVAnnotAccName	The name and brief description.

	kAVAnnotAccValue	The content (or content description).

	kAVAnnotAccDefaultAction	The description of the default action.

AVAnnotOp

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

enum AVAnnotOp {

  kAVAnnotAcceptFocus,


 


  kAVAnnotLostFocus,


 


  kAVAnnotDefaultAction,


 


  kAVAnnotShowMenu,


 


  kAVAnnotSuspendFocus,


 


  kAVAnnotResumeFocus,


 


  kAVAnnotDoPageHasOpened,


 


  kAVAnnotDoPageHasClosed,


 


  kAVAnnotDoPageIsInView,


 


  kAVAnnotDoPageIsNotInView,


 


  kAVAnnotAddNewReply,


 


  kAVAnnotGetStateModel

}

See Also

AVPageViewFocusAnnotPerformOp

File: AVExpT.h

Line: 3029

Elements

	kAVAnnotAcceptFocus	Accept input focus.

	kAVAnnotLostFocus	Lost the input focus.

	kAVAnnotDefaultAction	The user presses Enter while in focus.

	kAVAnnotShowMenu	Show a context menu for the annotation.

	kAVAnnotSuspendFocus	The focus is temporarily lost; it may be restored.

	kAVAnnotResumeFocus	The focus has been restored.

	kAVAnnotDoPageHasOpened	The page the annotation is on has become the current page.

	kAVAnnotDoPageHasClosed	The page the annotation is on is no longer the current page.

	kAVAnnotDoPageIsInView	The page this annotation is on has become visible to the user.

	kAVAnnotDoPageIsNotInView	The page this annotation is on is no longer visible to the user.

	kAVAnnotAddNewReply	The ui is requesting to create a reply annotation for this annotation.

	kAVAnnotGetStateModel	The ui is requesting to fetch state model data for this annotation.

AVAnnotOpReason

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

enum AVAnnotOpReason {

  kAVAnnotUnknown = 0,


 


  kAVAnnotClick,


 


  kAVAnnotTab

}

See Also

AVPageViewFocusAnnotPerformOp

File: AVExpT.h

Line: 3068

Elements

	kAVAnnotUnknown	The first entry for `memset` of AVAnnotOpDataRec to `0`.

	kAVAnnotClick	An operation triggered by a mouse click.

	kAVAnnotTab	An operation triggered by a Tab key press.

Structure Detail

_AVAnnotHandlerInfoRec

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

struct _AVAnnotHandlerInfoRec {

  ASSize_t size;  


 


  unsigned char* cName;  


 


  void* vBitmap;  

}

A structure used to describe information for a particular annotation type.

File: AVExpT.h

Line: 2995

Elements

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

	cName	The user interface name of the annotation type in the host encoding.

	vBitmap	A platform-dependent bitmap used as the annotation icon. If it is `NULL`, the annotation manager uses the unknown annotation icon for the annotation.

_t_AVAnnotAppearanceData

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

struct _t_AVAnnotAppearanceData {

  ASSize_t size;  


 


  CosObj appearanceObject;  


 


  CosObj selectedShapeAppearanceObj;  

}

File: AVExpT.h

Line: 3918

Elements

	size	Set by the viewer to the size of the structure. The annotation handler can query this to determine if a field is in the structure and can be set.

	appearanceObject	The annotation handler must provide an appearance object.

	selectedShapeAppearanceObj	The annotation handler can optionally provide a separate appearance for drawing the selection visual. The selection visual will surround the shape of this object. If no selection object is provided, `appearanceObject` will be used to draw the selection visual.

_t_AVAnnotHandler

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

struct _t_AVAnnotHandler {

  ASSize_t size;  


 


  AVFlagBits32 flags;  


 


  AVAnnotHandlerNotifyAnnotRemovedFromSelectionProc NotifyAnnotRemovedFromSelection;  


 


  AVAnnotHandlerNotifyAnnotAddedToSelectionProc NotifyAnnotAddedToSelection;  


 


  AVAnnotHandlerDrawProc Draw;  


 


  AVAnnotHandlerNewProc New;  


 


  AVAnnotHandlerGetTypeProc GetType;  


 


  AVAnnotHandlerNotifyDestroyProc NotifyDestroy;  


 


  AVAnnotHandlerDoPropertiesProc DoProperties;  


 


  AVAnnotHandlerDoKeyDownProc DoKeyDown;  


 


  AVAnnotHandlerGetLayerProc GetLayer;  


 


  AVAnnotHandlerCursorEnterProc CursorEnter;  


 


  AVAnnotHandlerCursorExitProc CursorExit;  


 


  AVAnnotHandlerCopyProc Copy;  


 


  AVAnnotHandlerGetInfoProc GetInfo;  


 


  AVAnnotHandlerDeleteInfoProc DeleteInfo;  


 


  AVAnnotHandlerCanPerformOpProc CanPerformOp;  


 


  AVAnnotHandlerPerformOpProc PerformOp;  


 


  AVAnnotHandlerDoKeyDownExProc DoKeyDownEx;  


 


  AVAnnotHandlerGetFlagsProc GetFlags;  


 


  AVAnnotHandlerDoClickProc DoClick;  


 


  AVAnnotHandlerAdjustCursorProc AdjustCursor;  


 


  AVAnnotHandlerPtInAnnotViewBBoxProc PtInAnnotViewBBox;  


 


  AVAnnotHandlerGetAnnotViewBBoxProc GetAnnotViewBBox;  


 


  AVAnnotHandlerDoClickProc DoRightClick;  


 


  AVAnnotHandlerDrawExProc DrawEx;  


 


  AVAnnotHandlerGetAppearanceProc GetAppearance;  


 


  AVAnnotHandlerAppearanceDrawingProc BeginAppearanceDrawing;  


 


  AVAnnotHandlerAppearanceDrawingProc FinishAppearanceDrawing;  


 


  AVAnnotHandlerAppearanceDrawingProc CancelAppearanceDrawing;  


 


  AVAnnotHandlerDoPropertiesExProc DoPropertiesEx;  


 


  AVAnnotHandlerGetLayerExProc GetLayerEx;  


 


  AVAnnotHandlerDoClickExProc DoClickEx;  


 


  AVAnnotHandlerDoClickExProc DoRightClickEx;  


 


  AVAnnotHandlerAdjustCursorExProc AdjustCursorEx;  


 


  AVAnnotHandlerGetAccessibilityStringProc GetAccessibilityString;  


 


  AVAnnotHandlerGetAnnotInTabOrderProc GetAnnotInTabOrder;  


 


  AVAnnotHandlerGetAuxIconCountProc GetAuxIconCount;  


 


  AVAnnotHandlerGetAuxIconsProc GetAuxIcons;  


 


  AVAnnotHandlerGetAppearanceExProc GetAppearanceEx;  


 


  AVAnnotHandlerPostDrawProc PostDraw;  

}

A data structure containing callbacks that implement an annotation handler. The callbacks implement the annotation handler functions. For example, they can draw the annotation or highlight the annotation when it is selected. The data specifies properties of the annotation (for example, text selection behavior).

Appearance drawing is new in Acrobat 6.0. If the handler implements the GetAppearance() callback, the new drawing style is used. If the GetAppearance() callback returns false or is not implemented, the viewer calls the drawing procedure (DrawEx() if present, Draw() otherwise) to draw the annotation using Acrobat 5.0-style drawing.

For the new style of appearance drawing, the viewer calls the handler's BeginAppearanceDrawing() callback, then draws the appearance object. If the drawing operation completes without errors, it call the the handler's BeginAppearanceDrawing() callback; if an error occurs, or the operation is canceled, it calls the CancelAppearanceDrawing() callback. This can happen if, for example, the user switches to another page before the drawing is completed.

The handler must not destroy or modify the appearance object while it is being drawn. It can do so only after the EndAppearanceDrawing() or CancelAppearanceDrawing() callback has executed.

See Also

File: AVExpT.h

Line: 4020

Elements

size

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

flags

A collection of flags that affect the annotation's behavior. The flags may be OR-ed together.

Permissible flags:

Flag	Description
ANNOT_CLIP_TEXT_SELECTION	If this flag is set, text selection in the main document never selects text within the annotation (that is, the annotation behaves like the Acrobat viewer's text annotation). If this flag is not set, text selection in the main document can select text within the annotation (that is, the annotation behaves like the Acrobat viewer's link annotation).
ANNOT_WANTS_SHIFT_KEY	This flag is set to prevent the standard shift-key ignores annotation's behavior.

Draw

Deprecated

_t_AVAnnotOpData

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

struct _t_AVAnnotOpData {

  ASSize_t size;  


 


  AVDevCoord x;  


 


  AVDevCoord y;  


 


  void* clientData;  


 


  AVAnnotOpReason reason;  


 


  ASInt32 pageNum;  

}

Additional information passed to the annotation when performing an operation. For some operations a NULL will be passed; in others a pointer to an AVAnnotOpData structure will be passed.

See Also

AVPageViewSetFocusAnnot

File: AVExpT.h

Line: 3086

Elements

	size	Set by Acrobat to the size of this record.

	x	If the operation is kAVAnnotShowMenu, this value provides the default location of the menu in AV device coordinates (`x`).

	y	If the operation is kAVAnnotShowMenu, this value provides the default location of the menu in AV device coordinates (`y`)

	clientData	Used by Forms and Annots to determine when an annotation is getting focus via a mouse click.

	reason	The reason for this operation

	pageNum	The page number this annotation is on.

Callbacks Detail

AVAnnotHandlerAdjustCursorExProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerAdjustCursorExProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView, AVAdjustCursorParams params)

(Optional) A callback for AVAnnotHandler. It controls the cursor shape when the cursor is within the annotation. If NULL, the annotation behaves as if the AdjustCursor() callback returned false.

See Also

AVAnnotHandlerAdjustCursorProc

File: AVExpT.h

Line: 3826

AVAnnotHandlerAdjustCursorProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerAdjustCursorProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView, AVDevCoord xHit, AVDevCoord yHit)

Deprecated in Acrobat 6.0. Use AVAnnotHandlerAdjustCursorExProc().

(Optional) A callback for AVAnnotHandler. It controls the cursor shape when the cursor is within the annotation. If NULL, the annotation behaves as if the AdjustCursor() callback returned false.

See Also

AVAnnotHandlerAdjustCursorExProc

File: AVExpT.h

Line: 3244

AVAnnotHandlerAppearanceDrawingProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerAppearanceDrawingProc)(AVAnnotHandler annotHandler, PDAnnot annot, AVPageView pageView, const AVDevRect *annotRect, const AVDevRect *updateRect)

A callback for AVAnnotHandler that draws the appearance of the annotation for the given page view. Use this prototype for three callbacks: BeginAppearanceDrawing(), FinishAppearanceDrawing(), and CancelAppearanceDrawing().

If the viewer must abandon the drawing of the appearance, it calls the CancelAppearanceDrawing() callback. If the viewer succeeds in drawing the appearance, it calls the FinishAppearanceDrawing() callback. In either case, the handler can destroy the appearance object. See AVAnnotHandler.

If the annotation sets the kAVAppearanceSelected flag, the viewer will draw a selection visual around the appearance object. To make room for the selection visual, the annotation handler should call AVAppGetAnnotAppearancePadding() and expand the annotation's view bounding box by that number of pixels, to avoid having the selection visual clipped.

See Also

AVAnnotHandlerGetAppearanceProc

File: AVExpT.h

Line: 3714

AVAnnotHandlerCanPerformOpProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerCanPerformOpProc)(AVAnnotHandler annotHandler, PDAnnot annot, AVPageView pageView, AVAnnotOp annotOp, AVAnnotOpData opData)

Called to determine if this annotation can perform the specified operation.

See Also

AVAnnotHandlerPerformOpProc

File: AVExpT.h

Line: 3543

AVAnnotHandlerCopyProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

PDAnnot (*AVAnnotHandlerCopyProc)(AVAnnotHandler annotHandler, AVDoc fromDoc, PDAnnot anAnnot, AVDoc toDoc)

(Optional) A callback for AVAnnotHandler. It is called upon to copy an annotation, possibly to another document. Annotation handlers should provide this callback to allow for copying their annotations. It is called by AVDocCopyAnnot().

See Also

AVDocCopyAnnot

File: AVExpT.h

Line: 3489

AVAnnotHandlerCursorEnterProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerCursorEnterProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView)

(Optional) A callback for AVAnnotHandler. It is called whenever the cursor moves over an annotation handled by this annotation handler.

See Also

AVAnnotHandlerCursorExitProc

File: AVExpT.h

Line: 3461

AVAnnotHandlerCursorExitProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerCursorExitProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView)

(Optional) A callback for AVAnnotHandler. It is called whenever the cursor moves off an annotation handled by this annotation handler.

See Also

AVAnnotHandlerCursorEnterProc

File: AVExpT.h

Line: 3474

AVAnnotHandlerDeleteInfoProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerDeleteInfoProc)(AVAnnotHandler avanh, AVAnnotHandlerInfo info)

(Optional) A callback for AVAnnotHandler. It deletes information associated with an annotation.

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

File: AVExpT.h

Line: 3521

AVAnnotHandlerDoClickExProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerDoClickExProc)(AVAnnotHandler annotHandler, PDAnnot hitAnnot, AVPageView pageView, AVClickParams clickParams)

(Optional) A callback for AVAnnotHandler. It handles both left and right mouse button clicks within the annotation. If NULL, the annotation behaves as if the callback returned false.

See Also

AVAnnotHandlerDoClickProc

File: AVExpT.h

Line: 3810

AVAnnotHandlerDoClickProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerDoClickProc)(AVAnnotHandler annotHandler, PDAnnot hitAnnot, AVPageView pageView, AVDevCoord xHit, AVDevCoord yHit, AVFlagBits16 flags, AVTCount clickNo)

Deprecated in Acrobat 6.0. Use AVAnnotHandlerDoClickExProc().

(Optional) A callback for AVAnnotHandler. It handles both left and right mouse button clicks within the annotation. If NULL, the annotation behaves as if the callback returned false.

See Also

AVAnnotHandlerDoKeyDownExProc

File: AVExpT.h

Line: 3219

AVAnnotHandlerDoKeyDownExProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerDoKeyDownExProc)(AVAnnotHandler annotHandler, PDAnnot annot, AVPageView pageView, AVKeyCode key, AVFlagBits16 flags)

Called for each keystroke received when an annotation has focus.

See Also

AVAnnotHandlerDoKeyDownProc

File: AVExpT.h

Line: 3586

AVAnnotHandlerDoKeyDownProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerDoKeyDownProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVKeyCode key, AVFlagBits16 flags)

Deprecated in Acrobat 6.0. Use AVAnnotHandlerDoKeyDownExProc().

(Optional) A callback for AVAnnotHandler. It is called to handle key presses in the annotation. If NULL, it is as if the callback returned false.

It is called when there is a key-down event and the annotation is selected, and the active tool does not want the event.

See Also

AVAnnotHandlerDoKeyDownExProc

File: AVExpT.h

Line: 3431

AVAnnotHandlerDoPropertiesExProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerDoPropertiesExProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView)

(Optional) A callback for AVAnnotHandler. It displays whatever user interface it wishes to allow a user to change an annotation's properties. Set it to NULL if the annotation type has no user-specified properties.

It is called when the user selects the Properties item from the Edit menu while an annotation of this type is selected. If NULL, the Properties menu item is dimmed when a corresponding object is selected.

See Also

AVAnnotHandlerDoPropertiesProc

File: AVExpT.h

Line: 3735

AVAnnotHandlerDoPropertiesProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerDoPropertiesProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVDoc doc)

Deprecated in Acrobat 6.0. Use AVAnnotHandlerDoPropertiesExProc().

See Also

AVAnnotHandlerDoPropertiesExProc

File: AVExpT.h

Line: 3412

AVAnnotHandlerDrawExProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerDrawExProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView, AVDevRect *updateRect)

Called to request that the annotation appearance be drawn.

See Also

AVAnnotHandlerDrawProc

File: AVExpT.h

Line: 3170

AVAnnotHandlerDrawProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerDrawProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView)

Deprecated in Acrobat 6.0. Use AVAnnotHandlerDrawExProc().

(Optional) A callback for AVAnnotHandler that draws the annotation. Set it to NULL if the annotation handler has no Draw method.

If the annotation has an appearance (AP) entry, use this information to draw the annotation. Read the annotation's appearance state (AS) entry to determine which appearance to use. Then read the Cos stream for the appropriate appearance and display it with AVPageViewDrawCosObj().

See Also

AVAnnotHandlerDrawExProc

File: AVExpT.h

Line: 3356

AVAnnotHandlerEnumProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerEnumProc)(AVAnnotHandler annotHandler, void *clientData)

A callback for AVAppEnumAnnotHandlers(). It is called once for each annotation handler currently registered with the Acrobat viewer (see AVAppRegisterAnnotHandler()).

See Also

AVAppEnumAnnotHandlers

File: AVExpT.h

Line: 3299

AVAnnotHandlerGetAccessibilityStringProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerGetAccessibilityStringProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, PDPageNumber pageNum, AVAnnotAccStrType strType, ASText accString)

A callback for AVAnnotHandler. It gets the accessibility string associated with an annotation.

File: AVExpT.h

Line: 3855

AVAnnotHandlerGetAnnotInTabOrderProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerGetAnnotInTabOrderProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView, AVPageViewTabOrder tabOrder, PDAnnot *tabToAnnot, ASInt32 *tabToPageNo)

A callback for AVAnnotHandler. It allows the annotation handler to determine which annot is next in the tab order.

File: AVExpT.h

Line: 3879

AVAnnotHandlerGetAnnotViewBBoxProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerGetAnnotViewBBoxProc)(AVAnnotHandler annotHandler, AVPageView pageView, PDAnnot anAnnot, AVDevRect *bbox)

A callback for AVAnnotHandler. It returns the rectangle enclosing the annotation on the screen.

See Also

AVAnnotHandlerPtInAnnotViewBBoxProc

File: AVExpT.h

Line: 3285

AVAnnotHandlerGetAppearanceExProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerGetAppearanceExProc)(AVAnnotHandler annotHandler, PDAnnot annot, ASUns32 *flags, AVPageView pageView, AVAnnotAppearanceDataRec *appearanceData)

A callback for AVAnnotHandler. It fills in a structure representing an annotation's appearance. Upon return, the annotation appearance is drawn according to the returned flag values

If this callback is present, it will be called and the GetAppearance() callback will not be called.

This callback works identically to the GetAppearance() callback, but allows the annotation handler to provide additional information. If the kAVAppearanceSelected flag is set, this callback can optionally provide a separate appearance object to be used to draw the selection marks around the annotation.

See Also

AVAnnotHandlerAppearanceDrawingProc

File: AVExpT.h

Line: 3973

AVAnnotHandlerGetAppearanceProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerGetAppearanceProc)(AVAnnotHandler annotHandler, PDAnnot annot, ASUns32 *flags, AVPageView pageView, CosObj *apprObj)

A callback for AVAnnotHandler. It fills in a CosObj representing a Form field. Upon return, the annotation appearance is drawn according to the returned flag values

Appearance drawing is new in Acrobat 6.0. If the handler implements this method and it returns true, the new drawing style is used. If this function returns false, the viewer calls the drawing procedure to draw the annotation appearance. See AVAnnotHandler.

The handler must not destroy or modify the appearance object while it is being drawn. It can do so only after the EndAppearanceDrawing() or CancelAppearanceDrawing() callback is exercised.

See Also

AVAnnotHandlerAppearanceDrawingProc

File: AVExpT.h

Line: 3673

AVAnnotHandlerGetAuxIconCountProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASInt32 (*AVAnnotHandlerGetAuxIconCountProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView)

A callback for AVAnnotHandler. It returns information about auxiliary icons for the annotation on the screen.

See Also

AVAnnotHandlerGetAuxIconsProc

File: AVExpT.h

Line: 3896

AVAnnotHandlerGetAuxIconsProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

AVIconBundle6 (*AVAnnotHandlerGetAuxIconsProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView)

A callback for AVAnnotHandler. It returns information about auxiliary icons for the annotation on the screen.

See Also

AVAnnotHandlerGetAuxIconCountProc

File: AVExpT.h

Line: 3913

AVAnnotHandlerGetFlagsProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

AVFlagBits32 (*AVAnnotHandlerGetFlagsProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot)

A callback for AVAnnotHandler. It returns the flags value for the annotation on the screen.

See Also

AVAnnotHandlerGetAppearanceProc

File: AVExpT.h

Line: 3599

AVAnnotHandlerGetInfoProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

AVAnnotHandlerInfo (*AVAnnotHandlerGetInfoProc)(AVAnnotHandler avanh)

(Optional) A callback for AVAnnotHandler. It gets information associated with an annotation.

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

File: AVExpT.h

Line: 3506

AVAnnotHandlerGetLayerExProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASFixed (*AVAnnotHandlerGetLayerExProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView)

A callback for AVAnnotHandler. It returns the annotation's layer. The layer need not be a constant. For example, the Acrobat viewer's built-in text annotations have a different layer depending on whether they are opened or closed. This ensures that a closed text annotation never appears on top of an open text annotation.

See Also

AVAnnotHandlerGetLayerProc

File: AVExpT.h

Line: 3754

AVAnnotHandlerGetLayerProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASFixed (*AVAnnotHandlerGetLayerProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot)

Deprecated in Acrobat 6.0. Use AVAnnotHandlerGetLayerExProc().

See Also

AVAnnotHandlerGetLayerExProc

File: AVExpT.h

Line: 3448

AVAnnotHandlerGetTypeProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASAtom (*AVAnnotHandlerGetTypeProc)(AVAnnotHandler annotHandler)

(Required) A callback for AVAnnotHandler. It returns an ASAtom indicating the annotation type for which the handler is responsible. This corresponds to the annotation's Subtype key in the PDF file.

This is the method that AVAppGetAnnotHandlerByName() uses to find the correct handler.

See Also

AVAppRegisterAnnotHandler

File: AVExpT.h

Line: 3386

AVAnnotHandlerNewProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerNewProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView)

(Unused) A callback for AVAnnotHandler. It allows the annotation handler to add any attributes to the annotation object to make sure the new annotation is in a valid initial state for its subclass.

File: AVExpT.h

Line: 3370

AVAnnotHandlerNotifyAnnotAddedToSelectionProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerNotifyAnnotAddedToSelectionProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView)

(Optional) A callback for AVAnnotHandler. It is called when an annotation is added to the selection, and should highlight the annotation. Set it to NULL if it is omitted.

To allow only a single annotation to be selected at a time, keep a global variable containing the selected annotation and, on each invocation of NotifyAnnotAddedToSelection(), first deselect the current selection, if any (that is, if selectedAnnot is non-NULL), call its AVAnnotHandlerNotifyAnnotRemovedFromSelectionProc(), select the new annotation, and set selectedAnnot. Of course, RemovedFrom should set selectedAnnot to NULL.

See Also

AVDocSetSelection

File: AVExpT.h

Line: 3337

AVAnnotHandlerNotifyAnnotRemovedFromSelectionProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerNotifyAnnotRemovedFromSelectionProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView)

(Optional) A callback for AVAnnotHandler. It is called when an annotation is removed from the selection, and should un-highlight the annotation. Set it to NULL if omitted.

See Also

AVDocClearSelection
AVDocSetSelection

File: AVExpT.h

Line: 3316

AVAnnotHandlerNotifyDestroyProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerNotifyDestroyProc)(AVAnnotHandler annotHandler)

Currently unused.

File: AVExpT.h

Line: 3392

AVAnnotHandlerPerformOpProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerPerformOpProc)(AVAnnotHandler annotHandler, PDAnnot annot, AVPageView pageView, AVAnnotOp annotOp, AVAnnotOpData opData)

Called to initiate the operation.

See Also

AVAnnotHandlerCanPerformOpProc

File: AVExpT.h

Line: 3562

AVAnnotHandlerPostDrawProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVAnnotHandlerPostDrawProc)(AVAnnotHandler annotHandler, PDAnnot anAnnot, AVPageView pageView, AVDevRect *updateRect)

Called to request that additional drawing is performed after the annotation appearance is drawn.

See Also

AVAnnotHandlerDrawProc

File: AVExpT.h

Line: 3188

AVAnnotHandlerPtInAnnotViewBBoxProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVAnnotHandlerPtInAnnotViewBBoxProc)(AVAnnotHandler annotHandler, AVPageView pageView, PDAnnot anAnnot, AVDevCoord xHit, AVDevCoord yHit)

A callback for AVAnnotHandler. It is called by AVPageViewIsAnnotAtPoint() to determine whether a point is within an annotation. The annotation handler is free to determine what it means for the point to be in the annotation. For example, if the annotation appears only as the outline of a circle, the point may be in the annotation only when it is near the border of the circle, but not when it is elsewhere within the circle.

See Also

AVPageViewIsAnnotAtPoint

File: AVExpT.h

Line: 3268

Method Detail

AVAnnotHandlerDeleteInfo

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





void AVAnnotHandlerDeleteInfo(AVAnnotHandler avanh, AVAnnotHandlerInfo info)

Deletes the AVAnnotHandlerInfo associated with an annotation handler.

Parameters

	`avanh` —	IN/OUT The annotation handler.

	`info` —	IN/OUT The AVAnnotHandlerInfo associated with the annotation handler. `info` contains the user interface name of the annotation type and the platform-dependent bitmap used as the annotation icon.

See Also

AVAnnotHandlerGetInfo

Since

PI_ACROVIEW_VERSION >= 0x00040000

File: AVProcs.h

Line: 4004

AVAnnotHandlerGetInfo

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVAnnotHandlerInfo AVAnnotHandlerGetInfo(AVAnnotHandler avanh)

Gets the information structure associated with an annotation handler.

Parameters

avanh —

IN/OUT The annotation handler for which the information structure is needed.

Returns

The information structure associated with the annotation handler, or NULL if the handler does not support this operation.

See Also

AVAnnotHandlerDeleteInfo

Since

PI_ACROVIEW_VERSION >= 0x00040000

File: AVProcs.h

Line: 3991

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

	kAVAnnotAcceptFocus,

	kAVAnnotLostFocus,

	kAVAnnotDefaultAction,

	kAVAnnotShowMenu,

	kAVAnnotSuspendFocus,

	kAVAnnotResumeFocus,

	kAVAnnotDoPageHasOpened,

	kAVAnnotDoPageHasClosed,

	kAVAnnotDoPageIsInView,

	kAVAnnotDoPageIsNotInView,

	kAVAnnotAddNewReply,

	kAVAnnotGetStateModel

	ASSize_t size;

	AVFlagBits32 flags;

	AVAnnotHandlerNotifyAnnotRemovedFromSelectionProc NotifyAnnotRemovedFromSelection;

	AVAnnotHandlerNotifyAnnotAddedToSelectionProc NotifyAnnotAddedToSelection;

	AVAnnotHandlerDrawProc Draw;

	AVAnnotHandlerNewProc New;

	AVAnnotHandlerGetTypeProc GetType;

	AVAnnotHandlerNotifyDestroyProc NotifyDestroy;

	AVAnnotHandlerDoPropertiesProc DoProperties;

	AVAnnotHandlerDoKeyDownProc DoKeyDown;

	AVAnnotHandlerGetLayerProc GetLayer;

	AVAnnotHandlerCursorEnterProc CursorEnter;

	AVAnnotHandlerCursorExitProc CursorExit;

	AVAnnotHandlerCopyProc Copy;

	AVAnnotHandlerGetInfoProc GetInfo;

	AVAnnotHandlerDeleteInfoProc DeleteInfo;

	AVAnnotHandlerCanPerformOpProc CanPerformOp;

	AVAnnotHandlerPerformOpProc PerformOp;

	AVAnnotHandlerDoKeyDownExProc DoKeyDownEx;

	AVAnnotHandlerGetFlagsProc GetFlags;

	AVAnnotHandlerDoClickProc DoClick;

	AVAnnotHandlerAdjustCursorProc AdjustCursor;

	AVAnnotHandlerPtInAnnotViewBBoxProc PtInAnnotViewBBox;

	AVAnnotHandlerGetAnnotViewBBoxProc GetAnnotViewBBox;

	AVAnnotHandlerDoClickProc DoRightClick;

	AVAnnotHandlerDrawExProc DrawEx;

	AVAnnotHandlerGetAppearanceProc GetAppearance;

	AVAnnotHandlerAppearanceDrawingProc BeginAppearanceDrawing;

	AVAnnotHandlerAppearanceDrawingProc FinishAppearanceDrawing;

	AVAnnotHandlerAppearanceDrawingProc CancelAppearanceDrawing;

	AVAnnotHandlerDoPropertiesExProc DoPropertiesEx;

	AVAnnotHandlerGetLayerExProc GetLayerEx;

	AVAnnotHandlerDoClickExProc DoClickEx;

	AVAnnotHandlerDoClickExProc DoRightClickEx;

	AVAnnotHandlerAdjustCursorExProc AdjustCursorEx;

	AVAnnotHandlerGetAccessibilityStringProc GetAccessibilityString;

	AVAnnotHandlerGetAnnotInTabOrderProc GetAnnotInTabOrder;

	AVAnnotHandlerGetAuxIconCountProc GetAuxIconCount;

	AVAnnotHandlerGetAuxIconsProc GetAuxIcons;

	AVAnnotHandlerGetAppearanceExProc GetAppearanceEx;

	AVAnnotHandlerPostDrawProc PostDraw;

	ASSize_t size;

	AVDevCoord x;

	AVDevCoord y;

	void* clientData;

	AVAnnotOpReason reason;

	ASInt32 pageNum;

	kAVAnnotAccName,

	kAVAnnotAccValue,

	kAVAnnotAccDefaultAction

	ASSize_t size;

	unsigned char* cName;

	void* vBitmap;

	ASSize_t size;

	CosObj appearanceObject;

	CosObj selectedShapeAppearanceObj;

Layer	AV_Layer
Object	AVAnnotHandler