AdapterView

public abstract class AdapterView
extends ViewGroup

java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.widget.AdapterView<T extends android.widget.Adapter>


An AdapterView is a view whose children are determined by an Adapter.

See ListView, GridView, Spinner and Gallery for commonly used subclasses of AdapterView.

Developer Guides

For more information about using AdapterView, read the Binding to Data with AdapterView developer guide.

Summary

Nested classes

class AdapterView.AdapterContextMenuInfo

Extra menu information provided to the View.OnCreateContextMenuListener.onCreateContextMenu(ContextMenu, View, ContextMenuInfo) callback when a context menu is brought up for this AdapterView. 

interface AdapterView.OnItemClickListener

Interface definition for a callback to be invoked when an item in this AdapterView has been clicked. 

interface AdapterView.OnItemLongClickListener

Interface definition for a callback to be invoked when an item in this view has been clicked and held. 

interface AdapterView.OnItemSelectedListener

Interface definition for a callback to be invoked when an item in this view has been selected. 

Inherited XML attributes

Constants

int INVALID_POSITION

Represents an invalid position.

long INVALID_ROW_ID

Represents an empty or invalid row id

int ITEM_VIEW_TYPE_HEADER_OR_FOOTER

The item view type returned by Adapter#getItemViewType(int) when the item is a header or footer.

int ITEM_VIEW_TYPE_IGNORE

The item view type returned by Adapter#getItemViewType(int) when the adapter does not want the item's view recycled.

Inherited constants

Inherited fields

Public constructors

AdapterView(Context context)
AdapterView(Context context, AttributeSet attrs)
AdapterView(Context context, AttributeSet attrs, int defStyleAttr)
AdapterView(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)

Public methods

void addView(View child, int index)

This method is not supported and throws an UnsupportedOperationException when called.

void addView(View child)

This method is not supported and throws an UnsupportedOperationException when called.

void addView(View child, ViewGroup.LayoutParams params)

This method is not supported and throws an UnsupportedOperationException when called.

void addView(View child, int index, ViewGroup.LayoutParams params)

This method is not supported and throws an UnsupportedOperationException when called.

CharSequence getAccessibilityClassName()

Return the class name of this object to be used for accessibility purposes.

abstract T getAdapter()

Returns the adapter currently associated with this widget.

int getCount()
View getEmptyView()

When the current adapter is empty, the AdapterView can display a special view called the empty view.

int getFirstVisiblePosition()

Returns the position within the adapter's data set for the first item displayed on screen.

Object getItemAtPosition(int position)

Gets the data associated with the specified position in the list.

long getItemIdAtPosition(int position)
int getLastVisiblePosition()

Returns the position within the adapter's data set for the last item displayed on screen.

final AdapterView.OnItemClickListener getOnItemClickListener()
final AdapterView.OnItemLongClickListener getOnItemLongClickListener()
final AdapterView.OnItemSelectedListener getOnItemSelectedListener()
int getPositionForView(View view)

Returns the position within the adapter's data set for the view, where view is a an adapter item or a descendant of an adapter item.

Object getSelectedItem()
long getSelectedItemId()
int getSelectedItemPosition()

Return the position of the currently selected item within the adapter's data set

abstract View getSelectedView()
void onProvideAutofillStructure(ViewStructure structure, int flags)

Populates a ViewStructure to fullfil an autofill request.

It also sets the autofill options in the structure; when overridden, it should set it as well, either explicitly by calling ViewStructure#setAutofillOptions(CharSequence[]) or implicitly by calling super.onProvideAutofillStructure(structure, flags).

boolean performItemClick(View view, int position, long id)

Call the OnItemClickListener, if it is defined.

void removeAllViews()

This method is not supported and throws an UnsupportedOperationException when called.

void removeView(View child)

This method is not supported and throws an UnsupportedOperationException when called.

void removeViewAt(int index)

This method is not supported and throws an UnsupportedOperationException when called.

abstract void setAdapter(T adapter)

Sets the adapter that provides the data and the views to represent the data in this widget.

void setEmptyView(View emptyView)

Sets the view to show if the adapter is empty

void setFocusable(int focusable)

Sets whether this view can receive focus.

void setFocusableInTouchMode(boolean focusable)

Set whether this view can receive focus while in touch mode.

void setOnClickListener(View.OnClickListener l)

Register a callback to be invoked when this view is clicked.

void setOnItemClickListener(AdapterView.OnItemClickListener listener)

Register a callback to be invoked when an item in this AdapterView has been clicked.

void setOnItemLongClickListener(AdapterView.OnItemLongClickListener listener)

Register a callback to be invoked when an item in this AdapterView has been clicked and held

void setOnItemSelectedListener(AdapterView.OnItemSelectedListener listener)

Register a callback to be invoked when an item in this AdapterView has been selected.

abstract void setSelection(int position)

Sets the currently selected item.

Protected methods

boolean canAnimate()

Indicates whether the view group has the ability to animate its children after the first layout.

void dispatchRestoreInstanceState(SparseArray<Parcelable> container)

Override to prevent thawing of any views created by the adapter.

void dispatchSaveInstanceState(SparseArray<Parcelable> container)

Override to prevent freezing of any views created by the adapter.

void onDetachedFromWindow()

This is called when the view is detached from a window.

void onLayout(boolean changed, int left, int top, int right, int bottom)

Called from layout when this view should assign a size and position to each of its children.

Inherited methods

Constants

INVALID_POSITION

Added in API level 1
public static final int INVALID_POSITION

Represents an invalid position. All valid positions are in the range 0 to 1 less than the number of items in the current adapter.

Constant Value: -1 (0xffffffff)

INVALID_ROW_ID

Added in API level 1
public static final long INVALID_ROW_ID

Represents an empty or invalid row id

Constant Value: -9223372036854775808 (0x8000000000000000)

Added in API level 1
public static final int ITEM_VIEW_TYPE_HEADER_OR_FOOTER

The item view type returned by Adapter#getItemViewType(int) when the item is a header or footer.

Constant Value: -2 (0xfffffffe)

ITEM_VIEW_TYPE_IGNORE

Added in API level 1
public static final int ITEM_VIEW_TYPE_IGNORE

The item view type returned by Adapter#getItemViewType(int) when the adapter does not want the item's view recycled.

Constant Value: -1 (0xffffffff)

Public constructors

AdapterView

Added in API level 1
public AdapterView (Context context)

Parameters
context Context

AdapterView

Added in API level 1
public AdapterView (Context context, 
                AttributeSet attrs)

Parameters
context Context

attrs AttributeSet

AdapterView

Added in API level 1
public AdapterView (Context context, 
                AttributeSet attrs, 
                int defStyleAttr)

Parameters
context Context

attrs AttributeSet

defStyleAttr int

AdapterView

Added in API level 1
public AdapterView (Context context, 
                AttributeSet attrs, 
                int defStyleAttr, 
                int defStyleRes)

Parameters
context Context

attrs AttributeSet

defStyleAttr int

defStyleRes int

Public methods

addView

Added in API level 1
public void addView (View child, 
                int index)

This method is not supported and throws an UnsupportedOperationException when called.

Parameters
child View: Ignored.

index int: Ignored.

Throws
UnsupportedOperationException Every time this method is invoked.

addView

Added in API level 1
public void addView (View child)

This method is not supported and throws an UnsupportedOperationException when called.

Parameters
child View: Ignored.

Throws
UnsupportedOperationException Every time this method is invoked.

addView

Added in API level 1
public void addView (View child, 
                ViewGroup.LayoutParams params)

This method is not supported and throws an UnsupportedOperationException when called.

Parameters
child View: Ignored.

params ViewGroup.LayoutParams: Ignored.

Throws
UnsupportedOperationException Every time this method is invoked.

addView

Added in API level 1
public void addView (View child, 
                int index, 
                ViewGroup.LayoutParams params)

This method is not supported and throws an UnsupportedOperationException when called.

Parameters
child View: Ignored.

index int: Ignored.

params ViewGroup.LayoutParams: Ignored.

Throws
UnsupportedOperationException Every time this method is invoked.

getAccessibilityClassName

Added in API level 23
public CharSequence getAccessibilityClassName ()

Return the class name of this object to be used for accessibility purposes. Subclasses should only override this if they are implementing something that should be seen as a completely new class of view when used by accessibility, unrelated to the class it is deriving from. This is used to fill in AccessibilityNodeInfo.setClassName.

Returns
CharSequence

getAdapter

Added in API level 1
public abstract T getAdapter ()

Returns the adapter currently associated with this widget.

Returns
T The adapter used to provide this view's content.

getCount

Added in API level 1
public int getCount ()

Returns
int The number of items owned by the Adapter associated with this AdapterView. (This is the number of data items, which may be larger than the number of visible views.)

getEmptyView

Added in API level 1
public View getEmptyView ()

When the current adapter is empty, the AdapterView can display a special view called the empty view. The empty view is used to provide feedback to the user that no data is available in this AdapterView.

Returns
View The view to show if the adapter is empty.

getFirstVisiblePosition

Added in API level 1
public int getFirstVisiblePosition ()

Returns the position within the adapter's data set for the first item displayed on screen.

Returns
int The position within the adapter's data set

getItemAtPosition

Added in API level 1
public Object getItemAtPosition (int position)

Gets the data associated with the specified position in the list.

Parameters
position int: Which data to get

Returns
Object The data associated with the specified position in the list

getItemIdAtPosition

Added in API level 1
public long getItemIdAtPosition (int position)

Parameters
position int

Returns
long

getLastVisiblePosition

Added in API level 1
public int getLastVisiblePosition ()

Returns the position within the adapter's data set for the last item displayed on screen.

Returns
int The position within the adapter's data set

getOnItemClickListener

Added in API level 1
public final AdapterView.OnItemClickListener getOnItemClickListener ()

Returns
AdapterView.OnItemClickListener The callback to be invoked with an item in this AdapterView has been clicked, or null if no callback has been set.

getOnItemLongClickListener

Added in API level 1
public final AdapterView.OnItemLongClickListener getOnItemLongClickListener ()

Returns
AdapterView.OnItemLongClickListener The callback to be invoked with an item in this AdapterView has been clicked and held, or null if no callback has been set.

getOnItemSelectedListener

Added in API level 1
public final AdapterView.OnItemSelectedListener getOnItemSelectedListener ()

Returns
AdapterView.OnItemSelectedListener This value may be null.

getPositionForView

Added in API level 1
public int getPositionForView (View view)

Returns the position within the adapter's data set for the view, where view is a an adapter item or a descendant of an adapter item.

Note: The result of this method only reflects the position of the data bound to view during the most recent layout pass. If the adapter's data set has changed without a subsequent layout pass, the position returned by this method may not match the current position of the data within the adapter.

Parameters
view View: an adapter item, or a descendant of an adapter item. This must be visible in this AdapterView at the time of the call.

Returns
int the position within the adapter's data set of the view, or INVALID_POSITION if the view does not correspond to a list item (or it is not currently visible)

getSelectedItem

Added in API level 1
public Object getSelectedItem ()

Returns
Object The data corresponding to the currently selected item, or null if there is nothing selected.

getSelectedItemId

Added in API level 1
public long getSelectedItemId ()

Returns
long The id corresponding to the currently selected item, or INVALID_ROW_ID if nothing is selected.

getSelectedItemPosition

Added in API level 1
public int getSelectedItemPosition ()

Return the position of the currently selected item within the adapter's data set

Returns
int int Position (starting at 0), or INVALID_POSITION if there is nothing selected.

getSelectedView

Added in API level 1
public abstract View getSelectedView ()

Returns
View The view corresponding to the currently selected item, or null if nothing is selected

onProvideAutofillStructure

Added in API level 26
public void onProvideAutofillStructure (ViewStructure structure, 
                int flags)

Populates a ViewStructure to fullfil an autofill request.

The structure should contain at least the following properties:

It's also recommended to set the following properties - the more properties the structure has, the higher the chances of an AutofillService properly using the structure:

The default implementation of this method already sets most of these properties based on related View methods (for example, the autofill id is set using getAutofillId(), the autofill type set using getAutofillType(), etc.), and views in the standard Android widgets library also override it to set their relevant properties (for example, TextView already sets the text properties), so it's recommended to only override this method (and call super.onProvideAutofillStructure()) when:

Note: The left and top values set in ViewStructure#setDimens(int, int, int, int, int, int) must be relative to the next ViewGroup#isImportantForAutofill() predecessor view included in the structure.

Views support the Autofill Framework mainly by:

  • Providing the metadata defining what the view means and how it can be autofilled.
  • Notifying the Android System when the view value changed by calling AutofillManager#notifyValueChanged(View).
  • Implementing the methods that autofill the view.

This method is responsible for the former; autofill(android.view.autofill.AutofillValue) is responsible for the latter.

It also sets the autofill options in the structure; when overridden, it should set it as well, either explicitly by calling ViewStructure#setAutofillOptions(CharSequence[]) or implicitly by calling super.onProvideAutofillStructure(structure, flags).

Parameters
structure ViewStructure: fill in with structured view data for autofill purposes.

flags int: optional flags. Value is either 0 or View.AUTOFILL_FLAG_INCLUDE_NOT_IMPORTANT_VIEWS

performItemClick

Added in API level 1
public boolean performItemClick (View view, 
                int position, 
                long id)

Call the OnItemClickListener, if it is defined. Performs all normal actions associated with clicking: reporting accessibility event, playing a sound, etc.

Parameters
view View: The view within the AdapterView that was clicked.

position int: The position of the view in the adapter.

id long: The row id of the item that was clicked.

Returns
boolean True if there was an assigned OnItemClickListener that was called, false otherwise is returned.

removeAllViews

Added in API level 1
public void removeAllViews ()

This method is not supported and throws an UnsupportedOperationException when called.

Throws
UnsupportedOperationException Every time this method is invoked.

removeView

Added in API level 1
public void removeView (View child)

This method is not supported and throws an UnsupportedOperationException when called.

Parameters
child View: Ignored.

Throws
UnsupportedOperationException Every time this method is invoked.

removeViewAt

Added in API level 1
public void removeViewAt (int index)

This method is not supported and throws an UnsupportedOperationException when called.

Parameters
index int: Ignored.

Throws
UnsupportedOperationException Every time this method is invoked.

setAdapter

Added in API level 1
public abstract void setAdapter (T adapter)

Sets the adapter that provides the data and the views to represent the data in this widget.

Parameters
adapter T: The adapter to use to create this view's content.

setEmptyView

Added in API level 1
public void setEmptyView (View emptyView)

Sets the view to show if the adapter is empty

Parameters
emptyView View

setFocusable

Added in API level 26
public void setFocusable (int focusable)

Sets whether this view can receive focus.

Setting this to FOCUSABLE_AUTO tells the framework to determine focusability automatically based on the view's interactivity. This is the default.

Setting this to NOT_FOCUSABLE will ensure that this view is also not focusable in touch mode.

Parameters
focusable int: Value is View.NOT_FOCUSABLE, View.FOCUSABLE, or View.FOCUSABLE_AUTO

setFocusableInTouchMode

Added in API level 1
public void setFocusableInTouchMode (boolean focusable)

Set whether this view can receive focus while in touch mode. Setting this to true will also ensure that this view is focusable.

Parameters
focusable boolean: If true, this view can receive the focus while in touch mode.

setOnClickListener

Added in API level 1
public void setOnClickListener (View.OnClickListener l)

Register a callback to be invoked when this view is clicked. If this view is not clickable, it becomes clickable.

Parameters
l View.OnClickListener: The callback that will run This value may be null.

setOnItemClickListener

Added in API level 1
public void setOnItemClickListener (AdapterView.OnItemClickListener listener)

Register a callback to be invoked when an item in this AdapterView has been clicked.

Parameters
listener AdapterView.OnItemClickListener: The callback that will be invoked. This value may be null.

setOnItemLongClickListener

Added in API level 1
public void setOnItemLongClickListener (AdapterView.OnItemLongClickListener listener)

Register a callback to be invoked when an item in this AdapterView has been clicked and held

Parameters
listener AdapterView.OnItemLongClickListener: The callback that will run

setOnItemSelectedListener

Added in API level 1
public void setOnItemSelectedListener (AdapterView.OnItemSelectedListener listener)

Register a callback to be invoked when an item in this AdapterView has been selected.

Parameters
listener AdapterView.OnItemSelectedListener: The callback that will run This value may be null.

setSelection

Added in API level 1
public abstract void setSelection (int position)

Sets the currently selected item. To support accessibility subclasses that override this method must invoke the overridden super method first.

Parameters
position int: Index (starting at 0) of the data item to be selected.

Protected methods

canAnimate

Added in API level 1
protected boolean canAnimate ()

Indicates whether the view group has the ability to animate its children after the first layout.

Returns
boolean true if the children can be animated, false otherwise

dispatchRestoreInstanceState

Added in API level 1
protected void dispatchRestoreInstanceState (SparseArray<Parcelable> container)

Override to prevent thawing of any views created by the adapter.

Parameters
container SparseArray: The SparseArray which holds previously saved state.

dispatchSaveInstanceState

Added in API level 1
protected void dispatchSaveInstanceState (SparseArray<Parcelable> container)

Override to prevent freezing of any views created by the adapter.

Parameters
container SparseArray: The SparseArray in which to save the view's state.

onDetachedFromWindow

Added in API level 1
protected void onDetachedFromWindow ()

This is called when the view is detached from a window. At this point it no longer has a surface for drawing.
If you override this method you must call through to the superclass implementation.

onLayout

Added in API level 1
protected void onLayout (boolean changed, 
                int left, 
                int top, 
                int right, 
                int bottom)

Called from layout when this view should assign a size and position to each of its children. Derived classes with children should override this method and call layout on each of their children.

Parameters
changed boolean: This is a new size or position for this view

left int: Left position, relative to parent

top int: Top position, relative to parent

right int: Right position, relative to parent

bottom int: Bottom position, relative to parent