Added in API level 1

ListView

open class ListView : AbsListView
kotlin.Any
   ↳ android.view.View
   ↳ android.view.ViewGroup
   ↳ android.widget.AdapterView<android.widget.ListAdapter>
   ↳ android.widget.AbsListView
   ↳ android.widget.ListView

Displays a vertically-scrollable collection of views, where each view is positioned immediatelybelow the previous view in the list. For a more modern, flexible, and performant approach to displaying lists, use androidx.recyclerview.widget.RecyclerView.

To display a list, you can include a list view in your layout XML file:

<ListView
       android:id="@+id/list_view"
       android:layout_width="match_parent"
       android:layout_height="match_parent" />

A list view is an adapter view that does not know the details, such as type and contents, of the views it contains. Instead list view requests views on demand from a ListAdapter as needed, such as to display new views as the user scrolls up or down.

In order to display items in the list, call setAdapter(android.widget.ListAdapter) to associate an adapter with the list. For a simple example, see the discussion of filling an adapter view with text in the Layouts guide.

To display a more custom view for each item in your dataset, implement a ListAdapter. For example, extend BaseAdapter and create and configure the view for each data item in getView(...):

private class MyAdapter extends BaseAdapter {
 
       // override other abstract methods here
 
       @Override
       public View getView(int position, View convertView, ViewGroup container) {
           if (convertView == null) {
               convertView = getLayoutInflater().inflate(R.layout.list_item, container, false);
           }
 
           ((TextView) convertView.findViewById(android.R.id.text1))
                   .setText(getItem(position));
           return convertView;
       }
   }

ListView attempts to reuse view objects in order to improve performance and avoid a lag in response to user scrolls. To take advantage of this feature, check if the convertView provided to getView(...) is null before creating or inflating a new view object.

To specify an action when a user clicks or taps on a single list item, see Handling click events.

To learn how to populate a list view with a CursorAdapter, see the discussion of filling an adapter view with text in the Layouts guide. See Using a Loader to learn how to avoid blocking the main thread when using a cursor.

Note, many examples use ListActivity or ListFragment to display a list view. Instead, favor the more flexible approach when writing your own app: use a more generic Activity subclass or Fragment subclass and add a list view to the layout or view hierarchy directly. This approach gives you more direct control of the list view and adapter.

Summary

Nested classes
open

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
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.
Inherited XML attributes
Inherited constants
Public constructors
ListView(context: Context!)

ListView(context: Context!, attrs: AttributeSet!)

ListView(context: Context!, attrs: AttributeSet!, defStyleAttr: Int)

ListView(context: Context!, attrs: AttributeSet!, defStyleAttr: Int, defStyleRes: Int)

Public methods
open Unit
addFooterView(v: View!, data: Any!, isSelectable: Boolean)

Add a fixed view to appear at the bottom of the list.

open Unit

Add a fixed view to appear at the bottom of the list.

open Unit
addHeaderView(v: View!, data: Any!, isSelectable: Boolean)

Add a fixed view to appear at the top of the list.

open Unit

Add a fixed view to appear at the top of the list.

open Boolean

open Boolean

open Boolean

open CharSequence!

open ListAdapter!

Returns the adapter currently in use in this ListView.

open LongArray!

Returns the set of checked items ids.

open Drawable?

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

open Int

open Int

open Int

open Boolean

open Int

open Drawable!

open Drawable!

open Boolean

open Unit

open Boolean
onKeyDown(keyCode: Int, event: KeyEvent!)

open Boolean
onKeyMultiple(keyCode: Int, repeatCount: Int, event: KeyEvent!)

open Boolean
onKeyUp(keyCode: Int, event: KeyEvent!)

open Boolean

Removes a previously-added footer view.

open Boolean

Removes a previously-added header view.

open Boolean
requestChildRectangleOnScreen(child: View, rect: Rect!, immediate: Boolean)

open Unit

Sets the data behind this ListView.

open Unit

open Unit
setDivider(divider: Drawable?)

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

open Unit

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

open Unit
setFooterDividersEnabled(footerDividersEnabled: Boolean)

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

open Unit
setHeaderDividersEnabled(headerDividersEnabled: Boolean)

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

open Unit
setItemsCanFocus(itemsCanFocus: Boolean)

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

open Unit

Sets the drawable that will be drawn below all other list content.

open Unit

Sets the drawable that will be drawn above all other list content.

open Unit

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

open Unit
setSelection(position: Int)

Sets the currently selected item.

open Unit

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

open Unit

Smoothly scroll to the specified adapter position offset.

open Unit

Smoothly scroll to the specified adapter position.

Protected methods
open Boolean

open Unit

open Boolean
drawChild(canvas: Canvas, child: View!, drawingTime: Long)

open Unit

open Unit

open Unit

open Unit
onFocusChanged(gainFocus: Boolean, direction: Int, previouslyFocusedRect: Rect?)

open Unit
onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int)

open Unit
onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int)

Inherited functions
Inherited properties

XML attributes

android:divider

android:divider
Drawable or color to draw between list items.

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

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

android:dividerHeight

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

May 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), and mm (millimeters).

android:entries

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

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

android:footerDividersEnabled

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

May be a boolean value, such as "true" or "false".

android:headerDividersEnabled

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

May be a boolean value, such as "true" or "false".

Public constructors

ListView

Added in API level 1
ListView(context: Context!)

ListView

Added in API level 1
ListView(
    context: Context!,
    attrs: AttributeSet!)

ListView

Added in API level 1
ListView(
    context: Context!,
    attrs: AttributeSet!,
    defStyleAttr: Int)

ListView

Added in API level 1
ListView(
    context: Context!,
    attrs: AttributeSet!,
    defStyleAttr: Int,
    defStyleRes: Int)

Public methods

addFooterView

Added in API level 1
open fun addFooterView(
    v: View!,
    data: Any!,
    isSelectable: Boolean
): Unit

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: When first introduced, this method could only be called before setting the adapter with setAdapter(android.widget.ListAdapter). Starting with android.os.Build.VERSION_CODES#KITKAT, this method may be called at any time. If the ListView's adapter does not extend HeaderViewListAdapter, it will be wrapped with a supporting instance of WrapperListAdapter.

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

addFooterView

Added in API level 1
open fun addFooterView(v: View!): Unit

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: When first introduced, this method could only be called before setting the adapter with setAdapter(android.widget.ListAdapter). Starting with android.os.Build.VERSION_CODES#KITKAT, this method may be called at any time. If the ListView's adapter does not extend HeaderViewListAdapter, it will be wrapped with a supporting instance of WrapperListAdapter.

Parameters
v View!: The view to add.

addHeaderView

Added in API level 1
open fun addHeaderView(
    v: View!,
    data: Any!,
    isSelectable: Boolean
): Unit

Add a fixed view to appear at the top of the list. If this method 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: When first introduced, this method could only be called before setting the adapter with setAdapter(android.widget.ListAdapter). Starting with android.os.Build.VERSION_CODES#KITKAT, this method may be called at any time. If the ListView's adapter does not extend HeaderViewListAdapter, it will be wrapped with a supporting instance of WrapperListAdapter.

Parameters
v View!: The view to add.
data Any!: Data to associate with this view
isSelectable Boolean: whether the item is selectable

addHeaderView

Added in API level 1
open fun addHeaderView(v: View!): Unit

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: When first introduced, this method could only be called before setting the adapter with setAdapter(android.widget.ListAdapter). Starting with android.os.Build.VERSION_CODES#KITKAT, this method may be called at any time. If the ListView's adapter does not extend HeaderViewListAdapter, it will be wrapped with a supporting instance of WrapperListAdapter.

Parameters
v View!: The view to add.

areFooterDividersEnabled

Added in API level 19
open fun areFooterDividersEnabled(): Boolean
Return
Boolean Whether the drawing of the divider for footer views is enabled

areHeaderDividersEnabled

Added in API level 19
open fun areHeaderDividersEnabled(): Boolean
Return
Boolean Whether the drawing of the divider for header views is enabled

dispatchKeyEvent

Added in API level 1
open fun dispatchKeyEvent(event: KeyEvent!): Boolean
Parameters
event KeyEvent!: The key event to be dispatched.
Return
Boolean True if the event was handled, false otherwise.

getAccessibilityClassName

Added in API level 23
open fun getAccessibilityClassName(): CharSequence!

getAdapter

Added in API level 1
open fun getAdapter(): ListAdapter!

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

Return
ListAdapter! The adapter currently used to display data in this ListView.

getCheckItemIds

Added in API level 4
Deprecated in API level 15
open fun getCheckItemIds(): LongArray!

Deprecated: 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.

Return
LongArray! A new array which contains the id of each checked item in the list.

getDivider

Added in API level 1
open fun getDivider(): Drawable?

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

Return
Drawable? the current drawable drawn between list elements This value may be null.

getDividerHeight

Added in API level 1
open fun getDividerHeight(): Int
Return
Int Returns the height of the divider that will be drawn between each item in the list.

getFooterViewsCount

Added in API level 1
open fun getFooterViewsCount(): Int

getHeaderViewsCount

Added in API level 1
open fun getHeaderViewsCount(): Int

getItemsCanFocus

Added in API level 1
open fun getItemsCanFocus(): Boolean
Return
Boolean Whether the views created by the ListAdapter can contain focusable items.

getMaxScrollAmount

Added in API level 1
open fun getMaxScrollAmount(): Int
Return
Int The maximum amount a list view will scroll in response to an arrow event.

getOverscrollFooter

Added in API level 9
open fun getOverscrollFooter(): Drawable!
Return
Drawable! The drawable that will be drawn below all other list content

getOverscrollHeader

Added in API level 9
open fun getOverscrollHeader(): Drawable!
Return
Drawable! The drawable that will be drawn above all other list content

isOpaque

Added in API level 7
open fun isOpaque(): Boolean
Return
Boolean True if this View is guaranteed to be fully opaque, false otherwise.

onInitializeAccessibilityNodeInfoForItem

Added in API level 19
open fun onInitializeAccessibilityNodeInfoForItem(
    view: View!,
    position: Int,
    info: AccessibilityNodeInfo!
): Unit
Parameters
view View!: View representing the list item.
position Int: Position of the list item within the adapter.
info AccessibilityNodeInfo!: Node info to populate.

onKeyDown

Added in API level 1
open fun onKeyDown(
    keyCode: Int,
    event: KeyEvent!
): Boolean
Parameters
keyCode Int: a key code that represents the button pressed, from android.view.KeyEvent
event KeyEvent!: the KeyEvent object that defines the button action
Return
Boolean If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

onKeyMultiple

Added in API level 1
open fun onKeyMultiple(
    keyCode: Int,
    repeatCount: Int,
    event: KeyEvent!
): Boolean
Parameters
keyCode Int: A key code that represents the button pressed, from android.view.KeyEvent.
count Number of pairs as returned by event.getRepeatCount().
event KeyEvent!: The KeyEvent object that defines the button action.
repeatCount Int: The number of times the action was made.
Return
Boolean If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

onKeyUp

Added in API level 1
open fun onKeyUp(
    keyCode: Int,
    event: KeyEvent!
): Boolean
Parameters
keyCode Int: A key code that represents the button pressed, from android.view.KeyEvent.
event KeyEvent!: The KeyEvent object that defines the button action.
Return
Boolean If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

removeFooterView

Added in API level 1
open fun removeFooterView(v: View!): Boolean

Removes a previously-added footer view.

Parameters
v View!: The view to remove
Return
Boolean true if the view was removed, false if the view was not a footer view

removeHeaderView

Added in API level 1
open fun removeHeaderView(v: View!): Boolean

Removes a previously-added header view.

Parameters
v View!: The view to remove
Return
Boolean true if the view was removed, false if the view was not a header view

requestChildRectangleOnScreen

Added in API level 1
open fun requestChildRectangleOnScreen(
    child: View,
    rect: Rect!,
    immediate: Boolean
): Boolean
Parameters
child View: The direct child making the request. This value cannot be null.
rectangle The rectangle in the child's coordinates the child wishes to be on the screen.
immediate Boolean: True to forbid animated or delayed scrolling, false otherwise
Return
Boolean Whether the group scrolled to handle the operation

setAdapter

Added in API level 1
open fun setAdapter(adapter: ListAdapter!): Unit

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 ListAdapter!: 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

setCacheColorHint

Added in API level 1
open fun setCacheColorHint(color: Int): Unit
Parameters
color Int: The background color

setDivider

Added in API level 1
open fun setDivider(divider: Drawable?): Unit

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

Note: If the drawable does not have an intrinsic height, you should also call setDividerHeight(int).

Parameters
divider Drawable?: the drawable to use This value may be null.

setDividerHeight

Added in API level 1
open fun setDividerHeight(height: Int): Unit

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(android.graphics.drawable.Drawable)

Parameters
height Int: The new height of the divider in pixels.

setFooterDividersEnabled

Added in API level 3
open fun setFooterDividersEnabled(footerDividersEnabled: Boolean): Unit

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

Parameters
footerDividersEnabled Boolean: True to draw the footers, false otherwise.

setHeaderDividersEnabled

Added in API level 3
open fun setHeaderDividersEnabled(headerDividersEnabled: Boolean): Unit

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

Parameters
headerDividersEnabled Boolean: True to draw the headers, false otherwise.

setItemsCanFocus

Added in API level 1
open fun setItemsCanFocus(itemsCanFocus: Boolean): Unit

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

Parameters
itemsCanFocus Boolean: true if items can get focus, false otherwise

setOverscrollFooter

Added in API level 9
open fun setOverscrollFooter(footer: Drawable!): Unit

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 Drawable!: The drawable to use

setOverscrollHeader

Added in API level 9
open fun setOverscrollHeader(header: Drawable!): Unit

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 Drawable!: The drawable to use

setRemoteViewsAdapter

Added in API level 11
open fun setRemoteViewsAdapter(intent: Intent!): Unit

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

Parameters
intent Intent!: the intent used to identify the RemoteViewsService for the adapter to connect to.

setSelection

Added in API level 1
open fun setSelection(position: Int): Unit

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 Int: Index (starting at 0) of the data item to be selected.

setSelectionAfterHeaderView

Added in API level 1
open fun setSelectionAfterHeaderView(): Unit

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

smoothScrollByOffset

Added in API level 11
open fun smoothScrollByOffset(offset: Int): Unit

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

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

smoothScrollToPosition

Added in API level 8
open fun smoothScrollToPosition(position: Int): Unit

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

Parameters
position Int: Scroll to this adapter position.

Protected methods

canAnimate

Added in API level 1
protected open fun canAnimate(): Boolean
Return
Boolean true if the children can be animated, false otherwise

dispatchDraw

Added in API level 1
protected open fun dispatchDraw(canvas: Canvas): Unit
Parameters
canvas Canvas: This value cannot be null.

drawChild

Added in API level 1
protected open fun drawChild(
    canvas: Canvas,
    child: View!,
    drawingTime: Long
): Boolean
Parameters
canvas Canvas: The canvas on which to draw the child This value cannot be null.
child View!: Who to draw
drawingTime Long: The time at which draw is occurring
Return
Boolean True if an invalidate() was issued

layoutChildren

Added in API level 1
protected open fun layoutChildren(): Unit

onDetachedFromWindow

Added in API level 1
protected open fun onDetachedFromWindow(): Unit

onFinishInflate

Added in API level 1
protected open fun onFinishInflate(): Unit

onFocusChanged

Added in API level 1
protected open fun onFocusChanged(
    gainFocus: Boolean,
    direction: Int,
    previouslyFocusedRect: Rect?
): Unit
Parameters
gainFocus Boolean: True if the View has focus; false otherwise.
direction Int: 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. Value is android.view.View#FOCUS_BACKWARD, android.view.View#FOCUS_FORWARD, android.view.View#FOCUS_LEFT, android.view.View#FOCUS_UP, android.view.View#FOCUS_RIGHT, or android.view.View#FOCUS_DOWN
previouslyFocusedRect Rect?: 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.

onMeasure

Added in API level 1
protected open fun onMeasure(
    widthMeasureSpec: Int,
    heightMeasureSpec: Int
): Unit
Parameters
widthMeasureSpec Int: horizontal space requirements as imposed by the parent. The requirements are encoded with android.view.View.MeasureSpec.
heightMeasureSpec Int: vertical space requirements as imposed by the parent. The requirements are encoded with android.view.View.MeasureSpec.

onSizeChanged

Added in API level 1
protected open fun onSizeChanged(
    w: Int,
    h: Int,
    oldw: Int,
    oldh: Int
): Unit
Parameters
w Int: Current width of this view.
h Int: Current height of this view.
oldw Int: Old width of this view.
oldh Int: Old height of this view.