LayerPD_Layer
ObjectPDAnnot

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

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



Define Summary
 Define
 CastToPDAnnot
Casts a link annotation or a text annotation to a generic annotation.
 pdAnnotHidden
The annotation is not visible and does not print.
 PDAnnotIgnorePerms
Allows modifying this annotation type in a write-protected document.
 PDAnnotInfoInit
 pdAnnotInvisible
If there is no annotation handler, the annotation is invisible.
 pdAnnotLock
The annotation does not move or resize with the view. Currently only form fields respect this flag. If the annotation is locked, the user cannot delete, move or change its associated form field's properties.
 pdAnnotLockContents
If the annotation is content-locked, the user can not change its content key.
 PDAnnotMaxDashes
 pdAnnotNoRotate
The annotation does not rotate with the page.
 pdAnnotNoView
The annotation does not view but can print.
 pdAnnotNoZoom
The annotation does not zoom with the view.
 PDAnnotOperationAll
All operations are allowed.
 PDAnnotOperationFilter
It is okay to filter annotations.
 PDAnnotOperationFlatten
When creating a flattened page include this annot
 PDAnnotOperationManager
It is okay to manage annotations.
 PDAnnotOperationSummarize
It is okay to summarize annotations.
 pdAnnotPrint
The annotation prints.
 pdAnnotReadOnly
The annotation does not interact with the user.
 pdAnnotSequenceAdjust
A place holder used only at runtime. Do not set this bit in PDF/FDF files.
 pdAnnotToggleNoView
A mouse-over or selection causes the noView bit to toggle.
Typedef Summary
 Typedef
 PDAnnot
An annotation on a page in a PDF file. Acrobat viewers have two built-in annotation types: PDTextAnnot and PDLinkAnnot. Physical attributes of the annotation can be set and queried. Plug-ins add movie and Widget (form field) annotations. Developers can define new annotation subtypes by creating new annotation handlers.
 PDAnnotArray
 PDAnnotArrayRec
 PDAnnotClipboardData
Used to store PDAnnot data for copy and paste operations.
 PDAnnotInfo
 PDAnnotInfoRec
Enumeration Summary
 Enumeration
  PDAnnotPrintOp
PDAnnotPrintOp is passed to the PDAnnotHandlerGetPrintAppearanceProc() callback to specify the type of print operation being performed.
Structure Summary
 Structure
 _PDAnnotInfoRec
Information associated with an annotation.
 _s_PDAnnotArray
Used by PDDocExportSomeNotes(). It represents an array of PDAnnot objects.
Callback Summary
 Callback
 PDAnnotWillPrintProc
A callback for PDAnnotHandler. This method is called to determine whether an annotation is printed.
Method Summary
 Method
 
ASBool PDAnnotCanCopy(PDPage sourcePage, PDAnnot annot)
Tests whether the data from an annotation on a given page can be copied to a clipboard for pasting. This depends on whether there is a PDAnnotHandler with copy and paste support for the annotation, and whether copying is allowed by document permissions.
 
ASBool PDAnnotCanPaste(PDPage destPage, const ASFixedPoint* center, PDAnnotClipboardData data)
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.
 
PDAnnotClipboardData PDAnnotCopy(PDPage sourcePage, PDAnnot annot)
Copies action object data to a clipboard structure, from which it can be pasted.
 
Destroys data that has been copied from an annotation object into a clipboard. Use this method after successfully pasting the data to a new document.
 
void PDAnnotDidChange(PDAnnot annot, ASAtom key, ASInt32 error, void* clientData)
An annotation changed in the specified way.
 
ASBool PDAnnotEqual(PDAnnot anAnnot, PDAnnot annot2)
Tests whether two annotations are identical.
 
Converts a dictionary Cos object to an annotation. This method does not copy the object, but is instead the logical equivalent of a type cast.
 
ASBool PDAnnotGetColor(PDAnnot anAnnot, PDColorValue color)
Gets a note or link annotation's color. If the annotation does not specify an explicit color, a default color is returned. Text annotations return default yellow; all others return black. Only RGB color specifications are currently supported.
 
Gets the Cos object corresponding to an annotation. This method does not copy the object, but is instead the logical equivalent of a type cast.
 
ASBool PDAnnotGetDate(PDAnnot anAnnot, ASTimeRecP date)
Gets an annotation's date.
 
ASUns32 PDAnnotGetFlags(PDAnnot anAnnot)
Gets an annotation's flags.
 
PDOCMD PDAnnotGetOCMD(PDAnnot annot)
Gets an optional-content membership dictionary (OCMD) object associated with the annotation.
 
void PDAnnotGetRect(PDAnnot anAnnot, ASFixedRect* boxP)
Gets the size and location of an annotation on its page.
 
ASAtom PDAnnotGetSubtype(PDAnnot anAnnot)
Gets an annotation's subtype.
 
ASInt32 PDAnnotGetTitle(PDAnnot anAnnot, char* buffer, ASInt32 bufSize)
Gets an annotation's label text.
 
void PDAnnotGetTitleASText(PDAnnot anAnnot, ASText title)
Gets an annotation's label text as an ASText object.
 
Tests whether an annotation with an OC entry is visible in a given optional-content context, considering the current ON-OFF states of the optional-content groups in the optional-content dictionary (OCMD) and the dictionary's visibility policy.
 
ASBool PDAnnotIsValid(PDAnnot anAnnot)
Tests whether an annotation is valid. This is intended only to ensure that the annotation has not been deleted, not to ensure that all necessary information is present and valid.
 
Broadcasts a PDAnnotDidChange() notification. Clients must call this method after making any change to a custom annotation.
 
Broadcasts a PDAnnotWillChange() notification. Clients must call this method before making any change to a custom annotation.
 
PDAnnot PDAnnotPaste(PDPage destPage, const ASFixedPoint* center, PDAnnotClipboardData data)
Pastes copied annotation data from a clipboard structure to a new annotation object in a specified document. After successfully pasting the data, use PDAnnotDestroyClipboardData() to free the associated memory.
 
Dissociates any optional-content membership dictionary (OCMD) object from the annotation.
 
void PDAnnotSetColor(PDAnnot anAnnot, const PDColorValue color)
Sets a note or link annotation's color. Only RGB color specifications are currently supported.
 
void PDAnnotSetDate(PDAnnot anAnnot, const ASTimeRecP date)
Sets an annotation's date.
 
void PDAnnotSetFlags(PDAnnot anAnnot, ASUns32 flags)
Sets an annotation's flags.
 
void PDAnnotSetOCMD(PDAnnot annot, PDOCMD pdocmd)
Associates an optional-content membership dictionary (OCMD) object with the annotation, making it optionally visible according to the OCMD's visibility policy. If the annotation already has a dictionary, the method replaces it.
 
void PDAnnotSetRect(PDAnnot anAnnot, const ASFixedRect* newBox)
Sets the size and location of an annotation on its page.
 
void PDAnnotSetTitle(PDAnnot anAnnot, const char* str, ASInt32 nBytes)
Sets an annotation's label text.
 
void PDAnnotSetTitleASText(PDAnnot anAnnot, const ASText title)
Sets an annotation's label text.
 
void PDAnnotWasCreated(PDAnnot annot, PDPage page, void* clientData)
An annotation was created.
 
void PDAnnotWillChange(PDAnnot annot, ASAtom key, void* clientData)
An annotation will change in the specified way.
Defines Detail
CastToPDAnnot 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CastToPDAnnot *(PDAnnot *)&(a)

Description

Casts a link annotation or a text annotation to a generic annotation.

See Also


File: PDExpT.h
Line: 426
pdAnnotHidden 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define pdAnnotHidden 0x02

Description

The annotation is not visible and does not print.


File: PDExpT.h
Line: 370
PDAnnotIgnorePerms 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDAnnotIgnorePerms 0x0008

Description

Allows modifying this annotation type in a write-protected document.


File: PDExpT.h
Line: 464
PDAnnotInfoInit 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDAnnotInfoInit do { \ ASmemset(x, 0, sizeof(PDAnnotInfoRec)); \ x->size = sizeof(PDAnnotInfoRec); \ x->fxLayer = fixedTwo; \ } while (0)

File: PDExpT.h
Line: 513
pdAnnotInvisible 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define pdAnnotInvisible 0x01

Description

If there is no annotation handler, the annotation is invisible.


File: PDExpT.h
Line: 365
pdAnnotLock 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define pdAnnotLock 0x80

Description

The annotation does not move or resize with the view. Currently only form fields respect this flag. If the annotation is locked, the user cannot delete, move or change its associated form field's properties.


File: PDExpT.h
Line: 401
pdAnnotLockContents 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define pdAnnotLockContents 0x200

Description

If the annotation is content-locked, the user can not change its content key.


File: PDExpT.h
Line: 411
PDAnnotMaxDashes 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDAnnotMaxDashes 10

File: PDExpT.h
Line: 1020
pdAnnotNoRotate 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define pdAnnotNoRotate 0x10

Description

The annotation does not rotate with the page.


File: PDExpT.h
Line: 385
pdAnnotNoView 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define pdAnnotNoView 0x20

Description

The annotation does not view but can print.


File: PDExpT.h
Line: 390
pdAnnotNoZoom 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define pdAnnotNoZoom 0x08

Description

The annotation does not zoom with the view.


File: PDExpT.h
Line: 380
PDAnnotOperationAll 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDAnnotOperationAll 0xFFFF

Description

All operations are allowed.


File: PDExpT.h
Line: 474
PDAnnotOperationFilter 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDAnnotOperationFilter 0x0002

Description

It is okay to filter annotations.


File: PDExpT.h
Line: 454
PDAnnotOperationFlatten 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDAnnotOperationFlatten 0x0010

Description

When creating a flattened page include this annot


File: PDExpT.h
Line: 469
PDAnnotOperationManager 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDAnnotOperationManager 0x0004

Description

It is okay to manage annotations.


File: PDExpT.h
Line: 459
PDAnnotOperationSummarize 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDAnnotOperationSummarize 0x0001

Description

It is okay to summarize annotations.


File: PDExpT.h
Line: 449
pdAnnotPrint 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define pdAnnotPrint 0x04

Description

The annotation prints.


File: PDExpT.h
Line: 375
pdAnnotReadOnly 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define pdAnnotReadOnly 0x40

Description

The annotation does not interact with the user.


File: PDExpT.h
Line: 395
pdAnnotSequenceAdjust 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define pdAnnotSequenceAdjust 0x80000000

Description

A place holder used only at runtime. Do not set this bit in PDF/FDF files.


File: PDExpT.h
Line: 416
pdAnnotToggleNoView 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define pdAnnotToggleNoView 0x100

Description

A mouse-over or selection causes the noView bit to toggle.


File: PDExpT.h
Line: 406

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

Syntax

typedef OPAQUE_64_BITS PDAnnot;

An annotation on a page in a PDF file. Acrobat viewers have two built-in annotation types: PDTextAnnot and PDLinkAnnot. Physical attributes of the annotation can be set and queried. Plug-ins add movie and Widget (form field) annotations. Developers can define new annotation subtypes by creating new annotation handlers.

See Also


File: PDExpT.h
Line: 317
PDAnnotArray 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _s_PDAnnotArray PDAnnotArray;

File: PDExpT.h
Line: 6268
PDAnnotArrayRec 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _s_PDAnnotArray PDAnnotArrayRec;

File: PDExpT.h
Line: 6268
PDAnnotClipboardData 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef struct _t_PDAnnotClipboardData* PDAnnotClipboardData;

Used to store PDAnnot data for copy and paste operations.

See Also


File: PDExpT.h
Line: 536
PDAnnotInfo 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _PDAnnotInfoRec PDAnnotInfo;

File: PDExpT.h
Line: 502
PDAnnotInfoRec 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _PDAnnotInfoRec PDAnnotInfoRec;

File: PDExpT.h
Line: 502

Enumeration Detail
PDAnnotPrintOp
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

enum PDAnnotPrintOp {
 kPDAnnotPrintStandard = 1,
 
 kPDAnnotPrintVariableData
}

See Also


File: PDExpT.h
Line: 547

Elements
kPDAnnotPrintStandard  

A standard print operation.

 
kPDAnnotPrintVariableData  

The user selected Form Fields Only.


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

Syntax

struct _PDAnnotInfoRec {
 ASSize_t size; 
 
 ASFlagBits nOperationFlags; 
 
 unsigned char* cAuthor; 
 
 unsigned char* cContents; 
 
 unsigned char* cDate; 
 
 ASFixed fxLayer; 
}

Information associated with an annotation.

See Also


File: PDExpT.h
Line: 482

Elements
size  

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

 
nOperationFlags  

The allowed operations.

 
cAuthor  

The author of this annotation.

 
cContents  

The associated text for this annotation.

 
cDate  

The modification date of this annotation.

 
fxLayer  

The layer of this annotation.

_s_PDAnnotArray 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

struct _s_PDAnnotArray {
 ASTArraySize annotCount; 
 
 PDAnnot annots; 
}

Used by PDDocExportSomeNotes(). It represents an array of PDAnnot objects.

See Also


File: PDExpT.h
Line: 6261

Elements
annotCount  

The annotation count.

 
annots  

A pointer to an array of PDAnnots.

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

Syntax

ASBool (*PDAnnotWillPrintProc)(PDAnnotHandler pdanh, PDAnnot annot)

A callback for PDAnnotHandler. This method is called to determine whether an annotation is printed.

See Also


File: PDExpT.h
Line: 655

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

Syntax

ASBool PDAnnotCanCopy(PDPage sourcePage, PDAnnot annot)

Tests whether the data from an annotation on a given page can be copied to a clipboard for pasting. This depends on whether there is a PDAnnotHandler with copy and paste support for the annotation, and whether copying is allowed by document permissions.

Parameters

sourcePage — 

The page containing the annotation to test. It can be NULL (as when copying annotations while spawning a hidden template).

 
annot — 

The annotation to test.

Returns

true if the annotation object can be copied, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10762
PDAnnotCanPaste() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDAnnotCanPaste(PDPage destPage, const ASFixedPoint* center, PDAnnotClipboardData data)

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.

Parameters

destPage — 

The page to which the annotation would be pasted.

 
center — 

The location for the center of the annotation on the destination page, or a NULL pointer to center the annotation on the destination page.

 
data — 

The copied annotation data to test.

Returns

true if the annotation data can be pasted, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10800
PDAnnotCopy() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDAnnotClipboardData PDAnnotCopy(PDPage sourcePage, PDAnnot annot)

Copies action object data to a clipboard structure, from which it can be pasted.

Parameters

sourcePage — 

The page containing the annotation to copy. It can be NULL (as when copying annotations while spawning a hidden template).

 
annot — 

The annotation to copy.

Returns

The annotation clipboard data object.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10778
PDAnnotDestroyClipboardData() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotDestroyClipboardData(PDAnnotClipboardData data)

Destroys data that has been copied from an annotation object into a clipboard. Use this method after successfully pasting the data to a new document.

Parameters

data — 

The clipboard annotation data to destroy.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10835
PDAnnotDidChange() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotDidChange(PDAnnot annot, ASAtom key, ASInt32 error, void* clientData)

An annotation changed in the specified way.

Parameters

annot — 

The annotation that changed.

 
key — 

The ASAtom specifying how the annotation changed. The ASAtom corresponding to the key that changed in the annotation's Cos dictionary. See Section 8.4 on annotations in the PDF Reference for information on the keys.

 
error — 

The error code. error is set to 0 if no errors occurred while changing the annotation. If an error occurred, error contains the error code.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

See Also

Notifications


File: PIPokes.h
Line: 993
PDAnnotEqual() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDAnnotEqual(PDAnnot anAnnot, PDAnnot annot2)

Tests whether two annotations are identical.

Parameters

anAnnot — 

The first annotation to compare.

 
annot2 — 

The second annotation to compare.

Returns

true if the annotations are equal, false otherwise. Two annotations are equal only if their Cos objects are equal (see CosObjEqual()).

See Also

Exceptions

pdErrBadAnnotation

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 380
PDAnnotFromCosObj() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDAnnot PDAnnotFromCosObj(CosObj obj)

Converts a dictionary Cos object to an annotation. This method does not copy the object, but is instead the logical equivalent of a type cast.

Parameters

obj — 

The dictionary Cos object whose annotation is obtained.

Returns

The PDAnnot corresponding to the Cos object.

See Also

Exceptions

pdErrBadAnnotation is raised if the annotation is invalid, as determined by PDAnnotIsValid().

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 561
PDAnnotGetColor() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDAnnotGetColor(PDAnnot anAnnot, PDColorValue color)

Gets a note or link annotation's color. If the annotation does not specify an explicit color, a default color is returned. Text annotations return default yellow; all others return black. Only RGB color specifications are currently supported.

Parameters

anAnnot — 

The note or link annotation whose color is obtained.

 
color — 

(Filled by the method) The annotation's color, which is used as follows:

Annotation

Use

Closed text note

The icon background color.

Open, un-selected text note

The bounding rectangle color.

Open, selected text note

The color of the annotation's title bar.

Link annotation

The link border color.

Returns

true if the annotation specifies an explicit color, false if a default color was used.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 410
PDAnnotGetCosObj() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

CosObj PDAnnotGetCosObj(PDAnnot annot)

Gets the Cos object corresponding to an annotation. This method does not copy the object, but is instead the logical equivalent of a type cast.

Parameters

annot — 

IN/OUT The annotation whose Cos object is obtained.

Returns

The dictionary Cos object for the annotation. The contents of the dictionary can be enumerated using CosObjEnum(). It returns a NULL Cos object if the annotation is not valid, as determined by PDAnnotIsValid().

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

Examples

go to source arrow CosObj coAnnot = PDAnnotGetCosObj(pdan);

File: PDProcs.h
Line: 547
PDAnnotGetDate() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDAnnotGetDate(PDAnnot anAnnot, ASTimeRecP date)

Gets an annotation's date.

Parameters

anAnnot — 

The annotation whose date is obtained.

 
date — 

(Filled by the method) The annotation's time and date.

Returns

true if the annotation contains a date key and the value of that key can be successfully parsed as a date string, false otherwise.

See Also

Exceptions

pdErrBadAnnotation is raised if the annotation is not valid or if the value of the annotation's M (ModDate) key is not a string.
genErrBadParm is raised if date is NULL.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 517
PDAnnotGetFlags() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASUns32 PDAnnotGetFlags(PDAnnot anAnnot)

Gets an annotation's flags.

Parameters

anAnnot — 

IN/OUT The annotation whose flags are obtained.

Returns

The flags, or 0 if the annotation does not have a flags key.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 717
PDAnnotGetOCMD() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDOCMD PDAnnotGetOCMD(PDAnnot annot)

Gets an optional-content membership dictionary (OCMD) object associated with the annotation.

Parameters

annot — 

The annotation from which the dictionary is obtained.

Returns

The dictionary object, or NULL if the annotation does not contain a dictionary.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9221
PDAnnotGetRect() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotGetRect(PDAnnot anAnnot, ASFixedRect* boxP)

Gets the size and location of an annotation on its page.

Parameters

anAnnot — 

IN/OUT The annotation whose location and size are set.

 
boxP — 

IN/OUT (Filled by the method) A pointer to a rectangle that specifies the annotation's bounding rectangle, specified in user space coordinates.

See Also

Exceptions

pdErrBadAnnotation

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 348
PDAnnotGetSubtype() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASAtom PDAnnotGetSubtype(PDAnnot anAnnot)

Gets an annotation's subtype.

Parameters

anAnnot — 

The annotation whose subtype is obtained.

Returns

The ASAtom for the annotation's subtype. This can be converted to a string using ASAtomGetString(). The storage pointed to by the return value is owned by the Acrobat viewer and should be assumed to be valid only until the next call into any client API method; it should be immediately copied by the client if the client wants to reference it later.

ASAtomNull if the annotation does not have a Subtype key or its value is not a name object.

Exceptions

pdErrBadAnnotation

Since

PI_PDMODEL_VERSION >= 0x00020000

Examples


File: PDProcs.h
Line: 330
PDAnnotGetTitle() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASInt32 PDAnnotGetTitle(PDAnnot anAnnot, char* buffer, ASInt32 bufSize)

Gets an annotation's label text.

Parameters

anAnnot — 

IN/OUT The annotation whose label is obtained.

 
buffer — 

IN/OUT (Filled by the method) The string into which the annotation's label string is copied. If the string is non-NULL, up to bufsSize bytes are copied into the buffer.

 
bufSize — 

IN/OUT The buffer size in bytes. Up to bufSize bytes of the annotation label string are copied into the string and an ASCII NULL character is appended. The caller is expected to have allocated bufSize + 1 bytes to allow for the NULL. If buffer is NULL, it copies nothing.

Returns

If the string is non-NULL, it returns the number of bytes copied, not counting the trailing NULL. If the string is NULL, it returns the number of bytes that would be copied if the string were not NULL.

See Also

Exceptions

pdErrBadAnnotation

Since

PI_PDMODEL_VERSION >= 0x00020000

Note

For Roman viewers, this text is always stored in the PDFDocEncoding. For non-Roman character set viewers, this text is stored as PDFDocEncoding or Unicode, depending on the file's creator. Files created in a non-Roman environment contain Unicode versions of these strings; in a Roman environment, files contain PDFDocEncoding versions of these strings.

File: PDProcs.h
Line: 470
PDAnnotGetTitleASText() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotGetTitleASText(PDAnnot anAnnot, ASText title)

Gets an annotation's label text as an ASText object.

Parameters

anAnnot — 

The annotation whose label is obtained.

 
title — 

(Filled by the method) The text object containing the annotation's label string. The client must pass a valid ASText object title. The routine does not allocate it.

See Also

Exceptions

pdErrBadAnnotation

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h
Line: 11316
PDAnnotIsCurrentlyVisible() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDAnnotIsCurrentlyVisible(PDAnnot annot, PDOCContext ocContext)

Tests whether an annotation with an OC entry is visible in a given optional-content context, considering the current ON-OFF states of the optional-content groups in the optional-content dictionary (OCMD) and the dictionary's visibility policy.

Parameters

annot — 

The annotation to test.

 
ocContext — 

The optional-content context in which the visibility is tested.

Returns

true if the annotation is visible in the given context or if the annotation has no OC entry, false if it is hidden.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9287
PDAnnotIsValid() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDAnnotIsValid(PDAnnot anAnnot)

Tests whether an annotation is valid. This is intended only to ensure that the annotation has not been deleted, not to ensure that all necessary information is present and valid.

Parameters

anAnnot — 

The annotation whose validity is tested.

Returns

true if anAnnot is a valid annotation object, false otherwise. An annotation is valid if it is a Cos dictionary object and has a Rect key.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

Examples

go to source arrow if (!PDAnnotIsValid(pdan) ||

File: PDProcs.h
Line: 313
PDAnnotNotifyDidChange() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotNotifyDidChange(PDAnnot annot, ASAtom key, ASInt32 err)

Broadcasts a PDAnnotDidChange() notification. Clients must call this method after making any change to a custom annotation.

Parameters

annot — 

The annotation that has changed.

 
key — 

The ASAtom corresponding to the name of the key in the annotation's Cos dictionary that is changing.

 
err — 

An error code to pass to any method registered to receive the PDAnnotDidChange() notification. Pass zero if the annotation was changed successfully. Pass a nonzero value if an error occurred while changing the annotation.

See Also

PDAnnotNotifyWillChange
AVAppRegisterNotification

Notifications

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 260
PDAnnotNotifyWillChange() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotNotifyWillChange(PDAnnot annot, ASAtom key)

Broadcasts a PDAnnotWillChange() notification. Clients must call this method before making any change to a custom annotation.

Parameters

annot — 

The annotation that has changed.

 
key — 

The ASAtom corresponding to the name of the key in the annotation's Cos dictionary that is changing.

See Also

PDAnnotNotifyDidChange
AVAppRegisterNotification

Notifications

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 241
PDAnnotPaste() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDAnnot PDAnnotPaste(PDPage destPage, const ASFixedPoint* center, PDAnnotClipboardData data)

Pastes copied annotation data from a clipboard structure to a new annotation object in a specified document. After successfully pasting the data, use PDAnnotDestroyClipboardData() to free the associated memory.

Parameters

destPage — 

The page to which the annotation is pasted.

 
center — 

The location for the center of the annotation on the destination page, or a NULL pointer to center the annotation on the destination page.

 
data — 

The copied annotation data to paste.

Returns

A newly created annotation object associated with the specified document, containing the same data as the copied annotation.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10822
PDAnnotRemoveOCMD() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotRemoveOCMD(PDAnnot annot)

Dissociates any optional-content membership dictionary (OCMD) object from the annotation.

Parameters

annot — 

The annotation for which to remove the dictionary.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9232
PDAnnotSetColor() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotSetColor(PDAnnot anAnnot, const PDColorValue color)

Sets a note or link annotation's color. Only RGB color specifications are currently supported.

Parameters

anAnnot — 

IN/OUT The note or link annotation whose color is set.

 
color — 

IN/OUT The annotation's color, which is used as follows:

Annotation

Use

Closed text note

The icon background color.

Open, un-selected text note

The bounding rectangle color.

Open, selected text note

The color of the annotation's title bar.

Link annotation

The link border color.

See Also

Notifications

Since

PI_PDMODEL_VERSION >= 0x00020000

Examples

go to source arrow PDAnnotSetColor(myannot,color);

File: PDProcs.h
Line: 436
PDAnnotSetDate() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotSetDate(PDAnnot anAnnot, const ASTimeRecP date)

Sets an annotation's date.

Parameters

anAnnot — 

IN/OUT The annotation whose date is set.

 
date — 

IN/OUT The annotation's time and date.

See Also

Notifications

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 532
PDAnnotSetFlags() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotSetFlags(PDAnnot anAnnot, ASUns32 flags)

Sets an annotation's flags.

Parameters

anAnnot — 

IN/OUT The annotation whose flags are set.

 
flags — 

IN/OUT An OR of the PDAnnot Flags values.

See Also

Notifications

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 732
PDAnnotSetOCMD() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotSetOCMD(PDAnnot annot, PDOCMD pdocmd)

Associates an optional-content membership dictionary (OCMD) object with the annotation, making it optionally visible according to the OCMD's visibility policy. If the annotation already has a dictionary, the method replaces it.

Parameters

annot — 

The annotation for which to set the dictionary.

 
pdocmd — 

The new dictionary.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9206
PDAnnotSetRect() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotSetRect(PDAnnot anAnnot, const ASFixedRect* newBox)

Sets the size and location of an annotation on its page.

Parameters

anAnnot — 

IN/OUT The annotation whose location and size are set.

 
newBox — 

IN/OUT A pointer to a rectangle that specifies the annotation's bounding rectangle, specified in user space coordinates.

See Also

Notifications

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 367
PDAnnotSetTitle() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotSetTitle(PDAnnot anAnnot, const char* str, ASInt32 nBytes)

Sets an annotation's label text.

Parameters

anAnnot — 

IN/OUT The annotation whose label is set.

 
str — 

IN/OUT The string containing the label to set.

 
nBytes — 

IN/OUT The length of the label. The first nBytes bytes of str are used as the label.

See Also

Notifications

Since

PI_PDMODEL_VERSION >= 0x00020000

Note

For Roman viewers, this text is always stored in the PDFDocEncoding. For non-Roman character set viewers, this text is stored as PDFDocEncoding or Unicode, depending on the file's creator. Files created in a non-Roman environment contain Unicode versions of these strings; in a Roman environment, files contain PDFDocEncoding versions of these strings.

File: PDProcs.h
Line: 496
PDAnnotSetTitleASText() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotSetTitleASText(PDAnnot anAnnot, const ASText title)

Sets an annotation's label text.

Parameters

anAnnot — 

The annotation whose label is set.

 
title — 

The text object containing the label to set.

See Also

Notifications

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h
Line: 11335
PDAnnotWasCreated() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotWasCreated(PDAnnot annot, PDPage page, void* clientData)

An annotation was created.

Parameters

annot — 

The annotation that was created.

 
page — 

The page to which the annotation was added.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

See Also

Notifications


File: PIPokes.h
Line: 940
PDAnnotWillChange() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDAnnotWillChange(PDAnnot annot, ASAtom key, void* clientData)

An annotation will change in the specified way.

Parameters

annot — 

The annotation that will change.

 
key — 

The ASAtom specifying how the annotation will change. The ASAtom corresponding to the key that changed in the annotation's Cos dictionary. See Section 8.4 on annotations in the PDF Reference for information on the keys.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

See Also

Notifications


File: PIPokes.h
Line: 965