Mac Developer Library

Developer

Quartz Framework Reference PDFAnnotation Class Reference

Options
Deployment Target:

On This Page
Language:

PDFAnnotation

Conforms To


Import Statement


Swift

import Quartz

Objective-C

@import Quartz;

Availability


Available in OS X v10.4 and later.

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

  • Initializes a PDF annotation object.

    Declaration

    Swift

    init!(bounds bounds: NSRect)

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Returns the page that the annotation is associated with.

    Declaration

    Swift

    func page() -> PDFPage!

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Returns the modification date of the annotation.

    Declaration

    Swift

    func modificationDate() -> NSDate!

    Objective-C

    - (NSDate *)modificationDate

    Return Value

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Sets the modification date of the annotation.

    Declaration

    Swift

    func setModificationDate(_ date: NSDate!)

    Objective-C

    - (void)setModificationDate:(NSDate *)date

    Parameters

    date

    The modification date to associate with the annotation.

    Discussion

    The modification date is optional.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns the name of the user who created the annotation.

    Declaration

    Swift

    func userName() -> String!

    Objective-C

    - (NSString *)userName

    Return Value

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

    See Also

    – setUserName

  • Sets the name of the user who created the annotation.

    Declaration

    Swift

    func setUserName(_ name: String!)

    Objective-C

    - (void)setUserName:(NSString *)name

    Parameters

    name

    The name of the user who created the annotation.

    Discussion

    The user name is optional.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

    See Also

    – userName

  • Returns the pop-up annotation associated with an annotation.

    Declaration

    Swift

    func popup() -> PDFAnnotationPopup!

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

    See Also

    – setPopup

  • Sets the pop-up annotation associated with an annotation.

    Declaration

    Swift

    func setPopup(_ popup: PDFAnnotationPopup!)

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

    See Also

    – popup

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

    Declaration

    Swift

    func mouseUpAction() -> PDFAction!

    Objective-C

    - (PDFAction *)mouseUpAction

    Return Value

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func setMouseUpAction(_ action: PDFAction!)

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns the type of the annotation.

    Declaration

    Swift

    func type() -> String!

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func contents() -> String!

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Specifies the textual content associated with the annotation.

    Declaration

    Swift

    func setContents(_ contents: String!)

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Returns text for display as a help tag.

    Declaration

    Swift

    func toolTip() -> String!

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Returns the bounding box for the annotation in page space.

    Declaration

    Swift

    func bounds() -> NSRect

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

    See Also

    – setBounds:

  • Sets the bounding box for the annotation.

    Declaration

    Swift

    func setBounds(_ bounds: NSRect)

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

    See Also

    – bounds

  • Returns the border style for the annotation.

    Declaration

    Swift

    func border() -> PDFBorder!

    Objective-C

    - (PDFBorder *)border

    Return Value

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

    See Also

    – setBorder:

  • Sets the border style for the annotation.

    Declaration

    Swift

    func setBorder(_ border: PDFBorder!)

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

    See Also

    – border

  • Returns the stroke color for the annotation.

    Declaration

    Swift

    func color() -> NSColor!

    Objective-C

    - (NSColor *)color

    Return Value

    The stroke color for the annotation.

    Discussion

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

    See Also

    – setColor:

  • Sets the stroke color for the annotation.

    Declaration

    Swift

    func setColor(_ color: NSColor!)

    Objective-C

    - (void)setColor:(NSColor *)color

    Parameters

    color

    The stroke color for the annotation.

    Discussion

    Where this color is used depends on the annotation type.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

    See Also

    – color

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

    Declaration

    Swift

    func hasAppearanceStream() -> Bool

    Objective-C

    - (BOOL)hasAppearanceStream

    Return Value

    YEStrue if the annotation has an appearance stream; otherwise NOfalse.

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Draws the annotation on its associated page.

    Declaration

    Swift

    func drawWithBox(_ box: PDFDisplayBox)

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func shouldDisplay() -> Bool

    Objective-C

    - (BOOL)shouldDisplay

    Return Value

    YEStrue if the annotation should be displayed; otherwise NOfalse.

    Discussion

    PDFPage respects this flag when drawing.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Specifies whether the annotation should be displayed.

    Declaration

    Swift

    func setShouldDisplay(_ display: Bool)

    Objective-C

    - (void)setShouldDisplay:(BOOL)display

    Parameters

    display

    Set this value to YEStrue to display the annotation or NOfalse otherwise.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func shouldPrint() -> Bool

    Objective-C

    - (BOOL)shouldPrint

    Return Value

    YEStrue if the annotation should appear when the PDF document is printed; otherwise NOfalse.

    Discussion

    PDFPage respects this flag when printing.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func setShouldPrint(_ print: Bool)

    Objective-C

    - (void)setShouldPrint:(BOOL)print

    Parameters

    print

    Set this value to YEStrue to ensure the annotation appears when the document is printed or NOfalse otherwise.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

    See Also

    – shouldPrint