Document Listeners

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

Register 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:

1
fragment.addDocumentListener(myDocumentListener)
1
fragment.addDocumentListener(myDocumentListener);

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

Unregister a Document Listener

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

1
fragment.removeDocumentListener(myDocumentListener)
1
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.

ℹ️ Note: All page numbers in PSPDFKit 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 simply overriding the associated methods in your subclassed activities:

Copy
MainActivity.kt
1
2
3
4
5
6
7
8
9
10
11
12
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()
    }
}
Copy
MainActivity.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
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();
    }
}