tobi/M7350
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M7350v1_en_gpl

Browse Source
This commit is contained in:
T
2024-09-09 08:52:07 +00:00
commit f9cc65cfda
65988 changed files with 26357421 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
base/docs/html/guide/topics/views/custom-views.jd
+544
View File
@@ -0,0 +1,544 @@
page.title=Building Custom Views
parent.title=Views and Layout
parent.link=index.html
@jd:body
<p>Android offers a sophisticated and powerful componentized model for building your UI, based on the fundamental building block classes {@link android.view.View} and {@link android.view.ViewGroup}. To start with, the platform includes a variety of prebuilt View and ViewGroup subclasses &mdash; called widgets and layouts, respectively &mdash; that you can use to construct your UI. The widgets and layouts are fully implemented and handle all of their own measuring and drawing, so you can use them right away. You can make new types of UI elements simply by nesting and grouping the widgets and layouts. Using widgets and layouts is the recommended approach to building a UI for your applications.</p>
<p>A partial list of available widgets includes {@link android.widget.Button Button},
{@link android.widget.TextView TextView},
{@link android.widget.EditText EditText},
{@link android.widget.ListView ListView},
{@link android.widget.CheckBox CheckBox},
{@link android.widget.RadioButton RadioButton},
{@link android.widget.Gallery Gallery},
{@link android.widget.Spinner Spinner}, and the more special-purpose
{@link android.widget.AutoCompleteTextView AutoCompleteTextView},
{@link android.widget.ImageSwitcher ImageSwitcher}, and
{@link android.widget.TextSwitcher TextSwitcher}. </p>
<p>Among the layouts available are {@link android.widget.LinearLayout LinearLayout},
{@link android.widget.FrameLayout FrameLayout}, {@link android.widget.AbsoluteLayout AbsoluteLayout}, and others. For more examples, see <a href="layout">Common Layout Objects</a>.</p>
<p>If none of the prebuilt widgets or layouts meets your needs, you can also create your own View subclass, such as a layout group or compound control. If you only need to make small adjustments to an existing widget or layout, you can simply subclass the widget or layout and override its methods.
</p>
<p>Creating your own View subclasses gives you precise control over the appearance and function of a screen element. To give an idea of the control you get with custom views, here are some examples of what you could do with them:</p>
<ul>
<li>
You could create a completely custom-rendered View type, for example a "volume
control" knob rendered using 2D graphics, and which resembles an
analog electronic control.
</li>
<li>
You could combine a group of View components into a new single component, perhaps
to make something like a ComboBox (a combination of popup list and free
entry text field), a dual-pane selector control (a left and right pane
with a list in each where you can re-assign which item is in which
list), and so on.
</li>
<li>
You could override the way that an EditText component is rendered on the screen
(the <a href="{@docRoot}resources/samples/NotePad/">Notepad sample</a> uses this to good effect,
to create a lined-notepad page).
</li>
<li>
You could capture other events like key presses and handle them in some custom
way (such as for a game).
</li>
</ul>
<p>
The sections below explain how to create custom Views and use them in your application.
For detailed reference information, see the {@link android.view.View} class. </p>
<p>This document covers the following:</p>
<ol class="toc">
<li><a href="#basic">The Basic Approach</a></li>
<li><a href="#custom">Fully Customized Views</a></li>
<li><a href="#customexample">Customized View Example</a></li>
<li><a href="#compound">Compound Controls</a></li>
<li><a href="#tweaking">Modifying an Existing Component Type</a></li>
</ol>
<a name="basic"></a>
<h2>The Basic Approach
</h2>
<p>
These steps provide a high level overview of
what you need to know to get started in creating your own
View components:</p>
<ol>
<li>
Extend an existing {@link android.view.View View} class or subclass
with your own class.
</li>
<li>
Override some of the methods from the superclass: the superclass methods
to override start with '<code>on</code>', for
example, {@link android.view.View#onDraw onDraw()},
{@link android.view.View#onMeasure onMeasure()}, and
{@link android.view.View#onKeyDown onKeyDown()}.
<ul>
<li>
This is similar to the <code>on...</code> events in {@link android.app.Activity
Activity} or {@link android.app.ListActivity ListActivity}
that you override for life cycle and other functionality hooks.
</li>
</ul>
<li>
Use your new extension class: once completed, your new extension class
can be used in place of the view upon which it was based, but now with the new
functionality.
</li>
</ol>
<p class="note"><strong>Tip:</strong>
Extension classes can be defined as inner classes inside the activities
that use them. This is useful because it controls access to them but
isn't necessary (perhaps you want to create a new public View for
wider use in your application).
</p>
<a name="custom"></a>
<h2>Fully Customized Components</h2>
<p>
Fully customized components can be used to create graphical components that
appear however you wish. Perhaps a graphical VU
meter that looks like an old analog gauge, or a sing-a-long text view where
a bouncing ball moves along the words so you can sing along with a karaoke
machine. Either way, you want something that the built-in components just
won't do, no matter how you combine them.</p>
<p>Fortunately, you can easily create components that look and behave in any
way you like, limited perhaps only by your imagination, the size of the
screen, and the available processing power (remember that ultimately your
application might have to run on something with significantly less power
than your desktop workstation).</p>
<p>To create a fully customized component:</p>
<ol>
<li>
The most generic view you can extend is, unsurprisingly, {@link
android.view.View View}, so you will usually start by extending this to
create your new super component.
</li>
<li>
You can supply a constructor which can
take attributes and parameters from the XML, and you can also consume
your own such attributes and parameters (perhaps the color and range of
the VU meter, or the width and damping of the needle, etc.)
</li>
<li>
You will probably want to create your own event listeners,
property accessors and modifiers, and possibly more sophisticated
behavior in your component class as well.
</li>
<li>
You will almost certainly want to override <code>onMeasure()</code> and
are also likely to need to override <code>onDraw()</code> if you want
the component to show something. While both have default behavior,
the default <code>onDraw()</code> will do nothing, and the default
<code>onMeasure()</code> will always set a size of 100x100 &mdash; which is
probably not what you want.
</li>
<li>
Other <code>on...</code> methods may also be overridden as required.
</li>
</ol>
<h4><code>onDraw()</code> and <code>onMeasure()</code></h4>
<p><code>onDraw()</code> delivers you a {@link android.graphics.Canvas Canvas}
upon which you can implement anything you want: 2D graphics, other standard or
custom components, styled text, or anything else you can think of.</p>
<p><em>Note:</em>
Except for 3D graphics. If you want to
use 3D graphics, you must extend {@link android.view.SurfaceView SurfaceView}
instead of View, and draw from a separate thread. See the
GLSurfaceViewActivity sample
for details.</p>
<p><code>onMeasure()</code> is a little more involved. <code>onMeasure()</code>
is a critical piece of the rendering contract between your component and its
container. <code>onMeasure()</code> should be overridden to efficiently and
accurately report the measurements of its contained parts. This is made
slightly more complex by the requirements of limits from the parent
(which are passed in to the <code>onMeasure()</code> method) and by the
requirement to call the <code>setMeasuredDimension()</code> method with the
measured width and height once they have been calculated. If you fail to
call this method from an overridden <code>onMeasure()</code> method, the
result will be an exception at measurement time.</p>
<p>At a high level, implementing <code>onMeasure()</code> looks something
like this:</p>
<ol>
<li>
The overridden <code>onMeasure()</code> method is called with width and
height measure specifications (<code>widthMeasureSpec</code> and
<code>heightMeasureSpec</code> parameters, both are integer codes
representing dimensions) which should be treated as requirements for
the restrictions on the width and height measurements you should produce. A
full reference to the kind of restrictions these specifications can require
can be found in the reference documentation under {@link
android.view.View#onMeasure View.onMeasure(int, int)} (this reference
documentation does a pretty good job of explaining the whole measurement
operation as well).
</li>
<li>
Your component's <code>onMeasure()</code> method should calculate a
measurement width and height which will be required to render the
component. It should try to stay within the specifications passed in,
although it can choose to exceed them (in this case, the parent can
choose what to do, including clipping, scrolling, throwing an exception,
or asking the <code>onMeasure()</code> to try again, perhaps with
different measurement specifications).
</li>
<li>
Once the width and height are calculated, the <code>setMeasuredDimension(int
width, int height)</code> method must be called with the calculated
measurements. Failure to do this will result in an exception being
thrown.
</li>
</ol>
<p>
Here's a summary of some of the other standard methods that the framework calls on views:
</p>
<table border="2" width="85%" align="center" cellpadding="5">
<thead>
<tr><th>Category</th> <th>Methods</th> <th>Description</th></tr>
</thead>
<tbody>
<tr>
<td rowspan="2">Creation</td>
<td>Constructors</td>
<td>There is a form of the constructor that are called when the view
is created from code and a form that is called when the view is
inflated from a layout file. The second form should parse and apply
any attributes defined in the layout file.
</td>
</tr>
<tr>
<td><code>{@link android.view.View#onFinishInflate()}</code></td>
<td>Called after a view and all of its children has been inflated
from XML.</td>
</tr>
<tr>
<td rowspan="3">Layout</td>
<td><code>{@link android.view.View#onMeasure}</code></td>
<td>Called to determine the size requirements for this view and all
of its children.
</td>
</tr>
<tr>
<td><code>{@link android.view.View#onLayout}</code></td>
<td>Called when this view should assign a size and position to all
of its children.
</td>
</tr>
<tr>
<td><code>{@link android.view.View#onSizeChanged}</code></td>
<td>Called when the size of this view has changed.
</td>
</tr>
<tr>
<td>Drawing</td>
<td><code>{@link android.view.View#onDraw}</code></td>
<td>Called when the view should render its content.
</td>
</tr>
<tr>
<td rowspan="4">Event processing</td>
<td><code>{@link android.view.View#onKeyDown}</code></td>
<td>Called when a new key event occurs.
</td>
</tr>
<tr>
<td><code>{@link android.view.View#onKeyUp}</code></td>
<td>Called when a key up event occurs.
</td>
</tr>
<tr>
<td><code>{@link android.view.View#onTrackballEvent}</code></td>
<td>Called when a trackball motion event occurs.
</td>
</tr>
<tr>
<td><code>{@link android.view.View#onTouchEvent}</code></td>
<td>Called when a touch screen motion event occurs.
</td>
</tr>
<tr>
<td rowspan="2">Focus</td>
<td><code>{@link android.view.View#onFocusChanged}</code></td>
<td>Called when the view gains or loses focus.
</td>
</tr>
<tr>
<td><code>{@link android.view.View#onWindowFocusChanged}</code></td>
<td>Called when the window containing the view gains or loses focus.
</td>
</tr>
<tr>
<td rowspan="3">Attaching</td>
<td><code>{@link android.view.View#onAttachedToWindow()}</code></td>
<td>Called when the view is attached to a window.
</td>
</tr>
<tr>
<td><code>{@link android.view.View#onDetachedFromWindow}</code></td>
<td>Called when the view is detached from its window.
</td>
</tr>
<tr>
<td><code>{@link android.view.View#onWindowVisibilityChanged}</code></td>
<td>Called when the visibility of the window containing the view
has changed.
</td>
</tr>
</tbody>
</table>
<a name="customexample"></a>
<h3>A Custom View Example</h3>
<p>The CustomView sample in the
<a href="{@docRoot}samples/ApiDemos/index.html">API Demos</a> provides an example
of a customized View. The custom View is defined in the
<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/view/LabelView.html">LabelView</a>
class.</p>
<p>The LabelView sample demonstrates a number of different aspects of custom components:</p>
<ul>
<li>Extending the View class for a completely custom component.</li>
<li>Parameterized constructor that takes the view inflation parameters
(parameters defined in the XML). Some of these are passed through to the
View superclass, but more importantly, there are some custom attributes defined
and used for LabelView.</li>
<li>Standard public methods of the type you would expect to see for a label
component, for example <code>setText()</code>, <code>setTextSize()</code>,
<code>setTextColor()</code> and so on.</li>
<li>An overridden <code>onMeasure</code> method to determine and set the
rendering size of the component. (Note that in LabelView, the real work is done
by a private <code>measureWidth()</code> method.)</li>
<li>An overridden <code>onDraw()</code> method to draw the label onto the
provided canvas.</li>
</ul>
<p>You can see some sample usages of the LabelView custom View in
<a href="{@docRoot}samples/ApiDemos/res/layout/custom_view_1.html">custom_view_1.xml</a>
from the samples. In particular, you can see a mix of both <code>android:</code>
namespace parameters and custom <code>app:</code> namespace parameters. These
<code>app:</code> parameters are the custom ones that the LabelView recognizes
and works with, and are defined in a styleable inner class inside of the
samples R resources definition class.</p>
<a name="compound"></a>
<h2>Compound Controls
</h2>
<p>If you don't want to create a completely customized component, but instead
are looking to put together a reusable component that consists of a group of
existing controls, then creating a Compound Component (or Compound Control) might
fit the bill. In a nutshell, this brings together a number of more atomic
controls (or views) into a logical group of items that can be treated as a
single thing. For example, a Combo Box can be thought of as a
combination of a single line EditText field and an adjacent button with an attached
PopupList. If you press the button and select
something from the list, it populates the EditText field, but the user can
also type something directly into the EditText if they prefer.</p>
<p>In Android, there are actually two other Views readily available to do
this: {@link android.widget.Spinner Spinner} and
{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, but
regardless, the concept of a Combo Box makes an easy-to-understand
example.</p>
<p>To create a compound component:</p>
<ol>
<li>
The usual starting point is a Layout of some kind, so create a class
that extends a Layout. Perhaps in the case of a Combo box we might use
a LinearLayout with horizontal orientation. Remember that other layouts
can be nested inside, so the compound component can be arbitrarily
complex and structured. Note that just like with an Activity, you can
use either the declarative (XML-based) approach to creating the
contained components, or you can nest them programmatically from your
code.
</li>
<li>
In the constructor for the new class, take whatever parameters the
superclass expects, and pass them through to the superclass constructor
first. Then you can set up the other views to use within your new
component; this is where you would create the EditText field and the
PopupList. Note that you also might introduce your own attributes and
parameters into the XML that can be pulled out and used by your
constructor.
</li>
<li>
You can also create listeners for events that your contained views might
generate, for example, a listener method for the List Item Click Listener
to update the contents of the EditText if a list selection is made.
</li>
<li>
You might also create your own properties with accessors and modifiers,
for example, allow the EditText value to be set initially in the
component and query for its contents when needed.
</li>
<li>
In the case of extending a Layout, you don't need to override the
<code>onDraw()</code> and <code>onMeasure()</code> methods since the
layout will have default behavior that will likely work just fine. However,
you can still override them if you need to.
</li>
<li>
You might override other <code>on...</code> methods, like
<code>onKeyDown()</code>, to perhaps choose certain default values from
the popup list of a combo box when a certain key is pressed.
</li>
</ol>
<p>
To summarize, the use of a Layout as the basis for a Custom Control has a
number of advantages, including:</p>
<ul>
<li>
You can specify the layout using the declarative XML files just like
with an activity screen, or you can create views programmatically and
nest them into the layout from your code.
</li>
<li>
The <code>onDraw()</code> and <code>onMeasure()</code> methods (plus
most of the other <code>on...</code> methods) will likely have suitable behavior so
you don't have to override them.
</li>
<li>
In the end, you can very quickly construct arbitrarily complex compound
views and re-use them as if they were a single component.
</li>
</ul>
<h4>Examples of Compound Controls</h4>
<p>In the API Demos project
that comes with the SDK, there are two List
examples &mdash; Example 4 and Example 6 under Views/Lists demonstrate a
SpeechView which extends LinearLayout to make a component for displaying
Speech quotes. The corresponding classes in the sample code are
<code>List4.java</code> and <code>List6.java</code>.</p>
<a name="tweaking"></a>
<h2>Modifying an Existing View Type
</h2>
<p>There is an even easier option for creating a custom View which is
useful in certain circumstances. If there is a component that is already very
similar to what you want, you can simply extend that component and just
override the behavior that you want to change. You can do all of the things
you would do with a fully customized component, but by starting with a more
specialized class in the View hierarchy, you can also get a lot of behavior for
free that probably does exactly what you want.</p>
<p>For example, the SDK includes a <a
href="{@docRoot}samples/NotePad/index.html">NotePad application</a> in the
samples. This demonstrates many aspects of using the Android platform, among
them is extending an EditText View to make a lined notepad. This is not a
perfect example, and the APIs for doing this might change from this early
preview, but it does demonstrate the principles.</p>
<p>If you haven't done so already, import the
NotePad sample into Eclipse (or
just look at the source using the link provided). In particular look at the definition of
<code>MyEditText</code> in the <a
href="{@docRoot}samples/NotePad/src/com/example/android/notepad/NoteEditor.html">NoteEditor.java</a>
file.</p>
<p>Some points to note here</p>
<ol>
<li>
<strong>The Definition</strong>
<p>The class is defined with the following line:</p>
<code>public static class MyEditText extends EditText</code><br><br>
<ul>
<li>
It is defined as an inner class within the <code>NoteEditor</code>
activity, but it is public so that it could be accessed as
<code>NoteEditor.MyEditText</code> from outside of the <code>NoteEditor</code>
class if desired.
</li>
<li>
It is <code>static</code>, meaning it does not generate the so-called
"synthetic methods" that allow it to access data from the parent
class, which in turn means that it really behaves as a separate
class rather than something strongly related to <code>NoteEditor</code>.
This is a cleaner way to create inner classes if they do not need
access to state from the outer class, keeps the generated class
small, and allows it to be used easily from other classes.
</li>
<li>
It extends <code>EditText</code>, which is the View we have chosen to
customize in this case. When we are finished, the new class will be
able to substitute for a normal <code>EditText</code> view.<br>
<br>
</li>
</ul>
</li>
<li>
<strong>Class Initialization</strong>
<p>As always, the super is called first. Furthermore,
this is not a default constructor, but a parameterized one. The
EditText is created with these parameters when it is inflated from an
XML layout file, thus, our constructor needs to both take them and pass them
to the superclass constructor as well.</p>
</li>
<li>
<strong>Overridden Methods</strong>
<p>In this example, there is only one method to be overridden:
<code>onDraw()</code> &mdash; but there could easily be others needed when you
create your own custom components.</p>
<p>For the NotePad sample, overriding the <code>onDraw()</code> method allows
us to paint the blue lines on the <code>EditText</code> view canvas (the
canvas is passed into the overridden <code>onDraw()</code> method). The
super.onDraw() method is called before the method ends. The
superclass method should be invoked, but in this case, we do it at the
end after we have painted the lines we want to include.</p>
<li>
<strong>Use the Custom Component</strong>
<p>We now have our custom component, but how can we use it? In the
NotePad example, the custom component is used directly from the
declarative layout, so take a look at <code>note_editor.xml</code> in the
<code>res/layout</code> folder.</p>
<pre>
&lt;view xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot;
class=&quot;com.android.notepad.NoteEditor$MyEditText&quot;
id=&quot;&#64;+id/note&quot;
android:layout_width=&quot;fill_parent&quot;
android:layout_height=&quot;fill_parent&quot;
android:background=&quot;&#64;android:drawable/empty&quot;
android:padding=&quot;10dip&quot;
android:scrollbars=&quot;vertical&quot;
android:fadingEdge=&quot;vertical&quot; /&gt; </pre>
<ul>
<li>
The custom component is created as a generic view in the XML, and
the class is specified using the full package. Note also that the
inner class we defined is referenced using the
<code>NoteEditor$MyEditText</code> notation which is a standard way to
refer to inner classes in the Java programming language.
</li>
<li>
The other attributes and parameters in the definition are the ones
passed into the custom component constructor, and then passed
through to the EditText constructor, so they are the same
parameters that you would use for an EditText view. Note that it is
possible to add your own parameters as well, and we will touch on
this again below.
</li>
</ul>
</li>
</ol>
<p>And that's all there is to it. Admittedly this is a simple case, but
that's the point &mdash; creating custom components is only as complicated as you
need it to be.</p>
<p>A more sophisticated component may override even more <code>on...</code> methods and
introduce some of its own helper methods, substantially customizing its properties and
behavior. The only limit is your imagination and what you need the component to
do.</p>
base/docs/html/guide/topics/views/intro.jd
+49
View File
@@ -0,0 +1,49 @@
page.title=Introduction to Views
parent.title=Views and Layout
parent.link=index.html
@jd:body
<p>The basic functional unit of an Android application is the <em>activity</em> &mdash; an object of the class {@link android.app.Activity android.app.Activity}. An activity can do many things, but by itself it does not have a presence on the screen. To give your activity a screen presence and design its UI, you work with <em>views</em> and <em>viewgroups</em> -- basic units of user interface expression on the Android platform.</p>
<h2>Views</h2>
<p>A view is an object of base class {@link android.view.View android.view.View}. It's a data structure whose properties store the layout and content for a specific rectangular area of the screen. A View object handles measuring and layout, drawing, focus change, scrolling, and key/gestures for the screen area it represents. </p>
<p>The View class serves as a base class for <em>widgets </em> &mdash; a set of fully implemented subclasses that draw interactive screen elements. Widgets handle their own measuring and drawing, so you can use them to build your UI more quickly. The list of widgets available includes Text, EditText, InputMethod, MovementMethod, Button, RadioButton, Checkbox, and ScrollView.</p>
<h2>Viewgroups </h2>
<p>A viewgroup is an object of class {@link android.view.ViewGroup android.view.Viewgroup}. As its name indicates, a viewgroup is a special type of view object whose function is to contain and manage a subordinate set of views and other viewgroups, Viewgroups let you add structure to your UI and build up complex screen elements that can be addressed as a single entity. </p>
<p>The Viewgroup class serves as a base class for <em>layouts</em> &mdash; a set of fully implemented subclasses that provide common types of screen layout. The layouts give you a way to build a structure for a set of views. </p>
<h2>A Tree-Structured UI</h2>
<p>On the Android platform, you define an Activity's UI using a tree of view and viewgroup nodes, as shown in the diagram below. The tree can be as simple or complex as you need to make it, and you can build it up using Android's set of predefined widgets and layouts or custom view types that you create yourself. </p>
<img src={@docRoot}images/viewgroup.png alt="An example of a tree of views and viewgroups" width="312" height="211" align="center"/>
<p>To attach the tree to the screen for rendering, your Activity calls its setContentView() method and passes a reference to the root node object. Once the Android system has the reference to the root node object, it can work directly with the node to invalidate, measure, and draw the tree. When your Activity becomes active and receives focus, the system notifies your activity and requests the root node to measure and draw the tree. The root node then requests that its child nodes draw themselves &mdash; in turn, each viewgroup node in the tree is responsible for drawing its direct children. </p>
<p>As mentioned previously, each view group has the responsibility of
measuring its available space, laying out its children, and calling Draw() on
each child to let it render itself. The children may request a size and location
in the parent, but the parent object has the final decision on where how big
each child can be.</p>
<h2>LayoutParams: How a Child Specifies Its Position and Size</h2>
<p>Every viewgroup class uses a nested class that extends {@link
android.view.ViewGroup.LayoutParams ViewGroup.LayoutParams}. This subclass
contains property types that define a child's size and position, in properties
appropriate for that view group class. </p>
<img src={@docRoot}images/layoutparams.png alt="An example of layoutparams" width="632" height="369" align="center"/>
<p>Note that every LayoutParams subclass has its own syntax for setting
values. Each child element must define LayoutParams that are appropriate for its parent, although it may define different LayoutParams for its children. </p>
<p>All viewgroups include width and height. Many also include margins and
borders. You can specify width and height exactly, though you probably won't want
to do this often. More often you will tell your view to size itself either to
the dimensions of its content, or to become as big as its containing object
will allow.</p>
base/docs/html/guide/topics/views/ui-xml.jd
+138
View File
@@ -0,0 +1,138 @@
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>