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 thePdfFragment
has finished loading your PDF document. The method is called with an instance of the loadedPdfDocument
. -
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 givenThrowable
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 clickedpageIndex
.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, ornull
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 thePdfFragment
). -
onPageChanged(PdfDocument, int)
is called every time the active page changes, providing the activePdfDocument
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.
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() } } |
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(); } } |