Autocomplete suggestions for PDF form fields on Android

Nutrient Android SDK can show a list of autocomplete suggestions while a user fills a text form field. When the user taps a suggestion, its value is written into the field. This is useful for fields with a known set of likely values — names, departments, site codes, or values you’ve already collected elsewhere in your app.

Suggestions are supplied by your app through FormManager.OnTextFormElementSuggestionRequestListener, so you decide which fields offer suggestions and what those suggestions are. No UI or view subclassing is required.

Providing suggestions

Register a listener on the PdfFragment and return the suggestions for the given form element. Returning an empty list disables autocomplete for that field:

    class MyActivity : PdfActivity() {
        override fun onDocumentLoaded(document: PdfDocument) {
            super.onDocumentLoaded(document)

            pdfFragment?.addOnTextFormElementSuggestionRequestListener { formElement ->
                when (formElement.name) {
                    "First Name" -> listOf("Alice", "Andrew", "Anna", "Bob", "Barbara")
                    "Last Name" -> listOf("Anderson", "Brown", "Davis", "Smith", "Wilson")
                    // Returning an empty list means this field has no suggestions.
                    else -> emptyList()
                }
            }
        }
    }

    public class MyActivity extends PdfActivity {
        @Override
        public void onDocumentLoaded(@NonNull PdfDocument document) {
            super.onDocumentLoaded(document);

            PdfFragment fragment = getPdfFragment();
            if (fragment == null) return;

            fragment.addOnTextFormElementSuggestionRequestListener(formElement -> {
                String name = formElement.getName();
                if ("First Name".equals(name)) {
                    return Arrays.asList("Alice", "Andrew", "Anna", "Bob", "Barbara");
                } else if ("Last Name".equals(name)) {
                    return Arrays.asList("Anderson", "Brown", "Davis", "Smith", "Wilson");
                }
                // Returning an empty list means this field has no suggestions.
                return Collections.emptyList();
            });
        }
    }

Call removeOnTextFormElementSuggestionRequestListener when you no longer want to provide suggestions.

The example above matches on FormElement#getName, but you can use any property of the supplied TextFormElement to decide what to return — for example, its inputFormat or the page it lives on.

Controlling when suggestions appear

By default, the suggestion list is shown as soon as the user starts editing the field. Override shouldShowSuggestionsImmediately and return false to show it only after the user taps the field again or begins typing:

    pdfFragment?.addOnTextFormElementSuggestionRequestListener(
        object : FormManager.OnTextFormElementSuggestionRequestListener {
            override fun onTextFormElementGetSuggestions(formElement: TextFormElement): List<String> =
                suggestionsFor(formElement)

            override fun shouldShowSuggestionsImmediately(formElement: TextFormElement): Boolean {
                // Only show the list once the user has typed something.
                return false
            }
        }
    )

    fragment.addOnTextFormElementSuggestionRequestListener(
        new FormManager.OnTextFormElementSuggestionRequestListener() {
            @NonNull
            @Override
            public List<String> onTextFormElementGetSuggestions(@NonNull TextFormElement formElement) {
                return suggestionsFor(formElement);
            }

            @Override
            public boolean shouldShowSuggestionsImmediately(@NonNull TextFormElement formElement) {
                // Only show the list once the user has typed something.
                return false;
            }
        }
    );

How suggestions are matched

• Suggestions are requested once: when the field enters editing mode. The returned list is then filtered locally as the user types, so the callback isn’t invoked on every keystroke.
• Filtering is a case-insensitive substring match against the current field contents — typing an matches both Anna and Alexander. The list is shown in the order you return it, so return it presorted if order matters to your users.
• If nothing matches the current text, the list is hidden.
• Tapping a suggestion replaces the entire contents of the field with the selected value and dismisses the list.

Styling

The suggestion list picks up the pspdf__suggestionListBackgroundColor and pspdf__suggestionListTextColor attributes of your pspdf__formSelectionStyle. See the form selection section of the appearance and styling guide for the full attribute list.

Things to keep in mind

• The callback is invoked on the main thread and has to return synchronously. If your suggestions come from a database or a network call, load them before the user reaches the field and return the cached values here.
• If you register more than one listener, the first one to return a non-empty list wins. For shouldShowSuggestionsImmediately, the list is shown immediately if any registered listener returns true.
• Suggestions are only offered for text form fields. They’re also suppressed on fields whose inputFormat is a date or a time while the date and time pickers are enabled, so that the picker and the suggestion list don’t compete for the same space.
• Suggestions are supported by PdfFragment and PdfActivity. They aren’t available in the Jetpack Compose SDK flavor.

Example

For a complete, runnable example, see FormTextFieldSuggestionExample in our Catalog app.