1page.title=Building a Flexible UI
2page.tags=fragments
3helpoutsWidget=true
4
5trainingnavtop=true
6
7@jd:body
8
9<div id="tb-wrapper">
10  <div id="tb">
11    <h2>This lesson teaches you to</h2>
12<ol>
13  <li><a href="#AddAtRuntime">Add a Fragment to an Activity at Runtime</a></li>
14  <li><a href="#Replace">Replace One Fragment with Another</a></li>
15</ol>
16
17    <h2>You should also read</h2>
18    <ul>
19      <li><a href="{@docRoot}guide/components/fragments.html">Fragments</a></li>
20      <li><a href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets and
21Handsets</a></li>
22    </ul>
23
24<h2>Try it out</h2>
25
26<div class="download-box">
27 <a href="http://developer.android.com/shareables/training/FragmentBasics.zip"
28class="button">Download the sample</a>
29 <p class="filename">FragmentBasics.zip</p>
30</div>
31
32  </div>
33</div>
34
35
36<p>When designing your application to support a wide range of screen sizes, you can reuse your
37fragments in different layout configurations to optimize the user experience based on the available
38screen space.</p>
39
40<p>For example, on a handset device it might be appropriate to display just one fragment at a time
41for a single-pane user interface.  Conversely, you may want to set fragments side-by-side on a
42tablet which has a wider screen size to display more information to the user.</p>
43
44<img src="{@docRoot}images/training/basics/fragments-screen-mock.png" alt="" />
45<p class="img-caption"><strong>Figure 1.</strong> Two fragments, displayed in different
46configurations for the same activity on different screen sizes. On a large screen, both fragments
47fit side by side, but on a handset device, only one fragment fits at a time so the fragments must
48replace each other as the user navigates.</p>
49
50<p>The {@link android.support.v4.app.FragmentManager} class provides methods that allow you to add,
51remove, and replace fragments to an activity at runtime in order to create a dynamic experience.</p>
52
53
54
55<h2 id="AddAtRuntime">Add a Fragment to an Activity at Runtime</h2>
56
57<p>Rather than defining the fragments for an activity in the layout file&mdash;as shown in the
58<a href="creating.html">previous lesson</a> with the {@code &lt;fragment>} element&mdash;you can add
59a fragment to the activity during the activity runtime. This is necessary
60if you plan to change fragments during the life of the activity.</p>
61
62<p>To perform a transaction such as add or
63remove a fragment, you must use the {@link android.support.v4.app.FragmentManager} to create a
64{@link android.support.v4.app.FragmentTransaction}, which provides APIs to add, remove, replace,
65and perform other fragment transactions.</p>
66
67<p>If your activity allows the fragments to be removed and replaced, you should add the
68initial fragment(s) to the activity during the activity's
69{@link android.app.Activity#onCreate onCreate()} method.</p>
70
71<p>An important rule when dealing with fragments&mdash;especially when adding fragments at
72runtime&mdash;is that your activity layout must include a container {@link android.view.View}
73in which you can insert the fragment.</p>
74
75<p>The following layout is an alternative to the layout shown in the <a
76href="creating.html">previous lesson</a> that shows only one fragment at a time. In order to replace
77one fragment with another, the activity's layout
78includes an empty {@link android.widget.FrameLayout} that acts as the fragment container.</p>
79
80<p>Notice that the filename is the same as the layout file in the previous lesson, but the layout
81directory does <em>not</em> have the <code>large</code> qualifier, so this layout is used when the
82device screen is smaller than <em>large</em> because the screen does not fit both fragments at
83the same time.</p>
84
85<p><code>res/layout/news_articles.xml:</code></p>
86<pre>
87&lt;FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
88    android:id="@+id/fragment_container"
89    android:layout_width="match_parent"
90    android:layout_height="match_parent" />
91</pre>
92
93<p>Inside your activity, call {@link
94android.support.v4.app.FragmentActivity#getSupportFragmentManager()} to get a {@link
95android.support.v4.app.FragmentManager} using the Support Library APIs. Then call {@link
96android.support.v4.app.FragmentManager#beginTransaction} to create a {@link
97android.support.v4.app.FragmentTransaction} and call {@link
98android.support.v4.app.FragmentTransaction#add add()} to add a fragment.</p>
99
100<p>You can perform multiple fragment transaction for the activity using the same {@link
101android.support.v4.app.FragmentTransaction}. When you're ready to make the changes, you must call
102{@link android.support.v4.app.FragmentTransaction#commit()}.</p>
103
104<p>For example, here's how to add a fragment to the previous layout:</p>
105
106<pre>
107import android.os.Bundle;
108import android.support.v4.app.FragmentActivity;
109
110public class MainActivity extends FragmentActivity {
111    &#64;Override
112    public void onCreate(Bundle savedInstanceState) {
113        super.onCreate(savedInstanceState);
114        setContentView(R.layout.news_articles);
115
116        // Check that the activity is using the layout version with
117        // the fragment_container FrameLayout
118        if (findViewById(R.id.fragment_container) != null) {
119
120            // However, if we're being restored from a previous state,
121            // then we don't need to do anything and should return or else
122            // we could end up with overlapping fragments.
123            if (savedInstanceState != null) {
124                return;
125            }
126
127            // Create a new Fragment to be placed in the activity layout
128            HeadlinesFragment firstFragment = new HeadlinesFragment();
129
130            // In case this activity was started with special instructions from an
131            // Intent, pass the Intent's extras to the fragment as arguments
132            firstFragment.setArguments(getIntent().getExtras());
133
134            // Add the fragment to the 'fragment_container' FrameLayout
135            getSupportFragmentManager().beginTransaction()
136                    .add(R.id.fragment_container, firstFragment).commit();
137        }
138    }
139}
140</pre>
141
142<p>Because the fragment has been added to the {@link android.widget.FrameLayout} container at
143runtime&mdash;instead of defining it in the activity's layout with a {@code &lt;fragment>}
144element&mdash;the activity can remove the fragment and replace it with a different one.</p>
145
146
147
148<h2 id="Replace">Replace One Fragment with Another</h2>
149
150<p>The procedure to replace a fragment is similar to adding one, but requires the {@link
151android.support.v4.app.FragmentTransaction#replace replace()} method instead of {@link
152android.support.v4.app.FragmentTransaction#add add()}.</p>
153
154<p>Keep in mind that when you perform fragment transactions, such as replace or remove one, it's
155often appropriate to allow the user to navigate backward and "undo" the change. To allow the user
156to navigate backward through the fragment transactions, you must call {@link
157android.support.v4.app.FragmentTransaction#addToBackStack addToBackStack()} before you commit the
158{@link android.support.v4.app.FragmentTransaction}.</p>
159
160<p class="note"><strong>Note:</strong> When you remove or replace a fragment and add the transaction
161to the back stack, the fragment that is removed is stopped (not destroyed). If the user navigates
162back to restore the fragment, it restarts. If you <em>do not</em> add the transaction to the back
163stack, then the fragment is destroyed when removed or replaced.</p>
164
165<p>Example of replacing one fragment with another:</p>
166
167<pre>
168// Create fragment and give it an argument specifying the article it should show
169ArticleFragment newFragment = new ArticleFragment();
170Bundle args = new Bundle();
171args.putInt(ArticleFragment.ARG_POSITION, position);
172newFragment.setArguments(args);
173
174FragmentTransaction transaction = getSupportFragmentManager().beginTransaction();
175
176// Replace whatever is in the fragment_container view with this fragment,
177// and add the transaction to the back stack so the user can navigate back
178transaction.replace(R.id.fragment_container, newFragment);
179transaction.addToBackStack(null);
180
181// Commit the transaction
182transaction.commit();
183</pre>
184
185<p>The {@link android.support.v4.app.FragmentTransaction#addToBackStack addToBackStack()} method
186takes an optional string parameter that specifies a unique name for the transaction. The name isn't
187needed unless you plan to perform advanced fragment operations using the {@link
188android.support.v4.app.FragmentManager.BackStackEntry} APIs.</p>
189
190
191
192
193