PSPDFAnnotation

Objective-C


@interface PSPDFAnnotation : PSPDFModel
extension Annotation: Identifiable

Swift

class Annotation : ModelObject

Annotation is the base class for all PDF annotations and form elements.

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

AnnotationManager searches the runtime for subclasses of Annotation and builds up a dictionary using supportedTypes.

As well as the various annotation subclasses, there are two types to model annotation types:

  • Annotation.Kind is mostly used for the type of an existing annotation. As an option set, it can be convenient to add and remote types from certain API such as the PDFConfiguration’s editableAnnotationTypes.

  • Annotation.Tool is mostly used as the type of a tool for creating annotations. As well as annotation types it includes pure tools such as .eraser. The tools are activated in the UI with AnnotationToolbar and AnnotationStateManager.

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.

Annotation properties are specified in normalized PDF coordinates: they take page rotation and CropBox offset into account. Prior to PSPDFKit 8 for iOS and PSPDFKit 3 for macOS properties were specified in PDF coordinates: not taking the page rotation and offset into account. After unarchiving annotations from NSCoder archives created with older versions of PSPDFKit, the properties will be untransformed, and will be modified to apply the page transform when the annotation is added to a document.

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.

For efficiency and control, you must manually notify PSPDFKit after modifying the properties of annotations. After changing any annotation properties, post an .PSPDFAnnotationChanged notification to ensure the annotation is re-rendered and the UI is updated. If you change multiple properties at once, you just need to post the notification once.

Warning

Annotations are mutable objects. Do not store them in NSSet or other objects that require a hash-value that does not change.

  • Annotation can be deleted under following rules:

    • is editable
    • is not locked

    For UI implementations, you might want to perform following additional checks that are not part of this helper:

    • document is savable.

    • annotation is part of editableAnnotationTypes on the document.

    Note

    Both annotations and forms (widgets) can be deleted. For forms, most of the time a reset is more appropriate though. Deleting forms/widgets requires licensing the Forms component. Deleting annotations requires the Annotation component.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isDeletable;

    Swift

    var isDeletable: Bool { get }

  • Returns the size of a fixed-size annotation. Defaults to PSPDFAnnotationFixedSizeDisabled for non-fixed-sized annotations.

    Declaration

    Objective-C

    @property (readonly) CGSize fixedSize;

    Swift

    var fixedSize: CGSize { get }

  • Returns YES if the annotation wants a selection border. Defaults to YES.

    Declaration

    Objective-C

    @property (readonly) BOOL wantsSelectionBorder;

    Swift

    var wantsSelectionBorder: Bool { get }

  • Returns YES if this annotation requires an implicit popup annotation.

    Declaration

    Objective-C

    @property (readonly) BOOL requiresPopupAnnotation;

    Swift

    var requiresPopupAnnotation: Bool { get }

  • This is a convenience property that checks for .readOnly in flags.

    See

    PSPDFAnnotationFlagReadOnly

    Declaration

    Objective-C

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

    Swift

    var isReadOnly: Bool { get }

  • This is a convenience property that checks for .locked in flags.

    See

    PSPDFAnnotationFlagLocked

    Declaration

    Objective-C

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

    Swift

    var isLocked: Bool { get }

  • This is a convenience property that checks for .lockedContents in flags.

    See

    PSPDFAnnotationFlagLockedContents

    Declaration

    Objective-C

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

    Swift

    var isContentsLocked: Bool { get }

  • Returns YES if this annotation type is moveable.

    Declaration

    Objective-C

    @property (readonly, getter=isMovable) 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) BOOL resizable;

    Swift

    var isResizable: Bool { get }

  • Whether the annotation should maintain its aspect ratio when resized.

    Defaults to false for most annotations. Defaults to true for drawn signatures (ink signatures), stamps, and images (including image signatures).

    This constraint is enforced by ResizableView, not by the annotation itself. If you resize an annotation programmatically, you may want to implement honoring this property.

    Declaration

    Objective-C

    @property (readonly) BOOL shouldMaintainAspectRatio;

    Swift

    var shouldMaintainAspectRatio: Bool { get }

  • Returns the minimum size that an annotation can properly display. Defaults to (16, 16).

    Declaration

    Objective-C

    @property (readonly) 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

  • The annotation position on the current page in the coordinate space of a UIView displaying the page.

    Declaration

    Objective-C

    - (CGRect)boundingBoxForPageRect:(CGRect)pageRect;

    Swift

    func boundingBox(forPageRect pageRect: CGRect) -> CGRect

    Parameters

    pageRect

    The bounds of a UIView that displays the page the annotation is on, where the page fills the view bounds exactly.

    Return Value

    The annotation bounding box in the coordinate space of the UIView whose bounds were passed in.

  • The annotation type.

    Declaration

    Objective-C

    @property (nonatomic, readonly) PSPDFAnnotationType type;

    Swift

    var type: Annotation.Kind { get }

  • Page index for current annotation. Page is relative to documentProvider. First page in the document is page 0.

    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 PSPDFPageIndex pageIndex;

    Swift

    var pageIndex: PageIndex { get set }

  • Page index relative to the document. First page in the document is page 0.

    Note

    Will be calculated each time from pageIndex and the current documentProvider and will change pageIndex if set.

    Declaration

    Objective-C

    @property PSPDFPageIndex absolutePageIndex;

    Swift

    var absolutePageIndex: PageIndex { get set }

  • Corresponding PSPDFDocumentProvider.

    Declaration

    Objective-C

    @property (weak, readonly) PSPDFDocumentProvider *_Nullable documentProvider;

    Swift

    weak var documentProvider: PSPDFDocumentProvider? { get }

  • Document is inferred from the documentProvider (Convenience method)

    Declaration

    Objective-C

    @property (weak, readonly) 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) 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) BOOL overlay;

    Swift

    var isOverlay: Bool { get set }

  • By default, annotations are editable when isReadOnly returns false. This property can be used to temporarily lock annotations that are originally editable. (menu won’t be shown) Setting editable to true will have no effect if isReadOnly is true. To ignore isReadOnly and make an annotation editable regardless, override the getter and make it always return true.

    The editable property also behaves a little differently for form elements. For them, the editable property refers to the form fields attached to the elements.

    Note

    This is a strictly transient property that is not written to the backing data store. To persistently disable editing, enable the .readOnly flag instead.

    Declaration

    Objective-C

    @property (getter=isEditable) 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 Document to delete annotations.

    Declaration

    Objective-C

    @property (getter=isDeleted) 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 (copy, readonly) PSPDFAnnotationString _Nonnull typeString;

    Swift

    var typeString: Annotation.Tool { get }

  • The tool variant, that was used during the annotation creation. Defaults to nil. This is a proprietary extension and saved into the PDF as PSPDF:Variant key.

    Note

    The style inspector stores previously used styles based on type + variant. See PSPDFAnnotationGroupItem.h for PSPDFAnnotationVariantString defaults.

    Declaration

    Objective-C

    @property (copy, nullable) PSPDFAnnotationVariantString variant;

    Swift

    var variant: Annotation.Variant? { 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.

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property 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 FreeTextAnnotation, 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.

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property (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)

    A nil border color means the border is black.

    Note

    If the dash array is invalid, the border will not be rendered. See PDF Reference §8.4.3.6 (Table 55).

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

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

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property (nullable) UIColor *fillColor;

    Swift

    var fillColor: UIColor? { get set }

  • Defines a custom blend mode.

    Supported values include kCGBlendModeNormal to kCGBlendModeExclusion.

    Note

    The blend mode is not defined in the PDF spec, therefore it’s not stored as part of the annotation dictionary, but in the annotation’s appearance stream. If another editor/viewer does not use appearance stream or ends up regenerating them to redraw then the blend mode set here might not be preserved.

    @b See Appearance Stream https://pspdfkit.com/blog/2018/what-are-appearance-streams/.

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property (nonatomic) CGBlendMode blendMode;

    Swift

    var blendMode: CGBlendMode { get set }

  • Various annotation types may contain text. Optional.

    For most annotation types, this is displayed as a note/comment in a popup. For free text annotations the contents is the text shown on the page.

    PSPDFKit’s UI will disallow editing this if .lockedContents is enabled in flags. However even in that case this property may still be changed programmatically.

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property (copy, nullable) NSString *contents;

    Swift

    var contents: String? { get set }

  • Subject property (corresponding to “Subj” key). Text representing a short description of the subject being addressed by the annotation. Prior to PSPDFKit 8.1 for iOS and 3.1 for macOS, this was used as the text displayed by a stamp annotation. It no longer has any effect on rendering.

    Declaration

    Objective-C

    @property (copy, nullable) NSString *subject;

    Swift

    var subject: String? { get set }

  • Dictionary for additional action types. The key is of type Annotation.TriggerEvent.

    Declaration

    Objective-C

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

  • (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 (copy, nullable) id value;

    Swift

    var value: Any? { get set }

  • An annotation’s flags property is an option set that encompasses various properties which may be used to alter visibility or restrict editing in the UI. Defaults to .print.

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property (nonatomic) PSPDFAnnotationFlags flags;

    Swift

    var flags: Annotation.Flag { get set }

  • This is a convenience property that checks for .hidden in flags.

    See

    PSPDFAnnotationFlagHidden

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property (nonatomic, getter=isHidden) 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)

    Note

    We generate a unique identifier for newly created annotations.

    Declaration

    Objective-C

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

    Swift

    var name: String? { get set }

  • The name of the user who created the annotation (AKA annotation author). Also sometimes called the title of the annotation, since this is the “T” property in the PDF.

    Declaration

    Objective-C

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

    Swift

    var user: String? { get set }

  • Annotation group key. May be used 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 (nonatomic, copy, nullable) NSString *group;

    Swift

    var group: String? { get set }

  • A unique in-memory identifier for each annotation. Stays the same when the object is copied via NSCopying. Generated at runtime, therefore not persisted (in the PDF).

    In contrast with name, this is guaranteed to be always set, even for existing annotations in a document.

    Declaration

    Objective-C

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

    Swift

    var uuid: String { get }

  • 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 (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 (nullable) NSDate *lastModified;

    Swift

    var lastModified: Date? { get set }

  • Border Line Width (only used in certain annotations)

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property (nonatomic) CGFloat lineWidth;

    Swift

    var lineWidth: CGFloat { get set }

  • Annotation border style.

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property (nonatomic) PSPDFAnnotationBorderStyle borderStyle;

    Swift

    var borderStyle: Annotation.BorderStyle { get set }

  • (Optional; valid only if the value of borderStyle is PSPDFAnnotationBorderStyleDashed) Array of boxed integer-values defining the dash style.

    Values | Dash

    [] | ━━━━━━━━━━━━━━━━━━━━ [3] | ━ ━━━ ━━━ ━━━ [2] | ━ ━ ━ ━ ━ ━ ━ [2,1]| ━━ ━━ ━━ ━━ ━━ ━━ ━━ [3,5]| ━━━ ━━━ ━━ [2,3]| ━ ━━ ━━ ━━ ━

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

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

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

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property (nonatomic) PSPDFAnnotationBorderEffect borderEffect;

    Swift

    var borderEffect: Annotation.BorderEffect { 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. Defaults to: 0.

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property (nonatomic) CGFloat borderEffectIntensity;

    Swift

    var borderEffectIntensity: CGFloat { get set }

  • The annotation’s size and location on the page, specified in page coordinates.

    Note

    Other properties might be adjusted, depending what shouldTransformOnBoundingBoxChange returns.

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

    @property (nonatomic) CGRect boundingBox;

    Swift

    var boundingBox: CGRect { get set }

  • Certain annotation types like highlight can have multiple rects.

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

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

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

    As with all annotation properties, post a .PSPDFAnnotationChanged notification to propagate changes.

    Declaration

    Objective-C

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

  • The PDF object number. If this is -1, the object is not referenced in the PDF yet.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSInteger objectNumber;

    Swift

    var objectNumber: Int { get }

  • Returns self.contents or something appropriate per annotation type to describe the object.

    Declaration

    Objective-C

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

    Swift

    var localizedDescription: String { get }

  • Return icon for the annotation, if there’s one defined.

    Declaration

    Objective-C

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

    Swift

    var annotationIcon: UIImage? { get }

  • YES if the annotation is a reply to another.

    This is specified by the presence of an IRT (in-reply-to) entry on the annotation in the PDF.

    The default is NO for newly created annotations.

    Calling this is faster than annotation.inReplyToAnnotation != nil and does not need Features.annotationReplies. So if your license does not include this feature and the annotation is a reply, inReplyToAnnotation will be nil but this property will still be YES.

    If you have a custom page rendering component you can use this property to hide replies on the page.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isReply) BOOL reply;

    Swift

    var isReply: Bool { get }

  • The annotation the receiver is a reply to. This is the IRT (in-reply-to) entry on the annotation in the PDF.

    This property is nil if this annotation is not a reply. The default is nil for newly created annotations.

    When setting this, the annotation being set must have been added to the document.

    This requires Features.annotationReplies. If that license feature is not available the getter will return nil and the setter will do nothing.

    To check if an annotation is a reply, it is faster to use isReply than to check if this property is nil.

    Declaration

    Objective-C

    @property (nonatomic, nullable) PSPDFAnnotation *inReplyToAnnotation;

    Swift

    var inReplyTo: Annotation? { get set }

  • Annotations can store additional user-specified data.

    PSPDFKit will not use or evaluate customData in the UI directly. You have full control over this property. For a new annotation, this defaults to nil.

    Custom data will be serialized via NSCoder, InstantJSON, XFDF and PDF saving. Setting customData will create a copy of the root object. Ensure to not store mutable objects that could be mutated externally.

    Note

    Following types are allowed: NSArray, NSDictionary, NSString, NSNull and NSNumber (and their Swift equivalents). For storing boolean values, use (id)kCFBooleanTrue, (id)kCFBooleanFalse, @YES, @NO, or an NSNumber initialized using +numberWithBool:. Only unique strings as dictionary keys are allowed, see NSJSONSerialization for details on object restrictions. Adding any other datatype will cause an assertion when setting this property.

    Declaration

    Objective-C

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

    Swift

    var customData: [String : Any]? { get set }

  • Compare.

    Declaration

    Objective-C

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

    Swift

    func isEqual(to otherAnnotation: Annotation) -> 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 (nonatomic, readonly) BOOL hasAppearanceStream;

    Swift

    var hasAppearanceStream: Bool { get }

  • Clears any appearance stream, if set.

    See

    hasAppearanceStream to check if one is set.

    Declaration

    Objective-C

    - (void)clearAppearanceStream;

    Swift

    func clearAppearanceStream()

  • Allows you to override the appearance stream generation method of this annotation. The appearanceStreamGenerator will be called when necessary to generate the annotations appearance stream.

    By default, this is set to +[PSPDFDrawingContextAppearanceStreamGenerator defaultDrawingContextAppearanceStreamGenerator] for all types except PSPDFFormElement. PSPDFStampAnnotations may in certain situations set PSPDFRetainExistingAppearanceStreamGenerator to prevent regeneration of an appearance stream if it would overwrite data.

    Setting a custom appearance stream generator will completely override the default design, and thus ignores any custom set properties such as fillColor or lineWidth. Therefore custom appearance stream generators should only be used for vector stamp annotations. Use with other annotation types is not supported.

    Note

    This does NOT automatically remove the existing appearance stream and replace it with the generated one. The appearance stream only gets generated if the annotation has been modified. Therefore you may want to set isDirty to true immediately after setting the appearanceStreamGenerator.

    Note

    appearanceStreamGenerator is not supported on SignatureFormElement. Please use PDFSignatureAppearance.

    Note

    If you intend to use appearanceStreamGenerator on a annotation subclass that has draw(context:options:) overridden, you have to call maybeRenderCustomAppearanceStream(with:options:) and return if it returns true.

    Declaration

    Objective-C

    @property (nullable) id<PSPDFAppearanceStreamGenerating> appearanceStreamGenerator;

    Swift

    var appearanceStreamGenerator: AppearanceStreamGenerating? { get set }

  • This method checks if a custom appearanceStreamGenerator is set and if it should be used to render the given annotation. If so, it might call the appearanceStreamGenerator and render the resulting appearance stream.

    This needs to be called in the beginning of drawInContext:options: and if it returns YES, no further drawing should be done in the method.

    Declaration

    Objective-C

    - (BOOL)
    maybeRenderCustomAppearanceStreamWithContext:(nonnull CGContextRef)context
                                         options:(nullable PSPDFRenderOptions *)
                                                     options;

    Swift

    func maybeRenderCustomAppearanceStream(with context: CGContext, options: PSPDFRenderOptions?) -> Bool

  • A set of properties to be taken into account when performing undo.

    This set doesn’t necessarily need to be a subset of propertyKeys. It can contain additional keys, as long as they they are read-write and conform to the KVC naming convention.

    This set can be overridden by subclasses to provide additional keys on top of the default ones. Remember to union the sets with super.

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSSet<NSString *> *_Nonnull propertyKeysForUndo;

    Swift

    class var propertyKeysForUndo: Set<String> { get }

  • A variant of setValue:forKeyPath: that is used when performing undo.

    This method can be overridden by subclasses to customize the behavior of setting certain properties when performing undo (e.g. to disable cascading changes).

    Declaration

    Objective-C

    - (void)setUndoneValue:(nullable id)value
            forKeyPath:(nonnull NSString *)keyPath;

    Swift

    func setUndoneValue(_ value: Any?, forKeyPath keyPath: String)

InstantCollaborationPermissions

  • The operations supported by this annotation in the context of Instant.

    This value is orthogonal to the flags property, which reflects things defined in the PDF that can be synced using Instant. (See the Instant JSON schema for annotations.)

    Declaration

    Objective-C

    @property (nonatomic, readonly) PSPDFInstantRecordOperations instantRecordOperations;

    Swift

    var instantRecordOperations: PSPDFInstantRecordOperations { get }

  • Record group of the annotation for use in Instant Collaboration Permissions.

    Declaration

    Objective-C

    @property (readonly, nullable) NSString *instantRecordGroup;

    Swift

    var instantRecordGroup: String? { get }

Drawing

  • Acquires all relevant locks, prepares the context for rendering, and then renders the receiver into it — either using the appearance stream, or by calling through to drawInContext:options:.

    Note

    When in doubt, prefer calling this method over drawInContext:options:. The latter is meant to be called when an AP stream is unavailable.

    Declaration

    Objective-C

    - (void)lockAndRenderInContext:(nonnull CGContextRef)context
                       options:(nullable PSPDFRenderOptions *)options;

    Swift

    func lockAndRender(in context: CGContext, options: PSPDFRenderOptions?)

  • The drawing primitive used when rendering the annotation. Can be overridden to customize the appearance of an annotation class.

    PSPDFKit will call this method when an annotation needs to be rendered in a graphics context — either for immediate display, or to preserve the exact appearance in the PDF file (also known as generating an appearance stream). This method expects to be called with a context that uses the normalized PDF coordinate space. Therefore, overrides that want to customize drawing by including additional view elements need to transform coordinates accordingly. Furthermore, you should either call super at the beginning of your override, or undo any coordinate transforms applied to context before calling super to avoid unexpected behavior.

    Note

    You should not call this method yourself! If you want to manually render an annotation, please use image(size:options:) instead.

    Declaration

    Objective-C

    - (void)drawInContext:(nonnull CGContextRef)context
              options:(nullable PSPDFRenderOptions *)options;

    Swift

    func draw(context: CGContext, options: PSPDFRenderOptions?)

    Parameters

    context

    A graphics context that uses the normalized PDF coordinate space.
    options

    Optionally contains details about how to draw the annotation, and for what purpose.

  • Renders the annotation as an image.

    Will return nil if size is doesn’t have positive width and height. To avoid exhausting memory, this will return a smaller image than requested if size is extremely large.

    Declaration

    Objective-C

    - (nullable UIImage *)imageWithSize:(CGSize)size
                            options:(nullable PSPDFRenderOptions *)options;

    Swift

    func image(size: CGSize, options: PSPDFRenderOptions?) -> UIImage?

  • Point for the note icon. Override to customize.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGPoint noteIconPoint;

    Swift

    var noteIconPoint: CGPoint { get }

  • Configures if the note icon, that indicates an attached note or replies to the annotation, should be drawn. Defaults to YES.

    Note

    Additional checks are honored, to determine if the note icon should be rendered:

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL shouldDrawNoteIconIfNeeded;

    Swift

    var shouldDrawNoteIconIfNeeded: Bool { get }

Advanced

  • Some annotations might change their points/lines/size when the bounding box changes. This returns NO by default.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL shouldUpdatePropertiesOnBoundsChange;

    Swift

    var shouldUpdatePropertiesOnBoundsChange: Bool { get }

  • Undocumented

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL shouldUpdateOptionalPropertiesOnBoundsChange

    Swift

    var shouldUpdateOptionalPropertiesOnBoundsChange: Bool { get }

  • Undocumented

    Declaration

    Objective-C

    - (void)updatePropertiesWithTransform:(CGAffineTransform)transform isSizeChange:(BOOL)isSizeChange meanScale:(CGFloat)meanScale;

    Swift

    func updateProperties(with transform: CGAffineTransform, isSizeChange: Bool, meanScale: CGFloat)

  • Undocumented

    Declaration

    Objective-C

    - (void)updateOptionalPropertiesWithTransform:(CGAffineTransform)transform isSizeChange:(BOOL)isSizeChange meanScale:(CGFloat)meanScale;

    Swift

    func updateOptionalProperties(with transform: CGAffineTransform, isSizeChange: Bool, meanScale: CGFloat)

  • Manually controls if with setting the boundingBox it should be transformed as well.

    Declaration

    Objective-C

    - (void)setBoundingBox:(CGRect)boundingBox
             transform:(BOOL)transform
       includeOptional:(BOOL)optionalProperties;

    Swift

    func setBoundingBox(_ boundingBox: CGRect, transform: Bool, includeOptional optionalProperties: Bool)

  • Copy annotation object to UIPasteboard (multiple formats).

    Declaration

    Objective-C

    - (void)copyToClipboard;

    Swift

    func copyToClipboard()

Fonts

  • 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 accessing data in this dictionary. Further attributes might be rendered and saved, but are not persisted in the PDF.

    Declaration

    Objective-C

    @property (nonatomic, copy, 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 (nonatomic, copy, 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 (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 (nonatomic) NSTextAlignment textAlignment;

    Swift

    var textAlignment: NSTextAlignment { get set }

  • Vertical text alignment. Defaults to PSPDFVerticalAlignmentNone.

    Note

    Shortcut for self.fontAttributes[PSPDFVerticalAlignmentName].

    Warning

    This is not defined in the PDF spec. (PSPDFKit extension), and is only supported for use with Free Text Annotations. This value is ignored for all other types of annotations.

    Declaration

    Objective-C

    @property (nonatomic) PSPDFVerticalAlignment verticalTextAlignment;

    Swift

    var verticalTextAlignment: Annotation.VerticalAlignment { 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 (nonatomic, readonly, 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
                         options:(nullable PSPDFRenderOptions *)options;

    Swift

    func attributedString(withContents contents: String?, options: PSPDFRenderOptions?) -> NSAttributedString?

  • Convenience forwarding contents and no options to attributedStringWithContents:options:.

    Declaration

    Objective-C

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

    Swift

    func attributedString(withContents contents: String?) -> NSAttributedString?

InstantJSON

  • Creates an annotation from JSON data that follows our Instant JSON specification.

    Declaration

    Objective-C

    + (nullable PSPDFAnnotation *)
    annotationFromInstantJSON:(nonnull NSData *)instantJSON
             documentProvider:(nonnull PSPDFDocumentProvider *)documentProvider
                        error:(NSError *_Nullable *_Nullable)error;

    Swift

    /*not inherited*/ init(fromInstantJSON instantJSON: Data, documentProvider: PSPDFDocumentProvider) throws

    Parameters

    instantJSON

    A Data object containing the Instant Annotation JSON. For example, NSData *data = [jsonString dataUsingEncoding:NSUTF8StringEncoding];
    documentProvider

    The document provider from which this annotation is to be generated.
    error

    A pointer to an NSError object that is set when an error occurs.

    Return Value

    Returns nil if an annotation could not be read from the JSON data and sets error.

  • Generates the JSON for the receiver according to the Instant Annotation JSON specification.

    This will use InstantJSONVersion.automatic.

    Note

    In order to generate the JSON serialization for an annotation, the annotation has to be added to a document.

    Declaration

    Objective-C

    - (nullable NSData *)generateInstantJSONWithError:
    (NSError *_Nullable *_Nullable)error;

    Swift

    func generateInstantJSON() throws -> Data

    Parameters

    error

    A pointer to an error object that is set to an actual error if an error occurs.

    Return Value

    A Data object containing the Instant JSON representation of the receiver. Can be converted into JSON string like so: NSString *jsonString = [[NSString alloc] initWithData:result encoding:NSUTF8StringEncoding];

  • Generates the JSON for the receiver according to the Instant Annotation JSON specification.

    Note

    In order to generate the JSON serialization for an annotation, the annotation has to be added to a document.

    Declaration

    Objective-C

    - (nullable NSData *)
    generateInstantJSONWithVersion:(PSPDFInstantJSONVersion)version
                             error:(NSError *_Nullable *_Nullable)error;

    Swift

    func generateInstantJSON(version: InstantJSONVersion) throws -> Data

    Parameters

    version

    The Instant JSON version to generate.
    error

    A pointer to an error object that is set to an actual error if an error occurs.

    Return Value

    A Data object containing the Instant JSON representation of the receiver. Can be converted into JSON string like so: NSString *jsonString = [[NSString alloc] initWithData:result encoding:NSUTF8StringEncoding];

  • Checks if this annotation has a binary Instant JSON attachment. For example, a stamp annotation with an image has one.

    You can use writeBinaryInstantJSONAttachmentToDataSink:error: to fetch the attachment.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL hasBinaryInstantJSONAttachment;

    Swift

    var hasBinaryInstantJSONAttachment: Bool { get }

  • If this annotation has a binary Instant JSON attachment, writes it into the dataSink.

    Declaration

    Objective-C

    - (nullable NSString *)
    writeBinaryInstantJSONAttachmentToDataSink:
        (nonnull id<PSPDFDataSink>)dataSink
                                         error:(NSError *_Nullable *_Nullable)
                                                   error;

    Swift

    func writeBinaryInstantJSONAttachment(to dataSink: DataSink) throws -> String

    Parameters

    dataSink

    The data sink the binary attachment will be written to. See PSPDFFileDataSink or PSPDFDataContainerSink.

    Return Value

    The mime type of the attachment if successful, otherwise nil.

  • Attaches a binary Instant JSON attachment to the annotation. Can be generated using writeBinaryInstantJSONAttachmentToDataSink:error:.

    Declaration

    Objective-C

    - (BOOL)attachBinaryInstantJSONAttachmentFromDataProvider:
            (nonnull id<PSPDFDataProviding>)dataProvider
                                                    error:(NSError *_Nullable
                                                               *_Nullable)error;

    Swift

    func attachBinaryInstantJSONAttachment(fromDataProvider dataProvider: DataProviding) throws

    Parameters

    dataProvider

    The data provider with the binary Instant JSON data.

    Return Value

    YES if successful, otherwise NO.

  • Additional action types.

    Declaration

    Swift

    public var additionalActions: [TriggerEvent : Action]? { get set }

  • (Optional; valid only if the value of borderStyle is PSPDFAnnotationBorderStyleDashed) Array of boxed integer-values defining the dash style.

    Values | Dash

    [] | ━━━━━━━━━━━━━━━━━━━━ [3] | ━ ━━━ ━━━ ━━━ [2] | ━ ━ ━ ━ ━ ━ ━ [2,1] | ━━ ━━ ━━ ━━ ━━ ━━ ━━ [3,5] | ━━━ ━━━ ━━ [2,3] | ━ ━━ ━━ ━━ ━

    Declaration

    Swift

    public var dashArray: [CGFloat]? { get set }

  • Certain annotation types like highlight can have multiple rects.

    Declaration

    Swift

    public var rects: [CGRect]? { get set }

  • Line, Polyline and Polygon annotations have points.

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

    Declaration

    Swift

    public var points: [CGPoint]? { get set }
  • See more

    Declaration

    Swift

    extension Annotation.Kind: CustomStringConvertible, ExpressibleByStringLiteral, Hashable
  • See more

    Declaration

    Swift

    extension Annotation.Tool
    extension Annotation.Tool: CustomStringConvertible, ExpressibleByStringLiteral
  • See more

    Declaration

    Swift

    extension Annotation.ToolVariantID: CustomStringConvertible

Replies and Review Workflows

  • Possible states of an annotation as detailed under section “Annotation States” in Chapter 8.4.5 of the PDF Reference, sixth edition.

    See more

    Declaration

    Swift

    public enum State : Hashable
  • id

    Maps UUID to id to conform to the identifiable protocol.

    Declaration

    Swift

    public var id: String { get }