page.title=Declaring a UI in XML
parent.title=Views and Layout
parent.link=index.html
@jd:body

<p>You can create your application's user interface in two ways: 
<ul>
<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>
<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>
</ul>

<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>

<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>

<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>

<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>

<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
example, the EditText element has a <code>text</code> attribute that corresponds to
EditText.setText. </p>

<div class="sidebox"><p>For your convenience, the API reference documentation for UI related classes lists the available XML attributes that correspond to the class methods, including inherited attributes.</p>

<p>To learn more about the available XML elements and attributes, as well as the format of the XML file, see <a
href="{@docRoot}reference/available-resources.html#layoutresources">Layout Resources</a>.</p>
 </div>

<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 &mdash; as a series of nested tags. </p>

<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.

<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>

<p>When you compile your application, each XML layout file is compiled into an
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()} 
implementation.</p>

<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>

<p>Attributes named <code>layout_<em>something</em></code> apply to that
object's LayoutParams member. <a href="{@docRoot}reference/available-resources.html#layoutresources">Layout
Resources</a> also describes how to learn the syntax for specifying
LayoutParams properties. </p>

<p>Also note that Android draws elements in the order in which they
appear in the XML. Therefore, if elements overlap, the last one in the XML
file will probably be drawn on top of any previously listed elements in that
same space.</p>

<p>The following values are supported for dimensions (described in {@link
android.util.TypedValue TypedValue}):</p>

<ul>
    <li>px (pixels) </li>
    <li>dip (device independent pixels) </li>
    <li>sp (scaled pixels &mdash; best for text size) </li>
    <li>pt (points) </li>
    <li>in (inches) </li>
    <li>mm (millimeters) </li>
</ul>

<p>Example: <code>android:layout_width=&quot;25px&quot;</code> </p>

<p>For more information about these dimensions, see <a href="{@docRoot}reference/available-resources.html#dimension">Dimension Values</a>.</p>

<p>The example below shows an XML file and the resulting screen in the UI. Note that the text on the
top of the screen was set by calling {@link
android.app.Activity#setTitle(java.lang.CharSequence) Activity.setTitle}. Note
that the attributes that refer to relative elements (i.e., layout_toLeft)
refer to the ID using the syntax of a relative resource
(@id/<em>id_number</em>). </p>

<table border="1">
    <tr>
        <td>
        <pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;!-- Demonstrates using a relative layout to create a form --&gt;
&lt;RelativeLayout xmlns:android=&quot;http://schemas.android.com/apk/res/android
                android:layout_width=&quot;fill_parent&quot; 
                android:layout_height=&quot;wrap_content&quot;
                android:background=&quot;@drawable/blue&quot;
                android:padding=&quot;10px&quot;&gt;

    &lt;TextView id=&quot;@+id/label&quot; 
              android:layout_width=&quot;fill_parent&quot; 
              android:layout_height=&quot;wrap_content&quot; 
              android:text=&quot;Type here:&quot;/&gt;

    &lt;EditText id=&quot;@+id/entry&quot; 
              android:layout_width=&quot;fill_parent&quot; 
              android:layout_height=&quot;wrap_content&quot; 
              android:background=&quot;@android:drawable/editbox_background&quot;
              android:layout_below=&quot;@id/label&quot;/&gt;
  
    &lt;Button id=&quot;@+id/ok&quot; 
            android:layout_width=&quot;wrap_content&quot; 
            android:layout_height=&quot;wrap_content&quot; 
            android:layout_below=&quot;@id/entry&quot;
            android:layout_alignParentRight=&quot;true&quot;
            android:layout_marginLeft=&quot;10px&quot;
            android:text=&quot;OK&quot; /&gt;

    &lt;Button android:layout_width=&quot;wrap_content&quot; 
            android:layout_height=&quot;wrap_content&quot;
            android:layout_toLeftOf=&quot;@id/ok&quot;
            android:layout_alignTop=&quot;@id/ok&quot;
            android:text=&quot;Cancel&quot; /&gt;
&lt;/RelativeLayout&gt;</pre></td>
        <td><img src="{@docRoot}images/designing_ui_layout_example.png" alt="Screen shot showing how this layout XML file is rendered."  /></td>
    </tr>
</table>

<h3>Loading the XML Resource </h3>

<p>Loading the compiled layout resource is very easy, and done with a single
call in the activity's onCreate() method, as shown here:</p>

<pre>
protected void onCreate(Bundle savedValues)
{
   // Be sure to call the super class.
   super.onCreate(savedValues);

   // Load the compiled layout resource into the window's
   // default ViewGroup.
   // The source file is res/layout/hello_activity.xml
    setContentView(R.layout.hello_activity);
  
   // Retrieve any important stored values.
   restoreValues(savedValues);
} </pre>
