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