PSPDFAnnotation


@interface PSPDFAnnotation
    : PSPDFModel <PSPDFUndoProtocol, PSPDFJSONSerializing>

PSPDFAnnotation is the base class for all PDF annotations and forms.

Don’t directly make an instance of this class, use subclasses like PSPDFNoteAnnotation or PSPDFLinkAnnotation. This class will return nil if initialized directly, unless with the type PSPDFAnnotationTypeUndefined.

PSPDFAnnotationManager searches the runtime for subclasses of PSPDFAnnotation and builds up a dictionary using supportedTypes.

Note

Thread safety: Annotation objects should only ever be edited on the main thread. Modify properties on the main thread only if they are already active (for creation, it doesn’t matter which thread creates them). Before rendering, obtain a copy of the annotation to ensure it’s not mutated while properties are read. Once the documentProvider is set, modifying properties on a background thread will throw an exception.

Annotations contain internal state once they are attached to a document. Don’t take them and add them to another document. Instead, create a new annotation and set the properties relevant for you, and add this annotation.

Warning

Annotations are mutable objects. Do not store them into NSSet or other objects that require a hash-value that does not change.
  • Converts JSON representation back into PSPDFAnnotation subclasses. Will return nil for invalid JSON or not recognized types. documentProvider is optional and if given the override dictionary will be honored (to return your custom PSPDFAnnotation* subclasses)

    Declaration

    Objective-C

    + (nullable PSPDFAnnotation *)
    annotationFromJSONDictionary:
        (nonnull NSDictionary<NSString *, id> *)JSONDictionary
                documentProvider:(nullable PSPDFDocumentProvider *)documentProvider
                           error:(NSError *_Nullable *_Nullable)error;

    Swift

    /*not inherited*/ init(fromJSONDictionary JSONDictionary: [String : Any], documentProvider: PSPDFDocumentProvider?) throws
  • Returns YES if PSPDFKit has support to write this annotation type back into the PDF.

    Declaration

    Objective-C

    + (BOOL)isWriteable;

    Swift

    class func isWriteable() -> Bool
  • Returns YES if PSPDFKit has support to delete this annotation type back into the PDF.

    Declaration

    Objective-C

    + (BOOL)isDeletable;

    Swift

    class func isDeletable() -> Bool
  • Returns YES if this annotation type has a fixed size, no matter the internal bounding box.

    Declaration

    Objective-C

    @property (readonly, nonatomic) BOOL isFixedSize;

    Swift

    var isFixedSize: Bool { get }
  • The size of a fixed-size annotation. Only valid when isFixedSize is set to YES.

    Declaration

    Objective-C

    @property (readonly, nonatomic) CGSize fixedSize;

    Swift

    var fixedSize: CGSize { get }
  • Returns YES if the annotation wants a selection border. Defaults to YES.

    Declaration

    Objective-C

    @property (readonly, nonatomic) BOOL wantsSelectionBorder;

    Swift

    var wantsSelectionBorder: Bool { get }
  • Returns YES if this annotation requires an implicit popup annotation.

    Declaration

    Objective-C

    @property (readonly, nonatomic) BOOL requiresPopupAnnotation;

    Swift

    var requiresPopupAnnotation: Bool { get }
  • Returns YES if the annotation is read only.

    Declaration

    Objective-C

    @property (readonly, getter=isReadOnly, nonatomic) BOOL readOnly;

    Swift

    var isReadOnly: Bool { get }
  • Returns YES if this annotation is locked. Checks annotationFlags for PSPDFAnnotationFlagLocked. - note: Even a locked PSPDFAnnotation object may have some properties modified, but this is the property that the UI layer should use to allow modifications to an annotation (selection/resizing).

    Declaration

    Objective-C

    @property (readonly, getter=isLocked, nonatomic) BOOL locked;

    Swift

    var isLocked: Bool { get }
  • Returns YES if this annotation’s contents are locked. Checks annotationFlags for PSPDFAnnotationFlagLockedContents.

    Declaration

    Objective-C

    @property (readonly, getter=isContentsLocked, nonatomic) BOOL contentsLocked;

    Swift

    var isContentsLocked: Bool { get }
  • Returns YES if this annotation type is moveable.

    Declaration

    Objective-C

    @property (readonly, getter=isMovable, nonatomic) BOOL movable;

    Swift

    var isMovable: Bool { get }
  • Returns YES if this annotation type is resizable (all but note and sound annotations usually are).

    Declaration

    Objective-C

    @property (readonly, getter=isResizable, nonatomic) BOOL resizable;

    Swift

    var isResizable: Bool { get }
  • Returns YES if the annotation should maintain its aspect ratio when resized. Defaults to NO for most annotations, except for the PSPDFStampAnnotation.

    Declaration

    Objective-C

    @property (readonly, nonatomic) BOOL shouldMaintainAspectRatio;

    Swift

    var shouldMaintainAspectRatio: Bool { get }
  • Returns the minimum size that an annotation can properly display. Defaults to (32.f, 32.f).

    Declaration

    Objective-C

    @property (readonly, nonatomic) CGSize minimumSize;

    Swift

    var minimumSize: CGSize { get }
  • Check if point is inside the annotation area, while making sure that the hit area is at least minDiameter wide. The default implementation performs hit testing based on the annotation bounding box, but concrete subclasses can (and do) override this behavior in order to perform custom checks (e.g., path-based hit testing). - note: The usage of minDiameter is annotation specific.

    Declaration

    Objective-C

    - (BOOL)hitTest:(CGPoint)point minDiameter:(CGFloat)minDiameter;

    Swift

    func hitTest(_ point: CGPoint, minDiameter: CGFloat) -> Bool
  • Calculates the exact annotation position in the current page.

    Declaration

    Objective-C

    - (CGRect)boundingBoxForPageRect:(CGRect)pageRect;

    Swift

    func boundingBox(forPageRect pageRect: CGRect) -> CGRect
  • The annotation type.

    Declaration

    Objective-C

    @property (readonly, nonatomic) PSPDFAnnotationType type;

    Swift

    var type: PSPDFAnnotationType { get }
  • Page index for current annotation. Page is relative to documentProvider. - warning: Only set the page at creation time and don’t change it later on. This would break internal caching. If you want to move an annotations to a different page, copy an annotation, add it again and then delete the original. - note: When an annotation is serialized as JSON using PSPDFJSONAdapter the value of this property is written with the key page for backwards compatibility.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSUInteger pageIndex;

    Swift

    var pageIndex: UInt { get set }
  • Page index relative to the document. - note: Will be calculated each time from pageIndex and the current documentProvider and will change pageIndex if set.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSUInteger absolutePageIndex;

    Swift

    var absolutePageIndex: UInt { get set }
  • Corresponding PSPDFDocumentProvider.

    Declaration

    Objective-C

    @property (readwrite, nonatomic)
        PSPDFDocumentProvider *_Nullable documentProvider;

    Swift

    weak var documentProvider: PSPDFDocumentProvider? { get set }
  • Document is inferred from the documentProvider (Convenience method)

    Declaration

    Objective-C

    @property (readonly, nonatomic) PSPDFDocument *_Nullable document;

    Swift

    weak var document: PSPDFDocument? { get }
  • If this annotation isn’t backed by the PDF, it’s dirty by default. After the annotation has been written to the file, this will be reset until the annotation has been changed.

    Declaration

    Objective-C

    @property (getter=isDirty, assign, readwrite, nonatomic) BOOL dirty;

    Swift

    var isDirty: Bool { get set }
  • If YES, the annotation will be rendered as a overlay. If NO, it will be statically rendered within the PDF content image. Rendering as overlay is more performant if you frequently change it, but might delay page display a bit. - note: PSPDFAnnotationTypeLink and PSPDFAnnotationTypeNote currently are rendered as overlay. If overlay is set to YES, you must also register the corresponding *annotationView class to render (override PSPDFAnnotationManager’s defaultAnnotationViewClassForAnnotation:)

    Declaration

    Objective-C

    @property (getter=isOverlay, assign, readwrite, nonatomic) BOOL overlay;

    Swift

    var isOverlay: Bool { get set }
  • Per default, annotations are editable when isWriteable returns YES. Override this to lock certain annotations. (menu won’t be shown)

    Declaration

    Objective-C

    @property (getter=isEditable, assign, readwrite, nonatomic) BOOL editable;

    Swift

    var isEditable: Bool { get set }
  • Indicator if annotation has been soft-deleted (Annotation may already be deleted locally, but not written back.) - note: Doesn’t check for the isDeletable property. Use removeAnnotations: on PSPDFDocument to delete annotations.

    Declaration

    Objective-C

    @property (getter=isDeleted, assign, readwrite, nonatomic) BOOL deleted;

    Swift

    var isDeleted: Bool { get set }
  • Annotation type string as defined in the PDF. Usually read from the annotDict. Don’t change this unless you know what you’re doing.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic) PSPDFAnnotationString _Nonnull typeString;

    Swift

    var typeString: PSPDFAnnotationString { get set }
  • The opacity of the annotation from 0 to 1. This is independent of the color and fillColor and applies to the whole annotation.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat alpha;

    Swift

    var alpha: CGFloat { get set }
  • Color associated with the annotation or nil if there is no color. This is the text color for PSPDFFreeTextAnnotation, PSPDFTextFieldFormElement, and PSPDFChoiceFormElement. - note: The annotation will only store the RGB part and discard the alpha channel set here. Annotation opacity is set via the alpha property. Setting UIColor.clearColor is equivalent to setting nil.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic, nullable) UIColor *color;

    Swift

    var color: UIColor? { get set }
  • Border Color usually redirects to color, unless overridden to have a real backing ivar. (PSPDFWidgetAnnotation has such a backing store)

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic, nullable) UIColor *borderColor;

    Swift

    var borderColor: UIColor? { get set }
  • Fill color. Only used for certain annotation types. (IC key, e.g. Shape Annotations) Fill color might be nil - treat like clearColor in that case. - note: The annotation will only store the RGB part and discard the alpha channel set here. Annotation opacity is set via the alpha property. Setting UIColor.clearColor is equivalent to setting nil. Apple Preview.app will not show you transparency in the fillColor.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic, nullable) UIColor *fillColor;

    Swift

    var fillColor: UIColor? { get set }
  • Various annotation types may contain text. Optional. This may be changed even if isContentsLocked is YES.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *contents;

    Swift

    var contents: String? { get set }
  • Subject property (corresponding to Subj key).

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *subject;

    Swift

    var subject: String? { get set }
  • Dictionary for additional action types. The key is of type PSPDFAnnotationTriggerEvent.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable)
        NSDictionary<NSNumber *, __kindof PSPDFAction *> *additionalActions;

    Swift

    var additionalActions: [NSNumber : PSPDFAction]? { get set }
  • (Optional; inheritable) The field’s value, whose format varies depending on the field type. See the descriptions of individual field types for further information.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) id value;

    Swift

    var value: Any? { get set }
  • Annotation flags. Defaults to PSPDFAnnotationFlagPrint.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) PSPDFAnnotationFlags flags;

    Swift

    var flags: PSPDFAnnotationFlags { get set }
  • Shortcut that checks for PSPDFAnnotationFlagHidden in flags.

    Declaration

    Objective-C

    @property (getter=isHidden, assign, readwrite, nonatomic) BOOL hidden;

    Swift

    var isHidden: Bool { get set }
  • The annotation name, a text string uniquely identifying it among all the annotations on its page. (Optional; PDF1.4, NM key)

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *name;

    Swift

    var name: String? { get set }
  • User (title) flag. (T property)

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *user;

    Swift

    var user: String? { get set }
  • Annotation group key. Allows to have multiple annotations that behave as single one, if their group string is equal. Only works within one page. This is a proprietary extension and saved into the PDF as PSPDF:GROUP key.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *group;

    Swift

    var group: String? { get set }
  • Date when the annotation was created. Might be nil. PSPDFKit will set this for newly created annotations. - note: Due to PDF standard limitations, the sub-second precision of NSDate is lost, if the annotation is saved and subsequently re-read from a PDF. This also impacts annotation equality checks.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic, nullable) NSDate *creationDate;

    Swift

    var creationDate: Date? { get set }
  • Date when the annotation was last modified. Might be nil. Saved into the PDF as the M property (Optional, since PDF 1.1) - note: This property is updated anytime a different property is modified. Due to PDF standard limitations, the sub-second precision of NSDate is lost, if the annotation is saved and subsequently re-read from a PDF.

    Declaration

    Objective-C

    @property (assign, readwrite, atomic, nullable) NSDate *lastModified;

    Swift

    var lastModified: Date? { get set }
  • Border Line Width (only used in certain annotations)

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat lineWidth;

    Swift

    var lineWidth: CGFloat { get set }
  • Annotation border style.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) PSPDFAnnotationBorderStyle borderStyle;

    Swift

    var borderStyle: PSPDFAnnotationBorderStyle { get set }
  • (Optional; valid only if the value of borderStyle is PSPDFAnnotationBorderStyleDashed) Array of boxed integer-values defining the dash style.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSArray<NSNumber *> *dashArray;

    Swift

    var dashArray: [NSNumber]? { get set }
  • Border effect. Currently supports No Effect or Cloudy. - note: borderEffectIntensity should be set to non-zero (e.g. 1.0) for Cloudy border to be displayed.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic)
        PSPDFAnnotationBorderEffect borderEffect;

    Swift

    var borderEffect: PSPDFAnnotationBorderEffect { get set }
  • (Optional; valid only if the value of borderEffect is PSPDFAnnotationBorderEffectCloudy) A number describing the intensity of the effect. The value is suggested to be between 0 and 2 but other values are valid as well. Default value: 0.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat borderEffectIntensity;

    Swift

    var borderEffectIntensity: CGFloat { get set }
  • Rectangle of specific annotation. (PDF coordinates) - note: Other properties might be adjusted, depending what shouldTransformOnBoundingBoxChange returns.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGRect boundingBox;

    Swift

    var boundingBox: CGRect { get set }
  • Rotation property (should be a multiple of 90, but there are exceptions, e.g. for stamp annotations) Defaults to 0. Allowed values are between 0 and 360.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSUInteger rotation;

    Swift

    var rotation: UInt { get set }
  • Certain annotation types like highlight can have multiple rects.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSArray<NSValue *> *rects;

    Swift

    var rects: [NSValue]? { get set }
  • Line, Polyline and Polygon annotations have points. Contains NSValue objects that box a CGPoint.

    Note

    These values might be generated on the fly from an internal, optimized representation.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSArray<NSValue *> *points;

    Swift

    var points: [NSValue]? { get set }
  • The PDF object number. If this is -1, the object is not reference in the PDF yet.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSInteger objectNumber;

    Swift

    var objectNumber: Int { get }
  • Returns self.contents or something appropriate per annotation type to describe the object.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSString *_Nonnull localizedDescription;

    Swift

    var localizedDescription: String { get }
  • Return icon for the annotation, if there’s one defined.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) UIImage *annotationIcon;

    Swift

    var annotationIcon: UIImage? { get }
  • Compare.

    Declaration

    Objective-C

    - (BOOL)isEqualToAnnotation:(nonnull PSPDFAnnotation *)otherAnnotation;

    Swift

    func isEqual(to otherAnnotation: PSPDFAnnotation) -> Bool
  • Returns YES if a custom appearance stream is attached to this annotation. - note: An appearance stream is a custom representation for annotations, much like a PDF within a PDF.

    Declaration

    Objective-C

    @property (readonly, nonatomic) BOOL hasAppearanceStream;

    Swift

    var hasAppearanceStream: Bool { get }
  • Draw current annotation in context. Coordinates here are in PDF coordinate space. Use PSPDFConvertViewRectToPDFRect: to convert your coordinates accordingly. (For performance considerations, you want to do this once, not every time drawInContext: is called) options is currently used to allow different annotation drawings during the annotation flattening process. options can be PSPDFAnnotationDrawAppearanceStreamKey, PSPDFAnnotationDrawFlattenedKey, PSPDFAnnotationIgnoreNoteIndicatorIconKey and other render-related keys.

    Declaration

    Objective-C

    - (void)drawInContext:(nonnull CGContextRef)context
              withOptions:(nullable NSDictionary<NSString *, id> *)options;

    Swift

    func draw(in context: CGContext, withOptions options: [String : Any]? = nil)
  • Renders annotation into an image.

    Declaration

    Objective-C

    - (nonnull UIImage *)imageWithSize:(CGSize)size
                           withOptions:
                               (nullable NSDictionary<NSString *, id> *)options;

    Swift

    func image(with size: CGSize, withOptions options: [String : Any]? = nil) -> UIImage
  • Point for the note icon. Override to customize.

    Declaration

    Objective-C

    @property (readonly, nonatomic) CGPoint noteIconPoint;

    Swift

    var noteIconPoint: CGPoint { get }
  • Supports attributes for the text rendering, similar to the attributes in NSAttributedString. - note: Supported keys are: NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName, valid values NSUnderlineStyleNone and NSUnderlineStyleSingle. A font can either be underline or strikethrough, not both. UIFontDescriptorTraitsAttribute takes a boxed value of UIFontDescriptorSymbolicTraits, valid options are UIFontDescriptorTraitItalic and UIFontDescriptorTraitBold. Setting NSForegroundColorAttributeName will also update the color property. Several other properties on this class are shortcuts for accesesing data in this dictionary. Further attributes might be rendered and saved, but are not persisted in the PDF.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable)
        NSDictionary<NSString *, id> *fontAttributes;

    Swift

    var fontAttributes: [String : Any]? { get set }
  • The font name, if defined. - note: Shortcut for [self.fontAttributes[NSFontAttributeName] familyName].

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *fontName;

    Swift

    var fontName: String? { get set }
  • Font size, if defined. Setting this to 0 will use the default size or (for forms) attempt auto-sizing the text. - note: Shortcut for self.fontAttributes[PSPDFFontSizeName].

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat fontSize;

    Swift

    var fontSize: CGFloat { get set }
  • Text justification. Allows NSTextAlignmentLeft, NSTextAlignmentCenter and NSTextAlignmentRight. - note: This is a shortcut for the data saved in fontAttributes (NSParagraphStyleAttributeName) and will modify fontAttributes.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSTextAlignment textAlignment;

    Swift

    var textAlignment: NSTextAlignment { get set }
  • Vertical text alignment. Defaults to PSPDFVerticalAlignmentTop. - note: Shortcut for self.fontAttributes[PSPDFVerticalAlignmentName]. - warning: This is not defined in the PDF spec. (PSPDFKit extension)

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic)
        PSPDFVerticalAlignment verticalTextAlignment;

    Swift

    var verticalTextAlignment: PSPDFVerticalAlignment { get set }
  • Return a default font size if not defined in the annotation.

    Declaration

    Objective-C

    - (CGFloat)defaultFontSize;

    Swift

    func defaultFontSize() -> CGFloat
  • Return a default font name (Helvetica) if not defined in the annotation.

    Declaration

    Objective-C

    - (nonnull NSString *)defaultFontName;

    Swift

    func defaultFontName() -> String
  • Returns the currently set font (calculated from defaultFontSize)

    Declaration

    Objective-C

    - (nonnull UIFont *)defaultFont;

    Swift

    func defaultFont() -> UIFont
  • Attributed string, used for free text, and text and choice form elements.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) NSAttributedString *attributedString;

    Swift

    var attributedString: NSAttributedString? { get }
  • This helper creates the attribute string. There are multiple events that can lead to a re-creation of the attributed string (such as background copies). Override this to fine-customize the properties for rendering. - note: Rendering uses CoreText, so certain UIKit-only attributes such as NSBackgroundColorAttributeName will not be rendered.

    Declaration

    Objective-C

    - (nullable NSAttributedString *)attributedStringWithContents:
        (nullable NSString *)contents;

    Swift

    func attributedString(withContents contents: String?) -> NSAttributedString?
  • Returns YES if this annotation type has a fixed size, no matter the internal bounding box.

    Declaration

    Objective-C

    + (BOOL)isFixedSize;

    Swift

    class func isFixedSize() -> Bool
  • The size of a fixed-size annotation. Only valid when isFixedSize is set to YES.

    Declaration

    Objective-C

    + (CGSize)fixedSize;

    Swift

    class func fixedSize() -> CGSize
  • If indexOnPage is set, it’s a native PDF annotation. If this is -1, it’s not yet saved in the PDF or saved externally.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSInteger indexOnPage;

    Swift

    var indexOnPage: Int { get }