From a3aa879166ea9d7405e07b0927ed3e2201141e65 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Mon, 24 Apr 2017 16:16:29 -0700 Subject: [PATCH] docs: Update ListView JavaDoc comments - Use more active and descriptive terms in first-line description - Recommend using RecyclerView - Add XML example code - Direct reader to set an adapter to populate list with views - Add pre tags to XML code snippet - Give example of displaying more complex views in list - Add aside about using convertView if provided - Link to guide on handling click events - Add cross-link to contextual action mode guide - Reframe link to list view guide - Advise reader to favor alternative approach to using ListActivity - Add paragraph tags - Escape @ symbol - Fix sentence fragment and change modern -> advanced - Fix title of cross-reference to layout guide - Remove reference to filename - Remove cross-link to contextual action mode - Fix malformed link tag - Add connecting word - Clean up links Test: Docs change only. Tested with docs build. Change-Id: Ideb5cc517a7bc08056bb2fe8025c7acea388128b --- core/java/android/widget/ListView.java | 74 ++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 4 deletions(-) diff --git a/core/java/android/widget/ListView.java b/core/java/android/widget/ListView.java index 12e35a14e3814..569fe017ac860 100644 --- a/core/java/android/widget/ListView.java +++ b/core/java/android/widget/ListView.java @@ -67,11 +67,77 @@ import java.util.function.Predicate; /** - * A view that shows items in a vertically scrolling list. The items - * come from the {@link ListAdapter} associated with this view. + *

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 {@link android.support.v7.widget.RecyclerView}.

* - *

See the List View - * guide.

+ *

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 {@link 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 {@link #setAdapter(ListAdapter adapter)} + * 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 {@link BaseAdapter} and create and configure the view for each data item in + * {@code 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 + * {@code convertView} provided to {@code getView(...)} is null before creating or inflating a new + * view object. See + * + * Making ListView Scrolling Smooth for more ways to ensure a smooth user experience.

+ * + *

For a more complete example of creating a custom adapter, see the + * + * Custom Choice List sample app.

+ * + *

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 {@link android.app.ListActivity ListActivity} + * or {@link android.app.ListFragment 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.

* * @attr ref android.R.styleable#ListView_entries * @attr ref android.R.styleable#ListView_divider