android.app.ListFragment Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* Copyright (C) 2010 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.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.view.animation.AnimationUtils;
import android.widget.AdapterView;
import android.widget.ListAdapter;
import android.widget.ListView;
import android.widget.TextView;
/**
* A fragment 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.
*
* ListFragment 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.
*
* Screen Layout
*
*
* ListFragment has a default layout that consists of a single list view.
* However, if you desire, you can customize the fragment layout by returning
* your own view hierarchy from {@link #onCreateView}.
* To do this, your view hierarchy must contain a ListView object with the
* id "@android:id/list" (or {@link android.R.id#list} if it's in code)
*
* Optionally, your view hierarchy 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:empty". Note that when an empty view is present, the list view
* will be hidden when there is no data to display.
*
* The following code demonstrates an (ugly) custom list layout. It has a list
* with a green background, and an alternate red "no data" message.
*
*
*
* <?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="@id/android:list"
* android:layout_width="match_parent"
* android:layout_height="match_parent"
* android:background="#00FF00"
* android:layout_weight="1"
* android:drawSelectorOnTop="false"/>
*
* <TextView android:id="@id/android:empty"
* android:layout_width="match_parent"
* android:layout_height="match_parent"
* android:background="#FF0000"
* android:text="No data"/>
* </LinearLayout>
*
*
*
* Row Layout
*
*
* 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 fragment
* (the ListAdapter binds the ListView to the data; more on this later).
*
* 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.
*
*
* 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.
*
*
*
* <?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>
*
*
*
* You must identify the data bound to each TextView object in this layout. The
* syntax for this is discussed in the next section.
*
*
* Binding to Data
*
*
* You bind the ListFragment'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.
*
*
* You must use
* {@link #setListAdapter(ListAdapter) ListFragment.setListAdapter()} to
* associate the list with an adapter. Do not directly call
* {@link ListView#setAdapter(ListAdapter) ListView.setAdapter()} or else
* important initialization will be skipped.
*
*
* @see #setListAdapter
* @see android.widget.ListView
*/
public class ListFragment extends Fragment {
final private Handler mHandler = new Handler();
final private Runnable mRequestFocus = new Runnable() {
public void run() {
mList.focusableViewAvailable(mList);
}
};
final private AdapterView.OnItemClickListener mOnClickListener
= new AdapterView.OnItemClickListener() {
public void onItemClick(AdapterView parent, View v, int position, long id) {
onListItemClick((ListView)parent, v, position, id);
}
};
ListAdapter mAdapter;
ListView mList;
View mEmptyView;
TextView mStandardEmptyView;
View mProgressContainer;
View mListContainer;
CharSequence mEmptyText;
boolean mListShown;
public ListFragment() {
}
/**
* Provide default implementation to return a simple list view. Subclasses
* can override to replace with their own layout. If doing so, the
* returned view hierarchy must have a ListView whose id
* is {@link android.R.id#list android.R.id.list} and can optionally
* have a sibling view id {@link android.R.id#empty android.R.id.empty}
* that is to be shown when the list is empty.
*
* If you are overriding this method with your own custom content,
* consider including the standard layout {@link android.R.layout#list_content}
* in your layout file, so that you continue to retain all of the standard
* behavior of ListFragment. In particular, this is currently the only
* way to have the built-in indeterminant progress state be shown.
*/
@Override
public View onCreateView(LayoutInflater inflater, ViewGroup container,
Bundle savedInstanceState) {
return inflater.inflate(com.android.internal.R.layout.list_content,
container, false);
}
/**
* Attach to list view once the view hierarchy has been created.
*/
@Override
public void onViewCreated(View view, Bundle savedInstanceState) {
super.onViewCreated(view, savedInstanceState);
ensureList();
}
/**
* Detach from list view.
*/
@Override
public void onDestroyView() {
mHandler.removeCallbacks(mRequestFocus);
mList = null;
mListShown = false;
mEmptyView = mProgressContainer = mListContainer = null;
mStandardEmptyView = null;
super.onDestroyView();
}
/**
* 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
*/
public void onListItemClick(ListView l, View v, int position, long id) {
}
/**
* Provide the cursor for the list view.
*/
public void setListAdapter(ListAdapter adapter) {
boolean hadAdapter = mAdapter != null;
mAdapter = adapter;
if (mList != null) {
mList.setAdapter(adapter);
if (!mListShown && !hadAdapter) {
// The list was hidden, and previously didn't have an
// adapter. It is now time to show it.
setListShown(true, getView().getWindowToken() != null);
}
}
}
/**
* Set the currently selected list item to the specified
* position with the adapter's data
*
* @param position
*/
public void setSelection(int position) {
ensureList();
mList.setSelection(position);
}
/**
* Get the position of the currently selected list item.
*/
public int getSelectedItemPosition() {
ensureList();
return mList.getSelectedItemPosition();
}
/**
* Get the cursor row ID of the currently selected list item.
*/
public long getSelectedItemId() {
ensureList();
return mList.getSelectedItemId();
}
/**
* Get the activity's list view widget.
*/
public ListView getListView() {
ensureList();
return mList;
}
/**
* The default content for a ListFragment has a TextView that can
* be shown when the list is empty. If you would like to have it
* shown, call this method to supply the text it should use.
*/
public void setEmptyText(CharSequence text) {
ensureList();
if (mStandardEmptyView == null) {
throw new IllegalStateException("Can't be used with a custom content view");
}
mStandardEmptyView.setText(text);
if (mEmptyText == null) {
mList.setEmptyView(mStandardEmptyView);
}
mEmptyText = text;
}
/**
* Control whether the list is being displayed. You can make it not
* displayed if you are waiting for the initial data to show in it. During
* this time an indeterminant progress indicator will be shown instead.
*
*
Applications do not normally need to use this themselves. The default
* behavior of ListFragment is to start with the list not being shown, only
* showing it once an adapter is given with {@link #setListAdapter(ListAdapter)}.
* If the list at that point had not been shown, when it does get shown
* it will be do without the user ever seeing the hidden state.
*
* @param shown If true, the list view is shown; if false, the progress
* indicator. The initial value is true.
*/
public void setListShown(boolean shown) {
setListShown(shown, true);
}
/**
* Like {@link #setListShown(boolean)}, but no animation is used when
* transitioning from the previous state.
*/
public void setListShownNoAnimation(boolean shown) {
setListShown(shown, false);
}
/**
* Control whether the list is being displayed. You can make it not
* displayed if you are waiting for the initial data to show in it. During
* this time an indeterminant progress indicator will be shown instead.
*
* @param shown If true, the list view is shown; if false, the progress
* indicator. The initial value is true.
* @param animate If true, an animation will be used to transition to the
* new state.
*/
private void setListShown(boolean shown, boolean animate) {
ensureList();
if (mProgressContainer == null) {
throw new IllegalStateException("Can't be used with a custom content view");
}
if (mListShown == shown) {
return;
}
mListShown = shown;
if (shown) {
if (animate) {
mProgressContainer.startAnimation(AnimationUtils.loadAnimation(
getActivity(), android.R.anim.fade_out));
mListContainer.startAnimation(AnimationUtils.loadAnimation(
getActivity(), android.R.anim.fade_in));
} else {
mProgressContainer.clearAnimation();
mListContainer.clearAnimation();
}
mProgressContainer.setVisibility(View.GONE);
mListContainer.setVisibility(View.VISIBLE);
} else {
if (animate) {
mProgressContainer.startAnimation(AnimationUtils.loadAnimation(
getActivity(), android.R.anim.fade_in));
mListContainer.startAnimation(AnimationUtils.loadAnimation(
getActivity(), android.R.anim.fade_out));
} else {
mProgressContainer.clearAnimation();
mListContainer.clearAnimation();
}
mProgressContainer.setVisibility(View.VISIBLE);
mListContainer.setVisibility(View.GONE);
}
}
/**
* Get the ListAdapter associated with this activity's ListView.
*/
public ListAdapter getListAdapter() {
return mAdapter;
}
private void ensureList() {
if (mList != null) {
return;
}
View root = getView();
if (root == null) {
throw new IllegalStateException("Content view not yet created");
}
if (root instanceof ListView) {
mList = (ListView)root;
} else {
mStandardEmptyView = (TextView)root.findViewById(
com.android.internal.R.id.internalEmpty);
if (mStandardEmptyView == null) {
mEmptyView = root.findViewById(android.R.id.empty);
} else {
mStandardEmptyView.setVisibility(View.GONE);
}
mProgressContainer = root.findViewById(com.android.internal.R.id.progressContainer);
mListContainer = root.findViewById(com.android.internal.R.id.listContainer);
View rawListView = root.findViewById(android.R.id.list);
if (!(rawListView instanceof ListView)) {
throw new RuntimeException(
"Content has view with id attribute 'android.R.id.list' "
+ "that is not a ListView class");
}
mList = (ListView)rawListView;
if (mList == null) {
throw new RuntimeException(
"Your content must have a ListView whose id attribute is " +
"'android.R.id.list'");
}
if (mEmptyView != null) {
mList.setEmptyView(mEmptyView);
} else if (mEmptyText != null) {
mStandardEmptyView.setText(mEmptyText);
mList.setEmptyView(mStandardEmptyView);
}
}
mListShown = true;
mList.setOnItemClickListener(mOnClickListener);
if (mAdapter != null) {
ListAdapter adapter = mAdapter;
mAdapter = null;
setListAdapter(adapter);
} else {
// We are starting without an adapter, so assume we won't
// have our data right away and start with the progress indicator.
if (mProgressContainer != null) {
setListShown(false, false);
}
}
mHandler.post(mRequestFocus);
}
}