PTToolEvents

@protocol PTToolEvents <NSObject>

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


                    
                    
                    -tool:annotationAdded:onPageNumber:

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.


                    
                    
                    -tool:annotationModified:onPageNumber:

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.


                    
                    
                    -tool:annotationRemoved:onPageNumber:

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.


                    
                    
                    -tool:annotationFlattened:onPageNumber:

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.


                    
                    
                    -tool:formFieldDataModified:onPageNumber:

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.


                    
                    
                    -tool:shouldHandleLinkAnnotation:orLinkInfo:onPageNumber:

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.


                    
                    
                    -tool:shouldInteractWithForm:onPageNumber:

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.


                    
                    
                    -tool:shouldHandleIndirectScribbleInteraction:forAnnotation:onPageNumber:

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.


                    
                    
                    -tool:shouldSelectAnnotation:onPageNumber:

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.


                    
                    
                    -tool:didSelectAnnotation:onPageNumber:

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.


                    
                    
                    -tool:willCopyReturnedText:toPasteboard:

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.


                    
                    
                    -tool:didCopyText:toPasteboard:

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


                    
                    
                    -tool:shouldShowMenu:forAnnotation:onPageNumber:

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.


                    
                    
                    -tool:handleFileAttachment:onPageNumber:

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.


                    
                    
                    -tool:didAttemptFileAttachmentSave:onPageNumber:success:

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.


                    
                    
                    -tool:handleFileSelected:

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


                    
                    
                    -tool:handleFileSelected:destinationPageNumber:

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


                    
                    
                    -tool:handleNamedAction:

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


                    
                    
                    -createSwitchToolEvent:

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


                    
                    
                    -tool:willDisplayAppearanceView:forAnnotation:onPageNumber:

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.


                    
                    
                    -tool:didEndDisplayingAppearanceView:forAnnotation:onPageNumber:

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.