1 page.title=XML Layouts 2 parent.title=User Interface 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 <ol> 10 <li><a href="#write">Write the XML</a></li> 11 <li><a href="#load">Load the XML Resource</a></li> 12 <li><a href="#attributes">Attributes</a> 13 <ol> 14 <li><a href="#id">ID</a></li> 15 <li><a href="#layout-params">Layout Parameters</a></li> 16 </ol> 17 </li> 18 <li><a href="#Position">Position</a></li> 19 <li><a href="#SizePaddingMargins">Size, Padding and Margins</a></li> 20 </ol> 21 22 <h2>Key classes</h2> 23 <ol> 24 <li>{@link android.view.View}</li> 25 <li>{@link android.view.ViewGroup}</li> 26 <li>{@link android.view.ViewGroup.LayoutParams}</li> 27 </ol> 28 </div> 29 </div> 30 31 <p>Your layout is the architecture for the user interface in an Activity. 32 It defines the layout structure and holds all the elements that appear to the user. 33 You can declare your layout in two ways:</p> 34 <ul> 35 <li><strong>Declare UI elements in XML</strong>. Android provides a straightforward XML 36 vocabulary that corresponds to the View classes and subclasses, such as those for widgets and layouts.</li> 37 <li><strong>Instantiate layout elements at runtime</strong>. Your 38 application can create View and ViewGroup objects (and manipulate their properties) programmatically. </li> 39 </ul> 40 41 <p>The Android framework gives you the flexibility to use either or both of these methods for declaring and managing your application's UI. For example, you could declare your application's default layouts in XML, including the screen elements that will appear in them and their properties. You could then add code in your application that would modify the state of the screen objects, including those declared in XML, at run time. </p> 42 43 <div class="sidebox-wrapper"> 44 <div class="sidebox"> 45 <ul> 46 <li>The <a href="{@docRoot}sdk/eclipse-adt.html">ADT 47 Plugin for Eclipse</a> offers a layout preview of your XML — 48 with the XML file opened, select the <strong>Layout</strong> tab.</li> 49 <li>You should also try the 50 <a href="{@docRoot}guide/developing/debugging/debugging-ui.html#hierarchyViewer">Hierarchy Viewer</a> tool, 51 for debugging layouts — it reveals layout property values, 52 draws wireframes with padding/margin indicators, and full rendered views while 53 you debug on the emulator or device.</li> 54 <li>The <a href="{@docRoot}guide/developing/debugging/debugging-ui.html#layoutopt">layoutopt</a> tool lets 55 you quickly analyze your layouts and hierarchies for inefficiencies or other problems.</li> 56 </div> 57 </div> 58 59 <p>The advantage to declaring your UI in XML is that it enables you to better separate the presentation of your application from the code that controls its behavior. Your UI descriptions are external to your application code, which means that you can modify or adapt it without having to modify your source code and recompile. For example, you can create XML layouts for different screen orientations, different device screen sizes, and different languages. Additionally, declaring the layout in XML makes it easier to visualize the structure of your UI, so it's easier to debug problems. As such, this document focuses on teaching you how to declare your layout in XML. If you're 60 interested in instantiating View objects at runtime, refer to the {@link android.view.ViewGroup} and 61 {@link android.view.View} class references.</p> 62 63 <p>In general, the XML vocabulary for declaring UI elements closely follows the structure and naming of the classes and methods, where element names correspond to class names and attribute names correspond to methods. In fact, the correspondence is often so direct that you can guess what XML attribute corresponds to a class method, or guess what class corresponds to a given xml element. However, note that not all vocabulary is identical. In some cases, there are slight naming differences. For 64 example, the EditText element has a <code>text</code> attribute that corresponds to 65 <code>EditText.setText()</code>. </p> 66 67 <p class="note"><strong>Tip:</strong> Learn more about different layout types in <a href="{@docRoot}guide/topics/ui/layout-objects.html">Common 68 Layout Objects</a>. There are also a collection of tutorials on building various layouts in the 69 <a href="{@docRoot}resources/tutorials/views/index.html">Hello Views</a> tutorial guide.</p> 70 71 <h2 id="write">Write the XML</h2> 72 73 <div class="sidebox-wrapper"> 74 <div class="sidebox"> 75 <p>For your convenience, the API reference documentation for UI related classes 76 lists the available XML attributes that correspond to the class methods, including inherited 77 attributes.</p> 78 <p>To learn more about the available XML elements and attributes, as well as the format of the XML file, see <a 79 href="{@docRoot}guide/topics/resources/available-resources.html#layoutresources">Layout Resources</a>.</p> 80 </div> 81 </div> 82 83 <p>Using Android's XML vocabulary, you can quickly design UI layouts and the screen elements they contain, in the same way you create web pages in HTML — with a series of nested elements. </p> 84 85 <p>Each layout file must contain exactly one root element, which must be a View or ViewGroup object. Once you've defined the root element, you can add additional layout objects or widgets as child elements to gradually build a View hierarchy that defines your layout. For example, here's an XML layout that uses a vertical {@link android.widget.LinearLayout} 86 to hold a {@link android.widget.TextView} and a {@link android.widget.Button}:</p> 87 <pre> 88 <?xml version="1.0" encoding="utf-8"?> 89 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 90 android:layout_width="fill_parent" 91 android:layout_height="fill_parent" 92 android:orientation="vertical" > 93 <TextView android:id="@+id/text" 94 android:layout_width="wrap_content" 95 android:layout_height="wrap_content" 96 android:text="Hello, I am a TextView" /> 97 <Button android:id="@+id/button" 98 android:layout_width="wrap_content" 99 android:layout_height="wrap_content" 100 android:text="Hello, I am a Button" /> 101 </LinearLayout> 102 </pre> 103 104 <p>After you've declared your layout in XML, save the file with the <code>.xml</code> extension, 105 in your Android project's <code>res/layout/</code> directory, so it will properly compile. </p> 106 107 <p>We'll discuss each of the attributes shown here a little later.</p> 108 109 <h2 id="load">Load the XML Resource</h2> 110 111 <p>When you compile your application, each XML layout file is compiled into a 112 {@link android.view.View} resource. You should load the layout resource from your application code, in your 113 {@link android.app.Activity#onCreate(android.os.Bundle) Activity.onCreate()} callback implementation. 114 Do so by calling <code>{@link android.app.Activity#setContentView(int) setContentView()}</code>, 115 passing it the reference to your layout resource in the form of: 116 <code>R.layout.<em>layout_file_name</em></code> 117 For example, if your XML layout is saved as <code>main_layout.xml</code>, you would load it 118 for your Activity like so:</p> 119 <pre> 120 public void onCreate(Bundle savedInstanceState) { 121 super.onCreate(savedInstanceState); 122 setContentView(R.layout.main_layout); 123 } 124 </pre> 125 126 <p>The <code>onCreate()</code> callback method in your Activity is called by the Android framework when 127 your Activity is launched (see the discussion about lifecycles, in the 128 <a href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">Activities</a> 129 document).</p> 130 131 132 <h2 id="attributes">Attributes</h2> 133 134 <p>Every View and ViewGroup object supports their own variety of XML attributes. 135 Some attributes are specific to a View object (for example, TextView supports the <code>textSize</code> 136 attribute), but these attributes are also inherited by any View objects that may extend this class. 137 Some are common to all View objects, because they are inherited from the root View class (like 138 the <code>id</code> attribute). And, other attributes are considered "layout parameters," which are 139 attributes that describe certain layout orientations of the View object, as defined by that object's 140 parent ViewGroup object.</p> 141 142 <h3 id="id">ID</h3> 143 144 <p>Any View object may have an integer ID associated with it, to uniquely identify the View within the tree. 145 When the application is compiled, this ID is referenced as an integer, but the ID is typically 146 assigned in the layout XML file as a string, in the <code>id</code> attribute. 147 This is an XML attribute common to all View objects 148 (defined by the {@link android.view.View} class) and you will use it very often. 149 The syntax for an ID, inside an XML tag is:</p> 150 <pre>android:id="@+id/my_button"</pre> 151 152 <p>The at-symbol (@) at the beginning of the string indicates that the XML parser should parse and expand the rest 153 of the ID string and identify it as an ID resource. The plus-symbol (+) means that this is a new resource name that must 154 be created and added to our resources (in the <code>R.java</code> file). There are a number of other ID resources that 155 are offered by the Android framework. When referencing an Android resource ID, you do not need the plus-symbol, 156 but must add the <code>android</code> package namespace, like so:</p> 157 <pre>android:id="@android:id/empty"</pre> 158 <p>With the <code>android</code> package namespace in place, we're now referencing an ID from the <code>android.R</code> 159 resources class, rather than the local resources class.</p> 160 161 <p>In order to create views and reference them from the application, a common pattern is to:</p> 162 <ol> 163 <li>Define a view/widget in the layout file and assign it a unique ID: 164 <pre> 165 <Button android:id="@+id/my_button" 166 android:layout_width="wrap_content" 167 android:layout_height="wrap_content" 168 android:text="@string/my_button_text"/> 169 </pre> 170 </li> 171 <li>Then create an instance of the view object and capture it from the layout 172 (typically in the <code>{@link android.app.Activity#onCreate(Bundle) onCreate()}</code> method): 173 <pre> 174 Button myButton = (Button) findViewById(R.id.my_button); 175 </pre> 176 </li> 177 </ol> 178 <p>Defining IDs for view objects is important when creating a {@link android.widget.RelativeLayout}. 179 In a relative layout, sibling views can define their layout relative to another sibling view, 180 which is referenced by the unique ID.</p> 181 <p>An ID need not be unique throughout the entire tree, but it should be 182 unique within the part of the tree you are searching (which may often be the entire tree, so it's best 183 to be completely unique when possible).</p> 184 185 186 <h3 id="layout-params">Layout Parameters</h3> 187 188 <p>XML layout attributes named <code>layout_<em>something</em></code> define 189 layout parameters for the View that are appropriate for the ViewGroup in which it resides.</p> 190 191 <p>Every ViewGroup class implements a nested class that extends {@link 192 android.view.ViewGroup.LayoutParams}. This subclass 193 contains property types that define the size and position for each child view, as 194 appropriate for the view group. As you can see in figure 1, the parent 195 view group defines layout parameters for each child view (including the child view group).</p> 196 197 <img src="{@docRoot}images/layoutparams.png" alt="" height="300" align="center"/> 198 <p class="img-caption"><strong>Figure 1.</strong> Visualization of a view hierarchy with layout 199 parameters associated with each view.</p> 200 201 <p>Note that every LayoutParams subclass has its own syntax for setting 202 values. Each child element must define LayoutParams that are appropriate for its parent, 203 though it may also define different LayoutParams for its own children. </p> 204 205 <p>All view groups include a width and height (<code>layout_width</code> and 206 <code>layout_height</code>), and each view is required to define them. Many 207 LayoutParams also include optional margins and borders. <p> 208 209 <p>You can specify width and height with exact measurements, though you probably 210 won't want to do this often. More often, you will use one of these constants to 211 set the width or height: </p> 212 213 <ul> 214 <li><var>wrap_content</var> tells your view to size itself to the dimensions 215 required by its content</li> 216 <li><var>fill_parent</var> (renamed <var>match_parent</var> in API Level 8) 217 tells your view to become as big as its parent view group will allow.</li> 218 </ul> 219 220 <p>In general, specifying a layout width and height using absolute units such as 221 pixels is not recommended. Instead, using relative measurements such as 222 density-independent pixel units (<var>dp</var>), <var>wrap_content</var>, or 223 <var>fill_parent</var>, is a better approach, because it helps ensure that 224 your application will display properly across a variety of device screen sizes. 225 The accepted measurement types are defined in the 226 <a href="{@docRoot}guide/topics/resources/available-resources.html#dimension"> 227 Available Resources</a> document.</p> 228 229 230 <h2 id="Position">Layout Position</h2> 231 <p> 232 The geometry of a view is that of a rectangle. A view has a location, 233 expressed as a pair of <em>left</em> and <em>top</em> coordinates, and 234 two dimensions, expressed as a width and a height. The unit for location 235 and dimensions is the pixel. 236 </p> 237 238 <p> 239 It is possible to retrieve the location of a view by invoking the methods 240 {@link android.view.View#getLeft()} and {@link android.view.View#getTop()}. The former returns the left, or X, 241 coordinate of the rectangle representing the view. The latter returns the 242 top, or Y, coordinate of the rectangle representing the view. These methods 243 both return the location of the view relative to its parent. For instance, 244 when getLeft() returns 20, that means the view is located 20 pixels to the 245 right of the left edge of its direct parent. 246 </p> 247 248 <p> 249 In addition, several convenience methods are offered to avoid unnecessary 250 computations, namely {@link android.view.View#getRight()} and {@link android.view.View#getBottom()}. 251 These methods return the coordinates of the right and bottom edges of the 252 rectangle representing the view. For instance, calling {@link android.view.View#getRight()} 253 is similar to the following computation: <code>getLeft() + getWidth()</code>. 254 </p> 255 256 257 <h2 id="SizePaddingMargins">Size, Padding and Margins</h2> 258 <p> 259 The size of a view is expressed with a width and a height. A view actually 260 possess two pairs of width and height values. 261 </p> 262 263 <p> 264 The first pair is known as <em>measured width</em> and 265 <em>measured height</em>. These dimensions define how big a view wants to be 266 within its parent. The 267 measured dimensions can be obtained by calling {@link android.view.View#getMeasuredWidth()} 268 and {@link android.view.View#getMeasuredHeight()}. 269 </p> 270 271 <p> 272 The second pair is simply known as <em>width</em> and <em>height</em>, or 273 sometimes <em>drawing width</em> and <em>drawing height</em>. These 274 dimensions define the actual size of the view on screen, at drawing time and 275 after layout. These values may, but do not have to, be different from the 276 measured width and height. The width and height can be obtained by calling 277 {@link android.view.View#getWidth()} and {@link android.view.View#getHeight()}. 278 </p> 279 280 <p> 281 To measure its dimensions, a view takes into account its padding. The padding 282 is expressed in pixels for the left, top, right and bottom parts of the view. 283 Padding can be used to offset the content of the view by a specific amount of 284 pixels. For instance, a left padding of 2 will push the view's content by 285 2 pixels to the right of the left edge. Padding can be set using the 286 {@link android.view.View#setPadding(int, int, int, int)} method and queried by calling 287 {@link android.view.View#getPaddingLeft()}, {@link android.view.View#getPaddingTop()}, 288 {@link android.view.View#getPaddingRight()} and {@link android.view.View#getPaddingBottom()}. 289 </p> 290 291 <p> 292 Even though a view can define a padding, it does not provide any support for 293 margins. However, view groups provide such a support. Refer to 294 {@link android.view.ViewGroup} and 295 {@link android.view.ViewGroup.MarginLayoutParams} for further information. 296 </p> 297 298 <p>For more information about dimensions, see 299 <a href="{@docRoot}guide/topics/resources/more-resources.html#Dimension">Dimension Values</a>. 300 </p> 301 302 303 304 305
