PDF viewer events

Nutrient provides the DocumentListener interface, which allows you to hook into interesting document events like document loading, page changes, page clicks, and more. Have a look at FragmentExample or CustomLayoutExample of the Catalog app, both of which, among other examples, showcase DocumentListener usage.

Registering a document listener

Add a document listener to a PdfFragment by registering it using the addDocumentListener() method. You can register as many document listeners as you like:

fragment.addDocumentListener(myDocumentListener)

fragment.addDocumentListener(myDocumentListener);

ℹ️ Note: To prevent memory leaks, PdfFragment removes all previously registered listeners inside its #onDetach method.

Unregistering a document listener

If you want to stop receiving document events on a listener, provide the listener instance to removeDocumentListener(). Performance wise, you’re encouraged to unregister the listener as soon as you don’t need it anymore, e.g. inside your activity’s onStop() method:

fragment.removeDocumentListener(myDocumentListener)

fragment.removeDocumentListener(myDocumentListener);

Document events

The DocumentListener interface provides callback methods for important and interesting document events:

• onDocumentLoaded(PdfDocument) is called as soon as PdfFragment has finished loading your PDF document. The method is called with an instance of the loaded PdfDocument.

• onDocumentLoadFailed(Throwable) is called in case of a loading error. If this method is called, your app has to recover from the error, e.g. by showing a message to the user. The given Throwable is the cause of failure.

• onPageClick(PdfDocument, int, MotionEvent, PointF, Annotation) is called if the user clicked on the displayed PDF document. This method has various parameters for handling the touch event:

  • PdfDocument is the visible document that was clicked.

  • int is the clicked pageIndex.

  • MotionEvent is the Android touch event that triggered the page click. This gives you access to screen coordinates, pointer numbers, etc.

  • PointF is the touched PDF coordinates in the page coordinate space. For an explanation of coordinates, see the Coordinate Space Conversions guide.

  • Annotation is the touched PDF annotation, or null if no annotation was touched by the user. You can use this to add custom annotation handling logic to your app.

• onDocumentClick() is called if the user clicks the document outside of any page (i.e. the background of the PdfFragment).

• onPageChanged(PdfDocument, int) is called every time the active page changes, and it provides the active PdfDocument and the new page number.

ℹ️ Note: All page numbers in Nutrient have a zero-based index, meaning 0 denotes the first page of a document and pageCount - 1 denotes the last document page.

Activity callbacks

PdfActivity implements DocumentListener interfaces by default, allowing you to listen for events by overriding the associated methods in your subclassed activities:

class MyActivity : PdfActivity() {

    override fun onDocumentLoaded(document : PdfDocument) {
        Toast.makeText(this, "Document has been loaded with ${document.pageCount} pages",
            Toast.LENGTH_SHORT).show()
    }

    override fun onDocumentLoadFailed(exception : Throwable?) {
        Toast.makeText(this, "Document loading failed!", Toast.LENGTH_SHORT).show()
        exception?.printStackTrace()
    }
}

public class MyActivity extends PdfActivity {

    @Override
    public void onDocumentLoaded(@NonNull PdfDocument document) {
        Toast.makeText(this, String.format("Document has been loaded with %d pages",
            document.getPageCount(), Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onDocumentLoadFailed(Throwable exception) {
        Toast.makeText(this, "Document loading failed!", Toast.LENGTH_SHORT).show();
        exception.printStackTrace();
    }
}