layout-resource.jd revision f940a1f316ddbed760f6f3ab9a3e4f2112909381
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="@+id/<em>name</em>" 39 android:layout_height="@+id/<em>string_name</em>" 40 android:layout_width="@+id/<em>string_name</em>" 41 [<em>other attributes</em>] > 42 <<a href="#view-element"><em>View</em></a> 43 android:id="@+id/<em>name</em>" 44 android:layout_height="@+id/<em>string_name</em>" 45 android:layout_width="@+id/<em>string_name</em>" 46 [<em>other 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</<em>ViewGroup</em>> 53</pre> 54<p class="note"><strong>Note:</strong> The root element can be either a 55{@link android.view.ViewGroup} or a {@link android.view.View}, but there must be only 56one root element and it must contain the {@code xmlns:android} attribute with the {@code android} 57namespace as shown.</p> 58</dd> 59 60<dt>elements:</dt> 61<dd> 62 <dl class="tag-list"> 63 64 <dt id="viewgroup-element"><code><ViewGroup></code></dt> 65 <dd>A container for other {@link android.view.View} elements. There are many 66 different kinds of {@link android.view.ViewGroup} objects and each one lets you 67 specify the layout of the child elements in different ways. Different kinds of 68 {@link android.view.ViewGroup} objects include {@link android.widget.LinearLayout}, 69 {@link android.widget.RelativeLayout}, and {@link android.widget.FrameLayout}. 70 <p>You should not assume that any derivation of {@link android.view.ViewGroup} 71 will accept nested {@link android.view.View}s. Some {@link android.view.ViewGroup}s 72 are implementations of the {@link android.widget.AdapterView} class, which determines 73 its children only from an {@link android.widget.Adapter}.</p> 74 <p class="caps">attributes:</p> 75 <dl class="atn-list"> 76 <dt><code>android:id</code></dt> 77 <dd><em>Resource name</em>. A unique resource name for the element, which you can 78use to obtain a reference to the {@link android.view.ViewGroup} from your application. 79 The value takes the form: <code>"@+id/<em>name</em>"</code>. See more about the 80 <a href="#idvalue">value for {@code android:id}</a> below. 81 </dd> 82 <dt><code>android:layout_height</code></dt> 83 <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the group, as a 84dimension value (or <a 85href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"} 86or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below. 87 </dd> 88 <dt><code>android:layout_width</code></dt> 89 <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The width for the group, as a 90dimension value (or <a 91href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"} 92or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below. 93 </dd> 94 </dl> 95 <p>More attributes are supported by the {@link android.view.ViewGroup} 96 base class, and many more are supported by each implementation of 97 {@link android.view.ViewGroup}. For a reference of all available attributes, 98 see the corresponding reference documentation for the {@link android.view.ViewGroup} class 99(for example, the <a 100 href="{@docRoot}reference/android/widget/LinearLayout#lattrs">LinearLayout XML attributes</a>).</p> 101 </dd> 102 <dt id="view-element"><code><View></code></dt> 103 <dd>An individual UI component, generally referred to as a "widget". Different 104 kinds of {@link android.view.View} objects include {@link android.widget.TextView}, 105 {@link android.widget.Button}, and {@link android.widget.CheckBox}. 106 <p class="caps">attributes:</p> 107 <dl class="atn-list"> 108 <dt><code>android:id</code></dt> 109 <dd><em>Resource name</em>. A unique resource name for the element, which you can use to 110 obtain a reference to the {@link android.view.View} from your application. 111 The value takes the form: <code>"@+id/<em>name</em>"</code>. See more about the 112 <a href="#idvalue">value for {@code android:id}</a> below. 113 </dd> 114 <dt><code>android:layout_height</code></dt> 115 <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the element, as 116a dimension value (or <a 117href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"} 118or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below. 119 </dd> 120 <dt><code>android:layout_width</code></dt> 121 <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The width for the element, as 122a dimension value (or <a 123href="more-resources.html#Dimension">dimension resource</a>) or a keyword ({@code "fill_parent"} 124or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> below. 125 </dd> 126 </dl> 127 <p>More attributes are supported by the {@link android.view.View} 128 base class, and many more are supported by each implementation of 129 {@link android.view.View}. Read <a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring 130 Layout</a> for more information. For a reference of all available attributes, 131 see the corresponding reference documentation (for example, the <a 132 href="{@docRoot}reference/android/widget/TextView.html#lattrs">TextView XML attributes</a>).</p> 133 </dd> 134 <dt id="requestfocus-element"><code><requestFocus></code></dt> 135 <dd>Any element representing a {@link android.view.View} object can include this empty element, 136 which gives it's parent initial focus on the screen. You can have only one of these 137 elements per file.</dd> 138 139 </dl> 140 141<h4 id="idvalue">Value for <code>android:id</code></h4> 142 143<p>For the ID value, you should use this syntax form: <code>"@+id/<em>name</em>"</code>. The plus symbol, 144{@code +}, indicates that this is a new resource ID and the aapt tool will create 145a new resource number to the {@code R.java} class, if it doesn't already exist. For example:</p> 146<pre> 147<TextView android:id="@+id/nameTextbox"/> 148</pre> 149<p>You can then refer to it this way in Java:</p> 150<pre> 151findViewById(R.id.nameTextbox); 152</pre> 153 154<h4 id="layoutvalues">Value for <code>android:layout_height</code> and 155<code>android:layout_width</code>:</h4> 156 157 <p>The height and width value can be expressed using any of the 158 <a href="more-resources.html#Dimension">dimension 159 units</a> supported by Android (px, dp, sp, pt, in, mm) or with the following keywords:</p> 160 <table><tr><th>Value</th><th>Description</th></tr> 161 <tr> 162 <td><code>match_parent</code></td> 163 <td>Sets the dimension to match that of the parent element. Added in API Level 8 to 164deprecate <code>fill_parent</code>.</td> 165 </tr> 166 <tr> 167 <td><code>fill_parent</code></td> 168 <td>Sets the dimension to match that of the parent element.</td> 169 </tr><tr> 170 <td><code>wrap_content</code></td> 171 <td>Sets the dimension only to the size required to fit the content of this element.</td> 172 </tr> 173 </table> 174 175<h4>Custom View elements</h4> 176 177<p>You can create your own custom {@link android.view.View} and {@link android.view.ViewGroup} 178elements and apply them to your layout the same as a standard layout 179element. You can also specify the attributes supported in the XML element. To learn more, 180read <a href="{@docRoot}guide/topics/ui/custom-components.html">Building Custom Components</a>. 181</p> 182 183</dd> <!-- end elements and attributes --> 184 185<dt>example:</dt> 186<dd>XML file saved at <code>res/layout/main_activity.xml</code>: 187<pre> 188<?xml version="1.0" encoding="utf-8"?> 189<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 190 android:layout_width="fill_parent" 191 android:layout_height="fill_parent" 192 android:orientation="vertical" > 193 <TextView android:id="@+id/text" 194 android:layout_width="wrap_content" 195 android:layout_height="wrap_content" 196 android:text="Hello, I am a TextView" /> 197 <Button android:id="@+id/button" 198 android:layout_width="wrap_content" 199 android:layout_height="wrap_content" 200 android:text="Hello, I am a Button" /> 201</LinearLayout> 202</pre> 203 <p>This application code will load the layout for an {@link android.app.Activity}, in the 204 {@link android.app.Activity#onCreate(Bundle) onCreate()} method:</dt> 205 <dd> 206<pre> 207public void onCreate(Bundle savedInstanceState) { 208 super.onCreate(savedInstanceState); 209 setContentView.(R.layout.main_activity); 210} 211</pre> 212</dd> <!-- end example --> 213 214 215<dt>see also:</dt> 216<dd> 217<ul> 218 <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></li> 219 <li>{@link android.view.View}</li> 220 <li>{@link android.view.ViewGroup}</li> 221</ul> 222</dd> 223 224</dl>