android.widget
Class AutoCompleteTextView

java.lang.Object
  android.view.View
      android.widget.TextView
          android.widget.EditText
              android.widget.AutoCompleteTextView

All Implemented Interfaces:

Drawable.Callback, KeyEvent.Callback, ViewTreeObserver.OnPreDrawListener, Filter.FilterListener

Direct Known Subclasses:

MultiAutoCompleteTextView, TextDialog

public class AutoCompleteTextView
extends EditText
implements Filter.FilterListener

An editable text view that shows completion suggestions automatically while the user is typing. The list of suggestions is displayed in a drop down menu from which the user can choose an item to replace the content of the edit box with.

The drop down can be dismissed at any time by pressing the back key or, if no item is selected in the drop down, by pressing the enter/dpad center key.

The list of suggestions is obtained from a data adapter and appears only after a given number of characters defined by the threshold.

The following code snippet shows how to create a text view which suggests various countries names while the user is typing:

 public class CountriesActivity extends Activity {
     protected void onCreate(Bundle icicle) {
         super.onCreate(icicle);
         setContentView(R.layout.countries);

         ArrayAdapter adapter = new ArrayAdapter(this,
                 android.R.layout.simple_dropdown_item_1line, COUNTRIES);
         AutoCompleteTextView textView = (AutoCompleteTextView)
                 findViewById(R.id.countries_list);
         textView.setAdapter(adapter);
     }

     private static final String[] COUNTRIES = new String[] {
         "Belgium", "France", "Italy", "Germany", "Spain"
     };
 }
 

Nested Class Summary

static interface

AutoCompleteTextView.Validator This interface is used to make sure that the text entered in this TextView complies to a certain format.

Nested classes/interfaces inherited from class android.widget.TextView

TextView.BufferType, TextView.SavedState

Nested classes/interfaces inherited from class android.view.View

View.BaseSavedState, View.MeasureSpec, View.OnClickListener, View.OnCreateContextMenuListener, View.OnFocusChangeListener, View.OnKeyListener, View.OnLongClickListener, View.OnTouchListener

Field Summary

Fields inherited from class android.view.View

DRAWING_CACHE_QUALITY_AUTO, DRAWING_CACHE_QUALITY_HIGH, DRAWING_CACHE_QUALITY_LOW, EMPTY_STATE_SET, ENABLED_FOCUSED_SELECTED_STATE_SET, ENABLED_FOCUSED_SELECTED_WINDOW_FOCUSED_STATE_SET, ENABLED_FOCUSED_STATE_SET, ENABLED_FOCUSED_WINDOW_FOCUSED_STATE_SET, ENABLED_SELECTED_STATE_SET, ENABLED_SELECTED_WINDOW_FOCUSED_STATE_SET, ENABLED_STATE_SET, ENABLED_WINDOW_FOCUSED_STATE_SET, FIRST_STATE_SET, FOCUS_BACKWARD, FOCUS_DOWN, FOCUS_FORWARD, FOCUS_LEFT, FOCUS_RIGHT, FOCUS_UP, FOCUSED_SELECTED_STATE_SET, FOCUSED_SELECTED_WINDOW_FOCUSED_STATE_SET, FOCUSED_STATE_SET, FOCUSED_WINDOW_FOCUSED_STATE_SET, GONE, INVISIBLE, KEEP_SCREEN_ON, LAST_STATE_SET, mBottom, mContext, mCurrentAnimation, MIDDLE_STATE_SET, mLayoutParams, mLeft, mLocation, mMeasuredHeight, mMeasuredWidth, mOnClickListener, mOnCreateContextMenuListener, mOnFocusChangeListener, mOnLongClickListener, mPaddingBottom, mPaddingLeft, mPaddingRight, mPaddingTop, mParent, mRight, mScrollX, mScrollY, mTag, mTop, NO_ID, PRESSED_ENABLED_FOCUSED_SELECTED_STATE_SET, PRESSED_ENABLED_FOCUSED_SELECTED_WINDOW_FOCUSED_STATE_SET, PRESSED_ENABLED_FOCUSED_STATE_SET, PRESSED_ENABLED_FOCUSED_WINDOW_FOCUSED_STATE_SET, PRESSED_ENABLED_SELECTED_STATE_SET, PRESSED_ENABLED_SELECTED_WINDOW_FOCUSED_STATE_SET, PRESSED_ENABLED_STATE_SET, PRESSED_ENABLED_WINDOW_FOCUSED_STATE_SET, PRESSED_FIRST_STATE_SET, PRESSED_FOCUSED_SELECTED_STATE_SET, PRESSED_FOCUSED_SELECTED_WINDOW_FOCUSED_STATE_SET, PRESSED_FOCUSED_STATE_SET, PRESSED_FOCUSED_WINDOW_FOCUSED_STATE_SET, PRESSED_LAST_STATE_SET, PRESSED_MIDDLE_STATE_SET, PRESSED_SELECTED_STATE_SET, PRESSED_SELECTED_WINDOW_FOCUSED_STATE_SET, PRESSED_SINGLE_STATE_SET, PRESSED_STATE_SET, PRESSED_WINDOW_FOCUSED_STATE_SET, SCROLLBARS_INSIDE_INSET, SCROLLBARS_INSIDE_OVERLAY, SCROLLBARS_OUTSIDE_INSET, SCROLLBARS_OUTSIDE_OVERLAY, SELECTED_STATE_SET, SELECTED_WINDOW_FOCUSED_STATE_SET, SINGLE_STATE_SET, SOUND_EFFECTS_ENABLED, VIEW_LOG_TAG, VISIBLE, WINDOW_FOCUSED_STATE_SET

Constructor Summary

AutoCompleteTextView(Context context)

AutoCompleteTextView(Context context, AttributeSet attrs)

AutoCompleteTextView(Context context, AttributeSet attrs, int defStyle)

Method Summary

protected CharSequence	convertSelectionToString(Object selectedItem) Converts the selected item from the drop down list into a sequence of character that can be used in the edit box.
void	dismissDropDown() Closes the drop down if present on screen.
boolean	enoughToFilter() Returns true if the amount of text in the field meets or exceeds the getThreshold() requirement.
(package private) void	finishInit() Sets this to be single line; a separate method so MultiAutoCompleteTextView can skip this.
ListAdapter	getAdapter() Returns a filterable list adapter used for auto completion.
protected Filter	getFilter() Returns the Filter obtained from Filterable.getFilter(), or null if setAdapter(T) was not called with a Filterable.
AdapterView.OnItemClickListener	getItemClickListener() Returns the listener that is notified whenever the user clicks an item in the drop down list.
AdapterView.OnItemSelectedListener	getItemSelectedListener() Returns the listener that is notified whenever the user selects an item in the drop down list.
int	getThreshold() Returns the number of characters the user must type before the drop down list is shown.
AutoCompleteTextView.Validator	getValidator() Returns the Validator set with setValidator(android.widget.AutoCompleteTextView.Validator), or null if it was not set.
boolean	isPopupShowing() Indicates whether the popup menu is showing.
void	onFilterComplete(int count) Notifies the end of a filtering operation.
protected void	onFocusChanged(boolean focused, int direction, Rect previouslyFocusedRect) Called by the view system when the focus state of this view changes.
boolean	onKeyDown(int keyCode, KeyEvent event) Default implementation of KeyEvent.Callback.onKeyMultiple(): perform press of the view when KeyEvent.KEYCODE_DPAD_CENTER or KeyEvent.KEYCODE_ENTER is released, if the view is enabled and clickable.
boolean	onKeyUp(int keyCode, KeyEvent event) Default implementation of KeyEvent.Callback.onKeyMultiple(): perform clicking of the view when KeyEvent.KEYCODE_DPAD_CENTER or KeyEvent.KEYCODE_ENTER is released.
protected void	onTextChanged(CharSequence text, int start, int before, int after) This method is called when the text is changed, in case any subclasses would like to know.
void	onWindowFocusChanged(boolean hasWindowFocus) Called when the window containing this view gains or loses focus.
void	performCompletion() Performs the text completion by converting the selected item from the drop down list into a string, replacing the text box's content with this string and finally dismissing the drop down menu.
protected void	performFiltering(CharSequence text, int keyCode) Starts filtering the content of the drop down list.
void	performValidation() If a validator was set on this view and the current string is not valid, ask the validator to fix it.
protected void	replaceText(CharSequence text) Performs the text completion by replacing the current text by the selected item.
<T extends ListAdapter & Filterable> void	setAdapter(T adapter) Changes the list of data used for auto completion.
void	setCompletionHint(CharSequence hint) Sets the optional hint text that is displayed at the bottom of the the matching list.
protected boolean	setFrame(int l, int t, int r, int b) Assign a size and position to this view.
void	setOnItemClickListener(AdapterView.OnItemClickListener l) Sets the listener that will be notified when the user clicks an item in the drop down list.
void	setOnItemSelectedListener(AdapterView.OnItemSelectedListener l) Sets the listener that will be notified when the user selects an item in the drop down list.
void	setThreshold(int threshold) Specifies the minimum number of characters the user has to type in the edit box before the drop down list is shown.
void	setValidator(AutoCompleteTextView.Validator validator)
void	showDropDown() Displays the drop down on screen.

Methods inherited from class android.widget.EditText

extendSelection, getDefaultEditable, getDefaultMovementMethod, getText, selectAll, setSelection, setSelection, setText

Methods inherited from class android.widget.TextView

addTextChangedListener, append, append, computeHorizontalScrollRange, computeScroll, computeVerticalScrollRange, debug, drawableStateChanged, getAutoLinkMask, getBaseline, getCompoundDrawablePadding, getCompoundDrawables, getCompoundPaddingBottom, getCompoundPaddingLeft, getCompoundPaddingRight, getCompoundPaddingTop, getCurrentHintTextColor, getCurrentTextColor, getEllipsize, getError, getExtendedPaddingBottom, getExtendedPaddingTop, getFilters, getFocusedRect, getFreezesText, getGravity, getHint, getHintTextColors, getKeyListener, getLayout, getLineBounds, getLineCount, getLineHeight, getLinksClickable, getLinkTextColors, getMovementMethod, getPaint, getPaintFlags, getSelectionEnd, getSelectionStart, getTextColor, getTextColors, getTextColors, getTextScaleX, getTextSize, getTotalPaddingBottom, getTotalPaddingLeft, getTotalPaddingRight, getTotalPaddingTop, getTransformationMethod, getTypeface, getUrls, hasSelection, length, makeNewLayout, onCreateContextMenu, onDetachedFromWindow, onDraw, onKeyShortcut, onMeasure, onPreDraw, onRestoreInstanceState, onSaveInstanceState, onTouchEvent, onTrackballEvent, performLongClick, removeTextChangedListener, setAutoLinkMask, setCompoundDrawablePadding, setCompoundDrawables, setCompoundDrawablesWithIntrinsicBounds, setCursorVisible, setEditableFactory, setEllipsize, setEms, setError, setError, setFilters, setFreezesText, setGravity, setHeight, setHighlightColor, setHint, setHint, setHintTextColor, setHintTextColor, setHorizontallyScrolling, setIncludeFontPadding, setKeyListener, setLines, setLineSpacing, setLinksClickable, setLinkTextColor, setLinkTextColor, setMaxEms, setMaxHeight, setMaxLines, setMaxWidth, setMinEms, setMinHeight, setMinLines, setMinWidth, setMovementMethod, setPadding, setPaintFlags, setScroller, setSelectAllOnFocus, setShadowLayer, setSingleLine, setSingleLine, setSpannableFactory, setText, setText, setText, setText, setTextAppearance, setTextColor, setTextColor, setTextKeepState, setTextKeepState, setTextScaleX, setTextSize, setTextSize, setTransformationMethod, setTypeface, setTypeface, setWidth

Methods inherited from class android.view.View

addFocusables, addTouchables, applyDrawableToTransparentRegion, bringToFront, buildDrawingCache, cancelLongPress, clearAnimation, clearFocus, computeHorizontalScrollExtent, computeHorizontalScrollOffset, computeVerticalScrollExtent, computeVerticalScrollOffset, createContextMenu, debug, debugIndent, destroyDrawingCache, dispatchDraw, dispatchKeyEvent, dispatchKeyShortcutEvent, dispatchRestoreInstanceState, dispatchSaveInstanceState, dispatchSetPressed, dispatchSetSelected, dispatchTouchEvent, dispatchTrackballEvent, dispatchUnhandledMove, dispatchWindowFocusChanged, dispatchWindowVisibilityChanged, draw, finalize, findFocus, findViewById, findViewTraversal, findViewWithTag, findViewWithTagTraversal, fitSystemWindows, focusSearch, forceLayout, gatherTransparentRegion, getAnimation, getApplicationWindowToken, getBackground, getBottom, getBottomFadingEdgeStrength, getContext, getContextMenuInfo, getDefaultSize, getDrawableState, getDrawingCache, getDrawingCacheBackgroundColor, getDrawingCacheQuality, getDrawingRect, getDrawingTime, getFocusables, getGlobalVisibleRect, getGlobalVisibleRect, getHandler, getHeight, getHitRect, getHorizontalFadingEdgeLength, getHorizontalScrollbarHeight, getId, getKeepScreenOn, getLayoutParams, getLeft, getLeftFadingEdgeStrength, getLocalVisibleRect, getLocationInWindow, getLocationOnScreen, getMeasuredHeight, getMeasuredWidth, getNextFocusDownId, getNextFocusLeftId, getNextFocusRightId, getNextFocusUpId, getOnFocusChangeListener, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getParent, getResources, getRight, getRightFadingEdgeStrength, getRootView, getScrollBarStyle, getScrollX, getScrollY, getSolidColor, getSuggestedMinimumHeight, getSuggestedMinimumWidth, getTag, getTop, getTopFadingEdgeStrength, getTouchables, getTouchDelegate, getVerticalFadingEdgeLength, getVerticalScrollbarWidth, getViewTreeObserver, getVisibility, getWidth, getWindowAttachCount, getWindowToken, getWindowVisibility, hasFocus, hasFocusable, hasWindowFocus, inflate, initializeFadingEdge, initializeScrollbars, invalidate, invalidate, invalidate, invalidateDrawable, isClickable, isDrawingCacheEnabled, isDuplicateParentStateEnabled, isEnabled, isFocusable, isFocusableInTouchMode, isFocused, isHorizontalFadingEdgeEnabled, isHorizontalScrollBarEnabled, isInTouchMode, isLayoutRequested, isLongClickable, isPressed, isRootNamespace, isSaveEnabled, isSelected, isShown, isSoundEffectsEnabled, isVerticalFadingEdgeEnabled, isVerticalScrollBarEnabled, layout, measure, mergeDrawableStates, offsetLeftAndRight, offsetTopAndBottom, onAnimationEnd, onAnimationStart, onAttachedToWindow, onCreateDrawableState, onFinishInflate, onKeyMultiple, onLayout, onScrollChanged, onSetAlpha, onSizeChanged, onWindowVisibilityChanged, performClick, playSoundEffect, post, postDelayed, postInvalidate, postInvalidate, postInvalidateDelayed, postInvalidateDelayed, refreshDrawableState, removeCallbacks, requestFocus, requestFocus, requestFocus, requestFocusFromTouch, requestLayout, requestRectangleOnScreen, requestRectangleOnScreen, resolveSize, restoreHierarchyState, saveHierarchyState, scheduleDrawable, scrollBy, scrollTo, setAnimation, setBackgroundColor, setBackgroundDrawable, setBackgroundResource, setClickable, setDrawingCacheBackgroundColor, setDrawingCacheEnabled, setDrawingCacheQuality, setDuplicateParentStateEnabled, setEnabled, setFadingEdgeLength, setFocusable, setFocusableInTouchMode, setHorizontalFadingEdgeEnabled, setHorizontalScrollBarEnabled, setId, setIsRootNamespace, setKeepScreenOn, setLayoutParams, setLongClickable, setMeasuredDimension, setMinimumHeight, setMinimumWidth, setNextFocusDownId, setNextFocusLeftId, setNextFocusRightId, setNextFocusUpId, setOnClickListener, setOnCreateContextMenuListener, setOnFocusChangeListener, setOnKeyListener, setOnLongClickListener, setOnTouchListener, setPressed, setSaveEnabled, setScrollBarStyle, setSelected, setSoundEffectsEnabled, setTag, setTouchDelegate, setVerticalFadingEdgeEnabled, setVerticalScrollBarEnabled, setVisibility, setWillNotCacheDrawing, setWillNotDraw, showContextMenu, startAnimation, unscheduleDrawable, unscheduleDrawable, verifyDrawable, willNotCacheDrawing, willNotDraw

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AutoCompleteTextView

public AutoCompleteTextView(Context context)

AutoCompleteTextView

public AutoCompleteTextView(Context context,
                            AttributeSet attrs)

AutoCompleteTextView

public AutoCompleteTextView(Context context,
                            AttributeSet attrs,
                            int defStyle)

Method Detail

finishInit

void finishInit()

Sets this to be single line; a separate method so MultiAutoCompleteTextView can skip this.

setCompletionHint

public void setCompletionHint(CharSequence hint)

Sets the optional hint text that is displayed at the bottom of the the matching list. This can be used as a cue to the user on how to best use the list, or to provide extra information.

Parameters:

hint - the text to be displayed to the user

getThreshold

public int getThreshold()

Returns the number of characters the user must type before the drop down list is shown.

Returns:

the minimum number of characters to type to show the drop down

See Also:

setThreshold(int)

setThreshold

public void setThreshold(int threshold)

Specifies the minimum number of characters the user has to type in the edit box before the drop down list is shown.

When threshold is less than or equals 0, a threshold of 1 is applied.

Parameters:

threshold - the number of characters to type before the drop down is shown

See Also:

getThreshold()

setOnItemClickListener

public void setOnItemClickListener(AdapterView.OnItemClickListener l)

Sets the listener that will be notified when the user clicks an item in the drop down list.

Parameters:

l - the item click listener

setOnItemSelectedListener

public void setOnItemSelectedListener(AdapterView.OnItemSelectedListener l)

Sets the listener that will be notified when the user selects an item in the drop down list.

Parameters:

l - the item selected listener

getItemClickListener

public AdapterView.OnItemClickListener getItemClickListener()

Returns the listener that is notified whenever the user clicks an item in the drop down list.

Returns:

the item click listener

getItemSelectedListener

public AdapterView.OnItemSelectedListener getItemSelectedListener()

Returns the listener that is notified whenever the user selects an item in the drop down list.

Returns:

the item selected listener

getAdapter

public ListAdapter getAdapter()

Returns a filterable list adapter used for auto completion.

Returns:

a data adapter used for auto completion

setAdapter

public <T extends ListAdapter & Filterable> void setAdapter(T adapter)

Changes the list of data used for auto completion. The provided list must be a filterable list adapter.

Parameters:

adapter - the adapter holding the auto completion data

See Also:

getAdapter(), Filterable, ListAdapter

onKeyUp

public boolean onKeyUp(int keyCode,
                       KeyEvent event)

Description copied from class: View

Default implementation of KeyEvent.Callback.onKeyMultiple(): perform clicking of the view when KeyEvent.KEYCODE_DPAD_CENTER or KeyEvent.KEYCODE_ENTER is released.

Specified by:

onKeyUp in interface KeyEvent.Callback

Overrides:

onKeyUp in class TextView

Parameters:

keyCode - A key code that represents the button pressed, from KeyEvent.

event - The KeyEvent object that defines the button action.

Returns:

If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

onKeyDown

public boolean onKeyDown(int keyCode,
                         KeyEvent event)

Description copied from class: View

Default implementation of KeyEvent.Callback.onKeyMultiple(): perform press of the view when KeyEvent.KEYCODE_DPAD_CENTER or KeyEvent.KEYCODE_ENTER is released, if the view is enabled and clickable.

Specified by:

onKeyDown in interface KeyEvent.Callback

Overrides:

onKeyDown in class TextView

Parameters:

keyCode - A key code that represents the button pressed, from KeyEvent.

event - The KeyEvent object that defines the button action.

Returns:

If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

enoughToFilter

public boolean enoughToFilter()

Returns true if the amount of text in the field meets or exceeds the getThreshold() requirement. You can override this to impose a different standard for when filtering will be triggered.

onTextChanged

protected void onTextChanged(CharSequence text,
                             int start,
                             int before,
                             int after)

Description copied from class: TextView

This method is called when the text is changed, in case any subclasses would like to know.

Overrides:

onTextChanged in class TextView

Parameters:

text - The text the TextView is displaying.

start - The offset of the start of the range of the text that was modified.

before - The offset of the former end of the range of the text that was modified. If text was simply inserted, this will be the same as start. If text was replaced with new text or deleted, the length of the old text was before-start.

after - The offset of the end of the range of the text that was modified. If text was simply deleted, this will be the same as start. If text was replaced with new text or inserted, the length of the new text is after-start.

isPopupShowing

public boolean isPopupShowing()

Indicates whether the popup menu is showing.

Returns:

true if the popup menu is showing, false otherwise

convertSelectionToString

protected CharSequence convertSelectionToString(Object selectedItem)

Converts the selected item from the drop down list into a sequence of character that can be used in the edit box.

Parameters:

selectedItem - the item selected by the user for completion

Returns:

a sequence of characters representing the selected suggestion

performFiltering

protected void performFiltering(CharSequence text,
                                int keyCode)

Starts filtering the content of the drop down list. The filtering pattern is the content of the edit box. Subclasses should override this method to filter with a different pattern, for instance a substring of text.

Parameters:

text - the filtering pattern

keyCode - the last character inserted in the edit box

performCompletion

public void performCompletion()

Performs the text completion by converting the selected item from the drop down list into a string, replacing the text box's content with this string and finally dismissing the drop down menu.

replaceText

protected void replaceText(CharSequence text)

Performs the text completion by replacing the current text by the selected item. Subclasses should override this method to avoid replacing the whole content of the edit box.

Parameters:

text - the selected suggestion in the drop down list

onFilterComplete

public void onFilterComplete(int count)

Description copied from interface: Filter.FilterListener

Notifies the end of a filtering operation.

Specified by:

onFilterComplete in interface Filter.FilterListener

Parameters:

count - the number of values computed by the filter

onWindowFocusChanged

public void onWindowFocusChanged(boolean hasWindowFocus)

Description copied from class: View

Called when the window containing this view gains or loses focus. Note that this is separate from view focus: to receive key events, both your view and its window must have focus. If a window is displayed on top of yours that takes input focus, then your own window will lose focus but the view focus will remain unchanged.

Overrides:

onWindowFocusChanged in class TextView

Parameters:

hasWindowFocus - True if the window containing this view now has focus, false otherwise.

onFocusChanged

protected void onFocusChanged(boolean focused,
                              int direction,
                              Rect previouslyFocusedRect)

Description copied from class: View

Called by the view system when the focus state of this view changes. When the focus change event is caused by directional navigation, direction and previouslyFocusedRect provide insight into where the focus is coming from.

Overrides:

onFocusChanged in class TextView

Parameters:

focused - True if the View has focus; false otherwise.

direction - The direction focus has moved when requestFocus() is called to give this view focus. Values are View.FOCUS_UP, View.FOCUS_DOWN, View.FOCUS_LEFT or View.FOCUS_RIGHT. It may not always apply, in which case use the default.

previouslyFocusedRect - The rectangle, in this view's coordinate system, of the previously focused view. If applicable, this will be passed in as finer grained information about where the focus is coming from (in addition to direction). Will be null otherwise.

dismissDropDown

public void dismissDropDown()

Closes the drop down if present on screen.

setFrame

protected boolean setFrame(int l,
                           int t,
                           int r,
                           int b)

Description copied from class: View

Assign a size and position to this view. This is called from layout.

Overrides:

setFrame in class TextView

Parameters:

l - Left position, relative to parent

t - Top position, relative to parent

r - Right position, relative to parent

b - Bottom position, relative to parent

Returns:

true if the new size and position are different than the previous ones

showDropDown

public void showDropDown()

Displays the drop down on screen.

setValidator

public void setValidator(AutoCompleteTextView.Validator validator)

getValidator

public AutoCompleteTextView.Validator getValidator()

Returns the Validator set with setValidator(android.widget.AutoCompleteTextView.Validator), or null if it was not set.

performValidation

public void performValidation()

If a validator was set on this view and the current string is not valid, ask the validator to fix it.

getFilter

protected Filter getFilter()

Returns the Filter obtained from Filterable.getFilter(), or null if setAdapter(T) was not called with a Filterable.