xref: /frameworks/base/docs/html/guide/topics/resources/layout-resource.jd

page.title=Layout Resource
parent.title=Resource Types
parent.link=available-resources.html
@jd:body

<div id="qv-wrapper">
  <div id="qv">
    <h2>See also</h2>
    <ol>
      <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></li>
    </ol>
  </div>
</div>

<p>A layout resource defines the architecture for the UI in an Activity or a component of a UI.</p>


<dl class="xml">

<dt>file location:</dt>
<dd><code>res/layout/<em>filename</em>.xml</code><br/>
The filename will be used as the resource ID.</dd>

<dt>compiled resource datatype:</dt>
<dd>Resource pointer to a {@link android.view.View} (or subclass) resource.</dd>

<dt>resource reference:</dt>
<dd>
In Java: <code>R.layout.<em>filename</em></code><br/>
In XML: <code>@[<em>package</em>:]layout/<em>filename</em></code>
</dd>

<dt>syntax:</dt>
<dd>
<pre class="stx">
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;<a href="#viewgroup-element"><em>ViewGroup</em></a> xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@[+][<em>package</em>:]id/<em>resource_name</em>"
    android:layout_height=["<em>dimension</em>" | "fill_parent" | "wrap_content"]
    android:layout_width=["<em>dimension</em>" | "fill_parent" | "wrap_content"]
    [<em>ViewGroup-specific attributes</em>] &gt;
    &lt;<a href="#view-element"><em>View</em></a>
        android:id="@[+][<em>package</em>:]id/<em>resource_name</em>"
        android:layout_height=["<em>dimension</em>" | "fill_parent" | "wrap_content"]
        android:layout_width=["<em>dimension</em>" | "fill_parent" | "wrap_content"]
        [<em>View-specific attributes</em>] &gt;
        &lt;<a href="#requestfocus-element">requestFocus</a>/&gt;
    &lt;/<em>View</em>&gt;
    &lt;<a href="#viewgroup-element"><em>ViewGroup</em></a> &gt;
        &lt;<a href="#view-element"><em>View</em></a> /&gt;
    &lt;/<em>ViewGroup</em>&gt;
    &lt;<a href="#include-element">include</a> layout="@layout/<i>layout_resource</i>"/&gt;
&lt;/<em>ViewGroup</em>&gt;
</pre>
<p class="note"><strong>Note:</strong> The root element can be either a
{@link android.view.ViewGroup}, a {@link android.view.View}, or a <a
href="#merge-element">{@code &lt;merge&gt;}</a> element, but there must be only
one root element and it must contain the {@code xmlns:android} attribute with the {@code android}
namespace as shown.</p>
</dd>

<dt>elements:</dt>
<dd>
  <dl class="tag-list">

  <dt id="viewgroup-element"><code>&lt;ViewGroup&gt;</code></dt>
    <dd>A container for other {@link android.view.View} elements. There are many
    different kinds of {@link android.view.ViewGroup} objects and each one lets you
    specify the layout of the child elements in different ways. Different kinds of
    {@link android.view.ViewGroup} objects include {@link android.widget.LinearLayout},
    {@link android.widget.RelativeLayout}, and {@link android.widget.FrameLayout}.
    <p>You should not assume that any derivation of {@link android.view.ViewGroup}
    will accept nested {@link android.view.View}s. Some {@link android.view.ViewGroup}s
    are implementations of the {@link android.widget.AdapterView} class, which determines
    its children only from an {@link android.widget.Adapter}.</p>
      <p class="caps">attributes:</p>
      <dl class="atn-list">
        <dt><code>android:id</code></dt>
        <dd><em>Resource ID</em>. A unique resource name for the element, which you can
use to obtain a reference to the {@link android.view.ViewGroup} from your application. See more
about the <a href="#idvalue">value for {@code android:id}</a> below.
        </dd>
        <dt><code>android:layout_height</code></dt>
        <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the group, as a
dimension value (or <a
href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"}
or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below.
        </dd>
        <dt><code>android:layout_width</code></dt>
        <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The width for the group, as a
dimension value (or <a
href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"}
or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below.
        </dd>
      </dl>
      <p>More attributes are supported by the {@link android.view.ViewGroup}
      base class, and many more are supported by each implementation of
      {@link android.view.ViewGroup}. For a reference of all available attributes,
      see the corresponding reference documentation for the {@link android.view.ViewGroup} class
(for example, the <a
      href="{@docRoot}reference/android/widget/LinearLayout.html#lattrs">LinearLayout XML
attributes</a>).</p>
    </dd>
  <dt id="view-element"><code>&lt;View&gt;</code></dt>
    <dd>An individual UI component, generally referred to as a "widget". Different
    kinds of {@link android.view.View} objects include {@link android.widget.TextView},
    {@link android.widget.Button}, and {@link android.widget.CheckBox}.
      <p class="caps">attributes:</p>
      <dl class="atn-list">
        <dt><code>android:id</code></dt>
        <dd><em>Resource ID</em>. A unique resource name for the element, which you can use to
          obtain a reference to the {@link android.view.View} from your application. See more about
the <a href="#idvalue">value for {@code android:id}</a> below.
        </dd>
        <dt><code>android:layout_height</code></dt>
        <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the element, as
a dimension value (or <a
href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"}
or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below.
        </dd>
        <dt><code>android:layout_width</code></dt>
        <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The width for the element, as
a dimension value (or <a
href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"}
or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below.
        </dd>
      </dl>
      <p>More attributes are supported by the {@link android.view.View}
      base class, and many more are supported by each implementation of
      {@link android.view.View}. Read <a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring
      Layout</a> for more information. For a reference of all available attributes,
      see the corresponding reference documentation (for example, the <a
      href="{@docRoot}reference/android/widget/TextView.html#lattrs">TextView XML attributes</a>).</p>
    </dd>
  <dt id="requestfocus-element"><code>&lt;requestFocus&gt;</code></dt>
    <dd>Any element representing a {@link android.view.View} object can include this empty element,
    which gives it's parent initial focus on the screen. You can have only one of these
    elements per file.</dd>

  <dt id="include-element"><code>&lt;include&gt;</code></dt>
    <dd>Includes a layout file into this layout.
      <p class="caps">attributes:</p>
      <dl class="atn-list">
        <dt><code>layout</code></dt>
        <dd><em>Layout resource</em>. <strong>Required</strong>. Reference to a layout
resource.</dd>
        <dt><code>android:id</code></dt>
        <dd><em>Resource ID</em>. Overrides the ID given to the root view in the included layout.
        </dd>
        <dt><code>android:layout_height</code></dt>
        <dd><em>Dimension or keyword</em>. Overrides the height given to the root view in the
included layout. Only effective if <code>android:layout_width</code> is also declared.
        </dd>
        <dt><code>android:layout_width</code></dt>
        <dd><em>Dimension or keyword</em>. Overrides the width given to the root view in the
included layout. Only effective if <code>android:layout_height</code> is also declared.
        </dd>
      </dl>
      <p>You can include any other layout attributes in the <code>&lt;include&gt;</code> that are
supported by the root element in the included layout and they will override those defined in the
root element.</p>

      <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>Another way to include a layout is to use {@link android.view.ViewStub}. It is a lightweight
View that consumes no layout space until you explicitly inflate it, at which point, it includes a
layout file defined by its {@code android:layout} attribute. For more information about using {@link
android.view.ViewStub}, read <a href="{@docRoot}resources/articles/layout-tricks-stubs.html">Layout
Tricks: ViewStubs</a>.</p>
    </dd>

  <dt id="merge-element"><code>&lt;merge&gt;</code></dt>
    <dd>An alternative root element that is not drawn in the layout hierarchy. Using this as the
root element is useful when you know that this layout will be placed into a layout
that already contains the appropriate parent View to contain the children of the
<code>&lt;merge&gt;</code> element. This is particularly useful when you plan to include this layout
in another layout file using <a href="#include-element"><code>&lt;include&gt;</code></a> and
this layout doesn't require a different {@link android.view.ViewGroup} container. For more
information about merging layouts, read <a
href="{@docRoot}resources/articles/layout-tricks-merge.html">Layout
Tricks: Merging</a>.</dd>

  </dl>



<h4 id="idvalue">Value for <code>android:id</code></h4>

<p>For the ID value, you should usually use this syntax form: <code>"@+id/<em>name</em>"</code>. The
plus symbol, {@code +}, indicates that this is a new resource ID and the <code>aapt</code> tool will
create a new resource integer in the {@code R.java} class, if it doesn't already exist. For
example:</p>
<pre>
&lt;TextView android:id="@+id/nameTextbox"/>
</pre>
<p>The <code>nameTextbox</code> name is now a resource ID attached to this element. You can then
refer to the {@link android.widget.TextView} to which the ID is associated in Java:</p>
<pre>
findViewById(R.id.nameTextbox);
</pre>
<p>This code returns the {@link android.widget.TextView} object.</p>

<p>However, if you have already defined an <a
href="{@docRoot}guide/topics/resources/drawable-resource.html#Id">ID resource</a> (and it is not
already used), then you can apply that ID to a {@link android.view.View} element by excluding the
plus symbol in the <code>android:id</code> value.</p>

<h4 id="layoutvalues">Value for <code>android:layout_height</code> and
<code>android:layout_width</code>:</h4>

  <p>The height and width value can be expressed using any of the
  <a href="more-resources.html#Dimension">dimension
  units</a> supported by Android (px, dp, sp, pt, in, mm) or with the following keywords:</p>
  <table><tr><th>Value</th><th>Description</th></tr>
    <tr>
      <td><code>match_parent</code></td>
      <td>Sets the dimension to match that of the parent element. Added in API Level 8 to
deprecate <code>fill_parent</code>.</td>
    </tr>
    <tr>
      <td><code>fill_parent</code></td>
      <td>Sets the dimension to match that of the parent element.</td>
    </tr><tr>
      <td><code>wrap_content</code></td>
      <td>Sets the dimension only to the size required to fit the content of this element.</td>
    </tr>
  </table>

<h4>Custom View elements</h4>

<p>You can create your own custom {@link android.view.View} and {@link android.view.ViewGroup}
elements and apply them to your layout the same as a standard layout
element. You can also specify the attributes supported in the XML element. To learn more,
read <a href="{@docRoot}guide/topics/ui/custom-components.html">Building Custom Components</a>.
</p>

</dd> <!-- end  elements and attributes -->

<dt>example:</dt>
<dd>XML file saved at <code>res/layout/main_activity.xml</code>:
<pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
              android:layout_width="fill_parent"
              android:layout_height="fill_parent"
              android:orientation="vertical" >
    &lt;TextView android:id="@+id/text"
              android:layout_width="wrap_content"
              android:layout_height="wrap_content"
              android:text="Hello, I am a TextView" />
    &lt;Button android:id="@+id/button"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:text="Hello, I am a Button" />
&lt;/LinearLayout>
</pre>
    <p>This application code will load the layout for an {@link android.app.Activity}, in the
    {@link android.app.Activity#onCreate(Bundle) onCreate()} method:</dt>
    <dd>
<pre>
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView.(R.layout.main_activity);
}
</pre>
</dd> <!-- end example -->


<dt>see also:</dt>
<dd>
<ul>
  <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></li>
  <li>{@link android.view.View}</li>
  <li>{@link android.view.ViewGroup}</li>
</ul>
</dd>

</dl>