PTAnnotationManager


@interface PTAnnotationManager : NSObject <PTOverridable>

Instances of the PTAnnotationManager class manage the annotations in a PTPDFViewCtrl and maintain annotation model objects that correspond to the PDF annotations.

  • Initializes a newly created PTAnnotationManager with the given PTPDFViewCtrl instance.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithPDFViewCtrl:
        (nonnull PTPDFViewCtrl *)pdfViewCtrl;

    Swift

    init(pdfViewCtrl: PTPDFViewCtrl)

    Parameters

    pdfViewCtrl

    The PTPDFViewCtrl that this annotation manager will coordinate with.

    Return Value

    an initialized PTAnnotationManager instance

  • Initializes a newly created PTAnnotationManager with the given PTToolManager instance.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithToolManager:
        (nonnull PTToolManager *)toolManager;

    Swift

    convenience init(toolManager: PTToolManager)

    Parameters

    toolManager

    The PTToolManager that this annotation manager will coordinate with.

    Return Value

    an initialized PTAnnotationManager instance

  • The PTPDFViewCtrl instance that this annotation manager coordinates with.

    Declaration

    Objective-C

    @property (nonatomic, strong) PTPDFViewCtrl *_Nonnull pdfViewCtrl;

    Swift

    var pdfViewCtrl: PTPDFViewCtrl { get set }
  • The PTToolManager instance that this annotation manager coordinates with.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) PTToolManager *toolManager;

    Swift

    weak var toolManager: PTToolManager? { get set }
  • The PTUndoRedoManager instance that this annotation manager coordinates with.

    Declaration

    Objective-C

    @property (nonatomic, strong, nullable) PTUndoRedoManager *undoRedoManager;

    Swift

    var undoRedoManager: PTUndoRedoManager? { get set }
  • The identifier of the current annotation author.

    Declaration

    Objective-C

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

    Swift

    var annotationAuthorIdentifier: String? { get set }
  • Controls whether annotations made by other authors can be edited by the current author, specified by the annotationAuthorIdentifier property.

    The default value of this property is PTAnnotationModeEditAll.

    Declaration

    Objective-C

    @property (nonatomic) PTAnnotationEditMode annotationEditMode;

    Swift

    var annotationEditMode: PTAnnotationManager.AnnotationEditMode { get set }
  • Returns whether the specified annotation is editable by the given author.

    Declaration

    Objective-C

    - (BOOL)isAnnotation:(nonnull PTAnnot *)annotation
                            inDocument:(nonnull PTSDFDoc *)document
        editableByAuthorWithIdentifier:
            (nonnull NSString *)otherAnnotationAuthorIdentifier;

    Swift

    func isAnnotation(_ annotation: PTAnnot, inDocument document: PTSDFDoc, editableByAuthorWithIdentifier otherAnnotationAuthorIdentifier: String) -> Bool

    Parameters

    annotation

    the annotation that will be edited

    document

    the document containing the annotation

    otherAnnotationAuthorIdentifier

    the identifier of the author editing the annotation

    Return Value

    YES if the annotation can be edited by the given author, NO otherwise

  • Returns whether the specified annotation, with the specified author identifier, is editable by the given author.

    Declaration

    Objective-C

    - (BOOL)isAnnotation:(nonnull PTAnnot *)annotation
                  withAuthorIdentifier:
                      (nonnull NSString *)annotationAuthorIdentifier
        editableByAuthorWithIdentifier:
            (nonnull NSString *)otherAnnotationAuthorIdentifier;

    Swift

    func isAnnotation(_ annotation: PTAnnot, withAuthorIdentifier annotationAuthorIdentifier: String, editableByAuthorWithIdentifier otherAnnotationAuthorIdentifier: String) -> Bool

    Parameters

    annotation

    the annotation that will be edited

    annotationAuthorIdentifier

    the identifier of the annotation’s author

    otherAnnotationAuthorIdentifier

    the identifier of the author editing the annotation

    Return Value

    YES if the annotation can be edited by the given author, NO otherwise

  • Generates and sets a new unique identifier for the specified annotation.

    Note

    This method acquires a write-lock on the pdfViewCtrl.

    Declaration

    Objective-C

    - (void)generateIdentifierForAnnotation:(nonnull PTAnnot *)annotation;

    Swift

    func generateIdentifier(forAnnotation annotation: PTAnnot)

    Parameters

    annotation

    The annotation for which to generate and set a new unique identifier

  • Updates the modification date for the specified annotation to the current date and time.

    Note

    This method acquires a write-lock on the pdfViewCtrl.

    Declaration

    Objective-C

    - (void)updateModificationDateForAnnotation:(nonnull PTAnnot *)annotation;

    Swift

    func updateModificationDate(forAnnotation annotation: PTAnnot)

    Parameters

    annotation

    The annotation for which to update the modification date

  • Removes the given PDF annotation from the specified PDF page in the current document.

    Note

    In Swift, this method is imported as a throwing function.

    Declaration

    Objective-C

    - (BOOL)removeAnnotation:(nonnull PTAnnot *)annotation
                onPageNumber:(int)pageNumber
                   withError:(NSError *_Nullable *_Nullable)error;

    Swift

    func removeAnnotation(_ annotation: PTAnnot, onPageNumber pageNumber: Int32) throws

    Parameters

    annotation

    The PDF annotation to be removed

    pageNumber

    The PDF page number containing the annotation

    error

    On input, a pointer to an error object. If an error occurs , this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

    Return Value

    YES if the annotation was successfully removed, NO if an error occurred.

  • Removes the given PDF annotations from the specified PDF page in the current document.

    Note

    In Swift, this method is imported as a throwing function.

    Declaration

    Objective-C

    - (BOOL)removeAnnotations:(nonnull NSArray<PTAnnot *> *)annotations
                 onPageNumber:(int)pageNumber
                    withError:(NSError *_Nullable *_Nullable)error;

    Swift

    func removeAnnotations(_ annotations: [PTAnnot], onPageNumber pageNumber: Int32) throws

    Parameters

    annotations

    The PDF annotations to be removed

    pageNumber

    The PDF page number containing the annotations

    error

    On input, a pointer to an error object. If an error occurs , this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

    Return Value

    YES if the annotations were successfully removed, NO if an error occurred.

  • Removes all of the PDF annotations on the specified PDF page in the current document.

    Note

    In Swift, this method is imported as a throwing function.

    Declaration

    Objective-C

    - (BOOL)removeAllAnnotationsOnPageNumber:(int)pageNumber
                                   withError:(NSError *_Nullable *_Nullable)error;

    Swift

    func removeAllAnnotations(onPageNumber pageNumber: Int32) throws

    Parameters

    pageNumber

    the PDF page number containing the annotations to remove

    error

    On input, a pointer to an error object. If an error occurs , this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

    Return Value

    YES if the annotations were successfully removed, NO if an error occurred.

  • Removes all of the PDF annotations in the current document.

    Note

    In Swift, this method is imported as a throwing function.

    Declaration

    Objective-C

    - (BOOL)removeAllAnnotationsWithError:(NSError *_Nullable *_Nullable)error;

    Swift

    func removeAllAnnotations() throws

    Parameters

    error

    On input, a pointer to an error object. If an error occurs , this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

    Return Value

    YES if the annotations were successfully removed, NO if an error occurred.

  • Updates the annotations in the document with the provided XFDF string.

    Note

    In Swift, this method is imported as a throwing function.

    Declaration

    Objective-C

    - (BOOL)updateAnnotationsWithXFDFString:(nonnull NSString *)xfdfString
                                      error:(NSError *_Nullable *_Nullable)error;

    Swift

    func updateAnnotations(withXFDFString xfdfString: String) throws

    Parameters

    xfdfString

    The XFDF string containing the updated annotation data.

    error

    On input, a pointer to an error object. If an error occurs , this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

    Return Value

    YES if the annotations in the document were updated successfuly, or NO if an error occurred.

  • Updates the annotations in the document with the provided XFDF command string.

    Note

    In Swift, this method is imported as a throwing function.

    Declaration

    Objective-C

    - (BOOL)updateAnnotationsWithXFDFCommand:(nonnull NSString *)xfdfCommand
                                       error:(NSError *_Nullable *_Nullable)error;

    Swift

    func updateAnnotations(withXFDFCommand xfdfCommand: String) throws

    Parameters

    xfdfCommand

    The XFDF command string containing the updated annotation data.

    error

    On input, a pointer to an error object. If an error occurs , this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

    Return Value

    YES if the annotations in the document were updated successfuly, or NO if an error occurred.

  • The top-level document model object representing the current PDF document in the pdfViewCtrl.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nullable) id<PTDocumentModel> documentModel;

    Swift

    var documentModel: PTDocumentModel? { get }
  • Whether the document model for the current PDF document is currently being loaded.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readonly,
              getter=isLoadingDocumentModel) BOOL loadingDocumentModel;

    Swift

    var isLoadingDocumentModel: Bool { get }
  • Whether the documentModel is loaded.

    The default value of this property is NO.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readonly,
              getter=isDocumentModelLoaded) BOOL documentModelLoaded;

    Swift

    var isDocumentModelLoaded: Bool { get }
  • Loads the document model for the current PDF document displayed in the pdfViewCtrl. It is safe to call this method multiple times.

    Declaration

    Objective-C

    - (void)loadDocumentModel;

    Swift

    func loadDocumentModel()
  • Loads the document model for the current PDF document displayed in the pdfViewCtrl.

    Declaration

    Objective-C

    - (void)loadDocumentModelWithCompletionHandler:
        (void (^_Nullable)(id<PTDocumentModel> _Nullable,
                           NSError *_Nullable))completion;

    Swift

    func loadDocumentModel() async throws -> PTDocumentModel

    Parameters

    completion

    an optional completion block to be executed when the document model has been loaded. On success, the documentModel parameter will contain the loaded document model, otherwise the error parameter will contain information describing the reason for failure.

  • If the annotation manager is currently loading annotation models.

    Changes to the document page ordering / number should not be made while annotations are loading.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readonly,
              getter=isLoadingAnnotations) BOOL loadingAnnotations;

    Swift

    var isLoadingAnnotations: Bool { get }
  • Whether the annotation models have been loaded.

    The default value of this property is NO.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readonly,
              getter=areAnnotationsLoaded) BOOL annotationsLoaded;

    Swift

    var areAnnotationsLoaded: Bool { get }
  • Starts or restarts the loading of annotation models by this annotation manager.

    Declaration

    Objective-C

    - (void)loadAnnotationModels;

    Swift

    func loadAnnotationModels()
  • Fetches or creates the annotation model object for the given PDF annotation.

    Declaration

    Objective-C

    - (void)annotationModelForAnnotation:(nonnull PTAnnot *)annotation
                            onPageNumber:(int)pageNumber
                   withCompletionHandler:
                       (nonnull void (^)(id<PTAnnotationModel> _Nullable,
                                         NSError *_Nullable))completionHandler;

    Swift

    func annotationModel(forAnnotation annotation: PTAnnot, onPageNumber pageNumber: Int32) async throws -> PTAnnotationModel

    Parameters

    annotation

    The annotation for which to get the model object

    pageNumber

    The PDF page number of the annotation

    completionHandler

    A block that will be called asynchronously with the results of this method. On success, the annotationModel block parameter will contain the annotation model object for the PDF annotation. If the annotation model object cannot be fetched or created, the annotationModel parameter will be nil and error information will be passed in the error block parameter.

  • Returns whether the specified annotation model object can be edited by the current annotation author.

    Declaration

    Objective-C

    - (BOOL)canEditAnnotationModel:(nonnull id<PTAnnotationModel>)annotationModel;

    Swift

    func canEdit(_ annotationModel: PTAnnotationModel) -> Bool

    Return Value

    YES if the specified annotation model object can be edited by the current annotation author, NO otherwise.

  • Used to notify the annotation manager that an annotation has been added.

    Declaration

    Objective-C

    - (void)annotationAdded:(nonnull PTAnnot *)annotation
               onPageNumber:(int)pageNumber;

    Swift

    func annotationAdded(_ annotation: PTAnnot, onPageNumber pageNumber: Int32)

    Parameters

    annotation

    The annotation that was added.

    pageNumber

    The page number of the PDF to which the annotation was added.

  • Used to notify the annotation manager that annotations have been added.

    Declaration

    Objective-C

    - (void)annotationsAdded:(nonnull NSArray<PTAnnot *> *)annotations
                onPageNumber:(int)pageNumber;

    Swift

    func annotationsAdded(_ annotations: [PTAnnot], onPageNumber pageNumber: Int32)

    Parameters

    annotations

    The annotations that were added.

    pageNumber

    The page number of the PDF that the annotations were added to.

  • Used to notify the annotation manager that an annotation will be modified

    Declaration

    Objective-C

    - (void)willModifyAnnotation:(nonnull PTAnnot *)annotation
                    onPageNumber:(int)pageNumber;

    Swift

    func willModifyAnnotation(_ annotation: PTAnnot, onPageNumber pageNumber: Int32)

    Parameters

    annotation

    The annotation will be modified.

    pageNumber

    The page number of the PDF that the annotation was modified on.

  • Used to notify the annotation manager that annotations will be modified.

    Declaration

    Objective-C

    - (void)willModifyAnnotations:(nonnull NSArray<PTAnnot *> *)annotations
                     onPageNumber:(int)pageNumber;

    Swift

    func willModifyAnnotations(_ annotations: [PTAnnot], onPageNumber pageNumber: Int32)

    Parameters

    annotations

    The annotations will be modified.

    pageNumber

    The page number of the PDF that the annotations were modified on.

  • Used to notify the annotation manager that an annotation has been modified.

    Declaration

    Objective-C

    - (void)annotationModified:(nonnull PTAnnot *)annotation
                  onPageNumber:(int)pageNumber;

    Swift

    func annotationModified(_ annotation: PTAnnot, onPageNumber pageNumber: Int32)

    Parameters

    annotation

    The annotation that was modified.

    pageNumber

    The page number of the PDF that the annotation was modified on.

  • Used to notify the annotation manager that annotations have been modified.

    Declaration

    Objective-C

    - (void)annotationsModified:(nonnull NSArray<PTAnnot *> *)annotations
                   onPageNumber:(int)pageNumber;

    Swift

    func annotationsModified(_ annotations: [PTAnnot], onPageNumber pageNumber: Int32)

    Parameters

    annotations

    The annotations that were modified.

    pageNumber

    The page number of the PDF that the annotations were modified on.

  • Used to notify the annotation manager that the data of a form field has been modified.

    Declaration

    Objective-C

    - (void)formFieldDataModifiedForAnnotation:(nonnull PTAnnot *)annotation
                                  onPageNumber:(int)pageNumber;

    Swift

    func formFieldDataModified(forAnnotation annotation: PTAnnot, onPageNumber pageNumber: Int32)

    Parameters

    annotation

    The form field annotation that has modified data.

    pageNumber

    The page number of the PDF that the form field annotation is on.

  • Used to notify the annotation manager that an annotation will be removed.

    Declaration

    Objective-C

    - (void)willRemoveAnnotation:(nonnull PTAnnot *)annotation
                    onPageNumber:(int)pageNumber;

    Swift

    func willRemoveAnnotation(_ annotation: PTAnnot, onPageNumber pageNumber: Int32)

    Parameters

    annotation

    The annotation that will be removed.

    pageNumber

    The page number of the PDF that the annotation was removed from.

  • Used to notify the annotation manager that annotations will be removed.

    Declaration

    Objective-C

    - (void)willRemoveAnnotations:(nonnull NSArray<PTAnnot *> *)annotations
                     onPageNumber:(int)pageNumber;

    Swift

    func willRemoveAnnotations(_ annotations: [PTAnnot], onPageNumber pageNumber: Int32)

    Parameters

    annotations

    The annotations that will be removed.

    pageNumber

    The page number of the PDF that the annotations will be removed from.

  • Used to notify the annotation manager that an annotation has been removed.

    Declaration

    Objective-C

    - (void)annotationRemoved:(nonnull PTAnnot *)annotation
                 onPageNumber:(int)pageNumber;

    Swift

    func annotationRemoved(_ annotation: PTAnnot, onPageNumber pageNumber: Int32)

    Parameters

    annotation

    The annotation that was removed.

    pageNumber

    The page number of the PDF that the annotation was removed from.

  • Used to notify the annotation manager that annotations have been removed.

    Declaration

    Objective-C

    - (void)annotationsRemoved:(nonnull NSArray<PTAnnot *> *)annotations
                  onPageNumber:(int)pageNumber;

    Swift

    func annotationsRemoved(_ annotations: [PTAnnot], onPageNumber pageNumber: Int32)

    Parameters

    annotations

    The annotations that were removed.

    pageNumber

    The page number of the PDF that the annotations were removed from.

  • Used to notify the annotation manager that annotations will be updated with an XFDF string.

    Declaration

    Objective-C

    - (void)willUpdateAnnotationsWithXFDFString:(nonnull NSString *)xfdfString;

    Swift

    func willUpdateAnnotations(withXFDFString xfdfString: String)

    Parameters

    xfdfString

    The XFDF string containing the updated annotation data.

  • Used to notify the annotation manager that annotations have been updated with an XFDF string.

    Declaration

    Objective-C

    - (void)didUpdateAnnotationsWithXFDFString:(nonnull NSString *)xfdfString;

    Swift

    func didUpdateAnnotations(withXFDFString xfdfString: String)

    Parameters

    xfdfString

    The XFDF string containing the updated annotation data.

  • Used to notify the annotation manager that annotations will be updated with an XFDF command string.

    Declaration

    Objective-C

    - (void)willUpdateAnnotationsWithXFDFCommand:(nonnull NSString *)xfdfCommand;

    Swift

    func willUpdateAnnotations(withXFDFCommand xfdfCommand: String)

    Parameters

    xfdfCommand

    The XFDF command string containing the updated annotation data.

  • Used to notify the annotation manager that annotations have been updated with an XFDF command string.

    Declaration

    Objective-C

    - (void)didUpdateAnnotationsWithXFDFCommand:(nonnull NSString *)xfdfCommand;

    Swift

    func didUpdateAnnotations(withXFDFCommand xfdfCommand: String)

    Parameters

    xfdfCommand

    The XFDF command string containing the updated annotation data.