M7350/base/docs/html/guide/topics/ui/layout-objects.jd

page.title=Common Layout Objects
parent.title=User Interface
parent.link=index.html
@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>In this document</h2>
  <ol>
    <li><a href="#framelayout">FrameLayout</a></li>
    <li><a href="#linearlayout">LinearLayout</a></li>
    <li><a href="#tablelayout">TableLayout</a></li>
    <li><a href="#relativelayout">RelativeLayout</a></li>
    <li><a href="#viewgroupsummary">Summary of Important View Groups</a></li>
  </ol>
</div>
</div>

<p>This section describes some of the more common types of layout objects
to use in your applications. Like all layouts, they are subclasses of {@link android.view.ViewGroup ViewGroup}.</p>

<p>Also see the <a href="{@docRoot}resources/tutorials/views/index.html">Hello Views</a> tutorials for
some guidance on using more Android View layouts.</p>

<h2 id="framelayout">FrameLayout</h2>
<p>{@link android.widget.FrameLayout FrameLayout} is the simplest type of layout
object. It's basically a blank space on your screen that you can
later fill with a single object &mdash; for example, a picture that you'll swap in and out.
All child elements of the FrameLayout are pinned to the top left corner of the screen; you cannot
specify a different location for a child view. Subsequent child views will simply be drawn over previous ones,
partially or totally obscuring them (unless the newer object is transparent).
</p>


<h2 id="linearlayout">LinearLayout</h2>
<p>{@link android.widget.LinearLayout LinearLayout} aligns all children in a
single direction &mdash; vertically or horizontally, depending on how you 
define the <code>orientation</code> attribute. All children are
stacked one after the other, so a vertical list will only have one child per
row, no matter how wide they are, and a horizontal list will only be one row
high (the height of the tallest child, plus padding). A {@link
android.widget.LinearLayout LinearLayout} respects <em>margin</em>s between children
and the <em>gravity</em> (right, center, or left alignment) of each child. </p>

<p>{@link android.widget.LinearLayout LinearLayout} also supports assigning a
<em>weight</em> to individual children. This attribute assigns an "importance" value to a view,
and allows it to expand to fill any remaining space in the parent view. 
Child views can specify an integer weight value, and then any remaining space in the view group is
assigned to children in the proportion of their declared weight. Default
weight is zero. For example, if there are three text boxes and two of
them declare a weight of 1, while the other is given no weight (0), the third text box without weight
will not grow and will only occupy the area required by its content.
The other two will expand equally to fill the space remaining after all three boxes are measured. 
If the third box is then given a weight of 2 (instead of 0), then it is now declared 
"more important" than both the others, so it gets half the total remaining space, while the first two
share the rest equally.</p>

<div class="sidebox-wrapper">
<div class="sidebox">
<p><strong>Tip</strong>: To create a proportionate size
layout on the screen, create a container view group object with the 
<code>layout_width</code> and <code>layout_height</code> attributes set to <var>fill_parent</var>; assign
the children <code>height</code> or <code>width</code> to <code>0</code> (zero); then assign relative 
<code>weight</code> values
to each child, depending on what proportion of the screen each should
have.</p>
</div>
</div>

<p>The following two forms represent a {@link android.widget.LinearLayout LinearLayout} with a set of elements: a
button, some labels and text boxes. The text boxes have their width set to <var>fill_parent</var>; other
elements are set to <var>wrap_content</var>. The gravity, by default, is left. 
The difference between the two versions of the form is that the form
on the left has weight values unset (0 by default), while the form on the right has
the comments text box weight set to 1. If the Name textbox had also been set
to 1, the Name and Comments text boxes would be the same height. </p>

<img src="{@docRoot}images/linearlayout.png" alt="" />

<p>Within a horizontal {@link android.widget.LinearLayout LinearLayout}, items are aligned by the position of
their text base line (the first line of the first list element &mdash; topmost or
leftmost &mdash; is considered the reference line). This is so that people scanning
elements in a form shouldn't have to jump up and down to read element text in
neighboring elements. This can be turned off by setting
<code>android:baselineAligned=&quot;false&quot;</code> in the layout XML. </p>

<p>To view other sample code, see the 
<a href="{@docRoot}resources/tutorials/views/hello-linearlayout.html">Hello LinearLayout</a> tutorial.</p>


<h2 id="tablelayout">TableLayout</h2>
<p>{@link android.widget.TableLayout} positions its children into rows
    and columns. TableLayout containers do not display border lines for their rows, columns,
    or cells. The table will have as many columns as the row with the most cells. A table can leave
cells empty, but cells cannot span columns, as they can in HTML.</p>
<p>{@link android.widget.TableRow} objects are the child views of a TableLayout
(each TableRow defines a single row in the table).
Each row has zero or more cells, each of which is defined by any kind of other View. So, the cells of a row may be
composed of a variety of View objects, like ImageView or TextView objects.
A cell may also be a ViewGroup object (for example, you can nest another TableLayout as a cell).</p>
<p>The following sample layout has two rows and two cells in each. The accompanying screenshot shows the 
result, with cell borders displayed as dotted lines (added for visual effect). </p>

<table class="columns">
    <tr>
        <td>
        <pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;TableLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:stretchColumns="1">
    &lt;TableRow>
        &lt;TextView
            android:text="@string/table_layout_4_open"
            android:padding="3dip" />
        &lt;TextView
            android:text="@string/table_layout_4_open_shortcut"
            android:gravity="right"
            android:padding="3dip" />
    &lt;/TableRow>

    &lt;TableRow>
        &lt;TextView
            android:text="@string/table_layout_4_save"
            android:padding="3dip" />
        &lt;TextView
            android:text="@string/table_layout_4_save_shortcut"
            android:gravity="right"
            android:padding="3dip" />
    &lt;/TableRow>
&lt;/TableLayout>
</pre></td>
        <td><img src="{@docRoot}images/table_layout.png" alt="" style="margin:0" /></td>
    </tr>
</table>

<p>Columns can be hidden, marked to stretch and fill the available screen space,
    or can be marked as shrinkable to force the column to shrink until the table
    fits the screen. See the {@link android.widget.TableLayout TableLayout reference} 
documentation for more details. </p>

<p>To view sample code, see the <a href="{@docRoot}resources/tutorials/views/hello-tablelayout.html">Hello
TableLayout</a> tutorial.</p>


<h2 id="relativelayout">RelativeLayout</h2>
<p>{@link android.widget.RelativeLayout} lets child views specify their
    position relative to the parent view or to each other (specified by ID). So you can
    align two elements by right border, or make one below another, centered in
    the screen, centered left, and so on. Elements are rendered in the order given, so if the first element
    is centered in the screen, other elements aligning themselves to that element
    will be aligned relative to screen center. Also, because of this ordering, if using XML to specify this layout, 
    the element that you will reference (in order to position other view objects) must be listed in the XML 
file before you refer to it from the other views via its reference ID. </p>
<p>The example below shows an XML file and the resulting screen in the UI. 
Note that the attributes that refer to relative elements (e.g., <var>layout_toLeft</var>)
refer to the ID using the syntax of a relative resource
(<var>@id/<em>id</em></var>). </p>

<table class="columns">
    <tr>
        <td>
        <pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&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 android: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 android: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 android: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="" style="margin:0"  /></td>
    </tr>
</table>


<p>Some of these properties are supported directly by
    the element, and some are supported by its LayoutParams member (subclass RelativeLayout
    for all the elements in this screen, because all elements are children of a RelativeLayout
    parent object). The defined RelativeLayout parameters are: <code>width</code>, <code>height</code>, 
    <code>below</code>, <code>alignTop</code>, <code>toLeft</code>, <code>padding[Bottom|Left|Right|Top]</code>, 
    and <code>margin[Bottom|Left|Right|Top]</code>. Note that some of these parameters specifically support
    relative layout positions &mdash; their values must be the ID of the element to which you'd like this view laid relative.
    For example, assigning the parameter <code>toLeft="my_button"</code> to a TextView would place the TextView to 
    the left of the View with the ID <var>my_button</var> (which must be written in the XML <em>before</em> the TextView). </p>

<p>To view this sample code, see the <a href="{@docRoot}resources/tutorials/views/hello-relativelayout.html">Hello
RelativeLayout</a> tutorial.</p>


<h2 id="viewgroupsummary">Summary of Important View Groups</h2>
<p>These objects all hold child UI elements. Some provide their own form of a visible UI, while others
    are invisible structures that only manage the layout of their child views.  </p>
<table width="100%" border="1">
    <tr>
        <th scope="col">Class</th>
        <th scope="col">Description</th>
    </tr>
    <tr>
        <td>{@link android.widget.FrameLayout FrameLayout}</td>
        <td>Layout that acts as a view frame to display
            a single object. </td>
    </tr>
    <tr>
        <td>{@link android.widget.Gallery Gallery} </td>
        <td>A horizontal scrolling display of images, from a bound list. </td>
    </tr>
    <tr>
        <td>{@link android.widget.GridView GridView} </td>
        <td>Displays a scrolling grid of m columns and n rows.</td>
    </tr>
    <tr>
        <td>{@link android.widget.LinearLayout LinearLayout} </td>
        <td>A layout that organizes its children into a single horizontal or vertical
            row. It creates a scrollbar if the length of the window exceeds the length
            of the screen. </td>
    </tr>
    <tr>
        <td>{@link android.widget.ListView ListView} </td>
        <td>Displays a scrolling single column list. </td>
    </tr>
    <tr>
        <td>{@link android.widget.RelativeLayout RelativeLayout} </td>
        <td>Enables you to specify the location of child objects relative to each
            other (child A to the left of child B) or to the parent (aligned to the
            top of the parent). </td>
    </tr>
    <tr>
        <td>{@link android.widget.ScrollView ScrollView} </td>
        <td>A vertically scrolling column of elements. </td>
    </tr>
    <tr>
        <td>{@link android.widget.Spinner Spinner} </td>
        <td>Displays a single item at a time from a bound list, inside a one-row
            textbox. Rather like a one-row listbox that can scroll either horizontally
            or vertically. </td>
    </tr>
    <tr>
        <td>{@link android.view.SurfaceView SurfaceView} </td>
        <td>Provides direct access to a dedicated drawing surface. It can hold child
            views layered on top of the surface, but is intended for applications
            that need to draw pixels, rather than using widgets. </td>
    </tr>
    <tr>
        <td>{@link android.widget.TabHost TabHost} </td>
        <td>Provides a tab selection list that monitors clicks and enables the application
            to change the screen whenever a tab is clicked. </td>
    </tr>
	<tr>
        <td>{@link android.widget.TableLayout TableLayout} </td>
        <td>A tabular layout with an arbitrary number of rows and columns, each cell
            holding the widget of your choice. The rows resize to fit the largest
            column. The cell borders are not
            visible. </td>
    </tr>
    <tr>
        <td>{@link android.widget.ViewFlipper ViewFlipper} </td>
        <td>A list that displays one item at a time, inside a one-row textbox. It
            can be set to swap items at timed intervals, like a slide show. </td>
    </tr>
    <tr>
        <td>{@link android.widget.ViewSwitcher ViewSwitcher} </td>
        <td>Same as ViewFlipper. </td>
    </tr>
</table>