ListFragment

Class Overview

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 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 onCreateView(LayoutInflater, ViewGroup, Bundle). To do this, your view hierarchy must contain a ListView object with the id "@android:id/list" (or 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 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 ListAdapter interface. Android provides two standard list adapters: SimpleAdapter for static data (Maps), and SimpleCursorAdapter for Cursor query results.

You must use ListFragment.setListAdapter() to associate the list with an adapter. Do not directly call ListView.setAdapter() or else important initialization will be skipped.

Summary

[Expand] Inherited XML Attributes

From class android.app.Fragment Attribute Name Related Method Description android:fragmentAllowEnterTransitionOverlap setAllowEnterTransitionOverlap(boolean) Sets whether the enter and exit transitions should overlap when transitioning forward.  android:fragmentAllowReturnTransitionOverlap setAllowReturnTransitionOverlap(boolean) Sets whether the enter and exit transitions should overlap when transitioning because of popping the back stack.  android:fragmentEnterTransition setEnterTransition(Transition) The Transition that will be used to move Views into the initial scene.  android:fragmentExitTransition setReturnTransition(Transition) The Transition that will be used to move Views out of the scene when the fragment is removed, hidden, or detached when not popping the back stack.  android:fragmentReenterTransition setReenterTransition(Transition) The Transition that will be used to move Views in to the scene when returning due to popping a back stack.  android:fragmentSharedElementEnterTransition setSharedElementEnterTransition(Transition) The Transition that will be used for shared elements transferred into the content Scene.  android:fragmentSharedElementReturnTransition setSharedElementReturnTransition(Transition) The Transition that will be used for shared elements transferred back during a pop of the back stack.

[Expand] Inherited Constants

From interface android.content.ComponentCallbacks2 int TRIM_MEMORY_BACKGROUND Level for onTrimMemory(int): the process has gone on to the LRU list. int TRIM_MEMORY_COMPLETE Level for onTrimMemory(int): the process is nearing the end of the background LRU list, and if more memory isn't found soon it will be killed. int TRIM_MEMORY_MODERATE Level for onTrimMemory(int): the process is around the middle of the background LRU list; freeing memory can help the system keep other processes running later in the list for better overall performance. int TRIM_MEMORY_RUNNING_CRITICAL Level for onTrimMemory(int): the process is not an expendable background process, but the device is running extremely low on memory and is about to not be able to keep any background processes running. int TRIM_MEMORY_RUNNING_LOW Level for onTrimMemory(int): the process is not an expendable background process, but the device is running low on memory. int TRIM_MEMORY_RUNNING_MODERATE Level for onTrimMemory(int): the process is not an expendable background process, but the device is running moderately low on memory. int TRIM_MEMORY_UI_HIDDEN Level for onTrimMemory(int): the process had been showing a user interface, and is no longer doing so.

[Expand] Inherited Methods
From class android.app.Fragment void dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args) Print the Fragments's state into the given stream. final boolean equals(Object o) Subclasses can not override equals(). final Activity getActivity() Return the Activity this fragment is currently associated with. boolean getAllowEnterTransitionOverlap() Returns whether the the exit transition and enter transition overlap or not. boolean getAllowReturnTransitionOverlap() Returns whether the the return transition and reenter transition overlap or not. final Bundle getArguments() Return the arguments supplied when the fragment was instantiated, if any. final FragmentManager getChildFragmentManager() Return a private FragmentManager for placing and managing Fragments inside of this Fragment. Transition getEnterTransition() Returns the Transition that will be used to move Views into the initial scene. Transition getExitTransition() Returns the Transition that will be used to move Views out of the scene when the fragment is removed, hidden, or detached when not popping the back stack. final FragmentManager getFragmentManager() Return the FragmentManager for interacting with fragments associated with this fragment's activity. final int getId() Return the identifier this fragment is known by. LoaderManager getLoaderManager() Return the LoaderManager for this fragment, creating it if needed. final Fragment getParentFragment() Returns the parent Fragment containing this Fragment. Transition getReenterTransition() Returns the Transition that will be used to move Views in to the scene when returning due to popping a back stack. final Resources getResources() Return getActivity().getResources(). final boolean getRetainInstance() Transition getReturnTransition() Returns the Transition that will be used to move Views out of the scene when the Fragment is preparing to be removed, hidden, or detached because of popping the back stack. Transition getSharedElementEnterTransition() Returns the Transition that will be used for shared elements transferred into the content Scene. Transition getSharedElementReturnTransition() Return the Transition that will be used for shared elements transferred back during a pop of the back stack. final String getString(int resId) Return a localized string from the application's package's default string table. final String getString(int resId, Object... formatArgs) Return a localized formatted string from the application's package's default string table, substituting the format arguments as defined in Formatter and format(String, Object...). final String getTag() Get the tag name of the fragment, if specified. final Fragment getTargetFragment() Return the target fragment set by setTargetFragment(Fragment, int). final int getTargetRequestCode() Return the target request code set by setTargetFragment(Fragment, int). final CharSequence getText(int resId) Return a localized, styled CharSequence from the application's package's default string table. boolean getUserVisibleHint() View getView() Get the root view for the fragment's layout (the one returned by onCreateView(LayoutInflater, ViewGroup, Bundle)), if provided. final int hashCode() Subclasses can not override hashCode(). static Fragment instantiate(Context context, String fname) Like instantiate(Context, String, Bundle) but with a null argument Bundle. static Fragment instantiate(Context context, String fname, Bundle args) Create a new instance of a Fragment with the given class name. final boolean isAdded() Return true if the fragment is currently added to its activity. final boolean isDetached() Return true if the fragment has been explicitly detached from the UI. final boolean isHidden() Return true if the fragment has been hidden. final boolean isInLayout() Return true if the layout is included as part of an activity view hierarchy via the <fragment> tag. final boolean isRemoving() Return true if this fragment is currently being removed from its activity. final boolean isResumed() Return true if the fragment is in the resumed state. final boolean isVisible() Return true if the fragment is currently visible to the user. void onActivityCreated(Bundle savedInstanceState) Called when the fragment's activity has been created and this fragment's view hierarchy instantiated. void onActivityResult(int requestCode, int resultCode, Intent data) Receive the result from a previous call to startActivityForResult(Intent, int). void onAttach(Activity activity) Called when a fragment is first attached to its activity. void onConfigurationChanged(Configuration newConfig) Called by the system when the device configuration changes while your component is running. boolean onContextItemSelected(MenuItem item) This hook is called whenever an item in a context menu is selected. void onCreate(Bundle savedInstanceState) Called to do initial creation of a fragment. Animator onCreateAnimator(int transit, boolean enter, int nextAnim) Called when a fragment loads an animation. void onCreateContextMenu(ContextMenu menu, View v, ContextMenu.ContextMenuInfo menuInfo) Called when a context menu for the view is about to be shown. void onCreateOptionsMenu(Menu menu, MenuInflater inflater) Initialize the contents of the Activity's standard options menu. View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) Called to have the fragment instantiate its user interface view. void onDestroy() Called when the fragment is no longer in use. void onDestroyOptionsMenu() Called when this fragment's option menu items are no longer being included in the overall options menu. void onDestroyView() Called when the view previously created by onCreateView(LayoutInflater, ViewGroup, Bundle) has been detached from the fragment. void onDetach() Called when the fragment is no longer attached to its activity. void onHiddenChanged(boolean hidden) Called when the hidden state (as returned by isHidden() of the fragment has changed. void onInflate(AttributeSet attrs, Bundle savedInstanceState) This method was deprecated in API level 12. Use onInflate(Activity, AttributeSet, Bundle) instead. void onInflate(Activity activity, AttributeSet attrs, Bundle savedInstanceState) Called when a fragment is being created as part of a view layout inflation, typically from setting the content view of an activity. void onLowMemory() This is called when the overall system is running low on memory, and actively running processes should trim their memory usage. boolean onOptionsItemSelected(MenuItem item) This hook is called whenever an item in your options menu is selected. void onOptionsMenuClosed(Menu menu) This hook is called whenever the options menu is being closed (either by the user canceling the menu with the back/menu button, or when an item is selected). void onPause() Called when the Fragment is no longer resumed. void onPrepareOptionsMenu(Menu menu) Prepare the Screen's standard options menu to be displayed. void onResume() Called when the fragment is visible to the user and actively running. void onSaveInstanceState(Bundle outState) Called to ask the fragment to save its current dynamic state, so it can later be reconstructed in a new instance of its process is restarted. void onStart() Called when the Fragment is visible to the user. void onStop() Called when the Fragment is no longer started. void onTrimMemory(int level) Called when the operating system has determined that it is a good time for a process to trim unneeded memory from its process. void onViewCreated(View view, Bundle savedInstanceState) Called immediately after onCreateView(LayoutInflater, ViewGroup, Bundle) has returned, but before any saved state has been restored in to the view. void onViewStateRestored(Bundle savedInstanceState) Called when all saved state has been restored into the view hierarchy of the fragment. void registerForContextMenu(View view) Registers a context menu to be shown for the given view (multiple views can show the context menu). void setAllowEnterTransitionOverlap(boolean allow) Sets whether the the exit transition and enter transition overlap or not. void setAllowReturnTransitionOverlap(boolean allow) Sets whether the the return transition and reenter transition overlap or not. void setArguments(Bundle args) Supply the construction arguments for this fragment. void setEnterSharedElementCallback(SharedElementCallback callback) When custom transitions are used with Fragments, the enter transition callback is called when this Fragment is attached or detached when not popping the back stack. void setEnterTransition(Transition transition) Sets the Transition that will be used to move Views into the initial scene. void setExitSharedElementCallback(SharedElementCallback callback) When custom transitions are used with Fragments, the exit transition callback is called when this Fragment is attached or detached when popping the back stack. void setExitTransition(Transition transition) Sets the Transition that will be used to move Views out of the scene when the fragment is removed, hidden, or detached when not popping the back stack. void setHasOptionsMenu(boolean hasMenu) Report that this fragment would like to participate in populating the options menu by receiving a call to onCreateOptionsMenu(Menu, MenuInflater) and related methods. void setInitialSavedState(Fragment.SavedState state) Set the initial saved state that this Fragment should restore itself from when first being constructed, as returned by FragmentManager.saveFragmentInstanceState. void setMenuVisibility(boolean menuVisible) Set a hint for whether this fragment's menu should be visible. void setReenterTransition(Transition transition) Sets the Transition that will be used to move Views in to the scene when returning due to popping a back stack. void setRetainInstance(boolean retain) Control whether a fragment instance is retained across Activity re-creation (such as from a configuration change). void setReturnTransition(Transition transition) Sets the Transition that will be used to move Views out of the scene when the Fragment is preparing to be removed, hidden, or detached because of popping the back stack. void setSharedElementEnterTransition(Transition transition) Sets the Transition that will be used for shared elements transferred into the content Scene. void setSharedElementReturnTransition(Transition transition) Sets the Transition that will be used for shared elements transferred back during a pop of the back stack. void setTargetFragment(Fragment fragment, int requestCode) Optional target for this fragment. void setUserVisibleHint(boolean isVisibleToUser) Set a hint to the system about whether this fragment's UI is currently visible to the user. void startActivity(Intent intent) Call startActivity(Intent) from the fragment's containing Activity. void startActivity(Intent intent, Bundle options) Call startActivity(Intent, Bundle) from the fragment's containing Activity. void startActivityForResult(Intent intent, int requestCode) Call startActivityForResult(Intent, int) from the fragment's containing Activity. void startActivityForResult(Intent intent, int requestCode, Bundle options) Call startActivityForResult(Intent, int, Bundle) from the fragment's containing Activity. String toString() Returns a string containing a concise, human-readable description of this object. void unregisterForContextMenu(View view) Prevents a context menu to be shown for the given view.
From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Invoked when the garbage collector has detected that this instance is no longer reachable. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
From interface android.content.ComponentCallbacks2 abstract void onTrimMemory(int level) Called when the operating system has determined that it is a good time for a process to trim unneeded memory from its process.
From interface android.view.View.OnCreateContextMenuListener abstract void onCreateContextMenu(ContextMenu menu, View v, ContextMenu.ContextMenuInfo menuInfo) Called when the context menu for this view is being built.
From interface android.content.ComponentCallbacks abstract void onConfigurationChanged(Configuration newConfig) Called by the system when the device configuration changes while your component is running. abstract void onLowMemory() This is called when the overall system is running low on memory, and actively running processes should trim their memory usage.