diff options
Diffstat (limited to 'docs/html/guide/topics/ui/layout-objects.jd')
| -rw-r--r-- | docs/html/guide/topics/ui/layout-objects.jd | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/docs/html/guide/topics/ui/layout-objects.jd b/docs/html/guide/topics/ui/layout-objects.jd new file mode 100644 index 0000000..cf85fd6 --- /dev/null +++ b/docs/html/guide/topics/ui/layout-objects.jd @@ -0,0 +1,305 @@ +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="#absolutelayout">AbsoluteLayout</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}guide/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 — 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 — 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"> +<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> + +<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 — topmost or +leftmost — 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="false"</code> in the layout XML. </p> + +<p>To view other sample code, see the +<a href="{@docRoot}guide/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> +<?xml version="1.0" encoding="utf-8"?> +<TableLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:stretchColumns="1"> + <TableRow> + <TextView + android:text="@string/table_layout_4_open" + android:padding="3dip" /> + <TextView + android:text="@string/table_layout_4_open_shortcut" + android:gravity="right" + android:padding="3dip" /> + </TableRow> + + <TableRow> + <TextView + android:text="@string/table_layout_4_save" + android:padding="3dip" /> + <TextView + android:text="@string/table_layout_4_save_shortcut" + android:gravity="right" + android:padding="3dip" /> + </TableRow> +</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}guide/tutorials/views/hello-tablelayout.html">Hello +TableLayout</a> tutorial.</p> + + +<h2 id="absolutelayout">AbsoluteLayout</h2> +<p>{@link android.widget.AbsoluteLayout} enables child views to specify + their own exact x/y coordinates on the screen. Coordinates <em>(0,0)</em> is the upper left + corner, and values increase as you move down and to the right. Margins are not + supported, and overlapping elements are allowed (although not recommended). We + generally recommend against using AbsoluteLayout unless you have good reasons + to use it, because it is fairly rigid and does not adjust to different types of + displays. </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> +<?xml version="1.0" encoding="utf-8"?> +<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 android:id="@+id/label" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:text="Type here:" /> + + <EditText android: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 android: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="" 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 — 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}guide/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.AbsoluteLayout AbsoluteLayout}<br /></td> + <td>Enables you to specify the location of child objects relative to the + parent in exact measurements (for example, pixels). </td> + </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> |