docs/html/guide/topics/views/ui-xml.jd - platform/frameworks/base - Git at Google

 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-wrapper">
 <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>
 </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>
	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-wrapper">
	<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>
	</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 — 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 — best for text size) </li>
	<li>pt (points) </li>
	<li>in (inches) </li>
	<li>mm (millimeters) </li>
	</ul>

	<p>Example: <code>android:layout_width="25px"</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><?xml version="1.0" encoding="utf-8"?>
	<!-- Demonstrates using a relative layout to create a form -->
	<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android
	android:layout_width="fill_parent"
	android:layout_height="wrap_content"
	android:background="@drawable/blue"
	android:padding="10px">

	<TextView id="@+id/label"
	android:layout_width="fill_parent"
	android:layout_height="wrap_content"
	android:text="Type here:"/>

	<EditText id="@+id/entry"
	android:layout_width="fill_parent"
	android:layout_height="wrap_content"
	android:background="@android:drawable/editbox_background"
	android:layout_below="@id/label"/>

	<Button id="@+id/ok"
	android:layout_width="wrap_content"
	android:layout_height="wrap_content"
	android:layout_below="@id/entry"
	android:layout_alignParentRight="true"
	android:layout_marginLeft="10px"
	android:text="OK" />

	<Button android:layout_width="wrap_content"
	android:layout_height="wrap_content"
	android:layout_toLeftOf="@id/ok"
	android:layout_alignTop="@id/ok"
	android:text="Cancel" />
	</RelativeLayout></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>