1 page.title=Declaring a UI in XML 2 parent.title=Views and Layout 3 parent.link=index.html 4 @jd:body 5 6 <p>You can create your application's user interface in two ways: 7 <ul> 8 <li>You can declare UI elements statically, in XML. Android provides a straightforward XML vocabulary that corresponds to the View classes and subclasses, such as those for widgets and layouts. </li> 9 <li>You can instantiate screen elements dynamically, at runtime, through code in your application. Your application can refer to or create View or other class objects and manipulate their properties programmatically. </li> 10 </ul> 11 12 <p>One advantage of declaring your UI in XML is that it enables you to better separate the presentation of your application from the code that controls it's behavior. Your UI description is 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 and for a variety of device screen sizes or languages. Additionally, declaring in XML makes it easier to see the elements and structure of your UI, so it's easier to debug problems. </p> 13 14 <p>The Android framework gives you the flexibility to use either or both of these ways of 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> 15 16 <p>You build your application's UI in approximately the same way, whether you are declaring it in XML or programmatically. In both cases, your UI will be a tree structure that may include multiple View or Viewgroup subclasses. <p> 17 18 <p>In general, the XML vocabulary for declaring UI elements closely follows the structure and naming of the framework's UI-related 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. </p> 19 20 <p>However, note that the XML vocabulary for defining UI is not entirely identical to the framework's classes and methods. In some cases, there are slight naming differences. For 21 example, the EditText element has a <code>text</code> attribute that corresponds to 22 EditText.setText. </p> 23 24 <div class="sidebox-wrapper"> 25 <div class="sidebox"> 26 <p>For your convenience, the API reference documentation for UI related classes 27 lists the available XML attributes that correspond to the class methods, including inherited 28 attributes.</p> 29 30 <p>To learn more about the available XML elements and attributes, as well as the format of the XML file, see <a 31 href="{@docRoot}reference/available-resources.html#layoutresources">Layout Resources</a>.</p> 32 </div> 33 </div> 34 35 <p>Using Android's XML vocabulary, you can quickly design UI layouts and the screen elements they contain, in the same way you create HTML files — as a series of nested tags. </p> 36 37 <p>Each layout file must contain exactly one root element, and the root element must be a View or ViewGroup object. Once you've defined the root element, you can add additional layout objects or controls as child elements of the root element, if needed. In the example below, the tree of XML elements evaluates to the outermost LinearLayout object. 38 39 <p>After you've declared your layout in XML, you must save the file, with the <code>.xml</code> extension, in the proper location, so that it will be compiled correctly. The proper location for storing layout files is in your application's <code>res/layout/</code> directory. </p> 40 41 <p>When you compile your application, each XML layout file is compiled into an 42 android.view.View resource. You can then load the layout resource from your application code, by calling <code>setContentView(R.layout.<em>layout_file_name</em>)</code> in your {@link android.app.Activity#onCreate(android.os.Bundle) Activity.onCreate()} 43 implementation.</p> 44 45 <p>When you load a layout resource, the Android system initializes run-time objects corresponding to the elements in your layout. It parses the elements of your layout in-order (depth-first), instantiating the Views and adding them to their parent(s). </p> 46 47 <p>Attributes named <code>layout_<em>something</em></code> apply to that 48 object's LayoutParams member. <a href="{@docRoot}reference/available-resources.html#layoutresources">Layout 49 Resources</a> also describes how to learn the syntax for specifying 50 LayoutParams properties. </p> 51 52 <p>Also note that Android draws elements in the order in which they 53 appear in the XML. Therefore, if elements overlap, the last one in the XML 54 file will probably be drawn on top of any previously listed elements in that 55 same space.</p> 56 57 <p>The following values are supported for dimensions (described in {@link 58 android.util.TypedValue TypedValue}):</p> 59 60 <ul> 61 <li>px (pixels) </li> 62 <li>dip (device independent pixels) </li> 63 <li>sp (scaled pixels — best for text size) </li> 64 <li>pt (points) </li> 65 <li>in (inches) </li> 66 <li>mm (millimeters) </li> 67 </ul> 68 69 <p>Example: <code>android:layout_width="25px"</code> </p> 70 71 <p>For more information about these dimensions, see <a href="{@docRoot}reference/available-resources.html#dimension">Dimension Values</a>.</p> 72 73 <p>The example below shows an XML file and the resulting screen in the UI. Note that the text on the 74 top of the screen was set by calling {@link 75 android.app.Activity#setTitle(java.lang.CharSequence) Activity.setTitle}. Note 76 that the attributes that refer to relative elements (i.e., layout_toLeft) 77 refer to the ID using the syntax of a relative resource 78 (@id/<em>id_number</em>). </p> 79 80 <table border="1"> 81 <tr> 82 <td> 83 <pre><?xml version="1.0" encoding="utf-8"?> 84 <!-- Demonstrates using a relative layout to create a form --> 85 <RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android 86 android:layout_width="fill_parent" 87 android:layout_height="wrap_content" 88 android:background="@drawable/blue" 89 android:padding="10px"> 90 91 <TextView id="@+id/label" 92 android:layout_width="fill_parent" 93 android:layout_height="wrap_content" 94 android:text="Type here:"/> 95 96 <EditText id="@+id/entry" 97 android:layout_width="fill_parent" 98 android:layout_height="wrap_content" 99 android:background="@android:drawable/editbox_background" 100 android:layout_below="@id/label"/> 101 102 <Button id="@+id/ok" 103 android:layout_width="wrap_content" 104 android:layout_height="wrap_content" 105 android:layout_below="@id/entry" 106 android:layout_alignParentRight="true" 107 android:layout_marginLeft="10px" 108 android:text="OK" /> 109 110 <Button android:layout_width="wrap_content" 111 android:layout_height="wrap_content" 112 android:layout_toLeftOf="@id/ok" 113 android:layout_alignTop="@id/ok" 114 android:text="Cancel" /> 115 </RelativeLayout></pre></td> 116 <td><img src="{@docRoot}images/designing_ui_layout_example.png" alt="Screen shot showing how this layout XML file is rendered." /></td> 117 </tr> 118 </table> 119 120 <h3>Loading the XML Resource </h3> 121 122 <p>Loading the compiled layout resource is very easy, and done with a single 123 call in the activity's onCreate() method, as shown here:</p> 124 125 <pre> 126 protected void onCreate(Bundle savedValues) 127 { 128 // Be sure to call the super class. 129 super.onCreate(savedValues); 130 131 // Load the compiled layout resource into the window's 132 // default ViewGroup. 133 // The source file is res/layout/hello_activity.xml 134 setContentView(R.layout.hello_activity); 135 136 // Retrieve any important stored values. 137 restoreValues(savedValues); 138 } </pre> 139
