1 page.title=Building a Flexible UI 2 page.tags=fragments 3 helpoutsWidget=true 4 5 trainingnavtop=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 21 Handsets</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" 28 class="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 37 fragments in different layout configurations to optimize the user experience based on the available 38 screen space.</p> 39 40 <p>For example, on a handset device it might be appropriate to display just one fragment at a time 41 for a single-pane user interface. Conversely, you may want to set fragments side-by-side on a 42 tablet 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 46 configurations for the same activity on different screen sizes. On a large screen, both fragments 47 fit side by side, but on a handset device, only one fragment fits at a time so the fragments must 48 replace 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, 51 remove, 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—as shown in the 58 <a href="creating.html">previous lesson</a> with the {@code <fragment>} element—you can add 59 a fragment to the activity during the activity runtime. This is necessary 60 if you plan to change fragments during the life of the activity.</p> 61 62 <p>To perform a transaction such as add or 63 remove 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, 65 and perform other fragment transactions.</p> 66 67 <p>If your activity allows the fragments to be removed and replaced, you should add the 68 initial 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—especially when adding fragments at 72 runtime—is that your activity layout must include a container {@link android.view.View} 73 in which you can insert the fragment.</p> 74 75 <p>The following layout is an alternative to the layout shown in the <a 76 href="creating.html">previous lesson</a> that shows only one fragment at a time. In order to replace 77 one fragment with another, the activity's layout 78 includes 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 81 directory does <em>not</em> have the <code>large</code> qualifier, so this layout is used when the 82 device screen is smaller than <em>large</em> because the screen does not fit both fragments at 83 the same time.</p> 84 85 <p><code>res/layout/news_articles.xml:</code></p> 86 <pre> 87 <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 94 android.support.v4.app.FragmentActivity#getSupportFragmentManager()} to get a {@link 95 android.support.v4.app.FragmentManager} using the Support Library APIs. Then call {@link 96 android.support.v4.app.FragmentManager#beginTransaction} to create a {@link 97 android.support.v4.app.FragmentTransaction} and call {@link 98 android.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 101 android.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> 107 import android.os.Bundle; 108 import android.support.v4.app.FragmentActivity; 109 110 public class MainActivity extends FragmentActivity { 111 @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 143 runtime—instead of defining it in the activity's layout with a {@code <fragment>} 144 element—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 151 android.support.v4.app.FragmentTransaction#replace replace()} method instead of {@link 152 android.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 155 often appropriate to allow the user to navigate backward and "undo" the change. To allow the user 156 to navigate backward through the fragment transactions, you must call {@link 157 android.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 161 to the back stack, the fragment that is removed is stopped (not destroyed). If the user navigates 162 back to restore the fragment, it restarts. If you <em>do not</em> add the transaction to the back 163 stack, 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 169 ArticleFragment newFragment = new ArticleFragment(); 170 Bundle args = new Bundle(); 171 args.putInt(ArticleFragment.ARG_POSITION, position); 172 newFragment.setArguments(args); 173 174 FragmentTransaction 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 178 transaction.replace(R.id.fragment_container, newFragment); 179 transaction.addToBackStack(null); 180 181 // Commit the transaction 182 transaction.commit(); 183 </pre> 184 185 <p>The {@link android.support.v4.app.FragmentTransaction#addToBackStack addToBackStack()} method 186 takes an optional string parameter that specifies a unique name for the transaction. The name isn't 187 needed unless you plan to perform advanced fragment operations using the {@link 188 android.support.v4.app.FragmentManager.BackStackEntry} APIs.</p> 189 190 191 192 193
