Customize the document viewer

Document viewers can be configured to suit your needs with ease.

Android

Customize document viewer in Xamarin.Android

This tutorial only applies to Xamarin.Android.

DocumentActivity and PdfViewCtrlTabHostFragment2 are highly configurable and can be easily customized using our document viewer configuration classes. UI components can be hidden and functionality can be disabled by initializing the document viewer using ViewerConfig.Builder.

For further customization, PDFViewCtrlConfig allows you to initialize PDFViewCtrl with low-level viewer settings, and ToolManagerBuilder allows you to customize annotation functionality in ToolManager.

Configure Document Viewer

DocumentActivity and PdfViewCtrlTabHostFragment2 can be initialized using ViewerConfig, which can be created with a ViewerConfig.Builder object.

For example:

// Customize settings in ViewerConfig
var config = new ViewerConfig.Builder()
    .FullscreenModeEnabled(true)
    .MultiTabEnabled(true)
    .DocumentEditingEnabled(true)
    .LongPressQuickMenuEnabled(true)
    .ShowPageNumberIndicator(true)
    .ShowBottomNavBar(true)
    .ShowThumbnailView(true)
    .ShowBookmarksView(true)
    .ToolbarTitle("My Reader")
    .ShowSearchView(true)
    .ShowShareOption(true)
    .ShowDocumentSettingsOption(true)
    .ShowAnnotationToolbarOption(true)
    .ShowOpenFileOption(true)
    .ShowOpenUrlOption(true)
    .ShowEditPagesOption(true)
    .ShowPrintOption(true)
    .ShowCloseTabOption(true)
    .ShowAnnotationsList(true)
    .ShowOutlineList(true)
    .ShowUserBookmarksList(true)
    .Build();
    
// Initialize your document viewer with a 
// a ViewerConfig when you open a document
DocumentActivity.OpenDocument(context, localFilePath, config)

A full list of settings for ViewerConfig.Builder can be found in the API documentation.

Configure PDFViewCtrl

PDFViewCtrl specific functionality can be configured using PDFViewCtrlConfig. You can then pass the configuration to ViewerConfig to initialize PDFViewCtrl in your document viewer with your specific settings.

For example:

// Customize settings in PDFViewCtrlConfig
var pdfViewCtrlConfig = PDFViewCtrlConfig.GetDefaultConfig(this)
    .SetClientBackgroundColor(Android.Graphics.Color.Yellow)
    .SetClientBackgroundColorDark(Android.Graphics.Color.Blue)
    .SetHighlightFields(true)
    .SetImageSmoothing(true)
    .SetUrlExtraction(true)
    .SetMaintainZoomEnabled(true);

// Pass the PDFViewCtrlConfig into your ViewerConfig
// so that it can be used to initialize PDFViewCtrl 
// in your document viewer
var builder = new ViewerConfig.Builder();
var config = builder
    .PdfViewCtrlConfig(pdfViewCtrlConfig)
    // ...
    .Build();

A full list of settings for PDFViewCtrlConfig can be found in the API documentation.

Configure ToolManager

Annotation tool functionality can be configured using ToolManagerBuilder, such as hiding/disabling specific annotation creation tools or disabling the quick menu. You can then pass the configuration to ViewerConfig to initialize ToolManager in your document viewer with your specific settings. Alternatively, you can also modify the style resource for ToolManager directly, and pass it to ViewerConfig.

• Configure ToolManager by setting ToolManagerBuilder to an instance of ViewerConfig:A full list of settings for ToolManagerBuilder can be found in the API documentation.

// Customize settings in ToolManagerBuilder
var toolManagerBuilder = ToolManagerBuilder.From()
    .SetEditFreeTextOnTap(false)
    .SetDisableQuickMenu(true);

// Pass the ToolManagerBuilder into your ViewerConfig
// so that it can be used to initialize ToolManager 
// in your document viewer
var builder = new ViewerConfig.Builder();
var config = builder
    .ToolManagerBuilder(toolManagerBuilder)
    // ...
    .Build();

• Configure ToolManager by setting an XML style resource:Defining a style for ToolManager is explained in detail in the ToolManager configuration guide .

// Pass the XML style resource R.style.MyToolManager to ViewerConfig
var builder = new ViewerConfig.Builder();
var config = builder
    .ToolManagerBuilderStyleRes(Resource.Style.MyToolManager)
    // ...
    .Build();

iOS

Customize document viewer in Xamarin.iOS

This document refers to the PTDocumentController

For the legacy PTDocumentViewController class, please see this guide .

This article explains how to customize the document viewer classes PTDocumentController 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.

PTDocumentController

Regular

The above image (items 1–5) indicates areas that are controllable via the PTDocumentController's API. Information on customizing these is available directly below.

The above image (items 7–12) 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.

Compact

The image on the left (items 1–6) indicates areas that are controllable via the PTDocumentController's API. Information on customizing these is available directly below.

The image on the right (items 7–12) 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.

On iPad and other regular horizontal size class devices, a number of default UI controls are accessible from the navigation bar, whereas on iPhones and compact size classes some of those controls appear in the toolbar at the bottom of the view.

Image Number	Button	Functionality	Location on iPad	Location on iPhone
7	searchButtonItem	PTTextSearchViewController	navigationItem.rightBarButtonItems	navigationItem.rightBarButtonItems
8	moreItemsButtonItem	PTMoreItemsViewController	navigationItem.rightBarButtonItems	navigationItem.rightBarButtonItems
10	navigationListsButtonItem	PTNavigationListsViewController	navigationItem.leftBarButtonItems	toolbar
11	thumbnailsButtonItem	PTThumbnailsViewController	navigationItem.leftBarButtonItems	toolbar
12	readerModeButtonItem	PTReflowViewController	navigationItem.rightBarButtonItems	toolbar

1: Toolbar switcher

Hide the toolbar switcher

The toolbar switcher can be hidden:

documentController.ToolGroupIndicatorView.Hidden = true;

Remove toolbars from the switcher

Toolbars can be removed by removing them from the toolGroupManager's groups array. The following code removes the "Draw" and "Pens" toolbars:

var mutableGroups = documentController.ToolGroupManager.Groups;
var groupsToRemove = new List<PTToolGroup> { documentController.ToolGroupManager.DrawItemGroup, documentController.ToolGroupManager.PensItemGroup};
documentController.ToolGroupManager.Groups = mutableGroups.Except(groupsToRemove).ToArray();

2: Navigation bar items

The buttons which are contained in the leftBarButtonItems and rightBarButtonItems arrays, are completely customizable. It is possible to

• Add buttons
• Remove (hide) buttons
• Move buttons
• Change icons

Add buttons

You can modify the navigation bar items. Here is an example of adding a new button (for the current size class):

var myItem = new UIBarButtonItem(UIImage.GetSystemImage("square.and.pencil"), UIBarButtonItemStyle.Plain, (sender, e) =>
{
    Console.WriteLine("button pressed:" + sender);
});

var currentItems = documentController.NavigationItem.RightBarButtonItems;
var itemsArray = new List<UIBarButtonItem>(currentItems);
itemsArray.Add(myItem);

documentController.NavigationItem.RightBarButtonItems = itemsArray.ToArray();

Tools can also be added:

var freeHand = documentController.ToolGroupManager.CreateItemForToolClass(new ObjCRuntime.Class(typeof(PTFreeHandCreate)));

var currentItems = documentController.NavigationItem.RightBarButtonItems;
var itemsArray = new List<UIBarButtonItem>(currentItems);
itemsArray.Add(freeHand);

documentController.NavigationItem.RightBarButtonItems = itemsArray.ToArray();

Note that in the example above, de-selecting the tool button item needs to be implemented by the app, by listening to the Tool Did Change notification.

Remove buttons

To remove any of the default buttons see the instructions here: Hide default buttons

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:

var rightItems = documentViewController.NavigationItem.RightBarButtonItems;
var rightItemsList = new List<UIBarButtonItem>(rightItems);
rightItemsList.Remove(documentViewController.SearchButtonItem);
rightItemsList.Add(documentViewController.NavigationListsButtonItem);

var bottomRightItems = documentViewController.ThumbnailSliderController.TrailingToolbarItems;
var bottomRightItemsList = new List<UIBarButtonItem>(bottomRightItems);
bottomRightItemsList.Remove(documentViewController.NavigationListsButtonItem);
bottomRightItemsList.Add(documentViewController.SearchButtonItem);

documentViewController.NavigationItem.RightBarButtonItems = rightItemsList.ToArray();
documentViewController.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:

// new search UIBarButtonItem
var newSearchItem = new UIBarButtonItem(UIBarButtonSystemItem.Search, documentController.SearchButtonItem.Target, documentController.SearchButtonItem.Action);
index = rightItemsList.IndexOf(documentController.SearchButtonItem);
rightItemsList.Remove(documentController.SearchButtonItem);
rightItemsList.Insert(index, newSearchItem);

// update the icons
documentController.NavigationItem.RightBarButtonItems = rightItemsList.ToArray();

3: Annotation toolbar

The currently-visible annotation toolbar is selected with the toolbar switcher.

Hide (and show) the annotation toolbar

The toolbar can be programmatically hidden by setting the mode to view group, which is a special group and the only group where the toolbar is hidden:

documentController.ToolGroupManager.SelectedGroup = documentController.ToolGroupManager.ViewItemGroup;

The toolbar can be shown again by changing the group to any group other than view:

documentController.ToolGroupManager.SelectedGroup = documentController.ToolGroupManager.DrawItemGroup;

Remove buttons from a toolbar

The example below shows how to remove the text highlight and text underline button from a toolbar.

Disabling a tool type entirely

If you want to disable a tool entirely, from all toolbars and the long press menu, please use the annotations permissions system.

var annotateGroup = documentController.ToolGroupManager.AnnotateItemGroup;

// tool buttons that exist currently
var defaultAnnotateGroupTools = annotateGroup.BarButtonItems;

// new set of tools to replace current ones
var newAnnotateGroupTools = new List<UIBarButtonItem>();

// add all currently existing tools except for the ones we don't want            
foreach (UIBarButtonItem defaultToolItem in defaultAnnotateGroupTools)
{
    if (defaultToolItem.IsKindOfClass(new ObjCRuntime.Class(typeof(PTToolBarButtonItem)))) {
        var toolBarButton = (PTToolBarButtonItem)defaultToolItem;
        if ( toolBarButton.ToolClass.Equals(new ObjCRuntime.Class(typeof(PTTextHighlightCreate))) ||
                toolBarButton.ToolClass.Equals(new ObjCRuntime.Class(typeof(PTTextUnderlineCreate))) )
        {
            // do not add this tool
            continue;
        }
        else
        {
            newAnnotateGroupTools.Add(toolBarButton);
        }
    }
    else
    {
        newAnnotateGroupTools.Add(defaultToolItem);
    }
}
// assign tools to new array
documentController.ToolGroupManager.AnnotateItemGroup.BarButtonItems = newAnnotateGroupTools.ToArray();

Add a tool button to a toolbar

// create a mutable array of the current items in the annotation toolbar group
var availableTools = new List<UIBarButtonItem>(documentController.ToolGroupManager.AnnotateItemGroup.BarButtonItems);

// create a new toolbar item for freehand annotations
var freeHandItem = documentController.ToolGroupManager.CreateItemForToolClass(new ObjCRuntime.Class(typeof(PTFreeHandCreate)));

// add the freehand annotation item to the front of the list
availableTools.Insert(0, freeHandItem);

// assign the array back to the annotation toolbar group.
documentController.ToolGroupManager.AnnotateItemGroup.BarButtonItems = availableTools.ToArray();

4: Page number indicator

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

5: 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.

6. Toolbar (iPhone only)

These are the buttons that appear at the bottom of the screen on iPhones and in Compact horizontal size classes. Buttons can be added, removed, or rearranged with convenient APIs.

Add buttons to toolbar

Remove buttons from toolbar

To remove any of the default buttons see the instructions here: Hide default buttons

7-12: Controls Presented by a PTDocumentController

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

Image number	Control
7	PTTextSearchViewController
8	PTMoreItemsViewController
9	PTPageIndicatorViewController
10	PTNavigationListsViewController
11	PTThumbnailsViewController
12	PTReflowViewController

Hide default buttons

Default buttons can be removed ("hidden") using built-in properties.

• searchButtonHidden
• moreItemsButtonHidden
• navigationListsButtonHidden
• thumbnailBrowserButtonHidden
• readerModeButtonHidden

For example to hide the search and more items buttons:

documentController.SearchButtonHidden = true;
documentController.MoreItemsButtonHidden = true;

PTTabbedDocumentViewController

The tabbed document view controller displays a collection of document 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 PTDocumentControllers

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

To configure a document 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.

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

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.