---

PDFAnnotation Class Reference

Overview

PDFAnnotation, a subclass of NSObject, represents an annotation in a PDF document, which associates an object (such as a note or a sound) with a location in a PDF document.

In addition to its primary textual content, a PDF file can contain annotations that represent links, form elements, highlighting circles, textual notes, and so on. Each annotation is associated with a specific location on a page and may offer interactivity with the user. See the Adobe PDF Specification for more on annotations.

You are not likely to work with a PDFAnnotation object by itself, because the specific subclasses, such as PDFAnnotationCircle, are much more useful. When a PDF file is being parsed, however, any unknown or unsupported annotation is represented as a PDFAnnotation object.

PDFAnnotation is an abstract superclass of the following concrete classes:

• PDFAnnotationButtonWidget

• PDFAnnotationCircle

• PDFAnnotationFreeText

• PDFAnnotationInk

• PDFAnnotationLine

• PDFAnnotationLink

• PDFAnnotationMarkup

• PDFAnnotationPopup

• PDFAnnotationSquare

• PDFAnnotationStamp

• PDFAnnotationText

• PDFAnnotationTextWidget

Tasks

Initializing an Annotation

• – initWithBounds:

Accessing Information About an Annotation

• – page
• – modificationDate
• – setModificationDate
• – userName
• – setUserName
• – popup
• – setPopup
• – mouseUpAction
• – setMouseUpAction
• – type
• – contents
• – setContents:
• – toolTip

Managing Annotation Display Characteristics

• – bounds
• – setBounds:
• – border
• – setBorder:
• – color
• – setColor:
• – hasAppearanceStream

Managing Annotation Drawing and Output

• – drawWithBox:
• – shouldDisplay
• – setShouldDisplay:
• – shouldPrint
• – setShouldPrint:

Instance Methods

border

Returns the border style for the annotation.

- (PDFBorder *)border

Return Value

The border style for the annotation. See “Constants” in the PDFBorder class for possible values.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setBorder:

Declared In

PDFAnnotation.h

bounds

Returns the bounding box for the annotation in page space.

- (NSRect)bounds

Return Value

The bounding box for the annotation in page space.

Discussion

Page space is a 72-dpi coordinate system with the origin at the lower-left corner of the current page.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setBounds:

Declared In

PDFAnnotation.h

color

Returns the stroke color for the annotation.

- (NSColor *)color

Return Value

The stroke color for the annotation.

Discussion

Where this color is used depends on the type of annotation.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setColor:

Declared In

PDFAnnotation.h

contents

Returns the textual content (if any) associated with the annotation.

- (NSString *)contents

Return Value

A string representing the textual content associated with the annotation.

Discussion

Textual content is typically associated with PDFAnnotationText and PDFAnnotationFreeText annotations.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setContents:
• – toolTip

Declared In

PDFAnnotation.h

drawWithBox:

Draws the annotation on its associated page.

- (void)drawWithBox:(PDFDisplayBox)box

Parameters

box

The bounding box used to draw the annotation in.

Discussion

The annotation is drawn relative to the origin of box in page space.

Page space is a 72 dpi coordinate system with the origin at the lower-left corner of the current page.

For additional information see the “Constants” section in the PDFPage class.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – boundsForBox:

Declared In

PDFAnnotation.h

hasAppearanceStream

Returns a Boolean value that indicates whether the annotation has an appearance stream associated with it.

- (BOOL) hasAppearanceStream

Return Value

YES if the annotation has an appearance stream; otherwise NO.

Discussion

An appearance stream is a sequence of draw instructions used to render a PDF item. If an appearance stream exists, PDF Kit draws the annotation using the stream, which may override existing set parameters (such as the stroke color set with setColor).

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDFAnnotation.h

initWithBounds:

Initializes a PDF annotation object.

- (id)initWithBounds:(NSRect)bounds

Parameters

bounds

The bounding box of the annotation, in page space.

Return Value

An initialized PDFAnnotation instance, or NULL if the object could not be initialized.

Discussion

Subclasses of PDFAnnotation should use this method to initialize annotation instances. Provide bounds in page space. Invoking initWithBounds: directly on a PDFAnnotation object creates an illegal NULL type.

Page space is a 72 dpi coordinate system with the origin at the lower-left corner of the current page.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDFAnnotation.h

modificationDate

Returns the modification date of the annotation.

- (NSDate *)modificationDate

Return Value

The modification date of the annotation, or NULL if there is no modification date.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setModificationDate

Declared In

PDFAnnotation.h

mouseUpAction

Returns the optional action performed when a user releases the mouse button within an annotation.

- (PDFAction *)mouseUpAction

Return Value

The PDF action performed when a user releases the mouse button within an annotation.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setMouseUpAction

Declared In

PDFAnnotation.h

page

Returns the page that the annotation is associated with.

- (PDFPage *)page

Return Value

The PDF page associated with the annotation.

Discussion

The addAnnotation: method in the PDFPage class lets you associate an annotation with a page.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDFAnnotation.h

popup

Returns the pop-up annotation associated with an annotation.

- (PDFAnnotationPopup *)popup

Return Value

The pop-up annotation associated with the annotation, or NULL if no pop-up exists.

Discussion

Pop-up annotations are not used with links or widgets. The bounds and open state of the pop-up annotation indicate the placement and open state of the pop-up window.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setPopup

Declared In

PDFAnnotation.h

setBorder:

Sets the border style for the annotation.

- (void)setBorder:(PDFBorder *)border

Parameters

border

The border style for the annotation. See “Constants” in the PDFBorder class for the available styles. The border style attribute is optional.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – border

Declared In

PDFAnnotation.h

setBounds:

Sets the bounding box for the annotation.

- (void)setBounds:(NSRect)bounds

Parameters

bounds

The bounding box for the annotation. Use page space for bounds. The bounds attribute is required for all annotations.

Discussion

Page space is a 72-dpi coordinate system with the origin at the lower-left corner of the current page.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – bounds

Declared In

PDFAnnotation.h

setColor:

Sets the stroke color for the annotation.

- (void)setColor:(NSColor *)color

Parameters

color

The stroke color for the annotation.

Discussion

Where this color is used depends on the annotation type.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – color

Declared In

PDFAnnotation.h

setContents:

Specifies the textual content associated with the annotation.

- (void)setContents:(NSString *)contents

Parameters

contents

A string representing the textual contents associated with the annotation.

Discussion

Textual content is typically associated with PDFAnnotationText and PDFAnnotationFreeText annotations. For most annotation types, PDFView displays the associated textual content as a help tag.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – contents
• – toolTip

Declared In

PDFAnnotation.h

setModificationDate

Sets the modification date of the annotation.

- (void)setModificationDate:(NSDate *)date

Parameters

date

The modification date to associate with the annotation.

Discussion

The modification date is optional.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – modificationDate

setMouseUpAction

Sets the action performed when a user releases the mouse button within an annotation.

- (void)setMouseUpAction:(PDFAction *)action

Parameters

action

The PDF action to be performed when a user releases the mouse button within an annotation.

Discussion

The mouse-up action is optional.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – mouseUpAction

setPopup

Sets the pop-up annotation associated with an annotation.

- (void)setPopup:(PDFAnnotationPopup *)popup

Parameters

popup

The pop-up annotation to associate with the annotation.

Discussion

A pop-up annotation is not associated with links or widgets. The bounds and open state of the pop-up annotation indicate the placement and open state of the pop-up window.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – popup

setShouldDisplay:

Specifies whether the annotation should be displayed.

- (void)setShouldDisplay:(BOOL)display

Parameters

display

Set this value to YES to display the annotation or NO otherwise.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – shouldDisplay

Declared In

PDFAnnotation.h

setShouldPrint:

Specifies whether the annotation should appear when the document is printed.

- (void)setShouldPrint:(BOOL)print

Parameters

print

Set this value to YES to ensure the annotation appears when the document is printed or NO otherwise.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – shouldPrint

Declared In

PDFAnnotation.h

setUserName

Sets the name of the user who created the annotation.

- (void)userName:(NSString *)name

Parameters

name

The name of the user who created the annotation.

Discussion

The user name is optional.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – userName

shouldDisplay

Returns a Boolean value indicating whether the annotation should be displayed.

- (BOOL)shouldDisplay

Return Value

YES if the annotation should be displayed; otherwise NO.

Discussion

PDFPage respects this flag when drawing.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setShouldDisplay:

Declared In

PDFAnnotation.h

shouldPrint

Returns a Boolean value indicating whether the annotation should appear when the document is printed.

- (BOOL)shouldPrint

Return Value

YES if the annotation should appear when the PDF document is printed; otherwise NO.

Discussion

PDFPage respects this flag when printing.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setShouldPrint:

Declared In

PDFAnnotation.h

toolTip

Returns text for display as a help tag.

- (NSString *)toolTip

Return Value

A string that contains help tag content, or NULL if there is no text associated with the annotation.

Discussion

This method is equivalent to sending the message [self contents]. PDF Kit’s annotation subclasses override this behavior as appropriate. For example, a PDFAnnotationLink object displays a URL or page destination for its help tag.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDFAnnotation.h

type

Returns the type of the annotation.

- (NSString *)type

Return Value

The type of the annotation. Types include Line, Link, Text, and so on, referring to the PDFAnnotation subclasses. In the Adobe PDF Specification, this attribute is called Subtype, and the common “type” for all annotations in the PDF Specification is Annot.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDFAnnotation.h

userName

Returns the name of the user who created the annotation.

- (NSString *)userName

Return Value

The name of the user who created the annotation, or NULL if no user name is set.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setUserName

Declared In

PDFAnnotation.h

---