1page.title=Re-using Layouts with <include/>
2parent.title=Improving Layout Performance
3parent.link=index.html
4
5trainingnavtop=true
6previous.title=Optimizing Layout Hierarchies
7previous.link=optimizing-layout.html
8next.title=Loading Views On Demand
9next.link=loading-ondemand.html
10
11@jd:body
12
13
14<div id="tb-wrapper">
15<div id="tb">
16
17<!-- table of contents -->
18<h2>This lesson teaches you to</h2>
19<ol>
20  <li><a href="#Create">Create a Re-usable Layout</a></li>
21  <li><a href="#Include">Use the &lt;include&gt; Tag</a></li>
22  <li><a href="#Merge">Use the &lt;merge&gt; Tag</a></li>
23</ol>
24
25<!-- other docs (NOT javadocs) -->
26<h2>You should also read</h2>
27<ul>
28  <li><a
29href="{@docRoot}guide/topics/resources/layout-resource.html#include-element">Layout
30Resources</a></li>
31</ul>
32
33</div>
34</div>
35
36
37
38<p>Although Android offers a variety of widgets to provide small and re-usable interactive elements,
39you might also need to re-use larger components that require a special layout. To efficiently
40re-use complete layouts, you can use the {@code <include/>} and {@code <merge/>} tags
41to embed another layout inside the current layout.</p>
42
43<p>Reusing layouts is particularly powerful as it allows you create reusable complex layouts. For
44example, a yes/no button panel, or custom progress bar with description text.
45It also means that any elements of your application that are common across multiple layouts can be
46extracted, managed separately, then included in each layout. So while
47you can create individual UI components by writing a custom {@link android.view.View}, you can
48do it even more easily by re-using a layout file.</p>
49
50
51<h2 id="Create">Create a Re-usable Layout</h2>
52
53<p>If you already know the layout that you want to re-use, create a new XML file and define the
54layout. For example, here's a layout from the G-Kenya codelab that defines a title bar to be
55included in each activity (<code>titlebar.xml</code>):</p>
56
57<pre>
58&lt;FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
59    android:layout_width="match_parent"
60    android:layout_height="wrap_content"
61    android:background="&#64;color/titlebar_bg">
62
63    &lt;ImageView android:layout_width="wrap_content"
64               android:layout_height="wrap_content"
65               android:src="&#64;drawable/gafricalogo" /&gt;
66&lt;/FrameLayout&gt;
67</pre>
68
69<p>The root {@link android.view.View} should be exactly how you'd like it to appear in each
70layout to which you add this layout.</p>
71
72
73<h2 id="Include">Use the &lt;include&gt; Tag</h2>
74
75<p>Inside the layout to which you want to add the re-usable component, add the {@code
76<include/>} tag. For example, here's a layout from the
77G-Kenya codelab that includes the title bar from above:</p>
78
79<p>Here's the layout file:</p>
80
81<pre>
82&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
83    android:orientation="vertical"
84    android:layout_width="match_parent"
85    android:layout_height="match_parent"
86    android:background="&#64;color/app_bg"
87    android:gravity="center_horizontal"&gt;
88
89    <strong>&lt;include layout="&#64;layout/titlebar"/&gt;</strong>
90
91    &lt;TextView android:layout_width="match_parent"
92              android:layout_height="wrap_content"
93              android:text="&#64;string/hello"
94              android:padding="10dp" /&gt;
95
96    ...
97
98&lt;/LinearLayout>
99</pre>
100
101<p>You can also override all the layout parameters (any {@code android:layout_*} attributes) of the
102included layout's root view by specifying them in the {@code <include/>} tag. For
103example:</p>
104
105<pre>
106&lt;include android:id="&#64;+id/news_title"
107         android:layout_width="match_parent"
108         android:layout_height="match_parent"
109         layout="@layout/title"/&gt;
110</pre>
111
112<p>However, if you want to override layout attributes using
113the <code>&lt;include&gt;</code> tag, you must override both
114<code>android:layout_height</code> and <code>android:layout_width</code> in order for
115other layout attributes to take effect.</p>
116
117
118<h2 id="Merge">Use the &lt;merge&gt; Tag</h2>
119
120<p>The {@code <merge />} tag helps eliminate redundant view groups in your view hierarchy
121when including one layout within another. For example, if your main layout is a vertical {@link
122android.widget.LinearLayout} in which two consecutive views can be
123re-used in multiple layouts, then the re-usable layout in which you place the two views requires its
124own root view. However, using another {@link android.widget.LinearLayout} as the root for the
125re-usable layout would result in a vertical {@link android.widget.LinearLayout} inside a
126vertical {@link android.widget.LinearLayout}. The nested {@link android.widget.LinearLayout}
127serves no real purpose other than to slow down your UI performance.</p>
128
129<p>To avoid including such a redundant view group, you can instead use the
130{@code <merge>} element as the root view for the re-usable layout. For example:</p>
131
132<pre>
133&lt;merge xmlns:android="http://schemas.android.com/apk/res/android"&gt;
134
135    &lt;Button
136        android:layout_width="fill_parent"
137        android:layout_height="wrap_content"
138        android:text="@string/add"/&gt;
139
140    &lt;Button
141        android:layout_width="fill_parent"
142        android:layout_height="wrap_content"
143        android:text="@string/delete"/&gt;
144
145&lt;/merge>
146</pre>
147
148<p>Now, when you include this layout in another layout (using the {@code <include/>} tag), the
149system ignores the {@code <merge>} element and places the two buttons directly in the
150layout, in place of the {@code <include/>} tag.</p>
151
152