Display documents using PDFViewCTRL with Apryse Android SDK

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:

XML

<!-- 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.

XML

<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

<?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">

    <com.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.

Java

private PDFViewCtrl mPdfViewCtrl;
// ...
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.my_activity_layout);
    
    mPdfViewCtrl = findViewById(R.id.pdfviewctrl);
    try {
        AppUtils.setupPDFViewCtrl(mPdfViewCtrl);
    } catch (PDFNetException e) {
        // Handle exception
    }
}

Kotlin

private var mPdfViewCtrl: PDFViewCtrl? = null
// ...
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.my_activity_layout)

    mPdfViewCtrl = findViewById(R.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

Java

import com.pdftron.pdf.utils.Utils;
// ...
private PDFDoc mPdfDoc;
// ...
public void viewFromResource(int resourceId, String fileName) throws PDFNetException {
    File file = Utils.copyResourceToLocal(this, resourceId, fileName, ".pdf");
    mPdfDoc = new PDFDoc(file.getAbsolutePath());
    mPdfViewCtrl.setDoc(mPdfDoc);
    // Alternatively, you can open the document using Uri:
    // Uri fileUri = Uri.fromFile(file);
    // mPdfDoc = mPdfViewCtrl.openPDFUri(fileUri, null);
}

Kotlin

import com.pdftron.pdf.utils.Utils
// ...
private var mPdfDoc: PDFDoc? = null
// ...
fun viewFromResource(resourceId: Int, fileName: String) {
    val file = Utils.copyResourceToLocal(this, resourceId, fileName, ".pdf")
    mPdfDoc = PDFDoc(file.absolutePath)
    mPdfViewCtrl?.doc = mPdfDoc
    // Alternatively, you can open the document using Uri:
    // val fileUri = Uri.fromFile(file)
    // mPdfDoc = mPdfViewCtrl?.openPDFUri(fileUri, null)
}

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:

Java

// ...
@Override
public void onPause() {
    super.onPause();
    if (mPdfViewCtrl != null) {
        mPdfViewCtrl.pause();
        mPdfViewCtrl.purgeMemory();
    }
}

@Override
public void onResume() {
    super.onResume();
    if (mPdfViewCtrl != null) {
        mPdfViewCtrl.resume();
    }
}

@Override
public void onDestroy() {
    super.onDestroy();
    if (mPdfViewCtrl != null) {
        mPdfViewCtrl.destroy();
        mPdfViewCtrl = null;
    }

    if (mPdfDoc != null) {
        try {
            mPdfDoc.close();
        } catch (Exception e) {
            // handle exception
        } finally {
            mPdfDoc = null;
        }
    }
}

Kotlin

// ...
override fun onPause() {
  super.onPause()
  mPdfViewCtrl?.pause()
  mPdfViewCtrl?.purgeMemory()
}

override fun onResume() {
  super.onResume()
  mPdfViewCtrl?.resume()
}

override fun onDestroy() {
  super.onDestroy()
  mPdfViewCtrl?.destroy()
  mPdfViewCtrl = null
  mPdfDoc?.close()
  mPdfDoc = null
}

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.

Check out the diagram of the overall view hierarchy for more.