# PDF viewer events

Nutrient provides the [`DocumentListener`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.listeners/-document-listener/index.html) 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`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.listeners/-document-listener/index.html) usage.

## Registering a document listener

Add a document listener to a [`PdfFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/index.html) by registering it using the [`addDocumentListener()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/add-document-listener.html) method. You can register as many document listeners as you like:

### KOTLIN

```kotlin

fragment.addDocumentListener(myDocumentListener)

```

### JAVA

```java

fragment.addDocumentListener(myDocumentListener);

```

To prevent memory leaks, [`PdfFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/index.html) 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()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/remove-document-listener.html). 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()`](http://developer.android.com/reference/android/app/Activity.html#onStop()) method:

### KOTLIN

```kotlin

fragment.removeDocumentListener(myDocumentListener)

```

### JAVA

```java

fragment.removeDocumentListener(myDocumentListener);

```

## Document events

The [`DocumentListener`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.listeners/-document-listener/index.html) interface provides callback methods for important and interesting document events:

- [`onDocumentLoaded(PdfDocument)`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.listeners/-document-listener/on-document-loaded.html) is called as soon as [`PdfFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/index.html) has finished loading your PDF document. The method is called with an instance of the loaded [`PdfDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-pdf-document/index.html).

- [`onDocumentLoadFailed(Throwable)`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.listeners/-document-listener/on-document-load-failed.html) 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`](http://developer.android.com/reference/java/lang/Throwable.html) is the cause of failure.

- [`onPageClick(PdfDocument, int, MotionEvent, PointF, Annotation)`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.listeners/-document-listener/on-page-click.html) is called if the user clicked on the displayed PDF document. This method has various parameters for handling the touch event:
  - [`PdfDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-pdf-document/index.html) is the visible document that was clicked.
  - `int` is the clicked `pageIndex`.
  - [`MotionEvent`](http://developer.android.com/reference/android/view/MotionEvent.html) is the Android touch event that triggered the page click. This gives you access to screen coordinates, pointer numbers, etc.
  - [`PointF`](http://developer.android.com/reference/android/graphics/PointF.html) is the touched PDF coordinates in the _page coordinate space_. For an explanation of coordinates, see the [Coordinate Space Conversions](https://www.nutrient.io/../../faq/coordinate-spaces) guide.
  - [`Annotation`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation/index.html) 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()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.listeners/-document-listener/on-document-click.html) is called if the user clicks the document outside of any page (i.e. the background of the [`PdfFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/index.html)).

- [`onPageChanged(PdfDocument, int)`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.listeners/-document-listener/on-page-changed.html) is called every time the active page changes, and it provides the active [`PdfDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-pdf-document/index.html) and the new page number.

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`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-activity/index.html) implements [`DocumentListener`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.listeners/-document-listener/index.html) interfaces by default, allowing you to listen for events by overriding the associated methods in your subclassed activities:

### MAINACTIVITY.KT

```kt

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

```java

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

```
---

## Related pages

- [Analytics](/guides/android/features/analytics.md)
- [Understand PDF form events in Android SDK](/guides/android/events-and-notifications/forms.md)
- [Analytics events](/guides/android/events-and-notifications/events.md)
- [Annotation events and notifications](/guides/android/events-and-notifications/annotation.md)
- [Events and notifications](/guides/android/events-and-notifications.md)
- [Text selection events and notifications](/guides/android/events-and-notifications/text-selection.md)