PDFAnnotation Class Reference

Inherits from
Conforms to
Framework
Library/Frameworks/Quartz.framework/Frameworks/PDFKit.framework
Availability
Available in OS X v10.4 and later.
Declared in
PDFAnnotation.h
Related sample code

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:

Tasks

Initializing an Annotation

Accessing Information About an Annotation

Managing Annotation Display Characteristics

Managing Annotation Drawing and Output

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 OS X v10.4 and later.
Related Sample Code
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 OS X v10.4 and later.
Related Sample Code
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 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 OS X v10.4 and later.
Related Sample Code
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 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 OS X v10.5 and later.
See Also
  • – setMouseUpAction
Related Sample Code
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 OS X v10.4 and later.
Related Sample Code
Declared In
PDFAnnotation.h

popup

Returns the pop-up annotation associated with an annotation.

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 OS X v10.5 and later.
See Also
  • – setPopup
Related Sample Code
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 OS X v10.4 and later.
See Also
Related Sample Code
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
Related Sample Code
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 OS X v10.4 and later.
Related Sample Code
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 OS X v10.5 and later.
See Also
  • – modificationDate
Declared In
PDFAnnotation.h

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 OS X v10.5 and later.
See Also
  • – mouseUpAction
Related Sample Code
Declared In
PDFAnnotation.h

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 OS X v10.5 and later.
See Also
  • – popup
Declared In
PDFAnnotation.h

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 OS X v10.4 and later.
Related Sample Code
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 OS X v10.4 and later.
Related Sample Code
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 OS X v10.5 and later.
See Also
  • – userName
Declared In
PDFAnnotation.h

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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 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 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 OS X v10.5 and later.
See Also
  • – setUserName
Declared In
PDFAnnotation.h