to top
Android APIs
public class

ListView

extends AbsListView
java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.widget.AdapterView<T extends android.widget.Adapter>
         ↳ android.widget.AbsListView
           ↳ android.widget.ListView
Known Direct Subclasses

Class Overview

A view that shows items in a vertically scrolling list. The items come from the ListAdapter associated with this view.

See the List View guide.

Summary

Nested Classes
class ListView.FixedViewInfo A class that represents a fixed view in a list, for example a header at the top or a footer at the bottom. 
XML Attributes
Attribute Name Related Method Description
android:divider Drawable or color to draw between list items. 
android:dividerHeight Height of the divider. 
android:entries Reference to an array resource that will populate the ListView. 
android:footerDividersEnabled When set to false, the ListView will not draw the divider before each footer view. 
android:headerDividersEnabled When set to false, the ListView will not draw the divider after each header view. 
[Expand]
Inherited XML Attributes
From class android.widget.AbsListView
From class android.view.ViewGroup
From class android.view.View
[Expand]
Inherited Constants
From class android.widget.AbsListView
From class android.widget.AdapterView
From class android.view.ViewGroup
From class android.view.View
[Expand]
Inherited Fields
From class android.view.View
Public Constructors
ListView(Context context)
ListView(Context context, AttributeSet attrs)
ListView(Context context, AttributeSet attrs, int defStyle)
Public Methods
void addFooterView(View v)
Add a fixed view to appear at the bottom of the list.
void addFooterView(View v, Object data, boolean isSelectable)
Add a fixed view to appear at the bottom of the list.
void addHeaderView(View v, Object data, boolean isSelectable)
Add a fixed view to appear at the top of the list.
void addHeaderView(View v)
Add a fixed view to appear at the top of the list.
boolean dispatchKeyEvent(KeyEvent event)
Dispatch a key event to the next view on the focus path.
ListAdapter getAdapter()
Returns the adapter currently in use in this ListView.
long[] getCheckItemIds()
This method was deprecated in API level 8. Use getCheckedItemIds() instead.
Drawable getDivider()
Returns the drawable that will be drawn between each item in the list.
int getDividerHeight()
int getFooterViewsCount()
Returns the number of footer views in the list.
int getHeaderViewsCount()
Returns the number of header views in the list.
boolean getItemsCanFocus()
int getMaxScrollAmount()
Drawable getOverscrollFooter()
Drawable getOverscrollHeader()
boolean isOpaque()
Indicates whether this View is opaque.
void onInitializeAccessibilityEvent(AccessibilityEvent event)
Initializes an AccessibilityEvent with information about this View which is the event source.
void onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info)
Initializes an AccessibilityNodeInfo with information about this view.
boolean onKeyDown(int keyCode, KeyEvent event)
Default implementation of KeyEvent.Callback.onKeyDown(): perform press of the view when KEYCODE_DPAD_CENTER or KEYCODE_ENTER is released, if the view is enabled and clickable.
boolean onKeyMultiple(int keyCode, int repeatCount, KeyEvent event)
Default implementation of KeyEvent.Callback.onKeyMultiple(): always returns false (doesn't handle the event).
boolean onKeyUp(int keyCode, KeyEvent event)
Default implementation of KeyEvent.Callback.onKeyUp(): perform clicking of the view when KEYCODE_DPAD_CENTER or KEYCODE_ENTER is released.
boolean removeFooterView(View v)
Removes a previously-added footer view.
boolean removeHeaderView(View v)
Removes a previously-added header view.
boolean requestChildRectangleOnScreen(View child, Rect rect, boolean immediate)
Called when a child of this group wants a particular rectangle to be positioned onto the screen.
void setAdapter(ListAdapter adapter)
Sets the data behind this ListView.
void setCacheColorHint(int color)
When set to a non-zero value, the cache color hint indicates that this list is always drawn on top of a solid, single-color, opaque background.
void setDivider(Drawable divider)
Sets the drawable that will be drawn between each item in the list.
void setDividerHeight(int height)
Sets the height of the divider that will be drawn between each item in the list.
void setFooterDividersEnabled(boolean footerDividersEnabled)
Enables or disables the drawing of the divider for footer views.
void setHeaderDividersEnabled(boolean headerDividersEnabled)
Enables or disables the drawing of the divider for header views.
void setItemsCanFocus(boolean itemsCanFocus)
Indicates that the views created by the ListAdapter can contain focusable items.
void setOverscrollFooter(Drawable footer)
Sets the drawable that will be drawn below all other list content.
void setOverscrollHeader(Drawable header)
Sets the drawable that will be drawn above all other list content.
void setRemoteViewsAdapter(Intent intent)
Sets up this AbsListView to use a remote views adapter which connects to a RemoteViewsService through the specified intent.
void setSelection(int position)
Sets the currently selected item.
void setSelectionAfterHeaderView()
setSelectionAfterHeaderView set the selection to be the first list item after the header views.
void setSelectionFromTop(int position, int y)
Sets the selected item and positions the selection y pixels from the top edge of the ListView.
void smoothScrollByOffset(int offset)
Smoothly scroll to the specified adapter position offset.
void smoothScrollToPosition(int position)
Smoothly scroll to the specified adapter position.
Protected Methods
boolean canAnimate()
Indicates whether the view group has the ability to animate its children after the first layout.
void dispatchDraw(Canvas canvas)
Called by draw to draw the child views.
boolean drawChild(Canvas canvas, View child, long drawingTime)
Draw one child of this View Group.
View findViewTraversal(int id)
View findViewWithTagTraversal(Object tag)
void layoutChildren()
Subclasses must override this method to layout their children.
void onFinishInflate()
Finalize inflating a view from XML.
void onFocusChanged(boolean gainFocus, int direction, Rect previouslyFocusedRect)
Called by the view system when the focus state of this view changes.
void onMeasure(int widthMeasureSpec, int heightMeasureSpec)

Measure the view and its content to determine the measured width and the measured height.

void onSizeChanged(int w, int h, int oldw, int oldh)
This is called during layout when the size of this view has changed.
[Expand]
Inherited Methods
From class android.widget.AbsListView
From class android.widget.AdapterView
From class android.view.ViewGroup
From class android.view.View
From class java.lang.Object
From interface android.graphics.drawable.Drawable.Callback
From interface android.text.TextWatcher
From interface android.view.KeyEvent.Callback
From interface android.view.ViewManager
From interface android.view.ViewParent
From interface android.view.ViewTreeObserver.OnGlobalLayoutListener
From interface android.view.ViewTreeObserver.OnTouchModeChangeListener
From interface android.view.accessibility.AccessibilityEventSource
From interface android.widget.Filter.FilterListener

XML Attributes

android:divider

Drawable or color to draw between list items.

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

Related Methods

android:dividerHeight

Height of the divider. Will use the intrinsic height of the divider if this is not specified.

Must be a dimension value, which is a floating point number appended with a unit such as "14.5sp". Available units are: px (pixels), dp (density-independent pixels), sp (scaled pixels based on preferred font size), in (inches), mm (millimeters).

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

Related Methods

android:entries

Reference to an array resource that will populate the ListView. For static content, this is simpler than populating the ListView programmatically.

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

Related Methods

android:footerDividersEnabled

When set to false, the ListView will not draw the divider before each footer view. The default value is true.

Must be a boolean value, either "true" or "false".

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

Related Methods

android:headerDividersEnabled

When set to false, the ListView will not draw the divider after each header view. The default value is true.

Must be a boolean value, either "true" or "false".

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

Related Methods

Public Constructors

public ListView (Context context)

Added in API level 1

public ListView (Context context, AttributeSet attrs)

Added in API level 1

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

Added in API level 1

Public Methods

public void addFooterView (View v)

Added in API level 1

Add a fixed view to appear at the bottom of the list. If addFooterView is called more than once, the views will appear in the order they were added. Views added using this call can take focus if they want.

NOTE: Call this before calling setAdapter. This is so ListView can wrap the supplied cursor with one that will also account for header and footer views.

Parameters
v The view to add.

public void addFooterView (View v, Object data, boolean isSelectable)

Added in API level 1

Add a fixed view to appear at the bottom of the list. If addFooterView is called more than once, the views will appear in the order they were added. Views added using this call can take focus if they want.

NOTE: Call this before calling setAdapter. This is so ListView can wrap the supplied cursor with one that will also account for header and footer views.

Parameters
v The view to add.
data Data to associate with this view
isSelectable true if the footer view can be selected

public void addHeaderView (View v, Object data, boolean isSelectable)

Added in API level 1

Add a fixed view to appear at the top of the list. If addHeaderView is called more than once, the views will appear in the order they were added. Views added using this call can take focus if they want.

NOTE: Call this before calling setAdapter. This is so ListView can wrap the supplied cursor with one that will also account for header and footer views.

Parameters
v The view to add.
data Data to associate with this view
isSelectable whether the item is selectable

public void addHeaderView (View v)

Added in API level 1

Add a fixed view to appear at the top of the list. If addHeaderView is called more than once, the views will appear in the order they were added. Views added using this call can take focus if they want.

NOTE: Call this before calling setAdapter. This is so ListView can wrap the supplied cursor with one that will also account for header and footer views.

Parameters
v The view to add.

public boolean dispatchKeyEvent (KeyEvent event)

Added in API level 1

Dispatch a key event to the next view on the focus path. This path runs from the top of the view tree down to the currently focused view. If this view has focus, it will dispatch to itself. Otherwise it will dispatch the next node down the focus path. This method also fires any key listeners.

Parameters
event The key event to be dispatched.
Returns
  • True if the event was handled, false otherwise.

public ListAdapter getAdapter ()

Added in API level 1

Returns the adapter currently in use in this ListView. The returned adapter might not be the same adapter passed to setAdapter(ListAdapter) but might be a WrapperListAdapter.

Returns
  • The adapter currently used to display data in this ListView.
See Also

public long[] getCheckItemIds ()

Added in API level 4

This method was deprecated in API level 8.
Use getCheckedItemIds() instead.

Returns the set of checked items ids. The result is only valid if the choice mode has not been set to CHOICE_MODE_NONE.

Returns
  • A new array which contains the id of each checked item in the list.

public Drawable getDivider ()

Added in API level 1

Returns the drawable that will be drawn between each item in the list.

Returns
  • the current drawable drawn between list elements

public int getDividerHeight ()

Added in API level 1

Returns
  • Returns the height of the divider that will be drawn between each item in the list.

public int getFooterViewsCount ()

Added in API level 1

Returns the number of footer views in the list. Footer views are special views at the bottom of the list that should not be recycled during a layout.

Returns
  • The number of footer views, 0 in the default implementation.

public int getHeaderViewsCount ()

Added in API level 1

Returns the number of header views in the list. Header views are special views at the top of the list that should not be recycled during a layout.

Returns
  • The number of header views, 0 in the default implementation.

public boolean getItemsCanFocus ()

Added in API level 1

Returns
  • Whether the views created by the ListAdapter can contain focusable items.

public int getMaxScrollAmount ()

Added in API level 1

Returns
  • The maximum amount a list view will scroll in response to an arrow event.

public Drawable getOverscrollFooter ()

Added in API level 9

Returns
  • The drawable that will be drawn below all other list content

public Drawable getOverscrollHeader ()

Added in API level 9

Returns
  • The drawable that will be drawn above all other list content

public boolean isOpaque ()

Added in API level 7

Indicates whether this View is opaque. An opaque View guarantees that it will draw all the pixels overlapping its bounds using a fully opaque color. Subclasses of View should override this method whenever possible to indicate whether an instance is opaque. Opaque Views are treated in a special way by the View hierarchy, possibly allowing it to perform optimizations during invalidate/draw passes.

Returns
  • True if this View is guaranteed to be fully opaque, false otherwise.

public void onInitializeAccessibilityEvent (AccessibilityEvent event)

Added in API level 14

Initializes an AccessibilityEvent with information about this View which is the event source. In other words, the source of an accessibility event is the view whose state change triggered firing the event.

Example: Setting the password property of an event in addition to properties set by the super implementation: 

 public void onInitializeAccessibilityEvent(AccessibilityEvent event) {
     super.onInitializeAccessibilityEvent(event);
     event.setPassword(true);
 }

If an View.AccessibilityDelegate has been specified via calling setAccessibilityDelegate(AccessibilityDelegate) its onInitializeAccessibilityEvent(View, AccessibilityEvent) is responsible for handling this call.

Note: Always call the super implementation before adding information to the event, in case the default implementation has basic information to add.

Parameters
event The event to initialize.

public void onInitializeAccessibilityNodeInfo (AccessibilityNodeInfo info)

Added in API level 14

Initializes an AccessibilityNodeInfo with information about this view. The base implementation sets:

Subclasses should override this method, call the super implementation, and set additional attributes.

If an View.AccessibilityDelegate has been specified via calling setAccessibilityDelegate(AccessibilityDelegate) its onInitializeAccessibilityNodeInfo(View, AccessibilityNodeInfo) is responsible for handling this call.

Parameters
info The instance to initialize.

public boolean onKeyDown (int keyCode, KeyEvent event)

Added in API level 1

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

Key presses in software keyboards will generally NOT trigger this listener, although some may elect to do so in some situations. Do not rely on this to catch software key presses.

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.

public boolean onKeyMultiple (int keyCode, int repeatCount, KeyEvent event)

Added in API level 1

Default implementation of KeyEvent.Callback.onKeyMultiple(): always returns false (doesn't handle the event).

Key presses in software keyboards will generally NOT trigger this listener, although some may elect to do so in some situations. Do not rely on this to catch software key presses.

Parameters
keyCode A key code that represents the button pressed, from KeyEvent.
repeatCount The number of times the action was made.
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.

public boolean onKeyUp (int keyCode, KeyEvent event)

Added in API level 1

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

Key presses in software keyboards will generally NOT trigger this listener, although some may elect to do so in some situations. Do not rely on this to catch software key presses.

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.

public boolean removeFooterView (View v)

Added in API level 1

Removes a previously-added footer view.

Parameters
v The view to remove
Returns
  • true if the view was removed, false if the view was not a footer view

public boolean removeHeaderView (View v)

Added in API level 1

Removes a previously-added header view.

Parameters
v The view to remove
Returns
  • true if the view was removed, false if the view was not a header view

public boolean requestChildRectangleOnScreen (View child, Rect rect, boolean immediate)

Added in API level 1

Called when a child of this group wants a particular rectangle to be positioned onto the screen. ViewGroups overriding this can trust that:

  • child will be a direct child of this group
  • rectangle will be in the child's coordinates

ViewGroups overriding this should uphold the contract:

  • nothing will change if the rectangle is already visible
  • the view port will be scrolled only just enough to make the rectangle visible

Parameters
child The direct child making the request.
rect The rectangle in the child's coordinates the child wishes to be on the screen.
immediate True to forbid animated or delayed scrolling, false otherwise
Returns
  • Whether the group scrolled to handle the operation

public void setAdapter (ListAdapter adapter)

Added in API level 1

Sets the data behind this ListView. The adapter passed to this method may be wrapped by a WrapperListAdapter, depending on the ListView features currently in use. For instance, adding headers and/or footers will cause the adapter to be wrapped.

Parameters
adapter The ListAdapter which is responsible for maintaining the data backing this list and for producing a view to represent an item in that data set.
See Also

public void setCacheColorHint (int color)

Added in API level 1

When set to a non-zero value, the cache color hint indicates that this list is always drawn on top of a solid, single-color, opaque background. Zero means that what's behind this object is translucent (non solid) or is not made of a single color. This hint will not affect any existing background drawable set on this view ( typically set via setBackgroundDrawable(Drawable)).

Parameters
color The background color

public void setDivider (Drawable divider)

Added in API level 1

Sets the drawable that will be drawn between each item in the list. If the drawable does not have an intrinsic height, you should also call setDividerHeight(int)

Parameters
divider The drawable to use.

public void setDividerHeight (int height)

Added in API level 1

Sets the height of the divider that will be drawn between each item in the list. Calling this will override the intrinsic height as set by setDivider(Drawable)

Parameters
height The new height of the divider in pixels.

public void setFooterDividersEnabled (boolean footerDividersEnabled)

Added in API level 3

Enables or disables the drawing of the divider for footer views.

Parameters
footerDividersEnabled True to draw the footers, false otherwise.
See Also

public void setHeaderDividersEnabled (boolean headerDividersEnabled)

Added in API level 3

Enables or disables the drawing of the divider for header views.

Parameters
headerDividersEnabled True to draw the headers, false otherwise.
See Also

public void setItemsCanFocus (boolean itemsCanFocus)

Added in API level 1

Indicates that the views created by the ListAdapter can contain focusable items.

Parameters
itemsCanFocus true if items can get focus, false otherwise

public void setOverscrollFooter (Drawable footer)

Added in API level 9

Sets the drawable that will be drawn below all other list content. This area can become visible when the user overscrolls the list, or when the list's content does not fully fill the container area.

Parameters
footer The drawable to use

public void setOverscrollHeader (Drawable header)

Added in API level 9

Sets the drawable that will be drawn above all other list content. This area can become visible when the user overscrolls the list.

Parameters
header The drawable to use

public void setRemoteViewsAdapter (Intent intent)

Added in API level 11

Sets up this AbsListView to use a remote views adapter which connects to a RemoteViewsService through the specified intent.

Parameters
intent the intent used to identify the RemoteViewsService for the adapter to connect to.

public void setSelection (int position)

Added in API level 1

Sets the currently selected item. If in touch mode, the item will not be selected but it will still be positioned appropriately. If the specified selection position is less than 0, then the item at position 0 will be selected.

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

public void setSelectionAfterHeaderView ()

Added in API level 1

setSelectionAfterHeaderView set the selection to be the first list item after the header views.

public void setSelectionFromTop (int position, int y)

Added in API level 1

Sets the selected item and positions the selection y pixels from the top edge of the ListView. (If in touch mode, the item will not be selected but it will still be positioned appropriately.)

Parameters
position Index (starting at 0) of the data item to be selected.
y The distance from the top edge of the ListView (plus padding) that the item will be positioned.

public void smoothScrollByOffset (int offset)

Added in API level 11

Smoothly scroll to the specified adapter position offset. The view will scroll such that the indicated position is displayed.

Parameters
offset The amount to offset from the adapter position to scroll to.

public void smoothScrollToPosition (int position)

Added in API level 8

Smoothly scroll to the specified adapter position. The view will scroll such that the indicated position is displayed.

Parameters
position Scroll to this adapter position.

Protected Methods

protected boolean canAnimate ()

Added in API level 1

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

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

protected void dispatchDraw (Canvas canvas)

Added in API level 1

Called by draw to draw the child views. This may be overridden by derived classes to gain control just before its children are drawn (but after its own view has been drawn).

Parameters
canvas the canvas on which to draw the view

protected boolean drawChild (Canvas canvas, View child, long drawingTime)

Added in API level 1

Draw one child of this View Group. This method is responsible for getting the canvas in the right state. This includes clipping, translating so that the child's scrolled origin is at 0, 0, and applying any animation transformations.

Parameters
canvas The canvas on which to draw the child
child Who to draw
drawingTime The time at which draw is occurring
Returns
  • True if an invalidate() was issued

protected View findViewTraversal (int id)

Added in API level 1

Parameters
id the id of the view to be found
Returns
  • the view of the specified id, null if cannot be found

protected View findViewWithTagTraversal (Object tag)

Added in API level 1

Parameters
tag the tag of the view to be found
Returns
  • the view of specified tag, null if cannot be found

protected void layoutChildren ()

Added in API level 1

Subclasses must override this method to layout their children.

protected void onFinishInflate ()

Added in API level 1

Finalize inflating a view from XML. This is called as the last phase of inflation, after all child views have been added.

Even if the subclass overrides onFinishInflate, they should always be sure to call the super method, so that we get called.

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

Added in API level 1

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. When overriding, be sure to call up through to the super class so that the standard focus handling will occur.

Parameters
gainFocus 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 FOCUS_UP, FOCUS_DOWN, FOCUS_LEFT, FOCUS_RIGHT, FOCUS_FORWARD, or FOCUS_BACKWARD. 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 onMeasure (int widthMeasureSpec, int heightMeasureSpec)

Added in API level 1

Measure the view and its content to determine the measured width and the measured height. This method is invoked by measure(int, int) and should be overriden by subclasses to provide accurate and efficient measurement of their contents.

CONTRACT: When overriding this method, you must call setMeasuredDimension(int, int) to store the measured width and height of this view. Failure to do so will trigger an IllegalStateException, thrown by measure(int, int). Calling the superclass' onMeasure(int, int) is a valid use.

The base class implementation of measure defaults to the background size, unless a larger size is allowed by the MeasureSpec. Subclasses should override onMeasure(int, int) to provide better measurements of their content.

If this method is overridden, it is the subclass's responsibility to make sure the measured height and width are at least the view's minimum height and width (getSuggestedMinimumHeight() and getSuggestedMinimumWidth()).

Parameters
widthMeasureSpec horizontal space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.
heightMeasureSpec vertical space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.

protected void onSizeChanged (int w, int h, int oldw, int oldh)

Added in API level 1

This is called during layout when the size of this view has changed. If you were just added to the view hierarchy, you're called with the old values of 0.

Parameters
w Current width of this view.
h Current height of this view.
oldw Old width of this view.
oldh Old height of this view.