| /* |
| * Copyright (C) 2006 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.app; |
| |
| import android.os.Bundle; |
| import android.os.Handler; |
| import android.view.View; |
| import android.widget.AdapterView; |
| import android.widget.ListAdapter; |
| import android.widget.ListView; |
| |
| /** |
| * An activity that displays a list of items by binding to a data source such as |
| * an array or Cursor, and exposes event handlers when the user selects an item. |
| * <p> |
| * ListActivity hosts a {@link android.widget.ListView ListView} object that can |
| * be bound to different data sources, typically either an array or a Cursor |
| * holding query results. Binding, screen layout, and row layout are discussed |
| * in the following sections. |
| * <p> |
| * <strong>Screen Layout</strong> |
| * </p> |
| * <p> |
| * ListActivity has a default layout that consists of a single, full-screen list |
| * in the center of the screen. However, if you desire, you can customize the |
| * screen layout by setting your own view layout with setContentView() in |
| * onCreate(). To do this, your own view MUST contain a ListView object with the |
| * id "@android:id/list" (or {@link android.R.id#list} if it's in code) |
| * <p> |
| * Optionally, your custom view can contain another view object of any type to |
| * display when the list view is empty. This "empty list" notifier must have an |
| * id "android:id/empty". Note that when an empty view is present, the list view |
| * will be hidden when there is no data to display. |
| * <p> |
| * The following code demonstrates an (ugly) custom screen layout. It has a list |
| * with a green background, and an alternate red "no data" message. |
| * </p> |
| * |
| * <pre> |
| * <?xml version="1.0" encoding="utf-8"?> |
| * <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" |
| * android:orientation="vertical" |
| * android:layout_width="match_parent" |
| * android:layout_height="match_parent" |
| * android:paddingLeft="8dp" |
| * android:paddingRight="8dp"> |
| * |
| * <ListView android:id="@android:id/list" |
| * android:layout_width="match_parent" |
| * android:layout_height="match_parent" |
| * android:background="#00FF00" |
| * android:layout_weight="1" |
| * android:drawSelectorOnTop="false"/> |
| * |
| * <TextView android:id="@android:id/empty" |
| * android:layout_width="match_parent" |
| * android:layout_height="match_parent" |
| * android:background="#FF0000" |
| * android:text="No data"/> |
| * </LinearLayout> |
| * </pre> |
| * |
| * <p> |
| * <strong>Row Layout</strong> |
| * </p> |
| * <p> |
| * You can specify the layout of individual rows in the list. You do this by |
| * specifying a layout resource in the ListAdapter object hosted by the activity |
| * (the ListAdapter binds the ListView to the data; more on this later). |
| * <p> |
| * A ListAdapter constructor takes a parameter that specifies a layout resource |
| * for each row. It also has two additional parameters that let you specify |
| * which data field to associate with which object in the row layout resource. |
| * These two parameters are typically parallel arrays. |
| * </p> |
| * <p> |
| * Android provides some standard row layout resources. These are in the |
| * {@link android.R.layout} class, and have names such as simple_list_item_1, |
| * simple_list_item_2, and two_line_list_item. The following layout XML is the |
| * source for the resource two_line_list_item, which displays two data |
| * fields,one above the other, for each list row. |
| * </p> |
| * |
| * <pre> |
| * <?xml version="1.0" encoding="utf-8"?> |
| * <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" |
| * android:layout_width="match_parent" |
| * android:layout_height="wrap_content" |
| * android:orientation="vertical"> |
| * |
| * <TextView android:id="@+id/text1" |
| * android:textSize="16sp" |
| * android:textStyle="bold" |
| * android:layout_width="match_parent" |
| * android:layout_height="wrap_content"/> |
| * |
| * <TextView android:id="@+id/text2" |
| * android:textSize="16sp" |
| * android:layout_width="match_parent" |
| * android:layout_height="wrap_content"/> |
| * </LinearLayout> |
| * </pre> |
| * |
| * <p> |
| * You must identify the data bound to each TextView object in this layout. The |
| * syntax for this is discussed in the next section. |
| * </p> |
| * <p> |
| * <strong>Binding to Data</strong> |
| * </p> |
| * <p> |
| * You bind the ListActivity's ListView object to data using a class that |
| * implements the {@link android.widget.ListAdapter ListAdapter} interface. |
| * Android provides two standard list adapters: |
| * {@link android.widget.SimpleAdapter SimpleAdapter} for static data (Maps), |
| * and {@link android.widget.SimpleCursorAdapter SimpleCursorAdapter} for Cursor |
| * query results. |
| * </p> |
| * <p> |
| * The following code from a custom ListActivity demonstrates querying the |
| * Contacts provider for all contacts, then binding the Name and Company fields |
| * to a two line row layout in the activity's ListView. |
| * </p> |
| * |
| * <pre> |
| * public class MyListAdapter extends ListActivity { |
| * |
| * @Override |
| * protected void onCreate(Bundle savedInstanceState){ |
| * super.onCreate(savedInstanceState); |
| * |
| * // We'll define a custom screen layout here (the one shown above), but |
| * // typically, you could just use the standard ListActivity layout. |
| * setContentView(R.layout.custom_list_activity_view); |
| * |
| * // Query for all people contacts using the {@link android.provider.Contacts.People} convenience class. |
| * // Put a managed wrapper around the retrieved cursor so we don't have to worry about |
| * // requerying or closing it as the activity changes state. |
| * mCursor = this.getContentResolver().query(People.CONTENT_URI, null, null, null, null); |
| * startManagingCursor(mCursor); |
| * |
| * // Now create a new list adapter bound to the cursor. |
| * // SimpleListAdapter is designed for binding to a Cursor. |
| * ListAdapter adapter = new SimpleCursorAdapter( |
| * this, // Context. |
| * android.R.layout.two_line_list_item, // Specify the row template to use (here, two columns bound to the two retrieved cursor |
| * rows). |
| * mCursor, // Pass in the cursor to bind to. |
| * new String[] {People.NAME, People.COMPANY}, // Array of cursor columns to bind to. |
| * new int[] {android.R.id.text1, android.R.id.text2}); // Parallel array of which template objects to bind to those columns. |
| * |
| * // Bind to our new adapter. |
| * setListAdapter(adapter); |
| * } |
| * } |
| * </pre> |
| * |
| * @see #setListAdapter |
| * @see android.widget.ListView |
| */ |
| public class ListActivity extends Activity { |
| /** |
| * This field should be made private, so it is hidden from the SDK. |
| * {@hide} |
| */ |
| protected ListAdapter mAdapter; |
| /** |
| * This field should be made private, so it is hidden from the SDK. |
| * {@hide} |
| */ |
| protected ListView mList; |
| |
| private Handler mHandler = new Handler(); |
| private boolean mFinishedStart = false; |
| |
| private Runnable mRequestFocus = new Runnable() { |
| public void run() { |
| mList.focusableViewAvailable(mList); |
| } |
| }; |
| |
| /** |
| * This method will be called when an item in the list is selected. |
| * Subclasses should override. Subclasses can call |
| * getListView().getItemAtPosition(position) if they need to access the |
| * data associated with the selected item. |
| * |
| * @param l The ListView where the click happened |
| * @param v The view that was clicked within the ListView |
| * @param position The position of the view in the list |
| * @param id The row id of the item that was clicked |
| */ |
| protected void onListItemClick(ListView l, View v, int position, long id) { |
| } |
| |
| /** |
| * Ensures the list view has been created before Activity restores all |
| * of the view states. |
| * |
| *@see Activity#onRestoreInstanceState(Bundle) |
| */ |
| @Override |
| protected void onRestoreInstanceState(Bundle state) { |
| ensureList(); |
| super.onRestoreInstanceState(state); |
| } |
| |
| /** |
| * @see Activity#onDestroy() |
| */ |
| @Override |
| protected void onDestroy() { |
| mHandler.removeCallbacks(mRequestFocus); |
| super.onDestroy(); |
| } |
| |
| /** |
| * Updates the screen state (current list and other views) when the |
| * content changes. |
| * |
| * @see Activity#onContentChanged() |
| */ |
| @Override |
| public void onContentChanged() { |
| super.onContentChanged(); |
| View emptyView = findViewById(com.android.internal.R.id.empty); |
| mList = (ListView)findViewById(com.android.internal.R.id.list); |
| if (mList == null) { |
| throw new RuntimeException( |
| "Your content must have a ListView whose id attribute is " + |
| "'android.R.id.list'"); |
| } |
| if (emptyView != null) { |
| mList.setEmptyView(emptyView); |
| } |
| mList.setOnItemClickListener(mOnClickListener); |
| if (mFinishedStart) { |
| setListAdapter(mAdapter); |
| } |
| mHandler.post(mRequestFocus); |
| mFinishedStart = true; |
| } |
| |
| /** |
| * Provide the cursor for the list view. |
| */ |
| public void setListAdapter(ListAdapter adapter) { |
| synchronized (this) { |
| ensureList(); |
| mAdapter = adapter; |
| mList.setAdapter(adapter); |
| } |
| } |
| |
| /** |
| * Set the currently selected list item to the specified |
| * position with the adapter's data |
| * |
| * @param position |
| */ |
| public void setSelection(int position) { |
| mList.setSelection(position); |
| } |
| |
| /** |
| * Get the position of the currently selected list item. |
| */ |
| public int getSelectedItemPosition() { |
| return mList.getSelectedItemPosition(); |
| } |
| |
| /** |
| * Get the cursor row ID of the currently selected list item. |
| */ |
| public long getSelectedItemId() { |
| return mList.getSelectedItemId(); |
| } |
| |
| /** |
| * Get the activity's list view widget. |
| */ |
| public ListView getListView() { |
| ensureList(); |
| return mList; |
| } |
| |
| /** |
| * Get the ListAdapter associated with this activity's ListView. |
| */ |
| public ListAdapter getListAdapter() { |
| return mAdapter; |
| } |
| |
| private void ensureList() { |
| if (mList != null) { |
| return; |
| } |
| setContentView(com.android.internal.R.layout.list_content_simple); |
| |
| } |
| |
| private AdapterView.OnItemClickListener mOnClickListener = new AdapterView.OnItemClickListener() { |
| public void onItemClick(AdapterView<?> parent, View v, int position, long id) |
| { |
| onListItemClick((ListView)parent, v, position, id); |
| } |
| }; |
| } |