docs/html/resources/articles/layout-tricks-reuse.jd

page.title=Layout Tricks: Creating Reusable UI Components
parent.title=Articles
parent.link=../browser.html?tag=article
@jd:body

<p>The Android platform offers a wide variety of UI <em>widgets</em>, small
visual construction blocks that you can glue together to present users with
complex and useful interfaces. However applications often need higher-level
visual <em>components</em>. To meet that need, and to do so efficiently, you can
combine multiple standard widgets into a single, reusable component. </p>

<p>For example, you could create a reusable component that contains a progress
bar and a cancel button, a panel containing two buttons (positive and negative
actions), a panel with an icon, a title and a description, and so on. You can
create UI components easily by writing a custom <code>View</code>, but you can
do it even more easily using only XML.</p>

<p>In Android XML layout files, each tag is mapped to an actual class instance
(the class is always a subclass of {@link android.view.View} The UI toolkit lets
you also use three special tags that are not mapped to a <code>View</code>
instance: <code>&lt;requestFocus /&gt;</code>, <code>&lt;merge /&gt;</code> and
<code>&lt;include /&gt;</code>. This article shows how to use <code>&lt;include
/&gt;</code> to create pure XML visual components. For information about how to
use <code>&lt;merge /&gt;</code>, which can be particularly powerful when 
combined with <code>&lt;include /&gt;</code>see the <a
href="{@docRoot}resources/articles/layout-tricks-merge.html">Merging Layouts</a>
article. </p>

<p>The <code>&lt;include /&gt;</code> element does exactly what its name
suggests; it includes another XML layout. Using this tag is straightforward as
shown in the following example, taken straight from <a
href="http://android.git.kernel.org/?p=platform/packages/apps/Launcher.git;a=
tree;h=refs/heads/master;hb=master">the source code of the Home application</a>
that ships with Android:</p>

<pre class="prettyprint">&lt;com.android.launcher.Workspace
    android:id="&#64;+id/workspace"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"

    launcher:defaultScreen="1"&gt;

    &lt;include android:id="&#64;+id/cell1" layout="@layout/workspace_screen" /&gt;
    &lt;include android:id="&#64;+id/cell2" layout="@layout/workspace_screen" /&gt;
    &lt;include android:id="&#64;+id/cell3" layout="@layout/workspace_screen" /&gt;

&lt;/com.android.launcher.Workspace&gt;</pre>

<p>In the <code>&lt;include /&gt;</code> only the <code>layout</code> attribute
is required. This attribute, without the <code>android</code> namespace prefix,
is a reference to the layout file you wish to include. In this example, the same
layout is included three times in a row. This tag also lets you override a few
attributes of the included layout. The above example shows that you can use
<code>android:id</code> to specify the id of the root view of the included
layout; it will also override the id of the included layout if one is defined.
Similarly, you can override all the layout parameters. This means that any
<code>android:layout_*</code> attribute can be used with the <code>&lt;include
/&gt;</code> tag. Here is an example in
which the same layout is included twice, but only the first one overrides the layout properties:</p>

<pre>
&lt;!-- override the layout height and width --&gt;
&lt;include layout="@layout/image_holder"
    android:layout_height="fill_parent"
    android:layout_width="fill_parent" /&gt;
&lt;!-- do not override layout dimensions; inherit them from image_holder --&gt;
&lt;include layout="@layout/image_holder" /&gt;
</pre>

<p class="caution"><strong>Caution:</strong> If you want to override the layout dimensions,
you must override both <code>android:layout_height</code> and
<code>android:layout_width</code>&mdash;you cannot override only the height or only the width.
If you override only one, it will not take effect. (Other layout properties, such as weight,
are still inherited from the source layout.)</p>

<p>This tag is particularly useful when you need to customize only part of your
UI depending on the device's configuration. For instance, the main layout of
your activity can be placed in the <code>layout/</code> directory and can
include another layout which exists in two flavors, in <code>layout-land/</code>
and <code>layout-port/</code>. This allows you to share most of the UI in
portrait and landscape.</p>