Some test text!

platform
search

Show a document in a Fragment

Contents

Prerequisites
Step 1: Update AndroidManifest.xml
Step 2: Launch the viewer
Step 3: Customize the viewer
Step 4: Customize the toolbar menu
Custom toolbar menu
Custom navigation icon
Interact with the fragment
This tutorial only applies to Xamarin.Android.
PdfViewCtrlTabHostFragment requires the full version of the PDFTron library. See PDFTron full or standard?

All actions related to the PDF viewer are handled through the PdfViewCtrlTabHostFragment fragment. This fragment extends android.support.v4.app.Fragment and is responsible for showing documents in tabs.

linkPrerequisites

  • Integrated PDFTron into your project and added the PDFTron.Android.Tools NuGet package into your project.
  • A valid evaluation or commercial license key. If you do not have a license key, please contact sales for a commercial license key or click here to get an evaluation key.
  • Minimum API: 16 (using Android Support Libraries)
  • Recommended target API: 28

linkStep 1: Update AndroidManifest.xml

  1. In order to support all the features in PdfViewCtrlTabHostFragment, we will need to add the Android permissions listed in this table. However if you would like to disable certain features and customize your document viewer, you should leave out unnecessary permissions.
Storage permission
Please note that from Android 6.0 (API 23) and up, applications need to request storage permission at runtime before accessing any files on device.
  1. Enable largeHeap and usesClearTextTraffic:

    <application
      ...
      android:largeHeap="true"
      android:usesCleartextTraffic="true">
    </application>
If your app is targeting Android SDK version 28 or higher, you will need to add the android:usesCleartextTraffic="true" attribute in your application tag.
  1. Define your Activity to extend AppCompatActivity and use an AppCompat theme:

    [Activity(Label = "MyReaderActivity",
      ConfigurationChanges = Android.Content.PM.ConfigChanges.ScreenSize | Android.Content.PM.ConfigChanges.Orientation | Android.Content.PM.ConfigChanges.KeyboardHidden,
      Theme = "@style/CustomAppTheme", 
      WindowSoftInputMode = SoftInput.AdjustPan)]
    public class MyReaderActivity : Android.Support.V7.App.AppCompatActivity
    {
    ...
    }
  1. If you have not done so already, add your license in the AndroidManifest.xml file. The final AndroidManifest.xml file should look something like this:

    <manifest ...>
        <!-- Required permissions are added here -->
        <uses-permission android:name="android.permission.INTERNET"/>
        <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
        <uses-permission android:name="android.permission.RECORD_AUDIO" />
        
        
        <!-- Add license key in meta-data tag here -->
        <meta-data
            android:name="pdftron_license_key"
            android:value="your_license_key_goes_here"/>
        
        <!-- Add enable largeHeap and usesCleartextTraffic -->
        <application 
            ...
            android:largeHeap="true"
            android:usesCleartextTraffic="true">    
            ...
        </application>
    </manifest>

linkStep 2: Launch the viewer

Displaying the PdfViewCtrlTabHostFragment in an activity is straightforward. Like any other fragment you should make an instance of the class and attach it to the activity. To create an instance of the host fragment you need to pass in a bundle that can be created using createBasicPdfViewCtrlTabBundle. The bundle specifies the document that should be shown when the host fragment is visible. For example, to open a document in the host fragment when you know the URI of the file (and its password if the file is password protected) you can call:

var args = PdfViewCtrlTabFragment.CreateBasicPdfViewCtrlTabBundle(this, fileUri, password);
var pdfViewCtrlTabHostFragment = PdfViewCtrlTabHostFragment.NewInstance(args);
Android.Support.V4.App.FragmentTransaction ft = this.SupportFragmentManager.BeginTransaction();
ft.Replace(Resource.Id.container, pdfViewCtrlTabHostFragment, null);
ft.Commit();

You can simply convert a file to a URI by:

var file = ...
var fileUri = Android.Net.Uri.FromFile(file);

Since PDFTron uses the Fragment class from the Support Library, your activity must extend FragmentActivity and call getSupportFragmentManager() to get the FragmentManager.

linkStep 3: (Optional) Customize the viewer

  • If you would like to customize the appearance of the viewer activity, define CustomAppTheme in styles.xml:

    <style name="CustomAppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
      <item name="colorPrimary">@color/app_color_primary_day</item>
      <item name="colorPrimaryDark">@color/app_color_primary_dark_day</item>
      <item name="colorAccent">@color/app_color_accent</item>
      <!-- Action bar -->
      <item name="actionModeBackground">?attr/colorPrimary</item>
      <item name="windowActionModeOverlay">true</item>
    </style>
    PdfViewCtrlTabHostFragment uses the AppCompat theme for material colors. Make sure that the value of android:theme in your activity tag also extends the AppCompat theme.
  • If you would like to customize the UI of PdfViewCtrlTabHostFragment, you can use ViewerConfig.Builder builder. For example:

    var builder = new pdftron.PDF.Config.ViewerConfig.Builder();
    var config = builder
      .FullscreenModeEnabled(true)
      .MultiTabEnabled(true)
      .DocumentEditingEnabled(true)
      .LongPressQuickMenuEnabled(true)
      .ToolbarTitle("Host Fragment")
      .ShowSearchView(true)
      .Build();
    
    var args = PdfViewCtrlTabFragment.CreateBasicPdfViewCtrlTabBundle(this, fileUri, password, viewerConfig);
    args.PutParcelable(PdfViewCtrlTabHostFragment.BundleTabHostConfig, viewerConfig);
    var pdfViewCtrlTabHostFragment = PdfViewCtrlTabHostFragment.NewInstance(args);

    For details on customizing the UI and using ViewerConfig.Builder, check out the configuration tutorial.

linkStep 4: (Optional) Customize the toolbar menu

The default toolbar menu consists of the following items:

  • App navigation
  • Document text search
  • Document sharing
  • View Mode configuration
  • Showing/hiding annotation toolbar
  • Overflow menu

You can fully customize and control the toolbar menu as well as the navigation icon.

linkCustom toolbar menu

In order to change the default toolbar menu items you need to create your own menu in menu resource folder and pass it to the host fragment through bundle:

args.PutInt(PdfViewCtrlTabHostFragment.BundleTabHostToolbarMenu, Resource.Menu.fragment_viewer_simple);

linkCustom navigation icon

To change the navigation icon, similar to the toolbar menu, you need to pass the desired icon to the host fragment through the bundle:

args.PutInt(PdfViewCtrlTabHostFragment.BundleTabHostNavIcon, Resource.Drawable.ic_arrow_back_white_24dp);

linkInteract with the fragment

If you want to interact with the host fragment you can override the methods that you are interested in through events. For example, you may want to override ToolbarOptionsItemSelected when you add a new menu item, so when the item is clicked you can get a callback. As another example, you can get the callback when the navigation icon is clicked if you override NavButtonPressed.

Here's an example that replaces the default navigation icon, and only keeps the annotation toolbar icon in the toolbar menu while adding a new menu item to show a toast when selected:

args.PutInt(PdfViewCtrlTabHostFragment.BundleTabHostNavIcon, Resource.Drawable.ic_arrow_back_white_24dp);
args.PutInt(PdfViewCtrlTabHostFragment.BundleTabHostToolbarMenu, Resource.Menu.fragment_viewer_simple);
var pdfViewCtrlTabHostFragment = PdfViewCtrlTabHostFragment.NewInstance(args);

pdfViewCtrlTabHostFragment.ToolbarOptionsItemSelected += (sender, e) =>
{
    // called when toolbar option item is selected
};
pdfViewCtrlTabHostFragment.NavButtonPressed += (sender, e) =>
{
    // called when navigation button has been clicked
}

The fragment_viewer_simple.xml should be placed in menu resource folder and contain:

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <item
        android:id="@+id/action_annotation_toolbar"
        android:icon="@drawable/ic_mode_edit_white"
        android:title="@string/action_annotation_toolbar"
        app:showAsAction="ifRoom"/>
    <item
        android:id="@+id/action_show_toast"
        android:title="Show toast"
        app:showAsAction="never" />
</menu>

With this complete, you will see:

Get the anwsers you need: Support

Contents

Prerequisites
Step 1: Update AndroidManifest.xml
Step 2: Launch the viewer
Step 3: Customize the viewer
Step 4: Customize the toolbar menu
Custom toolbar menu
Custom navigation icon
Interact with the fragment