1page.title=Creating a Fragment
2page.tags=fragments
3helpoutsWidget=true
4
5trainingnavtop=true
6
7@jd:body
8
9<div id="tb-wrapper">
10  <div id="tb">
11
12    <h2>This lesson teaches you to</h2>
13<ol>
14  <li><a href="#Create">Create a Fragment Class</a></li>
15  <li><a href="#AddInLayout">Add a Fragment to an Activity using XML</a></li>
16</ol>
17
18    <h2>You should also read</h2>
19    <ul>
20      <li><a href="{@docRoot}guide/components/fragments.html">Fragments</a></li>
21    </ul>
22
23<h2>Try it out</h2>
24
25<div class="download-box">
26 <a href="http://developer.android.com/shareables/training/FragmentBasics.zip"
27class="button">Download the sample</a>
28 <p class="filename">FragmentBasics.zip</p>
29</div>
30
31  </div>
32</div>
33
34<p>You can think of a fragment as a modular section of an activity, which has its own lifecycle,
35receives its own input events, and which you can add or remove while the activity is running (sort
36of like a "sub activity" that you can reuse in different activities). This lesson shows how to
37extend the {@link android.support.v4.app.Fragment} class using the <a
38href="{@docRoot}tools/support-library/index.html">Support Library</a> so your app
39remains compatible with devices running system versions as low as Android 1.6.</p>
40
41<p class="note"><strong>Note:</strong> If you decide that the minimum
42API level your app requires is 11 or higher, you don't need to use the Support
43Library and can instead use the framework's built in {@link android.app.Fragment} class and related
44APIs. Just be aware that this lesson is focused on using the APIs from the Support Library, which
45use a specific package signature and sometimes slightly different API names than the versions
46included in the platform.</p>
47
48<p>Before you begin this lesson, you must set up your Android project to use the Support Library.
49If you have not used the Support Library before, set up your project to use the <strong>v4</strong>
50library by following the <a href="{@docRoot}tools/support-library/setup.html">Support Library
51Setup</a> document. However, you can also include the <a href=
52"{@docRoot}guide/topics/ui/actionbar.html">action bar</a> in your activities by instead using the
53<strong>v7 appcompat</strong> library, which is compatible with Android 2.1 (API level 7)
54and also includes the {@link android.support.v4.app.Fragment} APIs.</p>
55
56
57
58<h2 id="Create">Create a Fragment Class</h2>
59
60<p>To create a fragment, extend the {@link android.support.v4.app.Fragment} class, then override
61key lifecycle methods to insert your app logic, similar to the way you would with an {@link
62android.app.Activity} class.</p>
63
64<p>One difference when creating a {@link android.support.v4.app.Fragment} is that you must use the
65{@link android.support.v4.app.Fragment#onCreateView onCreateView()} callback to define the layout.
66In fact, this is the only callback you need in order to get a fragment running. For
67example, here's a simple fragment that specifies its own layout:</p>
68
69<pre>
70import android.os.Bundle;
71import android.support.v4.app.Fragment;
72import android.view.LayoutInflater;
73import android.view.ViewGroup;
74
75public class ArticleFragment extends Fragment {
76    &#64;Override
77    public View onCreateView(LayoutInflater inflater, ViewGroup container,
78        Bundle savedInstanceState) {
79        // Inflate the layout for this fragment
80        return inflater.inflate(R.layout.article_view, container, false);
81    }
82}
83</pre>
84
85<p>Just like an activity, a fragment should implement other lifecycle callbacks that allow you to
86manage its state as it is added or removed from the activity and as the activity transitions
87between its lifecycle states. For instance, when the activity's {@link
88android.app.Activity#onPause()} method is called, any fragments in the activity also receive a call
89to {@link android.support.v4.app.Fragment#onPause()}.</p>
90
91<p>More information about the fragment lifecycle and callback methods is available in the <a
92href="{@docRoot}guide/components/fragments.html">Fragments</a> developer guide.</p>
93
94
95
96<h2 id="AddInLayout">Add a Fragment to an Activity using XML</h2>
97
98<p>While fragments are reusable, modular UI components, each instance of a {@link
99android.support.v4.app.Fragment} class must be associated with a parent {@link
100android.support.v4.app.FragmentActivity}. You can achieve this association by defining each
101fragment within your activity layout XML file.</p>
102
103<p class="note"><strong>Note:</strong> {@link android.support.v4.app.FragmentActivity} is a
104special activity provided in the Support Library to handle fragments on system versions older than
105API level 11. If the lowest system version you support is API level 11 or higher, then you can use a
106regular {@link android.app.Activity}.</p>
107
108<p>Here is an example layout file that adds two fragments to an activity when the device
109screen is considered "large" (specified by the <code>large</code> qualifier in the directory
110name).</p>
111
112<p class="code-caption">res/layout-large/news_articles.xml</p>
113<pre>
114&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
115    android:orientation="horizontal"
116    android:layout_width="fill_parent"
117    android:layout_height="fill_parent">
118
119    &lt;fragment android:name="com.example.android.fragments.HeadlinesFragment"
120              android:id="@+id/headlines_fragment"
121              android:layout_weight="1"
122              android:layout_width="0dp"
123              android:layout_height="match_parent" />
124
125    &lt;fragment android:name="com.example.android.fragments.ArticleFragment"
126              android:id="@+id/article_fragment"
127              android:layout_weight="2"
128              android:layout_width="0dp"
129              android:layout_height="match_parent" />
130
131&lt;/LinearLayout>
132</pre>
133
134<p class="note"><strong>Tip:</strong> For more about creating layouts for different
135screen sizes, read <a href="{@docRoot}training/multiscreen/screensizes.html">Supporting Different
136Screen Sizes</a>.</p>
137
138<p>Then apply the layout to your activity:</p>
139
140<pre>
141import android.os.Bundle;
142import android.support.v4.app.FragmentActivity;
143
144public class MainActivity extends FragmentActivity {
145    &#64;Override
146    public void onCreate(Bundle savedInstanceState) {
147        super.onCreate(savedInstanceState);
148        setContentView(R.layout.news_articles);
149    }
150}
151</pre>
152
153<p>If you're using the <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
154appcompat library</a>, your activity should instead extend {@link
155android.support.v7.app.ActionBarActivity}, which is a subclass of {@link
156android.support.v4.app.FragmentActivity} (for more information,
157read <a href="{@docRoot}training/basics/actionbar/index.html">Adding the Action Bar</a>).</p>
158
159
160<p class="note"><strong>Note:</strong> When you add a fragment to an activity layout by defining
161the fragment in the layout XML file, you <em>cannot</em> remove the fragment at runtime. If you plan
162to swap your fragments in and out during user interaction, you must add the fragment to the activity
163when the activity first starts, as shown in the next lesson.</p>
164
165
166
167