Customizing the Toolbar

By default, PSPDFKit works with UINavigationController to show the UINavigationBar as the toolbar. You can use regular UIBarButtonItem objects to populate the navigation bar or the (bottom) view controller toolbar.

Since PSPDFKit uses custom toolbar logic (for example, when the thumbnails are displayed, we hide the annotation bar button item), PDFViewController has a custom navigationItem that you can use to configure the bar button items for different view modes. If you use the leftBarButtonItems and rightBarButtonItems API from UINavigationItem, you will set the items for all view modes. Most likely, this is not what you want. Instead, use setLeftBarButtonItems(_:for:animated:) or the equivalent for the right side and specify the view mode you want to alter with that call.

If the view mode you change is the one that is currently visible, the navigation bar will update to represent these changes.

PSPDFKit provides several custom bar button items for the most common features:

Property Description
closeButtonItem Closes the PDFViewController if pushed modally. Default entry in leftBarButtonItems.
outlineButtonItem Presents the OutlineViewController if there is an outline defined in the PDF. Default entry in rightBarButtonItems.
searchButtonItem Shows the SearchViewController or the InlineSearchManager for searching text in the current document. See SearchMode in PDFConfiguration to configure this. Default entry in rightBarButtonItems.
thumbnailsButtonItem Toggles between the document and the thumbnail view state. See ViewMode and setViewMode(_:animated:). Default entry in rightBarButtonItems.
documentEditorButtonItem Toggles between the document and the Document Editor view state.
printButtonItem Presents the UIPrintInteractionController for document printing. Only displayed if the document is allowed to be printed. See allowsPrinting in Document. You should use the activityButtonItem instead. Share to UIActivity.ActivityType.PSPDFActivityTypeOpenIn.
openInButtonItem Presents the UIDocumentInteractionController controller to open documents in other apps. You should use the activityButtonItem instead.
emailButtonItem Presents the MFMailComposeViewController to send the document via email. Will only work when sending emails is configured on the device. You should use the activityButtonItem instead. Share to UIActivity.ActivityType.mail.
messageButtonItem Presents the MFMessageComposeViewController to send the document via SMS/iMessage. Will only work if iMessage or SMS is configured on the device. You should use the activityButtonItem instead. Share to UIActivity.ActivityType.message.
annotationButtonItem Shows and hides the AnnotationToolbar toolbar for creating annotations. Requires the Features.annotationEditing feature flag.
bookmarkButtonItem Presents the BookmarkViewController for creating/editing/viewing bookmarks.
brightnessButtonItem Presents the BrightnessViewController to control screen brightness. iOS has a similar feature in the Control Center, but PSPDFKit includes an additional software brightener.
activityButtonItem Presents the UIActivityViewController for various actions, including many of the above button items. You can configure which activities are included and excluded by setting applicationActivities and excludedActivityTypes in DocumentSharingConfiguration.

Positioning Buttons

When setting navigation button items on either the left or the right side, PSPDFKit will check that no item on the left side is already set on the right side and vice versa, and it will throw an assertion if items on one side are also on the other side.

PSPDFKit for iOS distributes the default navigation button items into a corresponding ViewMode as follows:

View Mode Default Right Buttons
.document thumbnailsButtonItem, activityButtonItem, outlineButtonItem, searchButtonItem, annotationButtonItem
.documentEditor thumbnailsButtonItem, documentEditorButtonItem
.thumbnails thumbnailsButtonItem, documentEditorButtonItem

This means that if you ever want to have, for instance, the outlineButton on the left rather than on the right, you first need to modify the buttons set on the right side to remove the outlineButton and then set the left items:

Copy
1
2
3
4
5
6
// First clean up the buttons on the right.
controller.navigationItem.setRightBarButtonItems([], for: .document, animated: false)

// Then set the left buttons.
let leftButtons = [controller.settingsButtonItem, controller.outlineButtonItem]
controller.navigationItem.setLeftBarButtonItems(leftButtons, for: .document, animated: false)
Copy
1
2
3
4
5
6
// First clean up the buttons on the right.
[controller.navigationItem setRightBarButtonItems:@[] forViewMode:PSPDFViewModeDocument animated:NO];

// Then set the left buttons.
NSArray *leftButtons = @[controller.settingsButtonItem, controller.outlineButtonItem];
[controller.navigationItem setLeftBarButtonItems:leftButtons forViewMode:PSPDFViewModeDocument animated:NO];

Customizing Button Appearance

Instead of trying to customize existing bar button items, it’s better to create your own bar button item and connect both target and action from the predefined buttons that we offer to get both the same tap behavior and complete customizability in terms of appearance.

If you want to call your own code before our stock code is invoked, you can set the target/action to your method and then call the stock method of the bar button item. Note that the spec allows for an optional sender parameter on target/action pairs, so to be absolutely correct, you should use a helper like the psc_targetActionBlock that we ship in PSPDFKit Catalog. Our internal methods define a sender parameter, but this is a detail your code should not rely on.

Button Visibility

When document is nil or document.isValid returns NO, most buttons will be disabled and not displayed by default. If you need a button to always be visible, add your bar buttons to the barButtonItemsAlwaysEnabled array. By default, this contains the closeButtonItem.

Changing any of these bar button-related properties will trigger a reload of the gallery.

Hiding the Close Button

The close button, used to dismiss PDFViewController when pushed modally, is added automatically to leftBarButtonItems. If you choose to manage the close behavior yourself, or if you just want to hide the close button, you can set closeBarButtonItem on the PDFViewController’s navigationItem to nil.

Hiding the Toolbar Completely

The navigation toolbar used in the standard configuration of PSPDFKit can be removed via the setNavigationBarHidden(_:animated:) call from the standard UINavigationController that displays the PDFViewController. Since the PDFViewController also has logic to show/hide the HUD, you need to set PDFConfiguration.userInterfaceViewMode to UserInterfaceViewMode.always.

Alternatively, you can subclass the PDFViewController to make sure that the navigation bar is always hidden:

Copy
1
2
3
4
5
override func viewWillLayoutSubviews() {
    super.viewWillLayoutSubviews()

    self.navigationController?.setNavigationBarHidden(true, animated: false)
}
1
2
3
4
5
6
- (void)viewWillLayoutSubviews {
	[super viewWillLayoutSubviews];


	[self.navigationController setNavigationBarHidden:YES animated:NO];
}