Android
android.widget
public class

android.widget.AutoCompleteTextView

java.lang.Object
android.view.View Drawable.Callback KeyEvent.Callback
android.widget.TextView ViewTreeObserver.OnPreDrawListener
android.widget.EditText
android.widget.AutoCompleteTextView 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 Classes
AutoCompleteTextView.Validator This interface is used to make sure that the text entered in this TextView complies to a certain format. 
Known Direct Subclasses

Summary

XML Attributes

Attribute name Related methods  
android:completionHint setCompletionHint(CharSequence)
 
Defines the hint displayed in the drop down menu. 
android:completionHintView   Defines the hint view displayed in the drop down menu. 
android:completionThreshold setThreshold(int)
 
Defines the number of characters that the user must type before completion suggestions are displayed in a drop down menu. 
android:dropDownSelector   Selector in a drop down list. 
XML Attributes inherited from class android.widget.TextView
XML Attributes inherited from class android.view.View
Constants inherited from class android.view.View
Fields inherited from class android.view.View

Public Constructors

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

Public Methods

          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.
          ListAdapter  getAdapter()

Returns a filterable list adapter used for auto completion.

          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(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.

          boolean  onKeyDown(int keyCode, KeyEvent event)
Default implementation of KeyEvent.Callback.onKeyMultiple(): perform press of the view when KEYCODE_DPAD_CENTER or 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 KEYCODE_DPAD_CENTER or KEYCODE_ENTER is released.
          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.

          void  performValidation()
If a validator was set on this view and the current string is not valid, ask the validator to fix it.
        <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.

          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.

Protected Methods

          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.

          Filter  getFilter()
Returns the Filter obtained from getFilter(), or null if setAdapter(T) was not called with a Filterable.
          void  onFocusChanged(boolean focused, int direction, Rect previouslyFocusedRect)
Called by the view system when the focus state of this view changes.
          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  performFiltering(CharSequence text, int keyCode)

Starts filtering the content of the drop down list.

          void  replaceText(CharSequence text)

Performs the text completion by replacing the current text by the selected item.

          boolean  setFrame(int l, int t, int r, int b)
Assign a size and position to this view.
Methods inherited from class android.widget.EditText
Methods inherited from class android.widget.TextView
Methods inherited from class android.view.View
Methods inherited from class java.lang.Object
Methods inherited from interface android.graphics.drawable.Drawable.Callback
Methods inherited from interface android.view.KeyEvent.Callback
Methods inherited from interface android.view.ViewTreeObserver.OnPreDrawListener
Methods inherited from interface android.widget.Filter.FilterListener

Details

XML Attributes

android:completionHint

Defines the hint displayed in the drop down menu.

Must be a string value, using '\\;' to escape characters such as '\\n' or '\\uxxxx' for a unicode character.

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol completionHint.

android:completionHintView

Defines the hint view displayed in the drop down menu.

Must be a reference to another resource, in the form "@[+][package:]type:name" or to a theme attribute in the form "?[package:][type:]name".

This corresponds to the global attribute resource symbol completionHintView.

Related Methods

android:completionThreshold

Defines the number of characters that the user must type before completion suggestions are displayed in a drop down menu.

Must be an integer value, such as "100".

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol completionThreshold.

Related Methods

android:dropDownSelector

Selector in a drop down list.

May be a reference to another resource, in the form "@[+][package:]type:name" or to a theme attribute in the form "?[package:][type:]name".

May be a color value, in the form of "#rgb", "#argb", "#rrggbb", or "#aarrggbb".

This corresponds to the global attribute resource symbol dropDownSelector.

Related Methods

Public Constructors

public AutoCompleteTextView(Context context)

public AutoCompleteTextView(Context context, AttributeSet attrs)

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

Public Methods

public void dismissDropDown()

Closes the drop down if present on screen.

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.

public ListAdapter getAdapter()

Returns a filterable list adapter used for auto completion.

Returns

  • a data adapter used for auto completion

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

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

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

public AutoCompleteTextView.Validator getValidator()

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

public boolean isPopupShowing()

Indicates whether the popup menu is showing.

Returns

  • true if the popup menu is showing, false otherwise

public void onFilterComplete(int count)

Notifies the end of a filtering operation.

public boolean onKeyDown(int keyCode, KeyEvent event)

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

Parameters

keyCode A key code that represents the button pressed, from KeyEvent.
event The KeyEvent object that defines the button action.

public boolean onKeyUp(int keyCode, KeyEvent event)

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

Parameters

keyCode A key code that represents the button pressed, from KeyEvent.
event The KeyEvent object that defines the button action.

public void onWindowFocusChanged(boolean hasWindowFocus)

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.

Parameters

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

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.

public void performValidation()

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

public 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

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.

Related XML Attributes

Parameters

hint the text to be displayed to the user

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

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

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.

Related XML Attributes

Parameters

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

See Also

public void setValidator(AutoCompleteTextView.Validator validator)

public void showDropDown()

Displays the drop down on screen.

Protected Methods

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

protected Filter getFilter()

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

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

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.

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.

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.

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.

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

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

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

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

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
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:56