PSPDFAnnotation
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 thePDFConfiguration
’seditableAnnotationTypes
.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 withAnnotationToolbar
andAnnotationStateManager
.
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 inNSSet
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
inflags
.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
inflags
.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
inflags
.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 leastminDiameter
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 ofminDiameter
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 usingPSPDFJSONAdapter
the value of this property is written with the keypage
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 frompageIndex
and the currentdocumentProvider
and will changepageIndex
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
andPSPDFAnnotationTypeNote
currently are rendered as overlay. Ifoverlay
is set to YES, you must also register the corresponding *annotationView class to render (overridePSPDFAnnotationManager
’sdefaultAnnotationViewClassForAnnotation:
)Declaration
Objective-C
@property (getter=isOverlay) BOOL overlay;
Swift
var isOverlay: Bool { get set }
-
By default, annotations are editable when
isReadOnly
returnsfalse
. This property can be used to temporarily lock annotations that are originally editable. (menu won’t be shown) Settingeditable
totrue
will have no effect ifisReadOnly
is true. To ignoreisReadOnly
and make an annotation editable regardless, override the getter and make it always returntrue
.The
editable
property also behaves a little differently for form elements. For them, theeditable
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 theisDeletable
property. UseremoveAnnotations:
onDocument
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. SeePSPDFAnnotationGroupItem.h
forPSPDFAnnotationVariantString
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
andfillColor
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 forFreeTextAnnotation
,PSPDFTextFieldFormElement
, andPSPDFChoiceFormElement
.Note
The annotation will only store the RGB part and discard the alpha channel set here. Annotation opacity is set via thealpha
property. SettingUIColor.clearColor
is equivalent to settingnil
.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 likeclearColor
in that case.Note
The annotation will only store the RGB part and discard the alpha channel set here. Annotation opacity is set via thealpha
property. SettingUIColor.clearColor
is equivalent to settingnil
. Apple Preview.app will not show you transparency in thefillColor
.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
tokCGBlendModeExclusion
.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 inflags
. 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;
-
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
inflags
.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
isPSPDFAnnotationBorderStyleDashed
) 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
isPSPDFAnnotationBorderEffectCloudy
) 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 whatshouldTransformOnBoundingBoxChange
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 aCGPoint
.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 }
-
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 needFeatures.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
andNSNumber
(and their Swift equivalents). For storing boolean values, use(id)kCFBooleanTrue
,(id)kCFBooleanFalse
,@YES
,@NO
, or anNSNumber
initialized using+numberWithBool:
. Only unique strings as dictionary keys are allowed, seeNSJSONSerialization
for details on object restrictions. Adding any other datatype will cause an assertion when setting this property. -
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. -
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 exceptPSPDFFormElement
.PSPDFStampAnnotations
may in certain situations setPSPDFRetainExistingAppearanceStreamGenerator
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
orlineWidth
. 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.Note
appearanceStreamGenerator
is not supported onSignatureFormElement
. Please usePDFSignatureAppearance
.Note
If you intend to useappearanceStreamGenerator
on a annotation subclass that hasdraw(context:options:)
overridden, you have to callmaybeRenderCustomAppearanceStream(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 theappearanceStreamGenerator
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).
-
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 }
-
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 overdrawInContext: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 callsuper
at the beginning of your override, or undo any coordinate transforms applied tocontext
before callingsuper
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 ifsize
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:- The annotation has
contents
set or has replies. - The annotation is not rendered for flattening (
PSPDFAnnotationDrawFlattenedKey
is not used). - The annotation author is not ‘AutoCAD SHX Text’. See https://knowledge.autodesk.com/support/autocad/learn-explore/caas/CloudHelp/cloudhelp/2016/ENU/AutoCAD-Core/files/GUID-56EA988C-A1DA-4E85-8765-B3F31A01AB02-htm.html
Declaration
Objective-C
@property (nonatomic, readonly) BOOL shouldDrawNoteIconIfNeeded;
Swift
var shouldDrawNoteIconIfNeeded: Bool { get }
- The annotation has
-
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).
-
Supports attributes for the text rendering, similar to the attributes in
NSAttributedString
.Note
Supported keys are:NSUnderlineStyleAttributeName
andNSStrikethroughStyleAttributeName
, valid valuesNSUnderlineStyleNone
andNSUnderlineStyleSingle
. A font can either be underline or strikethrough, not both.UIFontDescriptorTraitsAttribute
takes a boxed value ofUIFontDescriptorSymbolicTraits
, valid options areUIFontDescriptorTraitItalic
andUIFontDescriptorTraitBold
.Setting
NSForegroundColorAttributeName
will also update thecolor
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. -
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 forself.fontAttributes[PSPDFFontSizeName]
.Declaration
Objective-C
@property (nonatomic) CGFloat fontSize;
Swift
var fontSize: CGFloat { get set }
-
Text justification. Allows
NSTextAlignmentLeft
,NSTextAlignmentCenter
andNSTextAlignmentRight
.Note
This is a shortcut for the data saved infontAttributes
(NSParagraphStyleAttributeName
) and will modifyfontAttributes
.Declaration
Objective-C
@property (nonatomic) NSTextAlignment textAlignment;
Swift
var textAlignment: NSTextAlignment { get set }
-
Vertical text alignment. Defaults to
PSPDFVerticalAlignmentNone
.Note
Shortcut forself.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 asNSBackgroundColorAttributeName
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?
-
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.
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];
-
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
orPSPDFDataContainerSink
.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
isPSPDFAnnotationBorderStyleDashed
) 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 }
-
Declaration
Swift
extension Annotation.Kind: CustomStringConvertible, ExpressibleByStringLiteral, Hashable
-
Declaration
Swift
extension Annotation.Tool
extension Annotation.Tool: CustomStringConvertible, ExpressibleByStringLiteral
-
Declaration
Swift
extension Annotation.ToolVariantID: CustomStringConvertible
-
Possible states of an annotation as detailed under section “Annotation States” in Chapter 8.4.5 of the PDF Reference, sixth edition.
See moreDeclaration
Swift
public enum State : Hashable
-
Maps UUID to id to conform to the identifiable protocol.
Declaration
Swift
public var id: String { get }