From 1064dd9117cb8151d301e251d6fa7cc38661817c Mon Sep 17 00:00:00 2001
From: Scott Main <smain@google.com>
Date: Mon, 17 Jan 2011 16:06:12 -0800
Subject: docs: move the fragments dev guide into fundamentals topic

Change-Id: If6a9751e78db23e76256e179db99aa0e29126f85
---
 docs/html/guide/guide_toc.cs                     |   6 +-
 docs/html/guide/topics/fragments/index.jd        | 815 -----------------------
 docs/html/guide/topics/fundamentals/fragments.jd | 815 +++++++++++++++++++++++
 docs/html/guide/topics/ui/actionbar.jd           |   4 +-
 4 files changed, 820 insertions(+), 820 deletions(-)
 delete mode 100644 docs/html/guide/topics/fragments/index.jd
 create mode 100644 docs/html/guide/topics/fundamentals/fragments.jd

(limited to 'docs')

diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index a984acd..67f1fec 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -58,6 +58,9 @@
             <span class="zh-TW" style="display:none">應用程式基本原理</span>
 
           </a></li>
+      <li><a href="<?cs var:toroot ?>guide/topics/fundamentals/fragments.html">
+            <span class="en">Fragments</span>
+          </a> <span class="new">new!</span></li>
     </ul>
     <ul>
       <li class="toggle-list">
@@ -199,9 +202,6 @@
       </li>
     </ul>
     <ul>
-      <li><a href="<?cs var:toroot ?>guide/topics/fragments/index.html">
-            <span class="en">Fragments</span>
-          </a> <span class="new">new!</span></li>
       <li class="toggle-list">
         <div><a href="<?cs var:toroot ?>guide/topics/graphics/index.html">
                <span class="en">Graphics</span>
diff --git a/docs/html/guide/topics/fragments/index.jd b/docs/html/guide/topics/fragments/index.jd
deleted file mode 100644
index 045a1e8..0000000
--- a/docs/html/guide/topics/fragments/index.jd
+++ /dev/null
@@ -1,815 +0,0 @@
-page.title=Fragments
-@jd:body
-
-<div id="qv-wrapper">
-<div id="qv">
-
-  <h2>Quickview</h2>
-  <ul>
-    <li>Fragments decompose application functionality and UI into reusable modules</li>
-    <li>Add multiple fragments to a screen to avoid switching activities</li>
-    <li>Fragments have their own lifecycle, state, and back stack</li>
-    <li>Fragments require API Level HONEYCOMB or greater</li>
-  </ul>
-
-  <h2>In this document</h2>
-  <ol>
-    <li><a href="#Design">Design Philosophy</a></li>
-    <li><a href="#Creating">Creating a Fragment</a>
-      <ol>
-        <li><a href="#UI">Adding a user interface</a></li>
-        <li><a href="#Adding">Adding a fragment to an activity</a></li>
-      </ol>
-    </li>
-    <li><a href="#Managing">Managing Fragments</a></li>
-    <li><a href="#Transactions">Performing Fragment Transactions</a></li>
-    <li><a href="#CommunicatingWithActivity">Communicating with the Activity</a>
-      <ol>
-        <li><a href="#EventCallbacks">Creating event callbacks to the activity</a></li>
-        <li><a href="#ActionBar">Adding items to the Action Bar</a></li>
-      </ol>
-    </li>
-    <li><a href="#Lifecycle">Handling the Fragment Lifecycle</a>
-      <ol>
-        <li><a href="#CoordinadingWithActivity">Coordinating with the activity lifecycle</a></li>
-      </ol>
-    </li>
-    <li><a href="#Example">Example</a></li>
-  </ol>
-
-  <h2>Key classes</h2>
-  <ol>
-    <li>{@link android.app.Fragment}</li>
-    <li>{@link android.app.FragmentManager}</li>
-    <li>{@link android.app.FragmentTransaction}</li>
-  </ol>
-
-  <h2>Related samples</h2>
-  <ol>
-    <li><a
-href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment">ApiDemos</a></li>
-  </ol>
-</div>
-</div>
-
-<p>A {@link android.app.Fragment} represents a behavior or a portion of user interface in an
-{@link android.app.Activity}. You can combine multiple fragments in a single activity to build a
-multi-pane UI and reuse a fragment in multiple activities. You can think of a fragment as a
-modular section of an activity, which has its own lifecycle, receives its own input events, and
-which you can add or remove while the activity is running.</p>
-
-<p>A fragment must always be embedded in an activity and the fragment's lifecycle is directly
-affected by the activity's lifecycle. For example, when the activity is paused, so are all
-fragments in it, and when the activity is destroyed, so are all fragments. However, while an
-activity is running (it is in the <em>resumed</em> <a
-href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">lifecycle state</a>), you can
-manipulate each fragment independently, such as add or remove them. When you perform such a
-fragment transaction, you can it to a back stack managed by the
-activity&mdash;each back stack entry in the activity is a record of the fragment transaction that
-occurred. The back stack allows the user to reverse a fragment transaction (navigate backwards),
-by pressing the BACK key.</p>
-
-<p>When you add a fragment as a part of your activity layout, it lives in a {@link
-android.view.ViewGroup} inside the activity's view hierarchy and defines its own layout of views.
-You can insert a fragment into your activity layout by declaring the fragment in the activity's
-layout file, as a {@code &lt;fragment&gt;} element, or from your application code by adding it to an
-existing {@link android.view.ViewGroup}. However, a fragment is not required to be a part of the
-activity layout; you may also use a fragment as an invisible worker for the activity.</p>
-
-<p>This document describes how to build your application to use fragments, including
-how fragments can maintain their state when added to the activity's back stack, share
-events with the activity and other fragments in the activity, contribute to the activity's action
-bar, and more.</p>
-
-
-<h2 id="Design">Design Philosophy</h2>
-
-<p>Android introduced fragments in Android 3.0 (API Level "Honeycomb"), primarily to support more
-dynamic and flexible UI designs on large screens, such as tablets. Because a
-tablet's screen is much larger than that of a mobile phone, there's more room to combine and
-interchange UI components. Fragments allow such designs without the need for you to manage complex
-changes to the view hierarchy. By dividing the layout of an activity into fragments, you become able
-to modify the activity's appearance at runtime and preserve those changes in a back stack
-that's managed by the activity.</p>
-
-<p>For example, a news application can use one fragment to show a list of articles on the
-left and another fragment to display an article on the right&mdash;both fragments appear in one
-activity, side by side, and each fragment has its own set of lifecycle callback methods and handle
-their own user input events. Thus, instead of using one activity to select an article and another
-activity to read the article, the user can select an article and read it all within the same
-activity, as illustrated in figure 1.</p>
-
-<img src="{@docRoot}images/fundamentals/fragments.png" alt="" />
-<p class="img-caption"><strong>Figure 1.</strong> An example of how two UI modules that are
-typically separated into two activities can be combined into one activity, using fragments.</p>
-
-
-<p>A fragment should be a modular and reusable component in your application. That is, because the
-fragment defines its own layout and its own behavior using its own lifecycle callbacks, you
-can include one fragment in multiple activities. This is especially important because it allows you
-to adapt your user experience to different screen sizes. For instance, you might include multiple
-fragments in an activity only when the screen size is sufficiently large, and, when it is not,
-launch separate activities that use different fragments.</p>
-
-<p>For example&mdash;to continue with the news application example&mdash;the application can embed
-two
-fragments in <em>Activity A</em>, when running on an extra large screen (a tablet, for example).
-However, on a normal-sized screen (a phone, for example),
-there's not be enough room for both fragments, so <em>Activity A</em> includes only the fragment for
-the list of articles, and when the user selects an article, it starts <em>Activity B</em>, which
-includes the fragment to read the article. Thus, the application supports both design patterns
-suggested in figure 1.</p>
-
-
-
-<h2 id="Creating">Creating a Fragment</h2>
-
-<div class="figure" style="width:314px">
-<img src="{@docRoot}images/fragment_lifecycle.png" alt="" />
-<p class="img-caption"><strong>Figure 2.</strong> The lifecycle of a fragment (while its
-activity is running).</p>
-</div>
-
-<p>To create a fragment, you must create a subclass of {@link android.app.Fragment} (or an existing
-subclass of it). The {@link android.app.Fragment} class has code that looks a lot like
-an {@link android.app.Activity}. It contains callback methods similar to an activity, such
-as {@link android.app.Fragment#onCreate onCreate()}, {@link android.app.Fragment#onStart onStart()},
-{@link android.app.Fragment#onPause onPause()}, and {@link android.app.Fragment#onStop onStop()}. In
-fact, if you're converting an existing Android application to use fragments, you might simply move
-code from your activity's callback methods into the respective callback methods of your
-fragment.</p>
-
-<p>Usually, you should implement at least the following lifecycle methods:</p>
-
-<dl>
-  <dt>{@link android.app.Fragment#onCreate onCreate()}</dt>
-  <dd>The system calls this when creating the fragment. Within your implementation, you should
-initialize essential components of the fragment that you want to retain when the fragment is
-paused or stopped, then resumed.</dd>
-  <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt>
-  <dd>The system calls this when it's time for the fragment to draw its user interface for the
-first time. To draw a UI for your fragment, you must return a {@link android.view.View} from this
-method that is the root of your fragment's layout. You can return null if the fragment does not
-provide a UI.</dd>
-  <dt>{@link android.app.Activity#onPause onPause()}</dt>
-  <dd>The system calls this method as the first indication that the user is leaving the
-fragment (though it does not always mean the fragment is being destroyed). This is usually where you
-should commit any changes that should be persisted beyond the current user session (because
-the user might not come back).</dd>
-</dl>
-
-<p>Most applications should implement at least these three methods for every fragment, but there are
-several other callback methods you should also use to handle various stages of the
-fragment lifecycle. All the lifecycle callback methods are discussed more later, in the section
-about <a href="#Lifecycle">Handling the Fragment Lifecycle</a>.</p>
-
-
-<p>There are also a few subclasses that you might want to extend, instead of the base {@link
-android.app.Fragment} class:</p>
-
-<dl>
-  <dt>{@link android.app.DialogFragment}</dt>
-  <dd>Displays a floating dialog. Using this class to create a dialog is a good alternative to using
-the dialog helper methods in the {@link android.app.Activity} class, because you can
-incorporate a fragment dialog into the back stack of fragments managed by the activity,
-allowing the user to return to a dismissed fragment.</dd>
-
-  <dt>{@link android.app.ListFragment}</dt>
-  <dd>Displays a list of items that are managed by an adapter (such as a {@link
-android.widget.SimpleCursorAdapter}), similar to {@link android.app.ListActivity}. It provides
-several methods for managing a list view, such as the {@link
-android.app.ListFragment#onListItemClick(ListView,View,int,long) onListItemClick()} callback to
-handle click events.</dd>
-
-  <dt>{@link android.preference.PreferenceFragment}</dt>
-  <dd>Displays a hierarchy of {@link android.preference.Preference} objects as a list, similar to
-{@link android.preference.PreferenceActivity}. This is useful when creating a "settings"
-activity for your application.</dd>
-</dl>
-
-
-<h3 id="UI">Adding a user interface</h3>
-
-<p>A fragment is usually used as part of an activity's user interface and contributes its own
-layout to the activity.</p>
-
-<p>To provide a layout for a fragment, you must implement the {@link
-android.app.Fragment#onCreateView onCreateView()} callback method, which the Android system calls
-when it's time for the fragment to draw its layout. Your implementation of this method must return a
-{@link android.view.View} that is the root of your fragment's layout.</p>
-
-<p class="note"><strong>Note:</strong> If your fragment is a subclass of {@link
-android.app.ListFragment}, the default implementation returns a {@link android.widget.ListView} from
-{@link android.app.Fragment#onCreateView onCreateView()}, so you don't need to implement it.</p>
-
-<p>To return a layout from {@link
-android.app.Fragment#onCreateView onCreateView()}, you can inflate it from a <a
-href="{@docRoot}guide/topics/resources/layout-resource.html">layout resource</a> defined in XML. To
-help you do so, {@link android.app.Fragment#onCreateView onCreateView()} provides a
-{@link android.view.LayoutInflater} object.</p>
-
-<p>For example, here's a subclass of {@link android.app.Fragment} that loads a layout from the
-{@code example_fragment.xml} file:</p>
-
-<pre>
-public static class ExampleFragment extends Fragment {
-    &#64;Override
-    public View onCreateView(LayoutInflater inflater, ViewGroup container,
-                             Bundle savedInstanceState) {
-        // Inflate the layout for this fragment
-        return inflater.inflate(R.layout.example_fragment, container, false);
-    }
-}
-</pre>
-
-<div class="sidebox-wrapper">
-<div class="sidebox">
-  <h3>Creating a layout</h3>
-  <p>In the sample above, {@code R.layout.example_fragment} is a reference to a layout resource
-named {@code example_fragment.xml} saved in the application resources. For information about how to
-create a layout in XML, see the <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a>
-documentation.</p>
-</div>
-</div>
-
-<p>The {@code container} parameter passed to {@link android.app.Fragment#onCreateView
-onCreateView()} is the parent {@link android.view.ViewGroup} (from the activity's layout) in which
-your fragment layout
-will be inserted. The {@code savedInstanceState} parameter is a {@link android.os.Bundle} that
-provides data about the previous instance of the fragment, if the fragment is being resumed
-(restoring state is discussed more in the section about <a href="#Lifecycle">Handling the
-Fragment Lifecycle</a>).</p>
-
-<p>The {@link android.view.LayoutInflater#inflate(int,ViewGroup,boolean) inflate()} method takes
-three arguments:</p>
-<ul>
-  <li>The resource ID of the layout you want to inflate.</li>
-  <li>The {@link android.view.ViewGroup} to be the parent of the inflated layout. Passing the {@code
-container} is important in order for the system to apply layout parameters to the root view of the
-inflated layout, specified by the parent view in which it's going.</li>
-  <li>A boolean indicating whether the inflated layout should be attached to the {@link
-android.view.ViewGroup} (the second parameter) during inflation. (In this case, this
-is false because the system is already inserting the inflated layout into the {@code
-container}&mdash;passing true would create a redundant view group in the final layout.)</li>
-</ul>
-
-<p>Now you've seen how to create a fragment that provides a layout. Next, you need to add
-the fragment to your activity.</p>
-
-
-
-<h3 id="Adding">Adding a fragment to an activity</h3>
-
-<p>Usually, a fragment contributes a portion of UI to the host activity, which is embedded as a part
-of the activity's overall view hierarchy. There are two ways you can add a fragment to the activity
-layout:</p>
-
-<ul>
-  <li><b>Declare the fragment inside the activity's layout file.</b>
-<p>In this case, you can
-specify layout properties for the fragment as if it were a view. For example, here's the layout
-file for an activity with two fragments:</p>
-<pre>
-&lt;?xml version="1.0" encoding="utf-8"?&gt;
-&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
-    android:orientation="horizontal"
-    android:layout_width="match_parent"
-    android:layout_height="match_parent"&gt;
-    &lt;fragment android:name="com.example.news.ArticleListFragment"
-            android:id="@+id/list"
-            android:layout_weight="1"
-            android:layout_width="0dp"
-            android:layout_height="match_parent" /&gt;
-    &lt;fragment android:name="com.example.news.ArticleReaderFragment"
-            android:id="@+id/viewer"
-            android:layout_weight="2"
-            android:layout_width="0dp"
-            android:layout_height="match_parent" /&gt;
-&lt;/LinearLayout&gt;
-</pre>
-  <p>The {@code android:name} attribute in the {@code &lt;fragment&gt;} specifies the {@link
-android.app.Fragment} class to instantiate in the layout.</p>
-
-<p>When the system creates this activity layout, it instantiates each fragment specified in the
-layout and calls the {@link android.app.Fragment#onCreateView onCreateView()} method for each one,
-to retrieve each fragment's layout. The system inserts the {@link android.view.View} returned by the
-fragment directly in place of the {@code &lt;fragment&gt;} element.</p>
-
-<div class="note">
-  <p><strong>Note:</strong> Each fragment requires a unique identifier that
-the system can use to restore the fragment if the activity is restarted (and which you can use to
-capture the fragment to perform transactions, such as remove it). There are three ways to provide an
-ID for a fragment:</p>
-  <ul>
-    <li>Supply the {@code android:id} attribute with a unique ID.</li>
-    <li>Supply the {@code android:tag} attribute with a unique string.</li>
-    <li>If you provide neither of the previous two, the system uses the ID of the container 
-view.</li>
-  </ul>
-</div>
-  </li>
-
-  <li><b>Or, programmatically add the fragment to an existing {@link android.view.ViewGroup}.</b>
-<p>At any time while your activity is running, you can add fragments to your activity layout. You
-simply need to specify a {@link
-android.view.ViewGroup} in which to place the fragment.</p>
-  <p>To make fragment transactions in your activity (such as add, remove, or replace a
-fragment), you must use APIs from {@link android.app.FragmentTransaction}. You can get an instance
-of {@link android.app.FragmentTransaction} from your {@link android.app.Activity} like this:</p>
-
-<pre>
-FragmentManager fragmentManager = {@link android.app.Activity#getFragmentManager()}
-FragmentTransaction fragmentTransaction = fragmentManager.{@link android.app.FragmentManager#openTransaction()};
-</pre>
-
-<p>You can then add a fragment using the {@link
-android.app.FragmentTransaction#add(int,Fragment) add()} method, specifying the fragment to add and
-the view in which to insert it. For example:</p>
-
-<pre>
-ExampleFragment fragment = new ExampleFragment();
-fragmentTransaction.add(R.id.fragment_container, fragment);
-fragmentTransaction.commit();
-</pre>
-
-  <p>The first argument passed to {@link android.app.FragmentTransaction#add(int,Fragment) add()}
-is the {@link android.view.ViewGroup} in which the fragment should be placed, specified by
-resource ID, and the second parameter is the fragment to add.</p>
-  <p>Once you've made your changes with
-{@link android.app.FragmentTransaction}, you must
-call {@link android.app.FragmentTransaction#commit} for the changes to take effect.</p>
-  </li>
-</ul>
-
-
-<h4 id="AddingWithoutUI">Adding a fragment without a UI</h4>
-
-<p>The examples above show how to add a fragment to your activity in order to provide a UI. However,
-you can also use a fragment to provide a background behavior for the activity without presenting
-additional UI.</p>
-
-<p>To add a fragment without a UI, add the fragment from the activity using {@link
-android.app.FragmentTransaction#add(Fragment,String)} (supplying a unique string "tag" for the
-fragment, rather than a view ID). This adds the fragment, but, because it's not associated with a
-view in the activity layout, it does not receive a call to {@link
-android.app.Fragment#onCreateView onCreateView()}. So you don't need to implement that method.</p>
-
-<p>Supplying a string tag for the fragment isn't strictly for non-UI fragments&mdash;you can also
-supply string tags to fragments that do have a UI&mdash;but if the fragment does not have a
-UI, then the string tag is the only way to identify it. If you want to get the fragment from the
-activity later, you need to use {@link android.app.FragmentManager#findFragmentByTag
-findFragmentByTag()}.</p>
-
-<p>For an example activity that uses a fragment as a background worker, without a UI, see the <a
-href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentRetainInstance.html">{@code
-FragmentRetainInstance.java}</a> sample.</p>
-
-
-
-<h2 id="Managing">Managing Fragments</h2>
-
-<p>To manage the fragments in your activity, you need to use {@link android.app.FragmentManager}. To
-get it, call {@link android.app.Activity#getFragmentManager()} from your activity.</p>
-
-<p>Some things that you can do with {@link android.app.FragmentManager} include:</p>
-
-<ul>
-  <li>Get fragments that exist in the activity, with {@link
-android.app.FragmentManager#findFragmentById findFragmentById()} (for fragments that provide a UI in
-the activity layout) or {@link android.app.FragmentManager#findFragmentByTag
-findFragmentByTag()} (for fragments that do or don't provide a UI).</li> 
-  <li>Pop fragments off the back stack, with {@link
-android.app.FragmentManager#popBackStack()} (simulating a BACK command by the user).</li>
-  <li>Register a listener for changes to the back stack, with {@link
-android.app.FragmentManager#addOnBackStackChangedListener addOnBackStackChangedListener()}.</li>
-</ul>
-
-<p>For more information about these methods and others, refer to the {@link
-android.app.FragmentManager} class documentation.</p>
-
-<p>As demonstrated in the previous section, you can also use {@link android.app.FragmentManager}
-to open a {@link android.app.FragmentTransaction}, which allows you to perform transactions, such as
-add and remove fragments.</p>
-
-
-<h2 id="Transactions">Performing Fragment Transactions</h2>
-
-<p>A great feature about using fragments in your activity is the ability to add, remove, replace,
-and perform other actions with them, in response to user interaction. Each set of changes that you
-commit to the activity is called a transaction and you can perform one using APIs in {@link
-android.app.FragmentTransaction}. You can also save each transaction to a back stack managed by the
-activity, allowing the user to navigate backward through the fragment changes (similar to navigating
-backward through activities).</p>
-
-<p>You can acquire an instance of {@link android.app.FragmentTransaction} from the {@link
-android.app.FragmentManager} like this:</p>
-
-<pre>
-FragmentManager fragmentManager = {@link android.app.Activity#getFragmentManager()};
-FragmentTransaction fragmentTransaction = fragmentManager.{@link android.app.FragmentManager#openTransaction()};
-</pre>
-
-<p>Each transaction is a set of changes that you want to perform at the same time. You can set
-up all the changes you want to perform for a given transaction using methods such as {@link
-android.app.FragmentTransaction#add add()}, {@link android.app.FragmentTransaction#remove remove()},
-and {@link android.app.FragmentTransaction#replace replace()}. Then, to apply the transaction
-to the activity, you must call {@link android.app.FragmentTransaction#commit()}.</p>
-</dl>
-
-<p>Before you call {@link
-android.app.FragmentTransaction#commit()}, however, you might want to call {@link
-android.app.FragmentTransaction#addToBackStack addToBackStack()}, in order to add the transaction
-to a back stack of fragment transactions. This back stack is managed by the activity and allows
-the user to return to the previous fragment state, by pressing the BACK key.</p>
-
-<p>For example, here's how you can replace one fragment with another, and preserve the previous
-state in the back stack:</p>
-
-<pre>
-// Create new fragment and transaction
-Fragment newFragment = new ExampleFragment();
-FragmentTransaction transaction = getFragmentManager().openTransaction();
-
-// Replace whatever is in the fragment_container view with this fragment,
-// and add the transaction to the back stack
-transaction.replace(R.id.fragment_container, newFragment);
-transaction.addToBackStack(null);
-
-// Commit the transaction
-transaction.commit();
-</pre>
-
-<p>In this example, {@code newFragment} replaces whatever fragment (if any) is currently in the
-layout container identified by the {@code R.id.fragment_container} ID. By calling {@link
-android.app.FragmentTransaction#addToBackStack addToBackStack()}, the replace transaction is
-saved to the back stack so the user can reverse the transaction and bring back the
-previous fragment by pressing the BACK key.</p>
-
-<p>If you add multiple changes to the transaction (such as another {@link
-android.app.FragmentTransaction#add add()} or {@link android.app.FragmentTransaction#remove
-remove()}) and call {@link
-android.app.FragmentTransaction#addToBackStack addToBackStack()}, then all changes applied
-before you call {@link android.app.FragmentTransaction#commit commit()} are added to the
-back stack as a single transaction and the BACK key will reverse them all together.</p>
-
-<p>The order in which you add changes to a {@link android.app.FragmentTransaction} doesn't matter,
-except:</p>
-<ul>
-  <li>You must call {@link android.app.FragmentTransaction#commit()} last</li>
-  <li>If you're adding multiple fragments to the same container, then the order in which
-you add them determines the order they appear in the view hierarchy</li>
-</ul>
-
-<p>If you do not call {@link android.app.FragmentTransaction#addToBackStack(String)
-addToBackStack()} when you perform a transaction that removes a fragment, then that fragment is
-destroyed when the transaction is committed and the user cannot navigate back to it. Whereas, if you
-do call {@link android.app.FragmentTransaction#addToBackStack(String) addToBackStack()} when
-removing a fragment, then the fragment is <em>stopped</em> and will be resumed if the user navigates
-back.</p>
-
-<p class="note"><strong>Tip:</strong> For each fragment transaction, you can apply a transition
-animation, by calling {@link android.app.FragmentTransaction#setTransition setTransition()} before
-you commit.</p>
-
-<p>Calling {@link android.app.FragmentTransaction#commit()} does not perform the transaction
-immediately. Rather, it schedules it to run on the activity's UI thread (the "main" thread) as soon
-as the thread is able to do so. If necessary, however, you may call {@link
-android.app.FragmentManager#executePendingTransactions()} from your UI thread to immediately execute
-transactions submitted by {@link android.app.FragmentTransaction#commit()}. Doing so is
-usually not necessary unless the transaction is a dependency for jobs in other threads.</p>
-
-<p class="caution"><strong>Caution:</strong> You can commit a transaction using {@link
-android.app.FragmentTransaction#commit commit()} only prior to the activity <a
-href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">saving its
-state</a> (when the user leaves the activity). If you attempt to commit after that point, an
-exception will be thrown. This is because the state after the commit can be lost if the activity
-needs to be restored. For situations in which its okay that you lose the commit, use {@link
-android.app.FragmentTransaction#commitAllowingStateLoss()}.</p>
-
-
-
-
-<h2 id="CommunicatingWithActivity">Communicating with the Activity</h2>
-
-<p>Although a {@link android.app.Fragment} is implemented as an object that's independent from an
-{@link android.app.Activity} and can be used inside multiple activities, a given instance of
-a fragment is directly tied to the activity that contains it.</p>
-
-<p>Specifically, the fragment can access the {@link android.app.Activity} instance with {@link
-android.app.Fragment#getActivity()} and easily perform tasks such as find a view in the
-activity layout:</p>
-
-<pre>
-View listView = {@link android.app.Fragment#getActivity()}.{@link android.app.Activity#findViewById findViewById}(R.id.list);
-</pre>
-
-<p>Likewise, your activity can call methods in the fragment by acquiring a reference to the
-{@link android.app.Fragment} from {@link android.app.FragmentManager}, using {@link
-android.app.FragmentManager#findFragmentById findFragmentById()} or {@link
-android.app.FragmentManager#findFragmentByTag findFragmentByTag()}. For example:</p>
-
-<pre>
-ExampleFragment fragment = (ExampleFragment) getFragmentManager().findFragmentById(R.id.example_fragment);
-</pre>
-
-
-<h4 id="EventCallbacks">Creating event callbacks to the activity</h4>
-
-<p>In some cases, you might need a fragment to share events with the activity. A good way to do that
-is to define a callback interface inside the fragment and require that the host activity implement
-it. When the activity receives a callback through the interface, it can share the information with
-other fragments in the layout as necessary.</p>
-
-<p>For example, if a news application has two fragments in an activity&mdash;one to show a list of
-articles (fragment A) and another to display an article (fragment B)&mdash;then fragment A must tell
-the activity when a list item is selected so that it can tell fragment B to display the article. In
-this case, the {@code OnArticleSelectedListener} interface is declared inside fragment A:</p>
-
-<pre>
-public static class FragmentA extends ListFragment {
-    ...
-    // Container Activity must implement this interface
-    public interface OnArticleSelectedListener {
-        public void onArticleSelected(Uri articleUri);
-    }
-    ...
-}
-</pre>
-
-<p>Then the activity that hosts the fragment implements the {@code OnArticleSelectedListener}
-interface and
-overrides {@code onArticleSelected()} to notify fragment B of the event from fragment A. To ensure
-that the host activity implements this interface, fragment A's {@link
-android.app.Fragment#onAttach onAttach()} callback method (which the system calls when adding
-the fragment to the activity) instantiates an instance of {@code OnArticleSelectedListener} by
-casting the {@link android.app.Activity} that is passed into {@link android.app.Fragment#onAttach
-onAttach()}:</p>
-
-<pre>
-public static class FragmentA extends ListFragment {
-    OnArticleSelectedListener mListener;
-    ...
-    &#64;Override
-    public void onAttach(Activity activity) {
-        super.onAttach(activity);
-        try {
-            mListener = (OnArticleSelectedListener) activity;
-        } catch (ClassCastException e) {
-            throw new ClassCastException(activity.toString() + " must implement OnArticleSelectedListener");
-        }
-    }
-    ...
-}
-</pre>
-
-<p>If the activity has not implemented the interface, then the fragment throws a
-{@link java.lang.ClassCastException}.
-On success, the {@code mListener} member holds a reference to activity's implementation of 
-{@code OnArticleSelectedListener}, so that fragment A can share events with the activity by calling
-methods defined by the {@code OnArticleSelectedListener} interface. For example, if fragment A is an
-extension of {@link android.app.ListFragment}, each time
-the user clicks a list item, the system calls {@link android.app.ListFragment#onListItemClick
-onListItemClick()} in the fragment, which then calls {@code onArticleSelected()} to share
-the event with the activity:</p>
-
-<pre>
-public static class FragmentA extends ListFragment {
-    OnArticleSelectedListener mListener;
-    ...
-    &#64;Override
-    public void onListItemClick(ListView l, View v, int position, long id) {
-        // Append the clicked item's row ID with the content provider Uri
-        Uri noteUri = ContentUris.{@link android.content.ContentUris#withAppendedId withAppendedId}(ArticleColumns.CONTENT_URI, id);
-        // Send the event and Uri to the host activity
-        mListener.onArticleSelected(noteUri);
-    }
-    ...
-}
-</pre>
-
-<p>The {@code id} parameter passed to {@link
-android.app.ListFragment#onListItemClick onListItemClick()} is the row ID of the clicked item,
-which the activity (or other fragment) uses to fetch the article from the application's {@link
-android.content.ContentProvider}.</p>
-
-<p><!--To see a complete implementation of this kind of callback interface, see the <a
-href="{@docRoot}resources/samples/NotePad/index.html">NotePad sample</a>. -->More information about
-using a content provider is available in the <a
-href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> document.</p>
-
-
-
-<h3 id="ActionBar">Adding items to the Action Bar</h3>
-
-<p>Your fragments can contribute menu items to the activity's <a
-href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a> (and, consequently, the <a
-href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>) by implementing
-{@link android.app.Fragment#onCreateOptionsMenu(Menu,MenuInflater) onCreateOptionsMenu()}. In order
-for this method to receive calls, however, you must call {@link
-android.app.Fragment#setHasOptionsMenu(boolean) setHasOptionsMenu()} during {@link
-android.app.Fragment#onCreate(Bundle) onCreate()}, to indicate that the fragment
-would like to add items to the Options Menu (otherwise, the fragment will not receive a call to
-{@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()}).</p>
-
-<p>Any items that you then add to the Options Menu from the fragment are appended to the existing
-menu items. The fragment also receives callbacks to {@link
-android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} when a menu item
-is selected.</p>
-
-<p>You can also register a view in your fragment layout to provide a context menu by calling {@link
-android.app.Fragment#registerForContextMenu(View) registerForContextMenu()}. When the user opens
-the context menu, the fragment receives a call to {@link
-android.app.Fragment#onCreateContextMenu(ContextMenu,View,ContextMenu.ContextMenuInfo)
-onCreateContextMenu()}. When the user selects an item, the fragment receives a call to {@link
-android.app.Fragment#onContextItemSelected(MenuItem) onContextItemSelected()}.</p>
-
-<p class="note"><strong>Note:</strong> Although your fragment receives an on-item-selected callback
-for each menu item it adds, the activity is first to receive the respective callback when the user
-selects a menu item. If the activity's implementation of the on-item-selected callback does not
-handle the selected item, then the event is passed to the fragment's callback. This is true for
-the Options Menu and context menus.</p>
-
-<p>For more information about menus, see <a href="{@docRoot}guide/topics/ui/menus.html">Creating
-Menus</a> and <a href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a>.</p>
-
-
-
-
-<h2 id="Lifecycle">Handling the Fragment Lifecycle</h2>
-
-<div class="figure" style="width:403px">
-<img src="{@docRoot}images/activity_fragment_lifecycle.png" alt=""/>
-<p class="img-caption"><strong>Figure 3.</strong> The activity lifecycle's affect on the fragment
-lifecycle.</p>
-</div>
-
-<p>Managing the lifecycle of a fragment is a lot like managing the lifecycle of an activity. Like
-an activity, a fragment can exist in three states:</p>
-
-<dl>
-  <dt><i>Resumed</i></dt>
-    <dd>The fragment is visible in the running activity.</dd>
-
-  <dt><i>Paused</i></dt>
-    <dd>Another activity is in the foreground and has focus, but the activity in which this
-fragment lives is still visible (the foreground activity is partially transparent or doesn't
-cover the entire screen).</dd>
-
-  <dt><i>Stopped</i></dt>
-    <dd>The fragment is not visible. Either the host activity has been stopped or the
-fragment has been removed from the activity but added to the back stack. A stopped fragment is
-still alive (all state and member information is retained by the system). However, it is no longer
-visible to the user and will be killed if the activity is killed.</dd>
-</dl>
-
-<p>Also like an activity, you can retain the state of a fragment using a {@link
-android.os.Bundle}, in case the activity's process is killed and you need to restore the
-fragment state when the activity is recreated. You can save the state during the fragment's {@link
-android.app.Fragment#onSaveInstanceState onSaveInstanceState()} callback and restore it during
-either {@link android.app.Fragment#onCreate onCreate()}, {@link
-android.app.Fragment#onCreateView onCreateView()}, or {@link
-android.app.Fragment#onActivityCreated onActivityCreated()}. For more information about saving
-state, see the <a
-href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">Activities</a>
-document.</p>
-
-<p>The most significant difference in lifecycle between an activity and a fragment is how one is
-stored in its respective back stack. An activity is placed into a back stack of activities
-that's managed by the system when it's stopped, by default (so that the user can navigate back
-to it with the BACK key, as discussed in <a
-href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a>).
-However, a fragment is placed into a back stack managed by the host activity only when you
-explicitly request that the instance be saved by calling {@link
-android.app.FragmentTransaction#addToBackStack(String) addToBackStack()} during a transaction that
-removes the fragment.</p>
-
-<p>Otherwise, managing the fragment lifecycle is very similar to managing the activity
-lifecycle. So, the same practices for <a
-href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">managing the activity
-lifecycle</a> also apply to fragments. What you also need to understand, though, is how the life
-of the activity affects the life of the fragment.</p>
-
-
-<h3 id="CoordinatingWithActivity">Coordinating with the activity lifecycle</h3>
-
-<p>The lifecycle of the activity in which the fragment lives directly affects the lifecycle of the
-fragment, such that each lifecycle callback for the activity results in a similar callback for each
-fragment. For example, when the activity receives {@link android.app.Activity#onPause}, each
-fragment in the activity receives {@link android.app.Fragment#onPause}.</p>
-
-<p>Fragments have a few extra lifecycle callbacks, however, that handle unique interaction with the
-activity in order to perform actions such as build and destroy the fragment's UI. These additional
-callback methods are:</p>
-
-<dl>
-  <dt>{@link android.app.Fragment#onAttach onAttach()}</dt>
-    <dd>Called when the fragment has been associated with the activity (the {@link
-android.app.Activity} is passed in here).</dd>
-  <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt>
-    <dd>Called to create the view hierarchy associated with the fragment.</dd>
-  <dt>{@link android.app.Fragment#onActivityCreated onActivityCreated()}</dt>
-    <dd>Called when the activity's {@link android.app.Activity#onCreate
-onCreate()} method has returned.</dd>
-  <dt>{@link android.app.Fragment#onDestroyView onDestroyView()}</dt>
-    <dd>Called when the view hierarchy associated with the fragment is being removed.</dd>
-  <dt>{@link android.app.Fragment#onDetach onDetach()}</dt>
-    <dd>Called when the fragment is being disassociated from the activity.</dd>
-</dl>
-
-<p>The flow of a fragment's lifecycle, as it is affected by its host activity, is illustrated
-by figure 3. In this figure, you can see how each successive state of the activity determines which
-callback methods a fragment may receive. For example, when the activity has received its {@link
-android.app.Activity#onCreate onCreate()} callback, a fragment in the activity receives no more than
-the {@link android.app.Fragment#onActivityCreated onActivityCreated()} callback.</p>
-
-<p>Once the activity reaches the resumed state, you can freely add and remove fragments to the
-activity. Thus, only while the activity is in the resumed state can the lifecycle of a fragment
-change independently.</p>
-
-<p>However, when the activity leaves the resumed state, the fragment again is pushed through its
-lifecycle by the activity.</p>
-
-
-
-
-<h2 id="Example">Example</h2>
-
-<p>To bring everything discussed in this document together, here's an example of an activity
-using two fragments to create a two-pane layout. The activity below includes one fragment to
-show a list of Shakespeare play titles and another to show a summary of the play when selected
-from the list. It also demonstrates how to provide different configurations of the fragments,
-based on the screen configuration.</p>
-
-<p class="note"><strong>Note:</strong> The complete source code for this activity is available in
-<a href="resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.html">{@code
-FragmentLayout.java}</a>.</p>
-
-<p>The main activity applies a layout in the usual way, during {@link
-android.app.Activity#onCreate onCreate()}:</p>
-
-{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java main}
-
-<p>The layout applied is {@code fragment_layout.xml}:</p>
-
-{@sample development/samples/ApiDemos/res/layout-land/fragment_layout.xml layout}
-
-<p>Using this layout, the system instantiates the {@code TitlesFragment} (which lists the play
-titles) as soon as the activity loads the layout, while the {@link android.widget.FrameLayout}
-(where the fragment for showing the play summary will go) consumes space on the right side of the
-screen, but remains empty at first. As you'll see below, it's not until the user selects an item
-from the list that a fragment is placed into the {@link android.widget.FrameLayout}.</p>
-
-<p>However, not all screen configurations are wide enough to show both the list of
-plays and the summary, side by side. So, the layout above is used only for the landscape
-screen configuration, by saving it at {@code res/layout-land/fragment_layout.xml}.</p>
-
-<p>Thus, when the screen is in portrait orientation, the system applies the following layout, which
-is saved at {@code res/layout/fragment_layout.xml}:</p>
-
-{@sample development/samples/ApiDemos/res/layout/fragment_layout.xml layout}
-
-<p>This layout includes only {@code TitlesFragment}. This means that, when the device is in
-portrait orientation, only the list of play titles is visible. So, when the user clicks a list
-item in this configuration, the application will start a new activity to show the summary,
-instead of loading a second fragment.</p>
-
-<p>Next, you can see how this is accomplished in the fragment classes. First is {@code
-TitlesFragment}, which shows the list of Shakespeare play titles. This fragment extends {@link
-android.app.ListFragment} and relies on it to handle most of the list view work.</p>
-
-<p>As you inspect this code, notice that there are two possible behaviors when the user clicks a
-list item: depending on which of the two layouts is active, it can either create and display a new
-fragment to show the details in the same activity (adding the fragment to the {@link
-android.widget.FrameLayout}), or start a new activity (where the fragment can be shown).</p>
-
-{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java titles}
-
-<p>The second fragment, {@code DetailsFragment} shows the play summary for the item selected from
-the list from {@code TitlesFragment}:</p>
- 
-{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java details}
-
-<p>Recall from the {@code TitlesFragment} class, that, if the user clicks a list item and the
-current layout does <em>not</em> include the {@code R.id.details} view (which is where the
-{@code DetailsFragment} belongs), then the application starts the {@code DetailsActivity}
-activity to display the content of the item.</p>
-
-<p>Here is the {@code DetailsActivity}, which simply embeds the {@code DetailsFragment} to display
-the selected play summary when the screen is in portrait orientation:</p>
-
-{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java
-details_activity}
- 
-<p>Notice that this activity finishes itself if the configuration is landscape, so that the main
-activity can take over and display the {@code DetailsFragment} alongside the {@code TitlesFragment}.
-This can happen if the user begins the {@code DetailsActivity} while in portrait orientation, but
-then rotates to landscape (which restarts the current activity).</p>
-
-
-<p>For more samples using fragments (and complete source files for this example),
-see the sample code available in <a
-href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment">
-ApiDemos</a> (available for download from the <a
-href="{@docRoot}resources/samples/get.html">Samples SDK component</a>).</p>
-
-
diff --git a/docs/html/guide/topics/fundamentals/fragments.jd b/docs/html/guide/topics/fundamentals/fragments.jd
new file mode 100644
index 0000000..045a1e8
--- /dev/null
+++ b/docs/html/guide/topics/fundamentals/fragments.jd
@@ -0,0 +1,815 @@
+page.title=Fragments
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+
+  <h2>Quickview</h2>
+  <ul>
+    <li>Fragments decompose application functionality and UI into reusable modules</li>
+    <li>Add multiple fragments to a screen to avoid switching activities</li>
+    <li>Fragments have their own lifecycle, state, and back stack</li>
+    <li>Fragments require API Level HONEYCOMB or greater</li>
+  </ul>
+
+  <h2>In this document</h2>
+  <ol>
+    <li><a href="#Design">Design Philosophy</a></li>
+    <li><a href="#Creating">Creating a Fragment</a>
+      <ol>
+        <li><a href="#UI">Adding a user interface</a></li>
+        <li><a href="#Adding">Adding a fragment to an activity</a></li>
+      </ol>
+    </li>
+    <li><a href="#Managing">Managing Fragments</a></li>
+    <li><a href="#Transactions">Performing Fragment Transactions</a></li>
+    <li><a href="#CommunicatingWithActivity">Communicating with the Activity</a>
+      <ol>
+        <li><a href="#EventCallbacks">Creating event callbacks to the activity</a></li>
+        <li><a href="#ActionBar">Adding items to the Action Bar</a></li>
+      </ol>
+    </li>
+    <li><a href="#Lifecycle">Handling the Fragment Lifecycle</a>
+      <ol>
+        <li><a href="#CoordinadingWithActivity">Coordinating with the activity lifecycle</a></li>
+      </ol>
+    </li>
+    <li><a href="#Example">Example</a></li>
+  </ol>
+
+  <h2>Key classes</h2>
+  <ol>
+    <li>{@link android.app.Fragment}</li>
+    <li>{@link android.app.FragmentManager}</li>
+    <li>{@link android.app.FragmentTransaction}</li>
+  </ol>
+
+  <h2>Related samples</h2>
+  <ol>
+    <li><a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment">ApiDemos</a></li>
+  </ol>
+</div>
+</div>
+
+<p>A {@link android.app.Fragment} represents a behavior or a portion of user interface in an
+{@link android.app.Activity}. You can combine multiple fragments in a single activity to build a
+multi-pane UI and reuse a fragment in multiple activities. You can think of a fragment as a
+modular section of an activity, which has its own lifecycle, receives its own input events, and
+which you can add or remove while the activity is running.</p>
+
+<p>A fragment must always be embedded in an activity and the fragment's lifecycle is directly
+affected by the activity's lifecycle. For example, when the activity is paused, so are all
+fragments in it, and when the activity is destroyed, so are all fragments. However, while an
+activity is running (it is in the <em>resumed</em> <a
+href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">lifecycle state</a>), you can
+manipulate each fragment independently, such as add or remove them. When you perform such a
+fragment transaction, you can it to a back stack managed by the
+activity&mdash;each back stack entry in the activity is a record of the fragment transaction that
+occurred. The back stack allows the user to reverse a fragment transaction (navigate backwards),
+by pressing the BACK key.</p>
+
+<p>When you add a fragment as a part of your activity layout, it lives in a {@link
+android.view.ViewGroup} inside the activity's view hierarchy and defines its own layout of views.
+You can insert a fragment into your activity layout by declaring the fragment in the activity's
+layout file, as a {@code &lt;fragment&gt;} element, or from your application code by adding it to an
+existing {@link android.view.ViewGroup}. However, a fragment is not required to be a part of the
+activity layout; you may also use a fragment as an invisible worker for the activity.</p>
+
+<p>This document describes how to build your application to use fragments, including
+how fragments can maintain their state when added to the activity's back stack, share
+events with the activity and other fragments in the activity, contribute to the activity's action
+bar, and more.</p>
+
+
+<h2 id="Design">Design Philosophy</h2>
+
+<p>Android introduced fragments in Android 3.0 (API Level "Honeycomb"), primarily to support more
+dynamic and flexible UI designs on large screens, such as tablets. Because a
+tablet's screen is much larger than that of a mobile phone, there's more room to combine and
+interchange UI components. Fragments allow such designs without the need for you to manage complex
+changes to the view hierarchy. By dividing the layout of an activity into fragments, you become able
+to modify the activity's appearance at runtime and preserve those changes in a back stack
+that's managed by the activity.</p>
+
+<p>For example, a news application can use one fragment to show a list of articles on the
+left and another fragment to display an article on the right&mdash;both fragments appear in one
+activity, side by side, and each fragment has its own set of lifecycle callback methods and handle
+their own user input events. Thus, instead of using one activity to select an article and another
+activity to read the article, the user can select an article and read it all within the same
+activity, as illustrated in figure 1.</p>
+
+<img src="{@docRoot}images/fundamentals/fragments.png" alt="" />
+<p class="img-caption"><strong>Figure 1.</strong> An example of how two UI modules that are
+typically separated into two activities can be combined into one activity, using fragments.</p>
+
+
+<p>A fragment should be a modular and reusable component in your application. That is, because the
+fragment defines its own layout and its own behavior using its own lifecycle callbacks, you
+can include one fragment in multiple activities. This is especially important because it allows you
+to adapt your user experience to different screen sizes. For instance, you might include multiple
+fragments in an activity only when the screen size is sufficiently large, and, when it is not,
+launch separate activities that use different fragments.</p>
+
+<p>For example&mdash;to continue with the news application example&mdash;the application can embed
+two
+fragments in <em>Activity A</em>, when running on an extra large screen (a tablet, for example).
+However, on a normal-sized screen (a phone, for example),
+there's not be enough room for both fragments, so <em>Activity A</em> includes only the fragment for
+the list of articles, and when the user selects an article, it starts <em>Activity B</em>, which
+includes the fragment to read the article. Thus, the application supports both design patterns
+suggested in figure 1.</p>
+
+
+
+<h2 id="Creating">Creating a Fragment</h2>
+
+<div class="figure" style="width:314px">
+<img src="{@docRoot}images/fragment_lifecycle.png" alt="" />
+<p class="img-caption"><strong>Figure 2.</strong> The lifecycle of a fragment (while its
+activity is running).</p>
+</div>
+
+<p>To create a fragment, you must create a subclass of {@link android.app.Fragment} (or an existing
+subclass of it). The {@link android.app.Fragment} class has code that looks a lot like
+an {@link android.app.Activity}. It contains callback methods similar to an activity, such
+as {@link android.app.Fragment#onCreate onCreate()}, {@link android.app.Fragment#onStart onStart()},
+{@link android.app.Fragment#onPause onPause()}, and {@link android.app.Fragment#onStop onStop()}. In
+fact, if you're converting an existing Android application to use fragments, you might simply move
+code from your activity's callback methods into the respective callback methods of your
+fragment.</p>
+
+<p>Usually, you should implement at least the following lifecycle methods:</p>
+
+<dl>
+  <dt>{@link android.app.Fragment#onCreate onCreate()}</dt>
+  <dd>The system calls this when creating the fragment. Within your implementation, you should
+initialize essential components of the fragment that you want to retain when the fragment is
+paused or stopped, then resumed.</dd>
+  <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt>
+  <dd>The system calls this when it's time for the fragment to draw its user interface for the
+first time. To draw a UI for your fragment, you must return a {@link android.view.View} from this
+method that is the root of your fragment's layout. You can return null if the fragment does not
+provide a UI.</dd>
+  <dt>{@link android.app.Activity#onPause onPause()}</dt>
+  <dd>The system calls this method as the first indication that the user is leaving the
+fragment (though it does not always mean the fragment is being destroyed). This is usually where you
+should commit any changes that should be persisted beyond the current user session (because
+the user might not come back).</dd>
+</dl>
+
+<p>Most applications should implement at least these three methods for every fragment, but there are
+several other callback methods you should also use to handle various stages of the
+fragment lifecycle. All the lifecycle callback methods are discussed more later, in the section
+about <a href="#Lifecycle">Handling the Fragment Lifecycle</a>.</p>
+
+
+<p>There are also a few subclasses that you might want to extend, instead of the base {@link
+android.app.Fragment} class:</p>
+
+<dl>
+  <dt>{@link android.app.DialogFragment}</dt>
+  <dd>Displays a floating dialog. Using this class to create a dialog is a good alternative to using
+the dialog helper methods in the {@link android.app.Activity} class, because you can
+incorporate a fragment dialog into the back stack of fragments managed by the activity,
+allowing the user to return to a dismissed fragment.</dd>
+
+  <dt>{@link android.app.ListFragment}</dt>
+  <dd>Displays a list of items that are managed by an adapter (such as a {@link
+android.widget.SimpleCursorAdapter}), similar to {@link android.app.ListActivity}. It provides
+several methods for managing a list view, such as the {@link
+android.app.ListFragment#onListItemClick(ListView,View,int,long) onListItemClick()} callback to
+handle click events.</dd>
+
+  <dt>{@link android.preference.PreferenceFragment}</dt>
+  <dd>Displays a hierarchy of {@link android.preference.Preference} objects as a list, similar to
+{@link android.preference.PreferenceActivity}. This is useful when creating a "settings"
+activity for your application.</dd>
+</dl>
+
+
+<h3 id="UI">Adding a user interface</h3>
+
+<p>A fragment is usually used as part of an activity's user interface and contributes its own
+layout to the activity.</p>
+
+<p>To provide a layout for a fragment, you must implement the {@link
+android.app.Fragment#onCreateView onCreateView()} callback method, which the Android system calls
+when it's time for the fragment to draw its layout. Your implementation of this method must return a
+{@link android.view.View} that is the root of your fragment's layout.</p>
+
+<p class="note"><strong>Note:</strong> If your fragment is a subclass of {@link
+android.app.ListFragment}, the default implementation returns a {@link android.widget.ListView} from
+{@link android.app.Fragment#onCreateView onCreateView()}, so you don't need to implement it.</p>
+
+<p>To return a layout from {@link
+android.app.Fragment#onCreateView onCreateView()}, you can inflate it from a <a
+href="{@docRoot}guide/topics/resources/layout-resource.html">layout resource</a> defined in XML. To
+help you do so, {@link android.app.Fragment#onCreateView onCreateView()} provides a
+{@link android.view.LayoutInflater} object.</p>
+
+<p>For example, here's a subclass of {@link android.app.Fragment} that loads a layout from the
+{@code example_fragment.xml} file:</p>
+
+<pre>
+public static class ExampleFragment extends Fragment {
+    &#64;Override
+    public View onCreateView(LayoutInflater inflater, ViewGroup container,
+                             Bundle savedInstanceState) {
+        // Inflate the layout for this fragment
+        return inflater.inflate(R.layout.example_fragment, container, false);
+    }
+}
+</pre>
+
+<div class="sidebox-wrapper">
+<div class="sidebox">
+  <h3>Creating a layout</h3>
+  <p>In the sample above, {@code R.layout.example_fragment} is a reference to a layout resource
+named {@code example_fragment.xml} saved in the application resources. For information about how to
+create a layout in XML, see the <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a>
+documentation.</p>
+</div>
+</div>
+
+<p>The {@code container} parameter passed to {@link android.app.Fragment#onCreateView
+onCreateView()} is the parent {@link android.view.ViewGroup} (from the activity's layout) in which
+your fragment layout
+will be inserted. The {@code savedInstanceState} parameter is a {@link android.os.Bundle} that
+provides data about the previous instance of the fragment, if the fragment is being resumed
+(restoring state is discussed more in the section about <a href="#Lifecycle">Handling the
+Fragment Lifecycle</a>).</p>
+
+<p>The {@link android.view.LayoutInflater#inflate(int,ViewGroup,boolean) inflate()} method takes
+three arguments:</p>
+<ul>
+  <li>The resource ID of the layout you want to inflate.</li>
+  <li>The {@link android.view.ViewGroup} to be the parent of the inflated layout. Passing the {@code
+container} is important in order for the system to apply layout parameters to the root view of the
+inflated layout, specified by the parent view in which it's going.</li>
+  <li>A boolean indicating whether the inflated layout should be attached to the {@link
+android.view.ViewGroup} (the second parameter) during inflation. (In this case, this
+is false because the system is already inserting the inflated layout into the {@code
+container}&mdash;passing true would create a redundant view group in the final layout.)</li>
+</ul>
+
+<p>Now you've seen how to create a fragment that provides a layout. Next, you need to add
+the fragment to your activity.</p>
+
+
+
+<h3 id="Adding">Adding a fragment to an activity</h3>
+
+<p>Usually, a fragment contributes a portion of UI to the host activity, which is embedded as a part
+of the activity's overall view hierarchy. There are two ways you can add a fragment to the activity
+layout:</p>
+
+<ul>
+  <li><b>Declare the fragment inside the activity's layout file.</b>
+<p>In this case, you can
+specify layout properties for the fragment as if it were a view. For example, here's the layout
+file for an activity with two fragments:</p>
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?&gt;
+&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:orientation="horizontal"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"&gt;
+    &lt;fragment android:name="com.example.news.ArticleListFragment"
+            android:id="@+id/list"
+            android:layout_weight="1"
+            android:layout_width="0dp"
+            android:layout_height="match_parent" /&gt;
+    &lt;fragment android:name="com.example.news.ArticleReaderFragment"
+            android:id="@+id/viewer"
+            android:layout_weight="2"
+            android:layout_width="0dp"
+            android:layout_height="match_parent" /&gt;
+&lt;/LinearLayout&gt;
+</pre>
+  <p>The {@code android:name} attribute in the {@code &lt;fragment&gt;} specifies the {@link
+android.app.Fragment} class to instantiate in the layout.</p>
+
+<p>When the system creates this activity layout, it instantiates each fragment specified in the
+layout and calls the {@link android.app.Fragment#onCreateView onCreateView()} method for each one,
+to retrieve each fragment's layout. The system inserts the {@link android.view.View} returned by the
+fragment directly in place of the {@code &lt;fragment&gt;} element.</p>
+
+<div class="note">
+  <p><strong>Note:</strong> Each fragment requires a unique identifier that
+the system can use to restore the fragment if the activity is restarted (and which you can use to
+capture the fragment to perform transactions, such as remove it). There are three ways to provide an
+ID for a fragment:</p>
+  <ul>
+    <li>Supply the {@code android:id} attribute with a unique ID.</li>
+    <li>Supply the {@code android:tag} attribute with a unique string.</li>
+    <li>If you provide neither of the previous two, the system uses the ID of the container 
+view.</li>
+  </ul>
+</div>
+  </li>
+
+  <li><b>Or, programmatically add the fragment to an existing {@link android.view.ViewGroup}.</b>
+<p>At any time while your activity is running, you can add fragments to your activity layout. You
+simply need to specify a {@link
+android.view.ViewGroup} in which to place the fragment.</p>
+  <p>To make fragment transactions in your activity (such as add, remove, or replace a
+fragment), you must use APIs from {@link android.app.FragmentTransaction}. You can get an instance
+of {@link android.app.FragmentTransaction} from your {@link android.app.Activity} like this:</p>
+
+<pre>
+FragmentManager fragmentManager = {@link android.app.Activity#getFragmentManager()}
+FragmentTransaction fragmentTransaction = fragmentManager.{@link android.app.FragmentManager#openTransaction()};
+</pre>
+
+<p>You can then add a fragment using the {@link
+android.app.FragmentTransaction#add(int,Fragment) add()} method, specifying the fragment to add and
+the view in which to insert it. For example:</p>
+
+<pre>
+ExampleFragment fragment = new ExampleFragment();
+fragmentTransaction.add(R.id.fragment_container, fragment);
+fragmentTransaction.commit();
+</pre>
+
+  <p>The first argument passed to {@link android.app.FragmentTransaction#add(int,Fragment) add()}
+is the {@link android.view.ViewGroup} in which the fragment should be placed, specified by
+resource ID, and the second parameter is the fragment to add.</p>
+  <p>Once you've made your changes with
+{@link android.app.FragmentTransaction}, you must
+call {@link android.app.FragmentTransaction#commit} for the changes to take effect.</p>
+  </li>
+</ul>
+
+
+<h4 id="AddingWithoutUI">Adding a fragment without a UI</h4>
+
+<p>The examples above show how to add a fragment to your activity in order to provide a UI. However,
+you can also use a fragment to provide a background behavior for the activity without presenting
+additional UI.</p>
+
+<p>To add a fragment without a UI, add the fragment from the activity using {@link
+android.app.FragmentTransaction#add(Fragment,String)} (supplying a unique string "tag" for the
+fragment, rather than a view ID). This adds the fragment, but, because it's not associated with a
+view in the activity layout, it does not receive a call to {@link
+android.app.Fragment#onCreateView onCreateView()}. So you don't need to implement that method.</p>
+
+<p>Supplying a string tag for the fragment isn't strictly for non-UI fragments&mdash;you can also
+supply string tags to fragments that do have a UI&mdash;but if the fragment does not have a
+UI, then the string tag is the only way to identify it. If you want to get the fragment from the
+activity later, you need to use {@link android.app.FragmentManager#findFragmentByTag
+findFragmentByTag()}.</p>
+
+<p>For an example activity that uses a fragment as a background worker, without a UI, see the <a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentRetainInstance.html">{@code
+FragmentRetainInstance.java}</a> sample.</p>
+
+
+
+<h2 id="Managing">Managing Fragments</h2>
+
+<p>To manage the fragments in your activity, you need to use {@link android.app.FragmentManager}. To
+get it, call {@link android.app.Activity#getFragmentManager()} from your activity.</p>
+
+<p>Some things that you can do with {@link android.app.FragmentManager} include:</p>
+
+<ul>
+  <li>Get fragments that exist in the activity, with {@link
+android.app.FragmentManager#findFragmentById findFragmentById()} (for fragments that provide a UI in
+the activity layout) or {@link android.app.FragmentManager#findFragmentByTag
+findFragmentByTag()} (for fragments that do or don't provide a UI).</li> 
+  <li>Pop fragments off the back stack, with {@link
+android.app.FragmentManager#popBackStack()} (simulating a BACK command by the user).</li>
+  <li>Register a listener for changes to the back stack, with {@link
+android.app.FragmentManager#addOnBackStackChangedListener addOnBackStackChangedListener()}.</li>
+</ul>
+
+<p>For more information about these methods and others, refer to the {@link
+android.app.FragmentManager} class documentation.</p>
+
+<p>As demonstrated in the previous section, you can also use {@link android.app.FragmentManager}
+to open a {@link android.app.FragmentTransaction}, which allows you to perform transactions, such as
+add and remove fragments.</p>
+
+
+<h2 id="Transactions">Performing Fragment Transactions</h2>
+
+<p>A great feature about using fragments in your activity is the ability to add, remove, replace,
+and perform other actions with them, in response to user interaction. Each set of changes that you
+commit to the activity is called a transaction and you can perform one using APIs in {@link
+android.app.FragmentTransaction}. You can also save each transaction to a back stack managed by the
+activity, allowing the user to navigate backward through the fragment changes (similar to navigating
+backward through activities).</p>
+
+<p>You can acquire an instance of {@link android.app.FragmentTransaction} from the {@link
+android.app.FragmentManager} like this:</p>
+
+<pre>
+FragmentManager fragmentManager = {@link android.app.Activity#getFragmentManager()};
+FragmentTransaction fragmentTransaction = fragmentManager.{@link android.app.FragmentManager#openTransaction()};
+</pre>
+
+<p>Each transaction is a set of changes that you want to perform at the same time. You can set
+up all the changes you want to perform for a given transaction using methods such as {@link
+android.app.FragmentTransaction#add add()}, {@link android.app.FragmentTransaction#remove remove()},
+and {@link android.app.FragmentTransaction#replace replace()}. Then, to apply the transaction
+to the activity, you must call {@link android.app.FragmentTransaction#commit()}.</p>
+</dl>
+
+<p>Before you call {@link
+android.app.FragmentTransaction#commit()}, however, you might want to call {@link
+android.app.FragmentTransaction#addToBackStack addToBackStack()}, in order to add the transaction
+to a back stack of fragment transactions. This back stack is managed by the activity and allows
+the user to return to the previous fragment state, by pressing the BACK key.</p>
+
+<p>For example, here's how you can replace one fragment with another, and preserve the previous
+state in the back stack:</p>
+
+<pre>
+// Create new fragment and transaction
+Fragment newFragment = new ExampleFragment();
+FragmentTransaction transaction = getFragmentManager().openTransaction();
+
+// Replace whatever is in the fragment_container view with this fragment,
+// and add the transaction to the back stack
+transaction.replace(R.id.fragment_container, newFragment);
+transaction.addToBackStack(null);
+
+// Commit the transaction
+transaction.commit();
+</pre>
+
+<p>In this example, {@code newFragment} replaces whatever fragment (if any) is currently in the
+layout container identified by the {@code R.id.fragment_container} ID. By calling {@link
+android.app.FragmentTransaction#addToBackStack addToBackStack()}, the replace transaction is
+saved to the back stack so the user can reverse the transaction and bring back the
+previous fragment by pressing the BACK key.</p>
+
+<p>If you add multiple changes to the transaction (such as another {@link
+android.app.FragmentTransaction#add add()} or {@link android.app.FragmentTransaction#remove
+remove()}) and call {@link
+android.app.FragmentTransaction#addToBackStack addToBackStack()}, then all changes applied
+before you call {@link android.app.FragmentTransaction#commit commit()} are added to the
+back stack as a single transaction and the BACK key will reverse them all together.</p>
+
+<p>The order in which you add changes to a {@link android.app.FragmentTransaction} doesn't matter,
+except:</p>
+<ul>
+  <li>You must call {@link android.app.FragmentTransaction#commit()} last</li>
+  <li>If you're adding multiple fragments to the same container, then the order in which
+you add them determines the order they appear in the view hierarchy</li>
+</ul>
+
+<p>If you do not call {@link android.app.FragmentTransaction#addToBackStack(String)
+addToBackStack()} when you perform a transaction that removes a fragment, then that fragment is
+destroyed when the transaction is committed and the user cannot navigate back to it. Whereas, if you
+do call {@link android.app.FragmentTransaction#addToBackStack(String) addToBackStack()} when
+removing a fragment, then the fragment is <em>stopped</em> and will be resumed if the user navigates
+back.</p>
+
+<p class="note"><strong>Tip:</strong> For each fragment transaction, you can apply a transition
+animation, by calling {@link android.app.FragmentTransaction#setTransition setTransition()} before
+you commit.</p>
+
+<p>Calling {@link android.app.FragmentTransaction#commit()} does not perform the transaction
+immediately. Rather, it schedules it to run on the activity's UI thread (the "main" thread) as soon
+as the thread is able to do so. If necessary, however, you may call {@link
+android.app.FragmentManager#executePendingTransactions()} from your UI thread to immediately execute
+transactions submitted by {@link android.app.FragmentTransaction#commit()}. Doing so is
+usually not necessary unless the transaction is a dependency for jobs in other threads.</p>
+
+<p class="caution"><strong>Caution:</strong> You can commit a transaction using {@link
+android.app.FragmentTransaction#commit commit()} only prior to the activity <a
+href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">saving its
+state</a> (when the user leaves the activity). If you attempt to commit after that point, an
+exception will be thrown. This is because the state after the commit can be lost if the activity
+needs to be restored. For situations in which its okay that you lose the commit, use {@link
+android.app.FragmentTransaction#commitAllowingStateLoss()}.</p>
+
+
+
+
+<h2 id="CommunicatingWithActivity">Communicating with the Activity</h2>
+
+<p>Although a {@link android.app.Fragment} is implemented as an object that's independent from an
+{@link android.app.Activity} and can be used inside multiple activities, a given instance of
+a fragment is directly tied to the activity that contains it.</p>
+
+<p>Specifically, the fragment can access the {@link android.app.Activity} instance with {@link
+android.app.Fragment#getActivity()} and easily perform tasks such as find a view in the
+activity layout:</p>
+
+<pre>
+View listView = {@link android.app.Fragment#getActivity()}.{@link android.app.Activity#findViewById findViewById}(R.id.list);
+</pre>
+
+<p>Likewise, your activity can call methods in the fragment by acquiring a reference to the
+{@link android.app.Fragment} from {@link android.app.FragmentManager}, using {@link
+android.app.FragmentManager#findFragmentById findFragmentById()} or {@link
+android.app.FragmentManager#findFragmentByTag findFragmentByTag()}. For example:</p>
+
+<pre>
+ExampleFragment fragment = (ExampleFragment) getFragmentManager().findFragmentById(R.id.example_fragment);
+</pre>
+
+
+<h4 id="EventCallbacks">Creating event callbacks to the activity</h4>
+
+<p>In some cases, you might need a fragment to share events with the activity. A good way to do that
+is to define a callback interface inside the fragment and require that the host activity implement
+it. When the activity receives a callback through the interface, it can share the information with
+other fragments in the layout as necessary.</p>
+
+<p>For example, if a news application has two fragments in an activity&mdash;one to show a list of
+articles (fragment A) and another to display an article (fragment B)&mdash;then fragment A must tell
+the activity when a list item is selected so that it can tell fragment B to display the article. In
+this case, the {@code OnArticleSelectedListener} interface is declared inside fragment A:</p>
+
+<pre>
+public static class FragmentA extends ListFragment {
+    ...
+    // Container Activity must implement this interface
+    public interface OnArticleSelectedListener {
+        public void onArticleSelected(Uri articleUri);
+    }
+    ...
+}
+</pre>
+
+<p>Then the activity that hosts the fragment implements the {@code OnArticleSelectedListener}
+interface and
+overrides {@code onArticleSelected()} to notify fragment B of the event from fragment A. To ensure
+that the host activity implements this interface, fragment A's {@link
+android.app.Fragment#onAttach onAttach()} callback method (which the system calls when adding
+the fragment to the activity) instantiates an instance of {@code OnArticleSelectedListener} by
+casting the {@link android.app.Activity} that is passed into {@link android.app.Fragment#onAttach
+onAttach()}:</p>
+
+<pre>
+public static class FragmentA extends ListFragment {
+    OnArticleSelectedListener mListener;
+    ...
+    &#64;Override
+    public void onAttach(Activity activity) {
+        super.onAttach(activity);
+        try {
+            mListener = (OnArticleSelectedListener) activity;
+        } catch (ClassCastException e) {
+            throw new ClassCastException(activity.toString() + " must implement OnArticleSelectedListener");
+        }
+    }
+    ...
+}
+</pre>
+
+<p>If the activity has not implemented the interface, then the fragment throws a
+{@link java.lang.ClassCastException}.
+On success, the {@code mListener} member holds a reference to activity's implementation of 
+{@code OnArticleSelectedListener}, so that fragment A can share events with the activity by calling
+methods defined by the {@code OnArticleSelectedListener} interface. For example, if fragment A is an
+extension of {@link android.app.ListFragment}, each time
+the user clicks a list item, the system calls {@link android.app.ListFragment#onListItemClick
+onListItemClick()} in the fragment, which then calls {@code onArticleSelected()} to share
+the event with the activity:</p>
+
+<pre>
+public static class FragmentA extends ListFragment {
+    OnArticleSelectedListener mListener;
+    ...
+    &#64;Override
+    public void onListItemClick(ListView l, View v, int position, long id) {
+        // Append the clicked item's row ID with the content provider Uri
+        Uri noteUri = ContentUris.{@link android.content.ContentUris#withAppendedId withAppendedId}(ArticleColumns.CONTENT_URI, id);
+        // Send the event and Uri to the host activity
+        mListener.onArticleSelected(noteUri);
+    }
+    ...
+}
+</pre>
+
+<p>The {@code id} parameter passed to {@link
+android.app.ListFragment#onListItemClick onListItemClick()} is the row ID of the clicked item,
+which the activity (or other fragment) uses to fetch the article from the application's {@link
+android.content.ContentProvider}.</p>
+
+<p><!--To see a complete implementation of this kind of callback interface, see the <a
+href="{@docRoot}resources/samples/NotePad/index.html">NotePad sample</a>. -->More information about
+using a content provider is available in the <a
+href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> document.</p>
+
+
+
+<h3 id="ActionBar">Adding items to the Action Bar</h3>
+
+<p>Your fragments can contribute menu items to the activity's <a
+href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a> (and, consequently, the <a
+href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>) by implementing
+{@link android.app.Fragment#onCreateOptionsMenu(Menu,MenuInflater) onCreateOptionsMenu()}. In order
+for this method to receive calls, however, you must call {@link
+android.app.Fragment#setHasOptionsMenu(boolean) setHasOptionsMenu()} during {@link
+android.app.Fragment#onCreate(Bundle) onCreate()}, to indicate that the fragment
+would like to add items to the Options Menu (otherwise, the fragment will not receive a call to
+{@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()}).</p>
+
+<p>Any items that you then add to the Options Menu from the fragment are appended to the existing
+menu items. The fragment also receives callbacks to {@link
+android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} when a menu item
+is selected.</p>
+
+<p>You can also register a view in your fragment layout to provide a context menu by calling {@link
+android.app.Fragment#registerForContextMenu(View) registerForContextMenu()}. When the user opens
+the context menu, the fragment receives a call to {@link
+android.app.Fragment#onCreateContextMenu(ContextMenu,View,ContextMenu.ContextMenuInfo)
+onCreateContextMenu()}. When the user selects an item, the fragment receives a call to {@link
+android.app.Fragment#onContextItemSelected(MenuItem) onContextItemSelected()}.</p>
+
+<p class="note"><strong>Note:</strong> Although your fragment receives an on-item-selected callback
+for each menu item it adds, the activity is first to receive the respective callback when the user
+selects a menu item. If the activity's implementation of the on-item-selected callback does not
+handle the selected item, then the event is passed to the fragment's callback. This is true for
+the Options Menu and context menus.</p>
+
+<p>For more information about menus, see <a href="{@docRoot}guide/topics/ui/menus.html">Creating
+Menus</a> and <a href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a>.</p>
+
+
+
+
+<h2 id="Lifecycle">Handling the Fragment Lifecycle</h2>
+
+<div class="figure" style="width:403px">
+<img src="{@docRoot}images/activity_fragment_lifecycle.png" alt=""/>
+<p class="img-caption"><strong>Figure 3.</strong> The activity lifecycle's affect on the fragment
+lifecycle.</p>
+</div>
+
+<p>Managing the lifecycle of a fragment is a lot like managing the lifecycle of an activity. Like
+an activity, a fragment can exist in three states:</p>
+
+<dl>
+  <dt><i>Resumed</i></dt>
+    <dd>The fragment is visible in the running activity.</dd>
+
+  <dt><i>Paused</i></dt>
+    <dd>Another activity is in the foreground and has focus, but the activity in which this
+fragment lives is still visible (the foreground activity is partially transparent or doesn't
+cover the entire screen).</dd>
+
+  <dt><i>Stopped</i></dt>
+    <dd>The fragment is not visible. Either the host activity has been stopped or the
+fragment has been removed from the activity but added to the back stack. A stopped fragment is
+still alive (all state and member information is retained by the system). However, it is no longer
+visible to the user and will be killed if the activity is killed.</dd>
+</dl>
+
+<p>Also like an activity, you can retain the state of a fragment using a {@link
+android.os.Bundle}, in case the activity's process is killed and you need to restore the
+fragment state when the activity is recreated. You can save the state during the fragment's {@link
+android.app.Fragment#onSaveInstanceState onSaveInstanceState()} callback and restore it during
+either {@link android.app.Fragment#onCreate onCreate()}, {@link
+android.app.Fragment#onCreateView onCreateView()}, or {@link
+android.app.Fragment#onActivityCreated onActivityCreated()}. For more information about saving
+state, see the <a
+href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">Activities</a>
+document.</p>
+
+<p>The most significant difference in lifecycle between an activity and a fragment is how one is
+stored in its respective back stack. An activity is placed into a back stack of activities
+that's managed by the system when it's stopped, by default (so that the user can navigate back
+to it with the BACK key, as discussed in <a
+href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a>).
+However, a fragment is placed into a back stack managed by the host activity only when you
+explicitly request that the instance be saved by calling {@link
+android.app.FragmentTransaction#addToBackStack(String) addToBackStack()} during a transaction that
+removes the fragment.</p>
+
+<p>Otherwise, managing the fragment lifecycle is very similar to managing the activity
+lifecycle. So, the same practices for <a
+href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">managing the activity
+lifecycle</a> also apply to fragments. What you also need to understand, though, is how the life
+of the activity affects the life of the fragment.</p>
+
+
+<h3 id="CoordinatingWithActivity">Coordinating with the activity lifecycle</h3>
+
+<p>The lifecycle of the activity in which the fragment lives directly affects the lifecycle of the
+fragment, such that each lifecycle callback for the activity results in a similar callback for each
+fragment. For example, when the activity receives {@link android.app.Activity#onPause}, each
+fragment in the activity receives {@link android.app.Fragment#onPause}.</p>
+
+<p>Fragments have a few extra lifecycle callbacks, however, that handle unique interaction with the
+activity in order to perform actions such as build and destroy the fragment's UI. These additional
+callback methods are:</p>
+
+<dl>
+  <dt>{@link android.app.Fragment#onAttach onAttach()}</dt>
+    <dd>Called when the fragment has been associated with the activity (the {@link
+android.app.Activity} is passed in here).</dd>
+  <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt>
+    <dd>Called to create the view hierarchy associated with the fragment.</dd>
+  <dt>{@link android.app.Fragment#onActivityCreated onActivityCreated()}</dt>
+    <dd>Called when the activity's {@link android.app.Activity#onCreate
+onCreate()} method has returned.</dd>
+  <dt>{@link android.app.Fragment#onDestroyView onDestroyView()}</dt>
+    <dd>Called when the view hierarchy associated with the fragment is being removed.</dd>
+  <dt>{@link android.app.Fragment#onDetach onDetach()}</dt>
+    <dd>Called when the fragment is being disassociated from the activity.</dd>
+</dl>
+
+<p>The flow of a fragment's lifecycle, as it is affected by its host activity, is illustrated
+by figure 3. In this figure, you can see how each successive state of the activity determines which
+callback methods a fragment may receive. For example, when the activity has received its {@link
+android.app.Activity#onCreate onCreate()} callback, a fragment in the activity receives no more than
+the {@link android.app.Fragment#onActivityCreated onActivityCreated()} callback.</p>
+
+<p>Once the activity reaches the resumed state, you can freely add and remove fragments to the
+activity. Thus, only while the activity is in the resumed state can the lifecycle of a fragment
+change independently.</p>
+
+<p>However, when the activity leaves the resumed state, the fragment again is pushed through its
+lifecycle by the activity.</p>
+
+
+
+
+<h2 id="Example">Example</h2>
+
+<p>To bring everything discussed in this document together, here's an example of an activity
+using two fragments to create a two-pane layout. The activity below includes one fragment to
+show a list of Shakespeare play titles and another to show a summary of the play when selected
+from the list. It also demonstrates how to provide different configurations of the fragments,
+based on the screen configuration.</p>
+
+<p class="note"><strong>Note:</strong> The complete source code for this activity is available in
+<a href="resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.html">{@code
+FragmentLayout.java}</a>.</p>
+
+<p>The main activity applies a layout in the usual way, during {@link
+android.app.Activity#onCreate onCreate()}:</p>
+
+{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java main}
+
+<p>The layout applied is {@code fragment_layout.xml}:</p>
+
+{@sample development/samples/ApiDemos/res/layout-land/fragment_layout.xml layout}
+
+<p>Using this layout, the system instantiates the {@code TitlesFragment} (which lists the play
+titles) as soon as the activity loads the layout, while the {@link android.widget.FrameLayout}
+(where the fragment for showing the play summary will go) consumes space on the right side of the
+screen, but remains empty at first. As you'll see below, it's not until the user selects an item
+from the list that a fragment is placed into the {@link android.widget.FrameLayout}.</p>
+
+<p>However, not all screen configurations are wide enough to show both the list of
+plays and the summary, side by side. So, the layout above is used only for the landscape
+screen configuration, by saving it at {@code res/layout-land/fragment_layout.xml}.</p>
+
+<p>Thus, when the screen is in portrait orientation, the system applies the following layout, which
+is saved at {@code res/layout/fragment_layout.xml}:</p>
+
+{@sample development/samples/ApiDemos/res/layout/fragment_layout.xml layout}
+
+<p>This layout includes only {@code TitlesFragment}. This means that, when the device is in
+portrait orientation, only the list of play titles is visible. So, when the user clicks a list
+item in this configuration, the application will start a new activity to show the summary,
+instead of loading a second fragment.</p>
+
+<p>Next, you can see how this is accomplished in the fragment classes. First is {@code
+TitlesFragment}, which shows the list of Shakespeare play titles. This fragment extends {@link
+android.app.ListFragment} and relies on it to handle most of the list view work.</p>
+
+<p>As you inspect this code, notice that there are two possible behaviors when the user clicks a
+list item: depending on which of the two layouts is active, it can either create and display a new
+fragment to show the details in the same activity (adding the fragment to the {@link
+android.widget.FrameLayout}), or start a new activity (where the fragment can be shown).</p>
+
+{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java titles}
+
+<p>The second fragment, {@code DetailsFragment} shows the play summary for the item selected from
+the list from {@code TitlesFragment}:</p>
+ 
+{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java details}
+
+<p>Recall from the {@code TitlesFragment} class, that, if the user clicks a list item and the
+current layout does <em>not</em> include the {@code R.id.details} view (which is where the
+{@code DetailsFragment} belongs), then the application starts the {@code DetailsActivity}
+activity to display the content of the item.</p>
+
+<p>Here is the {@code DetailsActivity}, which simply embeds the {@code DetailsFragment} to display
+the selected play summary when the screen is in portrait orientation:</p>
+
+{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java
+details_activity}
+ 
+<p>Notice that this activity finishes itself if the configuration is landscape, so that the main
+activity can take over and display the {@code DetailsFragment} alongside the {@code TitlesFragment}.
+This can happen if the user begins the {@code DetailsActivity} while in portrait orientation, but
+then rotates to landscape (which restarts the current activity).</p>
+
+
+<p>For more samples using fragments (and complete source files for this example),
+see the sample code available in <a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment">
+ApiDemos</a> (available for download from the <a
+href="{@docRoot}resources/samples/get.html">Samples SDK component</a>).</p>
+
+
diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd
index 44d75c1..c17fc3c 100644
--- a/docs/html/guide/topics/ui/actionbar.jd
+++ b/docs/html/guide/topics/ui/actionbar.jd
@@ -53,7 +53,7 @@ href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">Options Menu</a> as "act
 items"&mdash;providing instant access to key user actions. (Menu items not appearing as action
 items are placed in the Overflow Menu, revealed by a drop-down in the Action Bar.)</li>
   <li>Provide tabs for navigating between <a
-href="{@docRoot}guide/topics/fragments/index.html">fragments</a>.</li>
+href="{@docRoot}guide/topics/fundamentals/fragments.html">fragments</a>.</li>
   <li>Provide drop-down navigation items.</li>
   <li>Provide interactive "action views" in place of action items.</li>
   <li>Use the application logo as a "return home" or "up" navigation action.</li>
@@ -432,7 +432,7 @@ tab.</p>
 the state of each fragment as necessary, so when the user switches fragments with the tabs,
 then returns to a previous fragment, it appears the way they left. For information about saving
 the state of your fragment, see the <a
-href="{@docRoot}guide/topics/fragments/index.html">Fragments</a> developer guide.</p>
+href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> developer guide.</p>
 
 
 
-- 
cgit v1.1