PTToolManager


@interface PTToolManager : UIView <PTOverridable, PTPDFViewCtrlToolDelegate,
                                   PTToolEvents, PTToolOptionsDelegate>

The PTToolManager class is responsbile for forwarding events from the PDFViewCtrl to Tools, and coordinating the control and data flow between tools.

  • The current tool.

    Declaration

    Objective-C

    @property (nonatomic, strong, nullable) PTTool *tool;

    Swift

    var tool: PTTool? { get set }

  • An object that conforms to the PTToolManagerDelegate protocol.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<PTToolManagerDelegate> delegate;

    Swift

    weak var delegate: (any PTToolManagerDelegate)? { get set }

  • The PTPDFViewCtrl that the PTToolManager was initialized with.

    Declaration

    Objective-C

    @property (nonatomic, weak, readonly) PTPDFViewCtrl *_Nullable pdfViewCtrl;

    Swift

    weak var pdfViewCtrl: PTPDFViewCtrl? { get }

  • The view controller that the tool manager is associated with. Determined by the tool manager’s delegate’s implementation of viewControllerForToolManager:,

    Declaration

    Objective-C

    @property (nonatomic, weak, readonly) UIViewController *_Nullable viewController;

    Swift

    weak var viewController: UIViewController? { get }

  • Returns a newly initialized tool manager with the required pointer to the PTPDFViewCtrl on which it will operate.

    Declaration

    Objective-C

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

    Swift

    init(pdfViewCtrl: PTPDFViewCtrl)

    Parameters

    pdfViewCtrl

    a pointer to the PTPDFViewCtrl that the tool manager will operate.

    Return Value

    A newly initialized tool manager object.

  • Create and set a new tool of the given type as the current tool.

    Declaration

    Objective-C

    - (nonnull __kindof PTTool *)changeTool:(nonnull Class)toolType;

    Swift

    func changeTool(_ toolType: AnyClass) -> PTTool

  • Selects the specified annotation.

    Declaration

    Objective-C

    - (BOOL)selectAnnotation:(nullable PTAnnot *)annotation
            onPageNumber:(unsigned long)pageNumber;

    Swift

    func selectAnnotation(_ annotation: PTAnnot?, onPageNumber pageNumber: UInt) -> Bool

    Parameters

    annotation

    the annotation to selected. If annotation is Nil, any selected annotation is deselected, and the tool is set to the default tool, typically PTPanTool.
    pageNumber

    the page number of the annotation

    Return Value

    YES if the annotation was selected, NO otherwise.

  • Prompts the user for bluetooth permission if they have not been already

    Used as part of detecting if an Apple Pencil is paired with the device.

    Will never prompt on iPhones.

    Declaration

    Objective-C

    - (void)promptForBluetoothPermission;

    Swift

    func promptForBluetoothPermission()

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)initWithFrame:(CGRect)frame NS_UNAVAILABLE;

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)initWithCoder:(NSCoder *)aDecoder NS_UNAVAILABLE;

  • A string that will be used to set the author field of annotations that are created.

    Declaration

    Objective-C

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

    Swift

    var annotationAuthor: String? { get set }

  • When true, the UIMenuController shows after a tap (in addition to after a long press). The default value of this property is false.

    Declaration

    Objective-C

    @property (nonatomic) BOOL showMenuOnTap;

    Swift

    var showMenuOnTap: Bool { get set }

  • When true, the digital signature tool allows the user to save signatures and apply previously saved signatures. The default value of this property is true.

    Declaration

    Objective-C

    @property (nonatomic) BOOL showDefaultSignature;

    Swift

    var showDefaultSignature: Bool { get set }

  • Whether the built-in page number indicator is enabled. The default value of this property is false.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isPageIndicatorEnabled) BOOL pageIndicatorEnabled;

    Swift

    var isPageIndicatorEnabled: Bool { get set }

  • Whether the document associated with the PTPDFViewCtrl is read-only. The default value is NO.

    When in read-only mode, annotation creation and editing are disabled as well as other actions that would modify the document.

    Declaration

    Objective-C

    @property (nonatomic, getter=isReadonly) BOOL readonly;

    Swift

    var isReadonly: Bool { get set }

  • Whether the tool should only create annotations with Apple Pencil touches and not finger touches.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL annotationsCreatedWithPencilOnly;

    Swift

    var annotationsCreatedWithPencilOnly: Bool { get }

  • Controls if Apple’s bluetooth permission prompt will be triggered the first time an Apple Pencil touch is detected, so that the system setting to only annotate with the Apple Pencil can be ignored when no Apple Pencil is currently paired with the device.

    Declaration

    Objective-C

    @property (nonatomic) BOOL allowBluetoothPermissionPrompt;

    Swift

    var allowBluetoothPermissionPrompt: Bool { get set }

  • Controls if Apple’s UIColorPickerViewController will be used when modifying annotation styles in the PTAnnotStyleViewController class. The default value of this property is NO.

    Declaration

    Objective-C

    @property (nonatomic) BOOL useSystemColorPicker;

    Swift

    var useSystemColorPicker: Bool { get set }

Annotation options

Annotation permissions

  • Returns whether the specified annotation allows editing.

    Declaration

    Objective-C

    - (BOOL)hasEditPermissionForAnnot:(nonnull PTAnnot *)annot;

    Swift

    func hasEditPermission(for annot: PTAnnot) -> Bool

  • Whether the permissions of an PTAnnot, returned via -[PTAnnot GetFlag:], are checked when determining whether the annotation can be edited. The default value of this property is NO.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isAnnotationPermissionCheckEnabled)
    BOOL annotationPermissionCheckEnabled;

    Swift

    var isAnnotationPermissionCheckEnabled: Bool { get set }

  • Whether the author of an PTAnnot is checked against the current annotationAuthor when determining whether the annotation can be edited. The default value of this property is NO.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isAnnotationAuthorCheckEnabled)
    BOOL annotationAuthorCheckEnabled;

    Swift

    var isAnnotationAuthorCheckEnabled: Bool { get set }

Interaction features

  • A boolean value that determines whether text selection is enabled.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isTextSelectionEnabled) BOOL textSelectionEnabled;

    Swift

    var isTextSelectionEnabled: Bool { get set }

  • A boolean value that determines whether form filling is enabled.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isFormFillingEnabled) BOOL formFillingEnabled;

    Swift

    var isFormFillingEnabled: Bool { get set }

  • A boolean value that determines whether link following is enabled.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isLinkFollowingEnabled) BOOL linkFollowingEnabled;

    Swift

    var isLinkFollowingEnabled: Bool { get set }

  • A boolean value that determines whether the eraser tool is enabled.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isEraserEnabled) BOOL eraserEnabled;

    Swift

    var isEraserEnabled: Bool { get set }

  • A value that determines if the eraser should erase an ink annotation’s individual points, or the entire thing as a single object. The default is to erase individual points (PTInkEraserModePoints).

    Declaration

    Objective-C

    @property (nonatomic) PTInkEraserMode eraserMode;

    Swift

    var eraserMode: PTInkEraserMode { get set }

  • A list of annotation types to prevent from being erased by the PTEraserTool

    The array entries are wrapped PTExtendedAnnotType enumeration values. The PTEraser will not erase any annotations whose type is included in the array. Example: myToolManager.excludedAnnotationTypesForPTEraser = @[@(PTExtendedAnnotTypeStamp)]; The default value of this property is nil.

    Declaration

    Objective-C

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

    Swift

    var eraserExcludedExtendedAnnotTypes: [NSNumber]? { get set }

  • Determines whether the PTSmartPen tool is enabled.

    The default value of this property is YES.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isSmartPenEnabled) BOOL smartPenEnabled;

    Swift

    var isSmartPenEnabled: Bool { get set }

  • A boolean value that determines whether free text annots should get automatically resized after being edited.

    The default value is true.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isAutoResizeFreeTextEnabled) BOOL autoResizeFreeTextEnabled;

    Swift

    var isAutoResizeFreeTextEnabled: Bool { get set }

  • A boolean value that determines whether measurement annots should snap to document geometry.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isSnapToDocumentGeometryEnabled)
    BOOL snapToDocumentGeometryEnabled;

    Swift

    var isSnapToDocumentGeometryEnabled: Bool { get set }

  • A boolean value that determines whether annots should snap to their initial aspect ratio while being resized.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isAnnotationsSnapToAspectRatioEnabled)
    BOOL annotationsSnapToAspectRatio;

    Swift

    var isAnnotationsSnapToAspectRatioEnabled: Bool { get set }

  • A boolean value that determines whether annotations are selected immediately after they are created. Default is true, or whatever value was last set by a PTToolsSettingsManager.

    Declaration

    Objective-C

    @property (nonatomic) BOOL selectAnnotationAfterCreation;

    Swift

    var selectAnnotationAfterCreation: Bool { get set }

  • Whether multiple annotations can be selected at once.

    The default value of this property is YES.

    Declaration

    Objective-C

    @property (nonatomic) BOOL allowsMultipleAnnotationSelection;

    Swift

    var allowsMultipleAnnotationSelection: Bool { get set }

  • A boolean value that determines whether PencilKit is used to create new free hand annotations. Availble only on iOS 13.1 and greater. Default is true, or whatever value was last set by a PTToolsSettingsManager.

    Declaration

    Objective-C

    @property (nonatomic) BOOL freehandUsesPencilKit;

    Swift

    var freehandUsesPencilKit: Bool { get set }

  • A boolean value that determines whether highlight-only annotations made with PencilKit use a multiply blend mode. Default is true, or whatever value was last set by a PTToolsSettingsManager.

    Declaration

    Objective-C

    @property (nonatomic) BOOL pencilHighlightMultiplyBlendModeEnabled;

    Swift

    var pencilHighlightMultiplyBlendModeEnabled: Bool { get set }

  • A value that determines whether only Pencil touches should be used for annotating. Default is to obey the iOS system setting, or whatever value was last set by a PTToolsSettingsManager.

    Declaration

    Objective-C

    @property (nonatomic) PTPencilInteractionMode pencilInteractionMode;

    Swift

    var pencilInteractionMode: PTPencilInteractionMode { get set }

  • A boolean value that determines if selected text will include an “edit” option that allows the user to edit the underlying PDF text. This feature is in development and is currently considered Beta. Please contact us if you are interested in a more advanced version than the current behaviour.

    Default value is false.

    Declaration

    Objective-C

    @property (nonatomic) BOOL textEditingEnabled;

    Swift

    var textEditingEnabled: Bool { get set }

  • A boolean value that determines if annotating in reflow mode is enabled.

    This property is disabled when the readonly property of the tool manager is set.

    The default value of this property is true.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isAnnotateOnReflowEnabled) BOOL annotateOnReflowEnabled;

    Swift

    var isAnnotateOnReflowEnabled: Bool { get set }

  • A boolean value that determines if form annots can be selected by long press or by the PTAnnotSelectTool multi-selection tool.

    Default value is false.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isSelectFormAnnotationsEnabled)
    BOOL selectFormAnnotationsEnabled;

    Swift

    var isSelectFormAnnotationsEnabled: Bool { get set }

  • A boolean value that determines if moving annotation between pages is allowed. This feature does not currently support moving annotation replies.

    Default value is false.

    Declaration

    Objective-C

    @property (nonatomic) BOOL moveAnnotsBetweenPagesEnabled;

    Swift

    var moveAnnotsBetweenPagesEnabled: Bool { get set }

  • Determines whether a label is shown on perimeter and area annotations.

    The default value of this property is false.

    Declaration

    Objective-C

    @property (nonatomic) BOOL showMeasurementLabel;

    Swift

    var showMeasurementLabel: Bool { get set }

  • A boolean value that determines whether annotation snapping is enabled.

    The default value is false.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isAnnotationSnappingEnabled) BOOL annotationSnappingEnabled;

    Swift

    var isAnnotationSnappingEnabled: Bool { get set }

  • The color of the annotation snapping line. If null, the tintColor will be used. Default is nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, nullable) UIColor *annotationSnappingLineColor;

    Swift

    var annotationSnappingLineColor: UIColor? { get set }

  • A list of annotation types that will not exhibit snapping behaviour.

    The array entries are wrapped PTExtendedAnnotType enumeration values. An annotation of a type specified here will not snap to other annotations or page center, nor be snapped to by other annotations. Example: myToolManager.annotationSnappingExcludedExtendedAnnotTypes = @[@(PTExtendedAnnotTypeStamp)]

    Declaration

    Objective-C

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

    Swift

    var annotationSnappingExcludedExtendedAnnotTypes: [NSNumber]? { get set }

Asset locations

  • A file path pointing to the digital certificate to use for digital signatures.

    Declaration

    Objective-C

    @property (nonatomic, strong) NSURL *_Nonnull digitalCertificateLocation;

    Swift

    var digitalCertificateLocation: URL { get set }

Annotation manager

Undo/redo

Page labels

Digital Signatures manager

Annotation events

  • Used to notify the tool 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 that the annotation was added to.

  • Used to notify the tool 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 tool 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 tool 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 will be removed.
    pageNumber

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

  • Used to notify the tool 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 tool manager that an annotation will be flattened

    Declaration

    Objective-C

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

    Swift

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

    Parameters

    annotation

    The annotation will be flattened.
    pageNumber

    The page number of the PDF that the annotation will be flattened onto.

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

    Declaration

    Objective-C

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

    Swift

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

    Parameters

    annotation

    The annotation that was flattened.
    pageNumber

    The page number of the PDF that the annotation was flattened onto.

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

    Declaration

    Objective-C

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

    Swift

    func formFieldDataModified(_ 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.

Page events

  • Used to notify the tool manager that a page has been added.

    Declaration

    Objective-C

    - (void)pageAddedForPageNumber:(int)pageNumber;

    Swift

    func pageAdded(forPageNumber pageNumber: Int32)

    Parameters

    pageNumber

    The page number of the page that was added.

  • Used to notify the tool manager that a page has been moved. *

    • - parameter: oldPageNumber The old page number of the page.
    • - parameter: newPageNumber The new page number of the page.

    Declaration

    Objective-C

    - (void)pageMovedFromPageNumber:(int)oldPageNumber
                   toPageNumber:(int)newPageNumber;

    Swift

    func pageMoved(fromPageNumber oldPageNumber: Int32, toPageNumber newPageNumber: Int32)

  • Used to notify the tool manager that a page has been removed.

    Declaration

    Objective-C

    - (void)pageRemovedForPageNumber:(int)pageNumber;

    Swift

    func pageRemoved(forPageNumber pageNumber: Int32)

    Parameters

    pageNumber

    The page number of the page that was removed.

Rotation

  • Used to notify the tool manager that a page will be rotated.

    Declaration

    Objective-C

    - (void)willRotatePageForPageNumber:(int)pageNumber;

    Swift

    func willRotatePage(forPageNumber pageNumber: Int32)

    Parameters

    pageNumber

    the page number of the page that will be rotated

  • Used to notify the tool manager that pages in the document will be rotated.

    Declaration

    Objective-C

    - (void)willRotatePagesForPageNumbers:(nonnull NSIndexSet *)pageNumbers;

    Swift

    func willRotatePages(forPageNumbers pageNumbers: IndexSet)

    Parameters

    pageNumbers

    the page numbers of the pages that will be rotated

  • Used to notify the tool manager that a page was rotated.

    Declaration

    Objective-C

    - (void)didRotatePageForPageNumber:(int)pageNumber;

    Swift

    func didRotatePage(forPageNumber pageNumber: Int32)

    Parameters

    pageNumber

    the page number of the page that was rotated

  • Used to notify the tool manager that pages in the document were rotated.

    Declaration

    Objective-C

    - (void)didRotatePagesForPageNumbers:(nonnull NSIndexSet *)pageNumbers;

    Swift

    func didRotatePages(forPageNumbers pageNumbers: IndexSet)

    Parameters

    pageNumbers

    the page numbers of the pages that were rotated

Observers

  • Adds the specified observer to the list of observers to be notified of changes in the tool manager.

    Note

    The observer object is held weakly internally and it is not necessary to remove an observer before it is deallocated.

    Declaration

    Objective-C

    - (void)addObserver:(nonnull id<PTToolManagerObserver>)observer;

    Swift

    func add(_ observer: any PTToolManagerObserver)

  • Removes the specified observer from the list of observers to be notified of changes in the tool manager.

    Declaration

    Objective-C

    - (void)removeObserver:(nonnull id<PTToolManagerObserver>)observer;

    Swift

    func remove(_ observer: any PTToolManagerObserver)