Open a document (Android)

You have a few options to open a document such as with an activity, fragment, or view. A diagram of the overall view hierarchy can be found here: View hierarchy.

Activity

Show a document in an Activity

This tutorial only applies to Xamarin.Android.

Apryse's Android SDK ships with DocumentActivity, an all-in-one document reader and PDF editor. In addition to PDF files, it also supports viewing other file formats such as .docx, .doc, .pptx, .xlsx, .md, .cbz and various image formats. In this activity you can also read, annotate, sign, fill in PDF forms and more.

DocumentActivity extends Android's AppCompatActivity and follows Material design guidelines.

Prerequisites

• Integrated Apryse into your project and added the PDFTron.Android.Tools NuGet package into your project.

• Minimum API: 21 (using AndroidX)

• Compile API: 35

• Recommended target API: 35

License Key Required

The trial of Apryse SDK requires a trial license key, which is provided in the box titled "License Key". A commercial license key is required for use in a production environment. Please contact sales to purchase a commercial key or if you need any other license key assistance.

Keep your license keys confidential.

License keys are uniquely generated. Please make sure that it is not publicly available (e.g. in your public GitHub).

Step 1: Update AndroidManifest.xml

1. In order to support all the features in DocumentActivity, 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:

<application ... android:largeHeap="true" android:usesCleartextTraffic="false">
</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 to open HTTP files in the viewer. If you are only working with HTTPS files, this is not required.

1. If you have not done so already, add your license in the AndroidManifest.xml file, and also declare DocumentActivity in the manifest 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.RECORD_AUDIO" />
    <!-- Add enable largeHeap -->
    <application ... android:largeHeap="true" android:usesCleartextTraffic="false">   
        
        <meta-data android:name="pdftron_license_key" android:value="your_license_key_goes_here"/>

        <!-- Document viewer activity declaration-->
        <activity android:name="com.pdftron.pdf.controls.DocumentActivity" android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize" android:windowSoftInputMode="adjustPan" android:theme="@style/PDFTronAppTheme"/>
        ...
    </application>
</manifest>

Step 2: Launch the viewer

Launch DocumentActivity by specifiying a local file path, an HTTP/HTTPS url, or a Content Uri:

// from internal storage
var uri = Android.Net.Uri.FromFile(new Java.IO.File("myLocalFilePath"));
// from content uri
var uri = Android.Net.Uri.Parse("myContentUri");
// from http/https
var uri = Android.Net.Uri.Parse("myFileLink");
// from assets
var uri = Android.Net.Uri.Parse("file:///android_asset/my_file.pdf");

// intent builder
var intent = DocumentActivity.IntentBuilder.FromActivityClass(this, Java.Lang.Class.FromType(typeof(DocumentActivity)))
    .WithUri(uri)
    .Build();
StartActivity(intent);

Step 3: (Optional) Customize the viewer

• If you would like to customize the appearance of the viewer activity, define PDFTronAppTheme in res/values/styles.xml:You can learn more about this in the customize the viewer's theme guide .

<style name="PDFTronAppTheme" parent="PDFTronAppThemeBase"> <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>

DocumentActivity uses the AppCompat theme for material colors. Make sure that the value of android:theme in your activity tag also extends the AppCompat theme.

• Also, if you would like to customize the UI components in DocumentActivity, you can use ViewerConfig.Builder. For example:For details on customizing the UI and using ViewerConfig.Builder, check out the configuration tutorial .

var builder = new pdftron.PDF.Config.ViewerConfig.Builder();
var config = builder
    .FullscreenModeEnabled(true)
    .MultiTabEnabled(true)
    .DocumentEditingEnabled(true)
    .LongPressQuickMenuEnabled(true)
    .ToolbarTitle("Simple Reader")
    .ShowSearchView(true)
    .Build();

Fragment

Display document in fragment on Android

This tutorial only applies to Xamarin.Android.

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

Prerequisites

• Integrated Apryse into your project and added the PDFTron.Android.Tools NuGet package into your project.

• Minimum API: 21 (using AndroidX)

• Compile API: 35

• Recommended target API: 35

License Key Required

The trial of Apryse SDK requires a trial license key, which is provided in the box titled "License Key". A commercial license key is required for use in a production environment. Please contact sales to purchase a commercial key or if you need any other license key assistance.

Keep your license keys confidential.

License keys are uniquely generated. Please make sure that it is not publicly available (e.g. in your public GitHub).

Step 1: Update AndroidManifest.xml

1. In order to support all the features in PdfViewCtrlTabHostFragment2, 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 to open HTTP files in the viewer. If you are only working with HTTPS files, this is not required.

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/PDFTronAppTheme", WindowSoftInputMode = SoftInput.AdjustPan)]
public class MyReaderActivity : 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.RECORD_AUDIO" />

    <!-- Add enable largeHeap and usesCleartextTraffic -->
    <application ... android:largeHeap="true" android:usesCleartextTraffic="true">    

        <!-- Add license key in meta-data tag here. This should be inside the application tag. -->
        <meta-data android:name="pdftron_license_key" android:value="your_license_key_goes_here"/>

    </application>
</manifest>

Step 2: Launch the viewer

Use ViewerBuilder2 to create an instance of PdfViewCtrlTabHostFragment2, and add it to your activity layout. To add a document viewer fragment for a given password-protected file, call the following method in your activity:

// Add a viewer fragment to the layout container in the specified activity, 
// and returns the added fragment
public PdfViewCtrlTabHostFragment2 addViewerFragment(int fragmentContainer, 
    AppCompatActivity activity, Uri fileUri, String password)
{
    // Create the viewer fragment
    PdfViewCtrlTabHostFragment2 fragment = 
        (PdfViewCtrlTabHostFragment2) ViewerBuilder2.WithUri(fileUri, password).Build(this);

    // Add the fragment to the layout fragment container
    activity.SupportFragmentManager.BeginTransaction()
        .Replace(fragmentContainer, fragment, null)
        .Commit();

    return fragment;
}

where fragmentContainer is the resource id of a layout in your activity that will contain your fragment:

For example:

<?xml version="1.0" encoding="utf-8"?>
<!-- This FrameLayout will contain our viewer fragment-->
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/fragment_container" android:layout_width="match_parent" android:layout_height="match_parent"/>

Alternatively if you have extended PdfViewCtrlTabFragment2 or PdfViewCtrlTabHostFragment2, you can specify your custom classes using the ViewerBuilder2.usingTabClass() method and the ViewerBuilder2.build() method as follows:

// Add a viewer fragment to the layout container in the specified activity, 
// and returns the added fragment
public MyCustomTabHostFragment addViewerFragment(int fragmentContainer, 
    AppCompatActivity activity, Uri fileUri, String password)
{
    // Create the viewer fragment with a custom 
    // PdfViewCtrlTabFragment2 and PdfViewCtrlTabHostFragment2
    PdfViewCtrlTabHostFragment2 fragment = 
        (PdfViewCtrlTabHostFragment2) ViewerBuilder2.WithUri(fileUri, password)
                    .UsingTabClass(Java.Lang.Class.FromType(typeof(MyCustomTabFragment)))
                    .Build(activity, Java.Lang.Class.FromType(typeof(MyCustomTabHostFragment)));

    // Add the fragment to the layout fragment container
    activity.SupportFragmentManager.BeginTransaction()
        .Replace(fragmentContainer, fragment, null)
        .Commit();
        
    return fragment;
}

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

Step 3: Customize the viewer

Customize document viewer style

• If you would like to customize the appearance of the viewer activity, define PDFTronAppTheme in styles.xml:You can learn more about this in the customize the viewer's theme guide .

<style name="PDFTronAppTheme" parent="PDFTronAppThemeBase"> <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>

PdfViewCtrlTabHostFragment2 uses the AppCompat theme for material colors. Make sure that the value of android:theme in your activity tag also extends the AppCompat theme.

Customize using ViewerConfig

• If you would like to customize certain viewer settings or the UI of PdfViewCtrlTabHostFragment2, you can use ViewerConfig.Builder. For example:

public PdfViewCtrlTabHostFragment2 createUsingViewerConfig(Context context, Uri fileUri, String password)
  {
      // Create a ViewerConfig object with custom settings
      var config = new ViewerConfig.Builder()
          .FullscreenModeEnabled(true)
          .MultiTabEnabled(true)
          .DocumentEditingEnabled(true)
          .LongPressQuickMenuEnabled(true)
          .ToolbarTitle("Host Fragment")
          .ShowSearchView(true)
          .Build();

      // Pass in the ViewerConfig object into the ViewerBuilder2
      return (PdfViewCtrlTabHostFragment2) ViewerBuilder2.WithUri(fileUri, password)
          .UsingConfig(config).Build(context);
  }

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

Customize the options toolbar

The default toolbar menu consists of the following buttons on phones:

• App navigation

• Toolbar switcher

• Tab switcher

• Overflow menu

The default toolbar menu consists of the following buttons on tablets:

• App navigation

• Toolbar switcher

• Document text search

• View mode configuration

• Thumbnails browser

• List container

• Overflow menu

You can fully customize the toolbar menu and the navigation icon by calling the following in ViewerBuilder2, with custom menu resource and drawable resource files:

public PdfViewCtrlTabHostFragment2 createUsingCustomToolbar(Context context, Uri fileUri, int navIcon, int[] menuRes)
{
    return ViewerBuilder2.WithUri(fileUri)
            .UsingCustomToolbar(menuRes)// Specify a custom toolbar
            .UsingNavIcon(navIcon)      // Specify a custom navigation component
            .Build(context);
}

To change the icon color and overflow icon color, in styles.xml:

<style name="ToolbarTheme" parent="ThemeOverlay.AppCompat.Dark.ActionBar"> <item name="colorControlNormal">@color/red</item> <item name="iconTint">@color/red</item> </style>

To change the navigation icon color, in styles.xml (assume MyTheme is used as the app theme):

<style name="MyTheme" parent="PDFTronAppTheme"> <item name="toolbarNavigationButtonStyle">@style/ToolbarButtonNavigationStyle</item> </style>

<style name="ToolbarButtonNavigationStyle" parent="Widget.AppCompat.Toolbar.Button.Navigation"> <item name="android:tint">@color/red</item> </style>

Step 4: Interact with the fragment

If you would like 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 uses a custom toolbar:

var PdfViewCtrlTabHostFragment2 =
    (PdfViewCtrlTabHostFragment2) ViewerBuilder2.WithUri(fileUri)
        // Specify a custom toolbar
        .UsingCustomToolbar(new int[] { Resource.Menu.my_custom_toolbar })
        // Specify a custom navigation component
        .UsingNavIcon(Resource.Drawable.ic_arrow_back_white_24dp)      
        .Build(context);

PdfViewCtrlTabHostFragment2.ToolbarOptionsItemSelected += (sender, e) =>
{
    // Called when toolbar option item is selected
};

PdfViewCtrlTabHostFragment2.NavButtonPressed += (sender, e) =>
{
    // Called when navigation button has been clicked
};

where ic_arrow_back_white_24dp.xml is a drawable resource file for a back arrow icon, and my_custom_toolbar.xml is a menu resource file that contains:

<?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_settings" android:icon="@drawable/ic_settings" android:title="@string/action_settings" app:showAsAction="ifRoom"/>
    <item android:id="@+id/action_show_toast" android:title="Show toast" app:showAsAction="never" />
</menu>

This sample replaces the navigation icon, removes all toolbar buttons except the annotation toolbar button, and adds a new Show Toast button:

View

Display PDF using PDFViewCTRL in Android

This tutorial only applies to Xamarin.Android. See Xamarin.iOS equivalent here .

If you are looking for a quick start on displaying documents in your application, please first take a look at Show a document in an Activity or Show a document in a Fragment as they are easier to setup and ready to launch from any activity or fragment. Continue reading this article if you are looking to embed PDFViewCtrl in your own layout.

** Before beginning, make sure the Apryse library is initialized prior to inflating the layout or calling setContentView in your activity.**

PDFViewCtrl is a ViewGroup that can be embedded in any layout. It encapsulates a rich set of functionalities for interactive viewing of PDF documents, including multi-threaded rendering, PDF rendering settings, scrolling, zooming, page navigation, different page viewing modes, coordinates conversion, text selection, text search, etc.

View documents using PDFViewCtrl

In this tutorial you will display a PDF file in your activity by using PDFViewCtrl.

1. In your AndroidManifest.xml, make sure you enable largeHeap in the <application> tag. Also, add a custom theme and set the android:windowSoftInputMode:"adjustPan" attribute in the <activity> tag as follow:

<!-- Include existing attributes in application -->
<application android:name="androidx.multidex.MultiDexApplication" android:largeHeap="true" android:usesCleartextTraffic="false">
    <!-- Include existing attributes in activity -->
    <activity android:windowSoftInputMode="adjustPan" android:theme="@style/PDFTronAppTheme"/>
</application>

If your app is targeting Android SDK version 28 or higher, please also set the android:usesCleartextTraffic="true" attribute in your application tag to open HTTP files in the viewer. If you are only working with HTTPS files, this is not required.

1. If you would like to customize the appearance of the viewer activity, define PDFTronAppTheme for your activity in res/values/styles.xml:You can learn more about this in the customize the viewer's theme guide.

<resources>
<style name="PDFTronAppTheme" parent="PDFTronAppThemeBase"> <item name="colorPrimary">#3F51B5</item> <item name="colorPrimaryDark">#303F9F</item> <item name="colorAccent">#FF4081</item> <!-- Action bar --> <item name="actionModeBackground">?attr/colorPrimary</item> <item name="windowActionModeOverlay">true</item> </style>
</resources>

PDFViewCtrl uses the AppCompat theme for material colors. Make sure that the value of android:theme in your <activity> tag also extends the AppCompat theme.

1. Now, add PDFViewCtrl to your activity's XML layout. For example:

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="match_parent">

    <pdftron.pdf.PDFViewCtrl android:id="@+id/pdfviewctrl" android:layout_width="match_parent" android:layout_height="match_parent" android:scrollbars="vertical|horizontal"/>

</FrameLayout>

1. In your activity, get a reference to PDFViewCtrl after inflating the layout and call AppUtils.SetupPDFViewCtrl.

using pdftron.PDF;
using pdftron.PDF.Config;
using pdftron.PDF.Tools.Utils;

private PDFViewCtrl mPdfViewCtrl;

protected override void OnCreate(Bundle bundle)
{
    base.OnCreate(bundle);
    SetContentView(Resource.Layout.Main);

    mPdfViewCtrl = FindViewById<PDFViewCtrl>(Resource.Id.pdfviewctrl);
    AppUtils.SetupPDFViewCtrl(mPdfViewCtrl);
}

1. Next, choose a document to display by using the following options:Add a sample PDF to src/main/res/raw folder, then call:

View from resource

using pdftron.PDF;
using pdftron.PDF.Config;
using pdftron.PDF.Tools.Utils;
using Android.Net;

private PDFDoc mPdfDoc;

void ViewFromResource(int resourceId, string fileName)
{
    var file = Utils.CopyResourceToLocal(this, resourceId, fileName, ".pdf");
    mPdfDoc = new PDFDoc(file.AbsolutePath);
    mPdfViewCtrl.SetDoc(mPdfDoc);
    // Alternatively, you can open the document using Uri:
    // mPdfDoc = mPdfViewCtrl.OpenPDFUri(Uri.FromFile(file), "");
}

View from local device storage

** Storage Permission **

Please follow the latest Android best practices and guidelines outlined here

Managing lifecycle

It is extremely important that you follow the Android activity/fragment lifecycle and clean up PDFViewCtrl and PDFDoc properly. Make sure you have the following in lifecycle callbacks:

// ...
protected override void OnPause()
{
    base.OnPause();
    mPdfViewCtrl?.Pause();
}

protected override void OnResume()
{
    base.OnResume();
    mPdfViewCtrl?.Resume();
}

protected override void OnDestroy()
{
    base.OnDestroy();
    mPdfViewCtrl?.Destroy();
    mPdfDoc?.Close();
}

Next steps

• Want to annotate on PDF files in PDFViewCtrl? Check out the Setup ToolManager guide.

• Want to display non-PDF files in PDFViewCtrl? Check out the viewing other document types guide.