layout-resource.jd revision 5dd0fd5c89099f194b9ec2323bb6413fa48e7db8
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=["<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="@+id/<em>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</<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.html#lattrs">LinearLayout XML 101attributes</a>).</p> 102 </dd> 103 <dt id="view-element"><code><View></code></dt> 104 <dd>An individual UI component, generally referred to as a "widget". Different 105 kinds of {@link android.view.View} objects include {@link android.widget.TextView}, 106 {@link android.widget.Button}, and {@link android.widget.CheckBox}. 107 <p class="caps">attributes:</p> 108 <dl class="atn-list"> 109 <dt><code>android:id</code></dt> 110 <dd><em>Resource name</em>. A unique resource name for the element, which you can use to 111 obtain a reference to the {@link android.view.View} from your application. 112 The value takes the form: <code>"@+id/<em>name</em>"</code>. See more about the 113 <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 </dl> 141 142<h4 id="idvalue">Value for <code>android:id</code></h4> 143 144<p>For the ID value, you should use this syntax form: <code>"@+id/<em>name</em>"</code>. The plus symbol, 145{@code +}, indicates that this is a new resource ID and the aapt tool will create 146a new resource number to the {@code R.java} class, if it doesn't already exist. For example:</p> 147<pre> 148<TextView android:id="@+id/nameTextbox"/> 149</pre> 150<p>You can then refer to it this way in Java:</p> 151<pre> 152findViewById(R.id.nameTextbox); 153</pre> 154 155<h4 id="layoutvalues">Value for <code>android:layout_height</code> and 156<code>android:layout_width</code>:</h4> 157 158 <p>The height and width value can be expressed using any of the 159 <a href="more-resources.html#Dimension">dimension 160 units</a> supported by Android (px, dp, sp, pt, in, mm) or with the following keywords:</p> 161 <table><tr><th>Value</th><th>Description</th></tr> 162 <tr> 163 <td><code>match_parent</code></td> 164 <td>Sets the dimension to match that of the parent element. Added in API Level 8 to 165deprecate <code>fill_parent</code>.</td> 166 </tr> 167 <tr> 168 <td><code>fill_parent</code></td> 169 <td>Sets the dimension to match that of the parent element.</td> 170 </tr><tr> 171 <td><code>wrap_content</code></td> 172 <td>Sets the dimension only to the size required to fit the content of this element.</td> 173 </tr> 174 </table> 175 176<h4>Custom View elements</h4> 177 178<p>You can create your own custom {@link android.view.View} and {@link android.view.ViewGroup} 179elements and apply them to your layout the same as a standard layout 180element. You can also specify the attributes supported in the XML element. To learn more, 181read <a href="{@docRoot}guide/topics/ui/custom-components.html">Building Custom Components</a>. 182</p> 183 184</dd> <!-- end elements and attributes --> 185 186<dt>example:</dt> 187<dd>XML file saved at <code>res/layout/main_activity.xml</code>: 188<pre> 189<?xml version="1.0" encoding="utf-8"?> 190<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 191 android:layout_width="fill_parent" 192 android:layout_height="fill_parent" 193 android:orientation="vertical" > 194 <TextView android:id="@+id/text" 195 android:layout_width="wrap_content" 196 android:layout_height="wrap_content" 197 android:text="Hello, I am a TextView" /> 198 <Button android:id="@+id/button" 199 android:layout_width="wrap_content" 200 android:layout_height="wrap_content" 201 android:text="Hello, I am a Button" /> 202</LinearLayout> 203</pre> 204 <p>This application code will load the layout for an {@link android.app.Activity}, in the 205 {@link android.app.Activity#onCreate(Bundle) onCreate()} method:</dt> 206 <dd> 207<pre> 208public void onCreate(Bundle savedInstanceState) { 209 super.onCreate(savedInstanceState); 210 setContentView.(R.layout.main_activity); 211} 212</pre> 213</dd> <!-- end example --> 214 215 216<dt>see also:</dt> 217<dd> 218<ul> 219 <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></li> 220 <li>{@link android.view.View}</li> 221 <li>{@link android.view.ViewGroup}</li> 222</ul> 223</dd> 224 225</dl>