/*
* 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);
}
};
}