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 |
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:
PDFAnnotationButtonWidgetPDFAnnotationCirclePDFAnnotationFreeTextPDFAnnotationInkPDFAnnotationLinePDFAnnotationLinkPDFAnnotationMarkupPDFAnnotationPopupPDFAnnotationSquarePDFAnnotationStampPDFAnnotationTextPDFAnnotationTextWidget
Tasks
Initializing an Annotation
Accessing Information About an Annotation
-
– page -
– modificationDate -
– setModificationDate: -
– userName -
– setUserName: -
– popup -
– setPopup: -
– mouseUpAction -
– setMouseUpAction: -
– type -
– contents -
– setContents: -
– toolTip
Managing Annotation Display Characteristics
Managing Annotation Drawing and Output
Instance Methods
border
Returns the border style for the annotation.
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.
See Also
Declared In
PDFAnnotation.hbounds
Returns the bounding box for the annotation in page space.
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.
See Also
Declared In
PDFAnnotation.hcolor
Returns the stroke color for the annotation.
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.
See Also
Declared In
PDFAnnotation.hcontents
Returns the textual content (if any) associated with the annotation.
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.
See Also
Declared In
PDFAnnotation.hdrawWithBox:
Draws the annotation on its associated page.
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.
See Also
Declared In
PDFAnnotation.hhasAppearanceStream
Returns a Boolean value that indicates whether the annotation has an appearance stream associated with it.
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.hinitWithBounds:
Initializes a PDF annotation object.
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.
Declared In
PDFAnnotation.hmodificationDate
Returns the modification date of the annotation.
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.hmouseUpAction
Returns the optional action performed when a user releases the mouse button within an annotation.
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
Declared In
PDFAnnotation.hpage
Returns the page that the annotation is associated with.
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.
Declared In
PDFAnnotation.hpopup
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
Declared In
PDFAnnotation.hsetBorder:
Sets the border style for the annotation.
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
Declared In
PDFAnnotation.hsetBounds:
Sets the bounding box for the annotation.
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.hsetColor:
Sets the stroke color for the annotation.
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
Declared In
PDFAnnotation.hsetContents:
Specifies the textual content associated with the annotation.
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.
See Also
Declared In
PDFAnnotation.hsetModificationDate:
Sets the modification date of the annotation.
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.hsetMouseUpAction:
Sets the action performed when a user releases the mouse button within an annotation.
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
Declared In
PDFAnnotation.hsetPopup:
Sets the pop-up annotation associated with an annotation.
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.hsetShouldDisplay:
Specifies whether the annotation should be displayed.
Parameters
- display
Set this value to
YESto display the annotation orNOotherwise.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
PDFAnnotation.hsetShouldPrint:
Specifies whether the annotation should appear when the document is printed.
Parameters
Set this value to
YESto ensure the annotation appears when the document is printed orNOotherwise.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
PDFAnnotation.hsetUserName:
Sets the name of the user who created the annotation.
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.hshouldDisplay
Returns a Boolean value indicating whether the annotation should be displayed.
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.
See Also
Declared In
PDFAnnotation.hshouldPrint
Returns a Boolean value indicating whether the annotation should appear when the document is printed.
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.
See Also
Declared In
PDFAnnotation.htoolTip
Returns text for display as a help tag.
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.htype
Returns the type of the annotation.
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.huserName
Returns the name of the user who created the annotation.
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© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-12-11)