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.

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

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()
    }
}

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();
    }
}