Understand PDF form events in Android SDK

In Nutrient Android SDK, form events are accessible through the FormManager interface, which is implemented by the PdfFragment. There, you can find the following listeners for subscription:

Listener Description
OnFormElementClickedListener Listener for form element click events.
OnFormElementDeselectedListener Listener for form element deselection.
OnFormElementEditingModeChangeListener Listener for form element editing mode enter/exit.
OnFormElementSelectedListener Listener for form element selection.
OnFormElementUpdatedListener Listener for form element updated events.
OnFormElementViewUpdatedListener Listener for form element view updates — validation, contents of the view changed, etc.

Reacting to Clicks on form elements

PdfActivity and PdfFragment include fully featured support for form filling. The default on-click behavior of form elements depends on their type:

  • Taps on push buttons lead to an execution of the Action, which is set on the form element.

  • Taps on signature fields start the signing flow.

  • Taps on other fields lead to form element selection as well as to entering the form editing mode.

Default tap behavior can be fully customized by registering OnFormElementClickedListener via addOnFormElementClickedListener() on PdfFragment:

fragment.addOnFormElementClickedListener { formElement ->
    when {
        formElement.type == FormType.SIGNATURE -> {
            // Implement custom signature flow here.
            ...

            // By returning `true`, you intercept the event and prevent PSPDFKit from showing the signature picker itself.
            true
        }
        formElement.type == FormType.PUSHBUTTON -> {
            // Implement custom push button click handling.
            ...

            // By returning `true`, you intercept the event and prevent PSPDFKit from executing the button's action.
            true
        }
        else -> {
            // This click event isn't interesting. Return `false` to let PSPDFKit handle this click event.
            false
        }
    }
}
fragment.addOnFormElementClickedListener(formElement -> {
    if (formElement.getType() == FormType.SIGNATURE) {
        // Implement custom signature flow here.
        ...

        // By returning `true`, you intercept the event and prevent PSPDFKit from showing the signature picker itself.
        return true;
    } else if (formElement.getType() == FormType.PUSHBUTTON) {
        // Implement custom push button click handling.
        ...

        // By returning `true`, you intercept the event and prevent PSPDFKit from executing the button's action.
        return true;
    }

    // This click event isn't interesting. Return `false` to let PSPDFKit handle this click event.
    return false;
});

Reacting to form element selection

Most form elements, with the exception of buttons and signature fields, can be selected for interactive editing. You can get notified about this via OnFormElementSelectedListener and OnFormElementDeselectedListener, both of which can be registered on PdfFragment.

Form selection also leads to entering the form element editing mode. You can react to its lifecycle by registering OnFormElementEditingModeListener on PdfFragment. If you want to learn more, refer to the custom form editing UI guide that describes how to use this listener to integrate Nutrient’s form filling UI when using custom activities built around PdfFragment.

For more information on how Nutrient Android SDK implements forms, please see our introduction to forms guide.