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 immediately below 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

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

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 top 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 Boolean

open Boolean

open Boolean

Dispatch a key event to the next view on the focus path.

open CharSequence!

A TYPE_VIEW_SCROLLED event should be sent whenever a scroll happens, even if the mFirstPosition and the child count have not changed.

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

Indicates whether this View is opaque.

open Unit

Initializes an AccessibilityNodeInfo with information about a particular item in the list.

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

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

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

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

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

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

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)

Called when a child of this group wants a particular rectangle to be positioned onto the screen.

open Unit

Sets the data behind this ListView.

open Unit

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.

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

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

open Unit

Called by draw to draw the child views.

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

Draw one child of this View Group.

open Unit

Subclasses must override this method to layout their children.

open Unit

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

open Unit

Finalize inflating a view from XML.

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

Called by the view system when the focus state of this view changes.

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

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

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

This is called during layout when the size of this view has changed.

Inherited functions