page.title=Hello, TabWidget
parent.title=Hello, Views
parent.link=index.html
@jd:body

<p>A {@link android.widget.TabWidget} offers the ability to easily draw an interface that uses
tabs to navigate between different views.</p>

<ol>
  <li>Start a new project/Activity called HelloTabWidget.</li>
  <li>Open the layout file and make it like so:</li>
  <pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;TabHost xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@android:id/tabhost"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent">
    &lt;LinearLayout
        android:orientation="vertical"
        android:layout_width="fill_parent"
        android:layout_height="fill_parent">
        &lt;TabWidget
            android:id="@android:id/tabs"
            android:layout_width="fill_parent"
            android:layout_height="wrap_content" />
        &lt;FrameLayout
            android:id="@android:id/tabcontent"
            android:layout_width="fill_parent"
            android:layout_height="fill_parent">
            &lt;TextView 
                android:id="@+id/textview1"
                android:layout_width="fill_parent"
                android:layout_height="fill_parent" 
                android:text="this is a tab" />
            &lt;TextView 
                android:id="@+id/textview2"
                android:layout_width="fill_parent"
                android:layout_height="fill_parent" 
                android:text="this is another tab" />
            &lt;TextView 
                android:id="@+id/textview3"
                android:layout_width="fill_parent"
                android:layout_height="fill_parent" 
                android:text="this is a third tab" />
    	&lt;/FrameLayout>
    &lt;/LinearLayout>
&lt;/TabHost>
</pre>
    <p>Here, we've created a {@link android.widget.TabHost} that contains the entire layout of the Activity.
    A TabHost requires two descendant elements: a {@link android.widget.TabWidget} and a {@link android.widget.FrameLayout}.
    In order to properly layout these elements, we've put them inside a vertical {@link android.widget.LinearLayout}.
    The FrameLayout is where we keep the content that will change with each tab. Each child in the FrameLayout will
    be associated with a different tab.
    In this case, each tab simply shows a different {@link android.widget.TextView} with some text. </p>
    <p>Notice that the TabWidget and the FrameLayout elements have specific <code>android</code> namespace IDs. These are necessary
    so that the TabHost can automatically retireve references to them, populate the TabWidget with the tabs that we'll define
    in our code, and swap the views in the FrameLayout. We've also defined our own IDs for each TextView, which we'll use to 
    associate each tab with the view that it should reveal.</p>
    <p>Of course, you can 
    make these child views as large as complex as you'd like &mdash; instead of the TextView elements, 
    you could start with other layout views and build a unique layout hierarchy for each tab.</p>
  </li>
  <li>Now we'll add our code. Open HelloTabWidget.java and make it a <code>TabActivity</code>.
    <p>By default, Eclipse creates a class that extends <code>Activity</code>. Change it to 
    extend <code>TabActivity</code>:</p>
    <pre>
public class HelloTabWidget extends TabActivity {
</pre>  
  </li>
  <li>Now fill in the the <code>onCreate</code> method like this:
  <pre>
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    mTabHost = getTabHost();
    
    mTabHost.addTab(mTabHost.newTabSpec("tab_test1").setIndicator("TAB 1").setContent(R.id.textview1));
    mTabHost.addTab(mTabHost.newTabSpec("tab_test2").setIndicator("TAB 2").setContent(R.id.textview2));
    mTabHost.addTab(mTabHost.newTabSpec("tab_test3").setIndicator("TAB 3").setContent(R.id.textview3));
    
    mTabHost.setCurrentTab(0);
}
</pre>
    <p>As usual, we start by setting our layout.</p>
    <p>We then call the TabActivity method <code>getTabHost()</code>,
    which returns us a reference to the TabHost we created in our layout. Upon our TabHost, we call <code>addTab()</code>
    for each of the tabs that we want to add to the TabWidget. Each time we call this, we pass a 
    {@link android.widget.TabHost.TabSpec} that we build on the fly, and with it, chain together two necessary methods:
    <code>setIndicator()</code> to set the text for the tab button, and <code>setContent()</code> to define
    which View we want to associate with the tab and reveal when pressed. Our indicator is just a text string and 
    our content is an ID reference to the TextView elements we inserted in the FrameLayout.</p>
    <p>At the end, we call <code>setCurrentTab()</code> to define which tab should be opened by default. The tabs
    are saved like a zero-based array, so to open the first tab, we pass zero (<var>0</var>).</p>
  </li>
  <li>To clean-up the presentation a bit more, let's remove the window title that appears at the top of the layout.
  Android includes a theme that removes that title for us. To add it, open the Android Manifest file and add
  the <var>NoTitleBar</var> theme to the <code>&lt;application></code> tag. It should end up like this:
    <pre>
&lt;application android:icon="&#64;drawable/icon" android:theme="&#64;android:style/Theme.NoTitleBar">
</pre>
  </li>
  <li>That's it. Run your application.</li>

</ol>


<p>Your application should look like this:</p>
<img src="images/hello-tabwidget.png" width="150px" />

<div class="special"><p>You can include icons in your tabs by passing a 
{@link android.graphics.drawable.Drawable} when you call <code>setIndicator()</code>. Here's an example
that uses a Drawable created from an image in the project resources:</p>
<pre>setIndicator("TAB 1", getResources().getDrawable(R.drawable.tab_icon))</pre>
</div>

<h3>References</h3>
<ul>
<li>{@link android.widget.TabWidget}</li>
<li>{@link android.widget.TabHost}</li>
<li>{@link android.widget.TabHost.TabSpec}</li>
<li>{@link android.widget.FrameLayout}</li>
</ul>

