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 the FragmentExample or the CustomLayoutExample of the catalog app 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 listeiners 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 the 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 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 the Android touch event that triggered the page click. This gives you access to screen coordinates, pointer numbers, etc.
  • PointF the touched PDF coordinates, in the page coordinate space. For an explanation of coordinates see the Coordinate space conversion guide.
  • Annotation 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, providing the active PdfDocument and the new page number.

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

Activity callbacks

PdfActivity implements the DocumentListener interfaces by default, allowing you to listen for the events by simply overriding those 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();
    }
}