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

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

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