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