LayerAV_Layer
ObjectAVAnnotHandler

An AVAnnotHandler is responsible for creating, displaying, selecting, and deleting a particular type of annotation. There is one annotation handler for each annotation type. Acrobat contains two built-in annotation types (notes and links), and plug-ins can add new annotation handlers by using AVAppRegisterAnnotHandler(). See Developing Plug-ins and Applications for details on creating new annotation types.

An AVAnnotHandler is generally accessed through AVApp methods.



Define Summary
 Define
 AVAnnotHandlerInfoInit
Typedef Summary
 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 Summary
 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 Summary
 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 Summary
 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 Summary
 Method
 
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.

See Also


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

See Also


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


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.

See Also


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


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


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


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


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


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


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


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


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.

See Also


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


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


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


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


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


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

(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


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


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


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


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


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


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


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


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


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


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.

See Also


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


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

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


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


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


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


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


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


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


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

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

Since

PI_ACROVIEW_VERSION >= 0x00040000

File: AVProcs.h
Line: 3991