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>Before you begin this lesson, you must set up your Android project to use the Support Library.
42If you have not used the Support Library before, set up your project to use the <strong>v4</strong>
43library by following the <a href="{@docRoot}tools/support-library/setup.html">Support Library
44Setup</a> document. However, you can also include the <a href=
45"{@docRoot}training/appbar/index.html">app bar</a> in your activities by instead using the
46<strong>v7 appcompat</strong> library, which is compatible with Android 2.1 (API level 7)
47and also includes the {@link android.support.v4.app.Fragment} APIs.</p>
48
49
50
51<h2 id="Create">Create a Fragment Class</h2>
52
53<p>To create a fragment, extend the {@link android.support.v4.app.Fragment} class, then override
54key lifecycle methods to insert your app logic, similar to the way you would with an {@link
55android.app.Activity} class.</p>
56
57<p>One difference when creating a {@link android.support.v4.app.Fragment} is that you must use the
58{@link android.support.v4.app.Fragment#onCreateView onCreateView()} callback to define the layout.
59In fact, this is the only callback you need in order to get a fragment running. For
60example, here's a simple fragment that specifies its own layout:</p>
61
62<pre>
63import android.os.Bundle;
64import android.support.v4.app.Fragment;
65import android.view.LayoutInflater;
66import android.view.ViewGroup;
67
68public class ArticleFragment extends Fragment {
69    &#64;Override
70    public View onCreateView(LayoutInflater inflater, ViewGroup container,
71        Bundle savedInstanceState) {
72        // Inflate the layout for this fragment
73        return inflater.inflate(R.layout.article_view, container, false);
74    }
75}
76</pre>
77
78<p>Just like an activity, a fragment should implement other lifecycle callbacks that allow you to
79manage its state as it is added or removed from the activity and as the activity transitions
80between its lifecycle states. For instance, when the activity's {@link
81android.app.Activity#onPause()} method is called, any fragments in the activity also receive a call
82to {@link android.support.v4.app.Fragment#onPause()}.</p>
83
84<p>More information about the fragment lifecycle and callback methods is available in the <a
85href="{@docRoot}guide/components/fragments.html">Fragments</a> developer guide.</p>
86
87
88
89<h2 id="AddInLayout">Add a Fragment to an Activity using XML</h2>
90
91<p>While fragments are reusable, modular UI components, each instance of a {@link
92android.support.v4.app.Fragment} class must be associated with a parent {@link
93android.support.v4.app.FragmentActivity}. You can achieve this association by defining each
94fragment within your activity layout XML file.</p>
95
96<p class="note"><strong>Note:</strong> {@link android.support.v4.app.FragmentActivity} is a
97special activity provided in the Support Library to handle fragments on system versions older than
98API level 11. If the lowest system version you support is API level 11 or higher, then you can use a
99regular {@link android.app.Activity}.</p>
100
101<p>Here is an example layout file that adds two fragments to an activity when the device
102screen is considered "large" (specified by the <code>large</code> qualifier in the directory
103name).</p>
104
105<p class="code-caption">res/layout-large/news_articles.xml</p>
106<pre>
107&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
108    android:orientation="horizontal"
109    android:layout_width="fill_parent"
110    android:layout_height="fill_parent">
111
112    &lt;fragment android:name="com.example.android.fragments.HeadlinesFragment"
113              android:id="@+id/headlines_fragment"
114              android:layout_weight="1"
115              android:layout_width="0dp"
116              android:layout_height="match_parent" />
117
118    &lt;fragment android:name="com.example.android.fragments.ArticleFragment"
119              android:id="@+id/article_fragment"
120              android:layout_weight="2"
121              android:layout_width="0dp"
122              android:layout_height="match_parent" />
123
124&lt;/LinearLayout>
125</pre>
126
127<p class="note"><strong>Tip:</strong> For more about creating layouts for different
128screen sizes, read <a href="{@docRoot}training/multiscreen/screensizes.html">Supporting Different
129Screen Sizes</a>.</p>
130
131<p>Then apply the layout to your activity:</p>
132
133<pre>
134import android.os.Bundle;
135import android.support.v4.app.FragmentActivity;
136
137public class MainActivity extends FragmentActivity {
138    &#64;Override
139    public void onCreate(Bundle savedInstanceState) {
140        super.onCreate(savedInstanceState);
141        setContentView(R.layout.news_articles);
142    }
143}
144</pre>
145
146<p>If you're using the <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
147appcompat library</a>, your activity should instead extend {@link
148android.support.v7.app.AppCompatActivity}, which is a subclass of {@link
149android.support.v4.app.FragmentActivity}. For more information,
150read <a href="{@docRoot}training/appbar/index.html">Adding the App Bar</a>).</p>
151
152
153<p class="note"><strong>Note:</strong> When you add a fragment to an activity layout by defining
154the fragment in the layout XML file, you <em>cannot</em> remove the fragment at runtime. If you plan
155to swap your fragments in and out during user interaction, you must add the fragment to the activity
156when the activity first starts, as shown in the next lesson.</p>
157
158
159
160