Repository files navigation

Need support, consulting, or have any other business-related question? Feel free toget in touch.

Like the project, make profit from it, or simply want to thank back? Please considersponsoring me!

Simple yet powerful autocomplete behavior forEditTexts, to avoid working withMultiAutoCompleteTextView APIs.

implementation("com.otaliastudios:autocomplete:1.1.0")

To see it in action, take a look at the sample app in thesample module.

• Usage
  • AutocompletePolicy
  • AutocompletePresenter
    • RecyclerViewPresenter
  • AutocompleteCallback
• Contributing

⠀

⠀

Autocomplete let's you add autocomplete behavior to anyEditText of your choice. The workflow isas follows:

• User types stuff into the edit text
• AutocompletePolicy detects if typed text should trigger the autocomplete popup
• If yes, the popup is shown
• AutocompletePolicy extracts thequery string from text. For instance, if text isLook atthis @john, you might want to look forjohn users in your database
• The query string is passed toAutocompletePresenter, that shows a list of items for that query
• When some item is clicked,AutocompleteCallback is notified and tells whether the popup should bedismissed or not.

These are the base components of the library. You will build anAutocomplete instance passingeach component you need, and that's it.

Autocomplete.on(editText)  .with(autocompletePolicy)  .with(autocompleteCallback)  .with(autocompletePresenter)  .with(popupBackground)  .with(popupElevation)  .build();

This is an interface that controls when to show/hide the popup. For simple cases (single autocompletion,with just one result, similar toAutocompleteTextView) you can leave this unspecified. The library willfallback toAutocomplete.SimplePolicy:

publicclassSimplePolicyimplementsAutocompletePolicy {@OverridepublicbooleanshouldShowPopup(Spannabletext,intcursorPos) {returntext.length() >0;    }@OverridepublicbooleanshouldDismissPopup(Spannabletext,intcursorPos) {returntext.length() ==0;    }@OverridepublicCharSequencegetQuery(Spannabletext) {returntext;    }@OverridepublicvoidonDismiss(Spannabletext) {}}

For more complex situations, you can go implementing the methods:

• shouldShowPopup(Spannable, int): called to understand whether the popup should be shown. Forinstance, you might want to trigger the popup only when the hashtag character '#' is typed.
• shouldDismissPopup(Spannable, int): whether the popup should be hidden. The typical implementationwould simply be to return!shouldShowPopup(), but that is up to you.
• getQuery(Spannable): called to understand which part of the text should be passed to presenters.For instance, user might have typed@john but you want to query forjohn of course.
• onDismiss(Spannable): this is the moment you should clear any span you have added to the text.

For the typical case of#hashtags,@usernames or whatever is triggered by a certain character,the library provides theCharPolicy class. It works as multi-autocomplete as well (e.g. for textslikeyou should see this @john @pete).

Autocomplete.on(editText)  .with(newCharPolicy('#'))  .with(autocompletePresenter)  .build();

The presenter controls the display of items and their filtering when a query is selected.It is recommended to extendRecyclerViewPresenter, which shows aRecyclerView list.For more complex needs, look at the baseAutocompletePresenter class and its comments.

Note: starting from1.1.0, if the view returned byAutocompletePresenter has 0 height, this is read as ano-data signal and the popup will be dismissed. Not doing so would cause drawing artifacts, byleaving the popup in a weird state.

If you are performing asynchronous loading, make sure to give some height to your view,for example by returning a 'loading' item from your adapter, or adding vertical padding.

This automatically inflates aRecyclerView into the popup. Some relevant callbacks to be overriden:

• instantiateAdapter(): you should provide an adapter for the recycler here.
• instantiateLayoutManager(): same for the layout manager. Defaults to verticalLinearLayoutManager.Complex managers might lead to UI inconsistencies.
• getPopupDimensions(): return dimensions for the popup (width, height, maxWidth, maxHeight).
• onViewShown(): you can perform further initialization on the recycler. The list now is about to be requested.
• onQuery(CharSequence): we have a query from the edit text, as returned byAutocompletePolicy.This is the time to display a list of results corresponding to this filter.
• onViewHidden(): release resources here if needed.

When a list item is clicked, please ensure you are callingdispatchClick(item) to dispatch theclick event to theAutocompleteCallback, if present.

publicinterfaceAutocompleteCallback<T> {booleanonPopupItemClicked(Editableeditable,Titem);voidonPopupVisibilityChanged(booleanshown);}

AutocompleteCallback controls what happens when either the popup visibility changes, or when anitem is selected. Typically at this point you might want to insert aString related to that iteminto theEditText.

This should be done by acting on theEditable interface that you should already know, usingmethods likeeditable.insert() oreditable.replace().

You are welcome to contribute with issues, PRs or suggestions.