PTToolEvents

@protocol PTToolEvents <NSObject>

The PTToolEvents protocol allows the adopting class to receive events from a PTToolSwitching and control the tool’s behavior.

  • Used by a tool to notify the tool manager that it has added an annotation.

    Declaration

    Objective-C

    - (void)tool:(nonnull PTTool *)tool
    annotationAdded:(nonnull PTAnnot *)annotation
       onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, annotationAdded annotation: PTAnnot, onPageNumber pageNumber: UInt)

    Parameters

    tool

    The tool that sent the message.
    annotation

    The annotation that was added.
    pageNumber

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

  • Used by a tool to notify the tool manager that it has modified an annotation.

    Declaration

    Objective-C

    - (void)tool:(nonnull PTTool *)tool
    annotationModified:(nonnull PTAnnot *)annotation
          onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, annotationModified annotation: PTAnnot, onPageNumber pageNumber: UInt)

    Parameters

    tool

    The tool that sent the message.
    annotation

    The annotation that was modified.
    pageNumber

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

  • Used by a tool to notify the tool manager that it has removed an annotation.

    Declaration

    Objective-C

    - (void)tool:(nonnull PTTool *)tool
    annotationRemoved:(nonnull PTAnnot *)annotation
         onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, annotationRemoved annotation: PTAnnot, onPageNumber pageNumber: UInt)

    Parameters

    tool

    The tool that sent the message.
    annotation

    The annotation that was removed.
    pageNumber

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

  • Used by a tool to notify the tool manager that it has flattened an annotation.

    Declaration

    Objective-C

    - (void)tool:(nonnull PTTool *)tool
    annotationFlattened:(nonnull PTAnnot *)annotation
           onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, annotationFlattened annotation: PTAnnot, onPageNumber pageNumber: UInt)

    Parameters

    tool

    The tool that sent the message.
    annotation

    The annotation that was flattened.
    pageNumber

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

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

    Declaration

    Objective-C

    - (void)tool:(nonnull PTTool *)tool
    formFieldDataModified:(nonnull PTAnnot *)annotation
             onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, formFieldDataModified annotation: PTAnnot, onPageNumber pageNumber: UInt)

    Parameters

    tool

    The tool that sent the message.
    annotation

    The form field annotation that has modified data.
    pageNumber

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

  • Allows the tool manager to take over link handling. Links can either be annotations, or detected as links by PDFNet via text pattern matching. One of the two first parameters will have a value, the other will be nil.

    See

    -[PTPDFViewCtrl SetUrlExtraction:]

    Declaration

    Objective-C

    - (BOOL)tool:(nonnull PTTool *)tool
    shouldHandleLinkAnnotation:(nullable PTAnnot *)annotation
                    orLinkInfo:(nullable PTLinkInfo *)linkInfo
                  onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, shouldHandleLinkAnnotation annotation: PTAnnot?, orLinkInfo linkInfo: PTLinkInfo?, onPageNumber pageNumber: UInt) -> Bool

    Parameters

    tool

    The tool that sent the message.
    annotation

    The link annotation, if it exists, that will be handled. If there is not a link annotation, then nil.
    linkInfo

    If it exists, the text that was detected as matching the format of a link. nil otherwise.
    pageNumber

    The page number that the annotation or link is on.

    Return Value

    YES if the tool should handle the link; NO if not.

  • Allows the tool manager to control whether the tool should interact the given form annotation on pageNumber.

    Declaration

    Objective-C

    - (BOOL)tool:(nonnull PTTool *)tool
    shouldInteractWithForm:(nonnull PTAnnot *)annotation
              onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, shouldInteractWithForm annotation: PTAnnot, onPageNumber pageNumber: UInt) -> Bool

    Parameters

    tool

    The tool that sent the message.
    annotation

    The form annotation that will be activated
    pageNumber

    The page number that the annotation is on.

    Return Value

    YES if the tool should continue to select the annotation; NO if not.

  • Allows the tool mananger to control whether the tool should handle the Apple Pencil Scribble interaction for a given annotation on pageNumber.

    Declaration

    Objective-C

    - (BOOL)tool:(nonnull PTTool *)tool
    shouldHandleIndirectScribbleInteraction:
        (nonnull UIIndirectScribbleInteraction *)scribbleInteraction
                              forAnnotation:(nonnull PTAnnot *)annotation
                               onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, shouldHandle scribbleInteraction: __UIIndirectScribbleInteraction, forAnnotation annotation: PTAnnot, onPageNumber pageNumber: UInt) -> Bool

    Parameters

    tool

    The tool that sent the message.
    scribbleInteraction

    the scribble interaction.
    annotation

    The annotation that will be selected.
    pageNumber

    The page number that the annotation is on.

    Return Value

    YES if the tool should continue to scribble on the annotation; NO if not.

  • Allows the tool manager to control whether the tool should select the given annotation on pageNumber.

    Declaration

    Objective-C

    - (BOOL)tool:(nonnull PTTool *)tool
    shouldSelectAnnotation:(nonnull PTAnnot *)annotation
              onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, shouldSelectAnnotation annotation: PTAnnot, onPageNumber pageNumber: UInt) -> Bool

    Parameters

    tool

    The tool that sent the message.
    annotation

    The annotation that will be selected
    pageNumber

    The page number that the annotation is on.

    Return Value

    YES if the tool should continue to select the annotation; NO if not.

  • Used by a tool to notify the tool manager that it has selected an annotation.

    Declaration

    Objective-C

    - (void)tool:(nonnull PTTool *)tool
    didSelectAnnotation:(nonnull PTAnnot *)annotation
           onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, didSelectAnnotation annotation: PTAnnot, onPageNumber pageNumber: UInt)

    Parameters

    tool

    The tool that sent the message.
    annotation

    The annotation that was selected.
    pageNumber

    The page number that the annotation is on.

  • Used by a tool to notify the tool manager that text will be copied.

    Declaration

    Objective-C

    - (nullable NSString *)tool:(nonnull PTTool *)tool
       willCopyReturnedText:(nullable NSString *)selectedText
               toPasteboard:(nonnull UIPasteboard *)pasteboard;

    Swift

    func tool(_ tool: PTTool, willCopyReturnedText selectedText: String?, to pasteboard: UIPasteboard) -> String?

    Parameters

    tool

    The tool that sent the message
    selectedText

    The text that will be copied
    pasteboard

    The pasteboard to which the text will be added

    Return Value

    The text that will be copied to the pasteboard. This may be different from the value of the textToCopy parameter.

  • Used by a tool to notify the tool manager that text was copied.

    Declaration

    Objective-C

    - (void)tool:(nonnull PTTool *)tool
     didCopyText:(nullable NSString *)copiedText
    toPasteboard:(nonnull UIPasteboard *)pasteboard;

    Swift

    func tool(_ tool: PTTool, didCopyText copiedText: String?, to pasteboard: UIPasteboard)

    Parameters

    tool

    The tool that sent the message
    copiedText

    An in-out pointer to the text that was copied
    pasteboard

    The pasteboard to which the text was added

  • Allows the tool manager to control whether to show a menu controller for the given annotation and page number.

    Declaration

    Objective-C

    - (BOOL)tool:(nonnull PTTool *)tool
    shouldShowMenu:(nonnull UIMenuController *)menuController
     forAnnotation:(nullable PTAnnot *)annotation
      onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, shouldShowMenu menuController: UIMenuController, forAnnotation annotation: PTAnnot?, onPageNumber pageNumber: UInt) -> Bool

    Parameters

    tool

    The tool that sent the message.
    menuController

    The menu to be shown.
    annotation

    The annotation.
    pageNumber

    The page number that the annotation is on.

    Return Value

    YES if the tool should show the UIMenuController; NO if not.

  • Allows the tool manager to control handling of file attachments.

    Declaration

    Objective-C

    - (void)tool:(nonnull PTTool *)tool
    handleFileAttachment:(nonnull PTFileAttachment *)fileAttachment
            onPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, handle fileAttachment: PTFileAttachment, onPageNumber pageNumber: UInt)

    Parameters

    tool

    The tool that sent the message.
    fileAttachment

    The file attachment annotation.
    pageNumber

    The page number that the annotation is on.

  • Allows the tool manager to control saving of file attachments.

    Declaration

    Objective-C

    - (void)tool:(nonnull PTTool *)tool
    didAttemptFileAttachmentSave:(nonnull PTFileAttachment *)fileAttachment
                    onPageNumber:(unsigned long)pageNumber
                         success:(BOOL)success;

    Swift

    func tool(_ tool: PTTool, didAttemptFileAttachmentSave fileAttachment: PTFileAttachment, onPageNumber pageNumber: UInt, success: Bool)

    Parameters

    tool

    The tool that sent the message.
    fileAttachment

    The file attachment annotation to be saved.
    pageNumber

    The page number that the annotation is on.

  • Allows the tool manager to control handling of file selections.

    Declaration

    Objective-C

    - (BOOL)tool:(nonnull PTTool *)tool
    handleFileSelected:(nonnull NSString *)filePath;

    Swift

    func tool(_ tool: PTTool, handleFileSelected filePath: String) -> Bool

    Parameters

    tool

    the tool that sent the message.
    filePath

    the selected file path

    Return Value

    YES if the selected file was handled, NO if not

  • Allows the tool manager to control handling of file selections with destination page numbers.

    Declaration

    Objective-C

    - (BOOL)tool:(nonnull PTTool *)tool
       handleFileSelected:(nonnull NSString *)filePath
    destinationPageNumber:(unsigned long)pageNumber;

    Swift

    func tool(_ tool: PTTool, handleFileSelected filePath: String, destinationPageNumber pageNumber: UInt) -> Bool

    Parameters

    tool

    the tool that sent the message.
    filePath

    the selected file path
    pageNumber

    the destination page number of the selected file

    Return Value

    YES if the selected file was handled, NO if not

  • Allows the tool manager to control handling of named actions.

    Declaration

    Objective-C

    - (BOOL)tool:(nonnull PTTool *)tool
    handleNamedAction:(nonnull NSString *)namedAction;

    Swift

    func tool(_ tool: PTTool, handleNamedAction namedAction: String) -> Bool

    Parameters

    tool

    the tool that sent the message.
    namedAction

    the namedAction

    Return Value

    YES if the named action was handled, NO if not

  • Dispatches a “custom” event.

    This method triggers an asynchronous call to -[PTToolSwitching onSwitchToolEvent:] with the provided user data.

    Declaration

    Objective-C

    - (void)createSwitchToolEvent:(nullable id)userData;

    Swift

    func createSwitchToolEvent(_ userData: Any?)

    Parameters

    userData

    Arbitrary data provided by the tool.

Appearance views

  • Notifies the receiver that the live-appearance view will be displayed for the specified annotation.

    Declaration

    Objective-C

    - (void)tool:(nonnull PTTool *)tool
    willDisplayAppearanceView:(nonnull UIView *)appearanceView
                forAnnotation:(nonnull PTAnnot *)annotation
                 onPageNumber:(int)pageNumber;

    Swift

    func tool(_ tool: PTTool, willDisplayAppearanceView appearanceView: UIView, forAnnotation annotation: PTAnnot, onPageNumber pageNumber: Int32)

    Parameters

    tool

    The tool sending this message.
    appearanceView

    The annotation appearance view that will be displayed.
    annotation

    The annotation.
    pageNumber

    The page number of the annotation.

  • Notifies the receiver that the live-appearance view is no longer being displayed for the specified annotation.

    Declaration

    Objective-C

    - (void)tool:(nonnull PTTool *)tool
    didEndDisplayingAppearanceView:(nonnull UIView *)appearanceView
                     forAnnotation:(nonnull PTAnnot *)annotation
                      onPageNumber:(int)pageNumber;

    Swift

    func tool(_ tool: PTTool, didEndDisplayingAppearanceView appearanceView: UIView, forAnnotation annotation: PTAnnot, onPageNumber pageNumber: Int32)

    Parameters

    tool

    The tool sending this message.
    appearanceView

    The annotation appearance view that was displayed.
    annotation

    The annotation.
    pageNumber

    The page number of the annotation.