layout-resource.jd revision dfe5c204403bc56c29bb36410574eab8b1950417
1page.title=Layout Resource 2parent.title=Resource Types 3parent.link=available-resources.html 4@jd:body 5 6<div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>See also</h2> 9 <ol> 10 <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></li> 11 </ol> 12 </div> 13</div> 14 15<p>A layout resource defines the architecture for the UI in an Activity or a component of a UI.</p> 16 17 18<dl class="xml"> 19 20<dt>file location:</dt> 21<dd><code>res/layout/<em>filename</em>.xml</code><br/> 22The filename will be used as the resource ID.</dd> 23 24<dt>compiled resource datatype:</dt> 25<dd>Resource pointer to a {@link android.view.View} (or subclass) resource.</dd> 26 27<dt>resource reference:</dt> 28<dd> 29In Java: <code>R.layout.<em>filename</em></code><br/> 30In XML: <code>@[<em>package</em>:]layout/<em>filename</em></code> 31</dd> 32 33<dt>syntax:</dt> 34<dd> 35<pre class="stx"> 36<?xml version="1.0" encoding="utf-8"?> 37<<a href="#viewgroup-element"><em>ViewGroup</em></a> xmlns:android="http://schemas.android.com/apk/res/android" 38 android:id="@[+][<em>package</em>:]id/<em>resource_name</em>" 39 android:layout_height=["<em>dimension</em>" | "fill_parent" | "wrap_content"] 40 android:layout_width=["<em>dimension</em>" | "fill_parent" | "wrap_content"] 41 [<em>ViewGroup-specific attributes</em>] > 42 <<a href="#view-element"><em>View</em></a> 43 android:id="@[+][<em>package</em>:]id/<em>resource_name</em>" 44 android:layout_height=["<em>dimension</em>" | "fill_parent" | "wrap_content"] 45 android:layout_width=["<em>dimension</em>" | "fill_parent" | "wrap_content"] 46 [<em>View-specific attributes</em>] > 47 <<a href="#requestfocus-element">requestFocus</a>/> 48 </<em>View</em>> 49 <<a href="#viewgroup-element"><em>ViewGroup</em></a> > 50 <<a href="#view-element"><em>View</em></a> /> 51 </<em>ViewGroup</em>> 52 <<a href="#include-element">include</a> layout="@layout/<i>layout_resource</i>"/> 53</<em>ViewGroup</em>> 54</pre> 55<p class="note"><strong>Note:</strong> The root element can be either a 56{@link android.view.ViewGroup}, a {@link android.view.View}, or a <a 57href="#merge-element">{@code <merge>}</a> element, but there must be only 58one root element and it must contain the {@code xmlns:android} attribute with the {@code android} 59namespace as shown.</p> 60</dd> 61 62<dt>elements:</dt> 63<dd> 64 <dl class="tag-list"> 65 66 <dt id="viewgroup-element"><code><ViewGroup></code></dt> 67 <dd>A container for other {@link android.view.View} elements. There are many 68 different kinds of {@link android.view.ViewGroup} objects and each one lets you 69 specify the layout of the child elements in different ways. Different kinds of 70 {@link android.view.ViewGroup} objects include {@link android.widget.LinearLayout}, 71 {@link android.widget.RelativeLayout}, and {@link android.widget.FrameLayout}. 72 <p>You should not assume that any derivation of {@link android.view.ViewGroup} 73 will accept nested {@link android.view.View}s. Some {@link android.view.ViewGroup}s 74 are implementations of the {@link android.widget.AdapterView} class, which determines 75 its children only from an {@link android.widget.Adapter}.</p> 76 <p class="caps">attributes:</p> 77 <dl class="atn-list"> 78 <dt><code>android:id</code></dt> 79 <dd><em>Resource ID</em>. A unique resource name for the element, which you can 80use to obtain a reference to the {@link android.view.ViewGroup} from your application. See more 81about the <a href="#idvalue">value for {@code android:id}</a> below. 82 </dd> 83 <dt><code>android:layout_height</code></dt> 84 <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the group, as a 85dimension value (or <a 86href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"} 87or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below. 88 </dd> 89 <dt><code>android:layout_width</code></dt> 90 <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The width for the group, as a 91dimension value (or <a 92href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"} 93or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below. 94 </dd> 95 </dl> 96 <p>More attributes are supported by the {@link android.view.ViewGroup} 97 base class, and many more are supported by each implementation of 98 {@link android.view.ViewGroup}. For a reference of all available attributes, 99 see the corresponding reference documentation for the {@link android.view.ViewGroup} class 100(for example, the <a 101 href="{@docRoot}reference/android/widget/LinearLayout.html#lattrs">LinearLayout XML 102attributes</a>).</p> 103 </dd> 104 <dt id="view-element"><code><View></code></dt> 105 <dd>An individual UI component, generally referred to as a "widget". Different 106 kinds of {@link android.view.View} objects include {@link android.widget.TextView}, 107 {@link android.widget.Button}, and {@link android.widget.CheckBox}. 108 <p class="caps">attributes:</p> 109 <dl class="atn-list"> 110 <dt><code>android:id</code></dt> 111 <dd><em>Resource ID</em>. A unique resource name for the element, which you can use to 112 obtain a reference to the {@link android.view.View} from your application. See more about 113the <a href="#idvalue">value for {@code android:id}</a> below. 114 </dd> 115 <dt><code>android:layout_height</code></dt> 116 <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the element, as 117a dimension value (or <a 118href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"} 119or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below. 120 </dd> 121 <dt><code>android:layout_width</code></dt> 122 <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The width for the element, as 123a dimension value (or <a 124href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"} 125or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below. 126 </dd> 127 </dl> 128 <p>More attributes are supported by the {@link android.view.View} 129 base class, and many more are supported by each implementation of 130 {@link android.view.View}. Read <a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring 131 Layout</a> for more information. For a reference of all available attributes, 132 see the corresponding reference documentation (for example, the <a 133 href="{@docRoot}reference/android/widget/TextView.html#lattrs">TextView XML attributes</a>).</p> 134 </dd> 135 <dt id="requestfocus-element"><code><requestFocus></code></dt> 136 <dd>Any element representing a {@link android.view.View} object can include this empty element, 137 which gives it's parent initial focus on the screen. You can have only one of these 138 elements per file.</dd> 139 140 <dt id="include-element"><code><include></code></dt> 141 <dd>Includes a layout file into this layout. 142 <p class="caps">attributes:</p> 143 <dl class="atn-list"> 144 <dt><code>layout</code></dt> 145 <dd><em>Layout resource</em>. <strong>Required</strong>. Reference to a layout 146resource.</dd> 147 <dt><code>android:id</code></dt> 148 <dd><em>Resource ID</em>. Overrides the ID given to the root view in the included layout. 149 </dd> 150 <dt><code>android:layout_height</code></dt> 151 <dd><em>Dimension or keyword</em>. Overrides the height given to the root view in the 152included layout. 153 </dd> 154 <dt><code>android:layout_width</code></dt> 155 <dd><em>Dimension or keyword</em>. Overrides the width given to the root view in the 156included layout. 157 </dd> 158 </dl> 159 <p>You can include any other layout attributes in the <code><include></code> that are 160supported by the root element in the included layout and they will override those defined in the 161root element.</p> 162 163 <p>Another way to include a layout is to use {@link android.view.ViewStub}. It is a lightweight 164View that consumes no layout space until you explicitly inflate it, at which point, it includes a 165layout file defined by its {@code android:layout} attribute. For more information about using {@link 166android.view.ViewStub}, read <a href="{@docRoot}resources/articles/layout-tricks-stubs.html">Layout 167Tricks: ViewStubs</a>.</p> 168 </dd> 169 170 <dt id="merge-element"><code><merge></code></dt> 171 <dd>An alternative root element that is not drawn in the layout hierarchy. Using this as the 172root element is useful when you know that this layout will be placed into a layout 173that already contains the appropriate parent View to contain the children of the 174<code><merge></code> element. This is particularly useful when you plan to include this layout 175in another layout file using <a href="#include-element"><code><include></code></a> and 176this layout doesn't require a different {@link android.view.ViewGroup} container. For more 177information about merging layouts, read <a 178href="{@docRoot}resources/articles/layout-tricks-merging.html">Layout 179Tricks: Merging</a>.</dd> 180 181 </dl> 182 183 184 185<h4 id="idvalue">Value for <code>android:id</code></h4> 186 187<p>For the ID value, you should usually use this syntax form: <code>"@+id/<em>name</em>"</code>. The 188plus symbol, {@code +}, indicates that this is a new resource ID and the <code>aapt</code> tool will 189create a new resource integer in the {@code R.java} class, if it doesn't already exist. For 190example:</p> 191<pre> 192<TextView android:id="@+id/nameTextbox"/> 193</pre> 194<p>The <code>nameTextbox</code> name is now a resource ID attached to this element. You can then 195refer to the {@link android.widget.TextView} to which the ID is associated in Java:</p> 196<pre> 197findViewById(R.id.nameTextbox); 198</pre> 199<p>This code returns the {@link android.widget.TextView} object.</p> 200 201<p>However, if you have already defined an <a 202href="{@docRoot}guide/topics/resources/drawable-resource.html#Id">ID resource</a> (and it is not 203already used), then you can apply that ID to a {@link android.view.View} element by excluding the 204plus symbol in the <code>android:id</code> value.</p> 205 206<h4 id="layoutvalues">Value for <code>android:layout_height</code> and 207<code>android:layout_width</code>:</h4> 208 209 <p>The height and width value can be expressed using any of the 210 <a href="more-resources.html#Dimension">dimension 211 units</a> supported by Android (px, dp, sp, pt, in, mm) or with the following keywords:</p> 212 <table><tr><th>Value</th><th>Description</th></tr> 213 <tr> 214 <td><code>match_parent</code></td> 215 <td>Sets the dimension to match that of the parent element. Added in API Level 8 to 216deprecate <code>fill_parent</code>.</td> 217 </tr> 218 <tr> 219 <td><code>fill_parent</code></td> 220 <td>Sets the dimension to match that of the parent element.</td> 221 </tr><tr> 222 <td><code>wrap_content</code></td> 223 <td>Sets the dimension only to the size required to fit the content of this element.</td> 224 </tr> 225 </table> 226 227<h4>Custom View elements</h4> 228 229<p>You can create your own custom {@link android.view.View} and {@link android.view.ViewGroup} 230elements and apply them to your layout the same as a standard layout 231element. You can also specify the attributes supported in the XML element. To learn more, 232read <a href="{@docRoot}guide/topics/ui/custom-components.html">Building Custom Components</a>. 233</p> 234 235</dd> <!-- end elements and attributes --> 236 237<dt>example:</dt> 238<dd>XML file saved at <code>res/layout/main_activity.xml</code>: 239<pre> 240<?xml version="1.0" encoding="utf-8"?> 241<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 242 android:layout_width="fill_parent" 243 android:layout_height="fill_parent" 244 android:orientation="vertical" > 245 <TextView android:id="@+id/text" 246 android:layout_width="wrap_content" 247 android:layout_height="wrap_content" 248 android:text="Hello, I am a TextView" /> 249 <Button android:id="@+id/button" 250 android:layout_width="wrap_content" 251 android:layout_height="wrap_content" 252 android:text="Hello, I am a Button" /> 253</LinearLayout> 254</pre> 255 <p>This application code will load the layout for an {@link android.app.Activity}, in the 256 {@link android.app.Activity#onCreate(Bundle) onCreate()} method:</dt> 257 <dd> 258<pre> 259public void onCreate(Bundle savedInstanceState) { 260 super.onCreate(savedInstanceState); 261 setContentView.(R.layout.main_activity); 262} 263</pre> 264</dd> <!-- end example --> 265 266 267<dt>see also:</dt> 268<dd> 269<ul> 270 <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></li> 271 <li>{@link android.view.View}</li> 272 <li>{@link android.view.ViewGroup}</li> 273</ul> 274</dd> 275 276</dl>