docs/html/guide/topics/views/index.jd

page.title=Views and Layout
@jd:body

<div id="qv-wrapper">
<div id="qv">

  <h2>Key classes and packages</h2>
  <ol>
    <li>{@link android.view.View}</li>
    <li>{@link android.view.ViewGroup}</li>
    <li>{@link android.widget}</li>
  </ol>

  <h2>In this document</h2>
  <ol>
    <li><a href="#ViewHierarchy">View Hierarchy</a></li>
    <li><a href="#Layout">Layout</a></li>
    <li><a href="#Widgets">Widgets</a></li>
    <li><a href="#Events">Events</a></li>
    <li><a href="#Adapters">Adapters</a></li>
    <li><a href="#StylesAndThemes">Styles and Themes</a></li>
  </ol>
</div>
</div>

<p>In an Android application, a user interface is built using {@link android.view.View} and 
{@link android.view.ViewGroup} objects. There are many types of views and view groups, each of which 
is a descendant of the {@link android.view.View} class.</p>

<p>View objects are the basic units of user interface expression on the Android platform. 
The View class serves as the base for subclasses called "widgets," which offer fully implemented
UI objects, like text fields and buttons. The ViewGroup class serves as the base for subclasses called "layouts,"
which offer different kinds of layout architecture, like linear, tabular and relative.</p>

<p>A View object is a data structure whose properties store the layout properties and content for a specific 
rectangular area of the screen. A View object handles its own measurement, layout, drawing, focus change, 
scrolling, and key/gesture interactions for the rectangular screen area it represents. </p>


<h2 id="ViewHierarchy">View Hierarchy</h2>

<p>On the Android platform, you will define an Activity's UI using a hierarchy of view and view group nodes, 
as shown in the diagram below. This hierarchy tree can be as simple or complex as you need it to be, and you 
can build it up using Android's set of predefined widgets and layouts, or with custom view types that you 
create yourself.</p>

<img src="{@docRoot}images/viewgroup.png" alt="" width="312" height="211" align="center"/>

<p>The Android system will notify your Activity when it becomes active and receives focus.
In order to attach the view hierarchy tree to the screen for rendering, your Activity must call its 
<code>setContentView()</code> method and pass a reference to the root node object. The Android system
receives this reference so that it can invalidate, measure, and draw the tree. The root node requests 
that its child nodes draw themselves &mdash; in turn, each view group node is responsible for 
calling <code>Draw()</code> on each of its own child views, so that each child view can render itself. 
The children may request a size and location within the parent, but the parent object has the final 
decision on where how big each child can be. To learn more about how a view group and its children are measured
and drawn, read <a href="how-android-draws.html">How Android Draws Views</a>.</p>


<h2 id="Layout">Layout</h2>

<p>The most common way to define your layout and express the view hierarchy is with an XML layout file.
XML offers a human-readable structure for the layout, much like HTML. Each element in XML is 
(usually a descendant of) either a View or ViewGroup object. View objects are leaves in the tree, 
ViewGroup objects are branches in the tree. The name of an XML element
is the respective class object name. So a <code>&lt;TextView></code> element creates
a {@link android.widget.TextView} widget in your UI, and a <code>&lt;LinearLayout></code> element creates
a {@link android.widget.LinearLayout} layout branch in the tree. To learn more about how to write your layout in XML, 
read <a href="declaring-layout.html">Declaring and Querying Layout</a>.

<div class="sidebox-wrapper">
<div class="sidebox">
  <p><b>Tip:</b> You can also draw new views and view groups from within your code, 
  by adding new View and ViewGroup objects to an
  existing ViewGroup (specifically, you'll use the <code>addView()</code> methods to dynamically insert new views). 
  To see how to add views in your code, see the {@link android.view.ViewGroup} reference.</p>
</div>
</div>

<p>There are a variety of ways in which you can layout your views, using different view groups.
Some pre-defined view groups offered by Android (called layouts) include LinearLayout, RelativeLayout, AbsoluteLayout,
TableLayout, GridLayout and others. Each offers a different mechanisms for arranging child views
among each other. 
To learn more about how to use some of these view groups for your layout, 
read <a href="layout.html">Common Layout Objects</a>.

<h3 id="IDs">IDs</h3>

<p>Views may have an integer ID associated with them. The ID is written as a string, but once the application is
compiled, it will be referenced as an integer.
These IDs are typically assigned in the layout XML file as an attribute of the view,
and are used to uniquely identify a view within the tree. The usual syntax for an ID, inside an XML tag is:</p>
<pre>id="&#64;+id/my_button"</pre>
<p>The  at-symbol (&#64;) at the beginning of the string indicates that the XML parser should parse and expand the rest
of the ID string and identify it as an ID resource. The plus-symbol (+) means that this is a new resource name that must
be created and added to our resources (in the <code>R.java</code> file). There are a number of other ID resources that
are offered by the Android framework. When referencing an Android resource ID, you do not need the plus-symbol,
but must add the <code>android</code> package namespace, like so:</p>
<pre>id="&#64;android:id/empty"</pre>
<p>With the <code>android</code> package namespace in place, we're now referencing an ID from the <code>android.R</code>
resources class, rather than the local resources class.</p>

<p>In order to create views and reference them from the application, a common pattern is to:</p>
<ol>
  <li>Define a view/widget in the layout file and assign it a unique ID. E.g.:
<pre>
&lt;Button id="&#64;+id/my_button"
  android:layout_width="wrap_content"
  android:layout_height="wrap_content"
  android:text="&#64;string/my_button_text"/>
</pre>
  </li>
  <li>Then create an instance of the view object and capture it from the layout 
(typically in the <code>onCreate()</code> method).
<pre>
Button myButton = (Button) findViewById(R.id.my_button);
</pre>
  </li>
</ol>
<p>Defining IDs for view objects is important when creating a {@link android.widget.RelativeLayout}.
In a relative layout, sibling views can define their layout relative to another sibling view, 
which is referenced by the unique ID.</p>
<p>An ID need not be unique throughout the entire tree, but it should be
unique within the part of the tree you are searching (which may often be the entire tree, so it's best 
to be completely unique when possible).</p>


<h3>Layout Parameters</h3>

<p>Every ViewGroup class implements a nested class that extends {@link
android.view.ViewGroup.LayoutParams}. This subclass
contains property types that define each child view's size and position, as
appropriate for that type of view group. As you can see in the figure below, the parent
view group defines layout parameters for each child view (including the child view group).</p>

<img src="{@docRoot}images/layoutparams.png" alt="" height="300" 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, 
though it may also define different LayoutParams for its own children. </p>

<p>All view groups include a width and height, and each view is required to define them. 
Many LayoutParams also include optional margins and
borders. You can specify width and height with exact measurements, though you probably won't want
to do this often. More often, you will tell your view to size itself either to
the dimensions required by its content, or to become as big as its parent view group
will allow (with the <var>wrap_content</var> and <var>fill_parent</var> values, respectively).
The accepted measurement types are defined in the 
<a href="{@docRoot}guide/topics/resources/available-resources.html#dimension">Available Resources</a> document.</p>

<h2 id="Widgets">Widgets</h2>


<p>The View class also serves as a base class for <em>widgets</em> &mdash; a set of fully implemented 
View subclasses that draw interactive screen elements, so you can quickly build your UI. 
Android provides a vast collection of widgets for special actions.
Some of them are basic interaction elements like buttons and text fields, while others are more complex, 
like a date picker or zoom controls.</p>
<p>For a list of all built-in widgets, see the {@link android.widget widget}.</p>

<p>You're not limited to the kinds of views, layouts and widgets provided by the Android platform. If you'd
like to do something more customized, create your own widget or layout, you can.
Read more in <a href="custom-components.html">Building Custom Components</a>.


<h2 id="Events">Events</h2>

<p>Once you've designed and built your UI layout, you need to handle the user interaction with it.
Obviously, the views that you've implemented in the layout are the 
receptors for such interaction events. Because the View class is built to listen for most interaction events,
receiving and handling them is pretty straigh-forward. When you want to perform an action upon an event, 
you need to do one of two things:</p>
<ul>
  <li>Override an existing callback method for the view you've implemented, which will be called when something
like a touch or focus event occurs.</li>
  <li>Define a listener interface, like {@link android.view.View.OnClickListener} (for handling "clicks" on a View). 
You must then define the listener for your view with the respective <code>set...Listener()</code>
method (such as {@link android.view.View#setOnClickListener(android.view.View.OnClickListener) setOnCLickListener()}).</li>
</ul>

<p>To learn more about handling events and writing your own listeners, 
read <a href="ui-events.html">Handling UI Events</a>.</p>


<h2 id="Adapters">Adapters</h2>

<p>Sometimes you'll want to populate a view group with some information that can't be hard-coded, instead, 
you want to bind your view to an external source of data. To do this, you use an AdapterView as
your view group and each child View is initialized and populated with data from the Adapter.</p>
<p>The AdapterView object is an implementation of ViewGroup that determines its child views
based on a given Adapter object. The Adapter acts like a courier between your data source (perhaps an
array of external strings) and the AdapterView, which displays it. There are several implementations
of the Adapter class, for specific tasks, such as the CursorAdapter for reading database data from a Cursor,
or an ArrayAdapter for reading from an arbitrary array.</p>
<p>To learn more about using an Adapter to populate your views, read 
<a href="binding.html">Binding to Data with AdapterView</a>.</p>


<h2 id="StylesAndThemes">Styles and Themes</h2>

<p>Perhaps you're not satisfied with the look of the standard widgets. To revise them, you can create some 
of your own styles and themes.</p>

<ul>
  <li>A style is a set of one or more formatting attributes that you can apply as a unit to individual elements 
in your layout. For example, you could define a style that specifies a certain text size and color, then 
apply it to only specific View elements.</li>
  <li>A theme is a set of one or more formatting attributes that you can apply as a unit to all activities in 
an application, or just a single activity. For example, you could define a theme that sets specific colors for 
the window frame and the panel background, and sets text sizes and colors for menus. This theme can then be 
applied to specific activities or the entire application.</li>
</ul>

<p>Styles and themes are resources. Android provides some default style and theme resources that you can use, 
or you can declare your own custom style and theme resources. Learn more about using styles and themes in the
<a href="themes.html">Applying Styles and Themes</a> document.</p>