Customizing the Toolbar in Our visionOS PDF Viewer

On visionOS, Nutrient’s main toolbar is, by default, added as an ornament anchored to the top of the window containing PDFViewController. This is in contrast to iOS and macOS, where Nutrient’s main toolbar buttons are inside the app window in a navigation bar.

Using ornaments

The new system feature of ornaments in visionOS enables us to expand our user interface (UI) outside the scope of a window, making it easier to show auxiliary content when compared to other Apple platforms. This enables us to move the toolbar items to ornaments, compared to the traditional navigation bar. In turn, this makes the main content area, where the PDF page is displayed, free of clutter, allowing users to focus on the actual content.

With a new API designed for Swift, the toolbar is completely configurable and allows you to add custom items to it as well.

Customizing the toolbar

The new toolbar makes use of a new OrnamentItem API that has been specifically designed for this purpose. The default ornament items provided by Nutrient can be found on PDFViewController (similar to our longstanding bar button item API for iOS and Mac Catalyst).

let controller = PDFViewController(document: ...)

// Specifying a set of ornament items for the document view mode.
controller.setMainToolbarOrnamentItems([
controller.backOrnamentItem,
controller.titleOrnamentItem,
OrnamentItem(kind: .divider),
controller.contentEditingOrnamentItem,
controller.annotationToolsOrnamentItem
], for: .document)

// Ornament items for the content editing view mode.
controller.setMainToolbarOrnamentItems([
controller.backOrnamentItem,
controller.titleOrnamentItem,
OrnamentItem(kind: .divider),
controller.contentEditingOrnamentItem,
], for: .contentEditing)

The order of the ornament items in the array determines the position in the toolbar. You’ll have to manually add backOrnamentItem and titleOrnamentItem if you want to display the back button and the title, respectively, on your toolbar.

Adding custom items to the toolbar

Create custom toolbar items using the OrnamentItem(kind:) API. This API allows you to add three kinds of items defined with OrnamentItem.Kind:

• Button — To add a custom button, use OrnamentItem.Kind.button. This enum case has an associated value of type ButtonConfiguration, which you should use to specify the button title, image, and action.

let customItem = OrnamentItem(kind: .button(configuration: .init(title: "Custom Item Title", image: UIImage(named: "customImage"),
     action: { sender in
     // Perform custom action here on ornament item tap.
}, showTitle: true, isHighlightable: true)))

• Title — Use OrnamentItem.Kind.title to add title text to the toolbar.

let customTitleItem = OrnamentItem(kind: .title(provider: { getMyCustomTitle() }))

• Divider — This item can be created using OrnamentItem.Kind.divider, which adds a horizontal divider between two items. This is useful for creating a visible segregation between different kinds of items.

All the above custom items can be added to the toolbar using the PDFViewController.setMainToolbarOrnamentItems(_ items: [OrnamentItem], for viewMode: ViewMode) API.

Showing an ornament when PDFViewController is a child view controller

PDFViewController displays the main toolbar, annotation toolbar, and scrubber bar as ornaments. Ornaments have to be added to the ornaments(opens in a new tab) property on the UIViewController when using UIKit.

PDFViewController ornaments, if specified, will automatically be displayed along with the ornaments of their parent view controller, as this is the default system behavior.

Displaying main toolbar buttons in the navigation bar

Use PDFConfiguration.mainToolbarMode to set the kind of the main toolbar on visionOS. Nutrient defaults to PDFConfiguration.MainToolbarMode.ornament, where the toolbar is added as an ornament. To show the main toolbar buttons in a navigation bar, set the mainToolbarMode property to .navigationBar.

let pdfController = PDFViewController(document: ...) {
    // Displays the main toolbar as a navigation bar.
    $0.mainToolbarMode = .navigationBar
}