Annotation style editor for iOS viewer

The PTAnnotStyleViewController class shows annotation style properties in a half-modal bottom sheet, or optionally in a popover view on large-screened devices such as iPads or large iPhones in landscape mode. With this style editor, users can edit annotation styles easily with style presets as well as choosing their own colors through the color picker.

Half-Modal Bottom Sheet	Popover

The annotation style editor is part of the Tools library, so make sure you have added the Tools library to your project.

The annotation style state for the given annotation is managed by an PTAnnotStyle instance. To create and display a new annotation style view controller from another view controller, first create and supply an PTAnnotStyle instance to the PTAnnotStyleViewController initializer:

1// Initialize annot style with a PTAnnot instance or PTAnnotType.
2let annotStyle = PTAnnotStyle(annot: annot)
3
4let stylePicker = PTAnnotStyleViewController(annotStyle: annotStyle)
5stylePicker.delegate = self
6
7let rect: PTPDFRect = annot.getRect()
8let annotRect: CGRect = self.pdfViewCtrl.pdfRectPage2CGRectScreen(rect, pageNumber: self.annotationPageNumber)
9
10stylePicker.presentationManager.popoverSourceView = self.pdfViewCtrl
11stylePicker.presentationManager.popoverSourceRect = annotRect
12
13self.present(stylePicker, animated: true, completion: nil)

1// Initialize annot style with a PTAnnot instance or PTAnnotType.
2PTAnnotStyle *annotStyle = [[PTAnnotStyle alloc] initWithAnnot:annot];
3annotStyle.saveValuesAsDefaults = NO;
4
5stylePicker = [[PTAnnotStyleViewController alloc] initWithAnnotStyle:annotStyle];
6stylePicker.delegate = self;
7
8// Calculate the CGRect to use as the sourceRect if you want to present the style editor in a popover on large-screened devices
9PTPDFRect* rect = [annot GetRect];
10CGRect annotRect = [self.pdfViewCtrl PDFRectPage2CGRectScreen:rect PageNumber:self.annotationPageNumber];
11
12stylePicker.presentationManager.popoverSourceView = self.pdfViewCtrl;
13stylePicker.presentationManager.popoverSourceRect = annotRect;
14    
15[self presentViewController:stylePicker animated:YES completion:nil];

PTAnnotStyle can also be initialized with an PTAnnotType, in which case the PTAnnotStyle will operate on the default style properties for that annotation type. (The default style properties are the ones that are used when a new annotation of that type is created.)

To hide the annotation style view controller programmatically, call dismissViewControllerAnimated:completion on either the presenting view controller or the annotation view controller itself.

To present the annotation style view controller in a popover, you should provide its presentation manager either:

• a sourceRect AND
• a sourceView

OR

• a barButtonItem

This will define the anchor point of the popover view. See the code sample above for an example of how to do this using an annotation's rect as the sourceRect, and the PDFViewCtrl as the sourceView.

The annotation view controller does not commit the annotation style changes back to the annotation unless explicitly told to do so. To commit the annotation style changes, implement the annotStyleViewController:didCommitStyle: and/or annotStyleViewController:didChangeStyle: methods of the AnnotStyleViewControllerDelegate protocol:

1func annotStyleViewController(_ annotStyleViewController: PTAnnotStyleViewController,
2                              didChange annotStyle: PTAnnotStyle) {
3    self.saveAnnotStyleChanges(annotStyle)
4}
5
6func annotStyleViewController(_ annotStyleViewController: PTAnnotStyleViewController,
7                              didCommit annotStyle: PTAnnotStyle) {
8    self.saveAnnotStyleChanges(annotStyle)
9    
10    annotStyleViewController.dismiss(animated: true, completion: nil)
11}

1- (void)annotStyleViewController:(PTAnnotStyleViewController *)annotStyleViewController
2                  didChangeStyle:(PTAnnotStyle *)annotStyle {
3    [self saveAnnotStyleChanges:annotStyle];
4}
5
6- (void)annotStyleViewController:(PTAnnotStyleViewController *)annotStyleViewController
7                  didCommitStyle:(PTAnnotStyle *)annotStyle {
8    [self saveAnnotStyleChanges:annotStyle];
9
10    [annotStyleViewController dismissViewControllerAnimated:YES completion:nil];
11}

The annotStyleViewController:didCommitStyle: method is called when the annotation style view controller is dismissed either by the user pressing the 'Done' button or de-selecting the current annotation. The optional annotStyleViewController:didChangeStyle: method is called immediately after any annotation style property is changed by the user. For slider-controlled properties (thickness, opacity, etc.), an event notifying of the change is triggered when the user releases the slider control.

The saveAnnotStyleChanges: helper method used above can be defined as follows:

1func saveAnnotStyleChanges(_ annotStyle: PTAnnotStyle) {
2    // Ensure annotation being edited is still valid.
3    guard self.currentAnnotation == annotStyle.annot,
4        self.currentAnnotation.isValid() else {
5        return;
6    }
7    
8    do {
9        try PTPDFNet.catchException {
10            self.pdfViewCtrl.docLock(true)
11            
12            annotStyle.saveChanges()
13            
14            self.currentAnnotation.refreshAppearance()
15            
16            self.pdfViewCtrl.update(with: self.currentAnnotation,
17                                    page_num: Int32(self.annotationPageNumber))
18            
19            // Optional: Save the style properties as the default for this annotation type.
20            annotStyle.setCurrentValuesAsDefaults()
21        }
22        defer {
23            self.pdfViewCtrl.docUnlock()
24        }
25    } catch let e as NSError {
26        print("Exception: \(e)", e)
27    }
28    
29    // Notify current Tool of change.
30    self.currentTool.annotationModified(self.currentAnnotation,
31                                        onPageNumber: UInt(self.annotationPageNumber))
32}

1- (void)saveAnnotStyleChanges:(PTAnnotStyle *)annotStyle {
2    // Ensure annotation being edited is still valid.
3    if (self.currentAnnotation != annotStyle.annot || ![annotStyle.annot IsValid]) {
4        return;
5    }
6
7    @try
8    {
9        [self.pdfViewCtrl DocLock:YES];
10        
11        [annotStyle saveChanges];
12        
13        [self.currentAnnotation RefreshAppearance];
14        
15        [self.pdfViewCtrl UpdateWithAnnot:self.currentAnnotation
16                                 page_num:self.annotationPageNumber];
17        
18        // Optional: Save the style properties as the default for this annotation type.
19        [annotStyle setCurrentValuesAsDefaults];
20    }
21    @catch (NSException *exception) {
22        NSLog(@"Exception: %@: %@", exception.name, exception.reason);
23    }
24    @finally {
25        [self.pdfViewCtrl DocUnlock];
26    }
27
28    // Notify current Tool of change.
29    [self.currentTool annotationModified:self.currentAnnotation
30                            onPageNumber:self.annotationPageNumber];
31}

The call to setCurrentValuesAsDefaults in the code above is not necessary if the saveValuesAsDefaults property (enabled by default) is set, as in this case saveChanges will automatically save the style as the new default style.

The sequence of document locking and annotation updates shown here is used throughout the Tools framework. For more information on document locking please see the dedicated guide .