Section:

Customize a document view controller in Xamarin

Legacy Viewer

This guide is for the legacy PTDocumentViewController class. This class is no longer being updated. For the best viewing experience and to take advantage of new developments, the PTDocumentController should be used. Please see this guide for information.

This article explains how to customize the document viewer classes PTDocumentViewController and PTTabbedDocumentViewController.

Because the document viewer classes are part of the open source Tools UI framework, it is possible to achieve virtually any required modification. That said, it is usually faster and more convenient to configure the viewers via APIs, which this guide describes.

PTDocumentViewController

Apryse Docs Image

The image on the left indicates areas that are controllable via the PTDocumentViewController's API. Information on customizing these is available directly below.

The image on the right indicates a number of default buttons that create and present new controls. Information on where to look to customize these presented controls can be found in the component controls table.

1: Left bar button item

When presented in a UINavigationController, the PTDocumentViewController's left bar button item will display the name of the previous view controller's navigation item's title (or, if set, its backBarButtonItem). When presented as a UINavigationController's root controller, the space will be empty.

The PTDocumentViewController's left bar button item can be added or replaced as follows:

C#

1var title = "Apryse";
2tabViewController.NavigationItem.LeftBarButtonItem = new UIBarButtonItem(title, UIBarButtonItemStyle.Plain, (sender, e) => {
3    // handle bar button item action
4});

2: Right bar button items

These buttons, which are contained in the rightBarButtonItems array, are completely customizable. It is possible to

Remove buttons

Default buttons can be removed ("hidden") using built-in properties. From left-to-right:

For example to hide the share and viewer settings buttons:

C#

1documentViewController.ShareButtonHidden = true;
2documentViewController.ViewerSettingsButtonHidden = true;

Add buttons

Buttons can be added by accessing the appropriate BarButtonItem array and adding a button:

Adds a button to the top navigation bar:

C#

1// add a button to the top bar
2var plusButtonTop = new UIBarButtonItem(UIBarButtonSystemItem.Add, (sender, e) =>
3{
4    Console.WriteLine("button pressed:" + sender);
5});
6
7var currentItems = documentViewController.NavigationItem.RightBarButtonItems;
8var itemsArray = new List<UIBarButtonItem>(currentItems);
9itemsArray.Add(plusButtonTop);
10
11documentViewController.NavigationItem.RightBarButtonItems = itemsArray.ToArray();
12
13// add a button to the right of the page slider
14var refreshButtonBottom = new UIBarButtonItem(UIBarButtonSystemItem.Refresh,(sender, e) => 
15{
16    Console.WriteLine("button pressed:" + sender);
17});
18
19currentItems = documentViewController.ThumbnailSliderController.TrailingToolbarItems;
20itemsArray = new List<UIBarButtonItem>(currentItems);
21itemsArray.Add(refreshButtonBottom);
22
23documentViewController.ThumbnailSliderController.TrailingToolbarItems = itemsArray.ToArray();

Move buttons

The default buttons are all accessible via properties, making it easy to rearrange or move them. The following code swaps the position of the search button and navigation lists button:

C#

1var rightItems = documentViewController.NavigationItem.RightBarButtonItems;
2var rightItemsList = new List<UIBarButtonItem>(rightItems);
3rightItemsList.Remove(documentViewController.SearchButtonItem);
4rightItemsList.Add(documentViewController.NavigationListsButtonItem);
5
6var bottomRightItems = documentViewController.ThumbnailSliderController.TrailingToolbarItems;
7var bottomRightItemsList = new List<UIBarButtonItem>(bottomRightItems);
8bottomRightItemsList.Remove(documentViewController.NavigationListsButtonItem);
9bottomRightItemsList.Add(documentViewController.SearchButtonItem);
10
11documentViewController.NavigationItem.RightBarButtonItems = rightItemsList.ToArray();
12documentViewController.ThumbnailSliderController.TrailingToolbarItems = bottomRightItemsList.ToArray();

Change icons

The icons of existing buttons may be changed by creating new UIBarButtonItems that have the same target and action as an existing item, and replacing the existing item with the new item:

C#

1// new share UIBarButtonItem
2var newShareItem = new UIBarButtonItem(UIBarButtonSystemItem.Action, documentViewController.ShareButtonItem.Target, documentViewController.ShareButtonItem.Action);
3var rightItems = documentViewController.NavigationItem.RightBarButtonItems;
4var rightItemsList = new List<UIBarButtonItem>(rightItems);
5var index = rightItemsList.IndexOf(documentViewController.ShareButtonItem);
6rightItemsList.Remove(documentViewController.ShareButtonItem);
7rightItemsList.Insert(index, newShareItem);
8
9// new search UIBarButtonItem
10var newSearchItem = new UIBarButtonItem(UIBarButtonSystemItem.Search, documentViewController.SearchButtonItem.Target, documentViewController.SearchButtonItem.Action);
11index = rightItemsList.IndexOf(documentViewController.SearchButtonItem);
12rightItemsList.Remove(documentViewController.SearchButtonItem);
13rightItemsList.Insert(index, newSearchItem);
14
15// update the icons
16documentViewController.NavigationItem.RightBarButtonItems = rightItemsList.ToArray();

3: PDFViewCtrl

The PTPDFViewCtrl is a UIView that displays the PDF. It is customizable via is properties/methods and delegate methods.

For an overview see the PTPDFViewCtrl Guide , or the detailed API documentation.

Note that all PDF "interaction" (annotations, form filling, text selection, link following, etc.) is supplementary to the PDFViewCtrl, and is implemented in the open source tools.framework.

4: Page number indicator

The page indicator can be enabled/disabled via the pageIndicatorEnabled property.

5: Thumbnail slider controller

The thumbnail slider can be enabled/disabled via the bottomToolbarEnabled property.

The default buttons presented to the right and left of the slider are easily hidden through the convenience properties thumbnailBrowserButtonHidden and navigationListsButtonHidden on the PTDocumentViewController:

C#

1documentViewController.ThumbnailBrowserButtonHidden = true;

6-12: Controls Presented by a PTDocumentViewController

To customize the controls that are presented by the PTDocumentViewController's default buttons, please see the corresponding guide or API:

Image number

Control

6

PTTextSearchViewController

7

UIDocumentInteractionController

8

PTSettingsViewController

9

PTAnnotationToolbar

10

PTPageIndicatorViewController

11

PTThumbnailSliderViewController

12

PTNavigationListsViewController

PTTabbedDocumentViewController

The tabbed document view controller displays a collection of document viewer controllers in tabs.

Tab Settings

Tabs can be disabled using the TabsEnabled property, and the maximum number of allowed tabs can be set using MaximumTabCount.

Access to child PTDocumentViewControllers

The current document view controller can be accessed via SelectedViewController, and others via documentViewControllerAtIndex

To configure a document view controller before it is displayed, conform to and implement the PTTabbedDocumentViewControllerDelegate method willAddDocumentViewController. Note that it is permissible to assign the internal PTDocumentViewController's delegate to an external object.

C#

1tabbedDocumentViewController.WillAddDocumentViewController += (sender, e) =>
2{
3    // do something with e.DocumentViewController
4};

Summary

API

Functionality

TabsEnabled

Enables/disables tabs.

MaximumTabCount

Controls the maximum number of concurrent tabs.

SelectedViewController

The current PTDocumentViewController.

documentViewControllerAtIndex

The PTDocumentViewController at the given index.

willAddDocumentViewController

Access to a PTDocumentViewController that is about to be displayed.

Did you find this helpful?

Trial setup questions?

Ask experts on Discord

Need other help?

Contact Support

Pricing or product questions?

Contact Sales