docs: add dev guide for action bar and update other relevant documents

          <li><a href="<?cs var:toroot ?>guide/topics/ui/menus.html">

               <span class="en">Creating Menus</span>

              </a></li>

          <li><a href="<?cs var:toroot ?>guide/topics/ui/actionbar.html">

               <span class="en">Using the Action Bar</span>

              </a> <span class="new">new!</span></li>

          <li><a href="<?cs var:toroot ?>guide/topics/ui/dialogs.html">

                <span class="en">Creating Dialogs</span>

              </a></li>

page.title=Using the Action Bar

parent.title=User Interface

parent.link=index.html

@jd:body

<div id="qv-wrapper">

<div id="qv">

  <h2>Quickview</h2>

  <ul>

    <li>A replacement for the title bar for displaying global actions for the activity</li>

    <li>Provides toolbar actions and modes of navigating around the application</li>

    <li>Switches to contextual menu options when one or more items are selected</li>

    <li>Requires API Level HONEYCOMB</li>

  </ul>

  <h2>In this document</h2>

  <ol>

    <li><a href="#Adding">Adding the Action Bar</a></li>

    <li><a href="#ActionItems">Adding Action Items</a>

      <ol>

        <li><a href="#Home">Using the application icon as an action item</a></li>

      </ol>

    </li>

    <li><a href="#Tabs">Adding Tabs</a></li>

    <li><a href="#Dropdown">Adding Drop-down Navigation</a></li>

    <li><a href="#Search">Adding Search</a></li>

  </ol>

  <h2>Key classes</h2>

  <ol>

    <li>{@link android.app.ActionBar}</li>

    <li>{@link android.view.Menu}</li>

  </ol>

  <h2>See also</h2>

  <ol>

    <li><a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a></li>

  </ol>

</div>

</div>

<p>The action bar is a widget for activities that replaces the traditional title bar at

the top of an activity. By default, the action bar includes the application logo on the left side,

followed by the activity title. The action bar offers several useful features for

applications—especially those targeted to tablet devices. The action bar features include

the ability to:</p>

<ul>

  <li>Display menu items from the <a

href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> as "action

items"&mdash;providing instant access to key user actions.</li>

  <li>Provide tabs for navigating between <a

href="{@docRoot}guide/topics/fragments/index.html">fragments</a>.</li>

  <li>Provide drop-down navigation items.</li>

  <li>Embed a {@link android.widget.SearchView} for instant searching.</li>

  <li>Use the application logo as a "return home" or "up" navigation action.</li>

</ul>

<img src="{@docRoot}images/ui/actionbar.png" height="36" alt="" />

<p class="img-caption"><strong>Figure 1.</strong> A screenshot of the action bar in the NotePad

sample application, containing action items to save and delete the note.</p>

<h2 id="Adding">Adding the Action Bar</h2>

<p>To add the Action Bar to your activity, apply the holographic theme&mdash;{@code

Theme.Holo}—or the action bar theme—{@code Theme.WithActionBar}—in your manifest

file. For example:</p>

<pre>

<activity android:theme="@android:style/Theme.Holo" >

</pre>

<p>The activity now appears with the action bar in place of the traditional title bar.</p>

<h2 id="ActionItems">Adding Action Items</h2>

<p>For each action item you want to add to the action bar, you must add a menu item to the

activity's <a href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> and declare

that the item be shown as an action, using the {@code android:showAsAction} attribute in the menu

XML or with {@link android.view.MenuItem#setShowAsAction setShowAsAction()} on the {@link

android.view.MenuItem}.</p>

<div class="figure" style="width:359px">

  <img src="{@docRoot}images/ui/actionbar-item-withtext.png" height="57" alt="" />

  <p class="img-caption"><strong>Figure 2.</strong> A screenshot from an action bar with two

action items.</p>

</div>

<p>You can specify a menu item to appear as an action item in the action bar&mdash;if there is room

for it&mdash;from the <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu

resource</a> by declaring {@code

android:showAsAction="ifRoom"} for the {@code <item>} element. This way, the item will display

in the action bar for quick access only if there is room available for it—if there's not

enough room, the item is placed the options menu (revealed by the drop-down icon on the right side

of the action bar). From your application code, you can specify the item to appear as an action item

by calling {@link android.view.MenuItem#setShowAsAction setShowAsAction()} on the {@link

android.view.MenuItem} and passing {@link android.view.MenuItem#SHOW_AS_ACTION_IF_ROOM}.</p>

<p>If your item supplies both a title and an icon, then the action item shows only

the icon by defult. If you want to include the text with the action item, add the <em>with text</em>

flag—in XML, add {@code withText} to the {@code android:showAsAction} attribute or, in

your application code, use the {@link android.view.MenuItem#SHOW_AS_ACTION_WITH_TEXT} flag when

calling {@link android.view.MenuItem#setShowAsAction setShowAsAction()}. Figure 2 shows a screenshot

of an action bar with two action items that include text.</p>

<p>Here's an example of how you can declare a menu item as an action item in a <a

href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> file:</p>

<pre>

<?xml version="1.0" encoding="utf-8"?>

<menu xmlns:android="http://schemas.android.com/apk/res/android">

    <item android:id="@+id/menu_add"

          android:icon="@drawable/ic_menu_save"

          android:title="@string/menu_save"

          <b>android:showAsAction="ifRoom|withText"</b> /&gt;

</menu>

</pre>

<p>In this case, both the {@code ifRoom} and {@code withText} flags are set, so that when this

item appears as an action item, it includes the title text along with the icon.</p>

<p>A menu item placed in the action bar triggers the same callback methods as other items in the

options menu. When the user selects an item in the action bar, your activity receives a call to

{@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}, passing the

item ID. (If you added the item from a fragment, then the respective {@link

android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method is called

for that fragment.)</p>

<p class="note"><strong>Note:</strong> Even menu items that are contained in the options menu

(and not shown as action items) will show an icon, so when using the action bar, you should

provide an icon for every item in the options menu.</p>

<p>You can also declare an item to <em>always</em> appear as an action item,  but you should avoid

doing so. Most of the time, there will be enough room for several action items and they will appear

in the order you declare them. If you set items to always appear as action

items  (instead of <em>if room</em>), then they are added without discrimination and there is a risk

that they will collide with other elements in the action bar, such as tabs or custom views.</p>

<p>For more information about menus, see the <a

href="{@docRoot}guide/topics/ui/menus.html#options-menu">Creating Menus</a> developer guide.</p>

<h3 id="Home">Using the application icon as an action item</h3>

<p>By default, the application icon appears in the action bar on the left side, but does nothing

when tapped. To use the application icon as an action item when tapped, you simply need to add a

condition to your {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method

that performs an action when the {@link android.view.MenuItem} ID is {@code android.R.id.home}.

This ID is delivered every time the user taps the application icon.</p>

<p>For example, here's an implementation of {@link android.app.Activity#onOptionsItemSelected

onOptionsItemSelected()} that returns to the application's "home" activity:</p>

<pre>

@Override

public boolean onOptionsItemSelected(MenuItem item) {

    switch (item.getItemId()) {

        case android.R.id.home:

            // app icon in action bar clicked; go home

            Intent intent = new Intent(this, HomeActivity.class);

            startActivity(intent);

            break;

    }

    return super.onOptionsItemSelected(item);

}

</pre>

<div class="figure" style="width:144px">

  <img src="{@docRoot}images/ui/actionbar-logo.png" height="140" alt="" />

  <p class="img-caption"><strong>Figure 3.</strong> The standard icon for the Email application

(top) and the "up navigation" icon (bottom).</p>

</div>

<p>You can also use the application icon to provide "up" navigation. The way you handle the event

when a user taps the icon is the same, but if the user experience for the event is to <em>navigate

up to the parent activity</em>, then you should indicate this behavior by setting the

action bar to "show home as up." You can do so by calling {@link

android.app.ActionBar#setDisplayOptions setDisplayOptions()} on your activity's {@link

android.app.ActionBar}, and passing the {@link

android.app.ActionBar#DISPLAY_HOME_AS_UP} display option.</p>

<p>To get the {@link android.app.ActionBar}, call {@link android.app.Activity#getActionBar} from

your {@link android.app.Activity} during {@link android.app.Activity#onCreate onCreate()} (but be

sure you do so <em>after</em> you've called {@link android.app.Activity#setContentView

setContentView()}).</p>

<p>For example, here's how you can change the action bar display mode to show the application

icon as an "up" action:</p>

<pre>

@Override

protected void onStart() {

  super.onStart();

  ActionBar actionBar = this.getActionBar();

  actionBar.setDisplayOptions(ActionBar.DISPLAY_HOME_AS_UP, ActionBar.DISPLAY_HOME_AS_UP);

}

</pre>

<p class="caution"><strong>Caution:</strong> If your activity does not have an action bar (if you

did not set the theme of your activity or application to the holographic or action bar theme), then

{@link android.app.Activity#getActionBar} returns null.</p>

<h2 id="Tabs">Adding Tabs</h2>

<p>The action bar can display tabs that allow the user navigate between different fragments in the

activity. Each tab can include a title and/or an icon.</p>

<p>To begin, your layout must include a {@link android.view.View} in which each {@link

android.app.Fragment} associated with a tab is displayed. Be sure the view has an ID that you

can use to reference it from your code.</p>

<p>To add tabs to the action bar:</p>

<ol>

  <li>Create an implementation of {@link android.app.ActionBar.TabListener} to handle the

interaction events on the action bar tabs. You must implement all methods: {@link

android.app.ActionBar.TabListener#onTabSelected onTabSelected()}, {@link

android.app.ActionBar.TabListener#onTabUnselected onTabUnselected()}, and {@link

android.app.ActionBar.TabListener#onTabReselected onTabReselected()}.

    <p>Each callback method passes the {@link android.app.ActionBar.Tab} that received the

event and a {@link android.app.FragmentTransaction} for you to perform the fragment

transactions (add or remove fragments).</p>

    <p>For example:</p>

<pre>

private class MyTabListener implements ActionBar.TabListener {

    private TabContentFragment mFragment;

    // Called to create an instance of the listener when adding a new tab

    public TabListener(TabContentFragment fragment) {

        mFragment = fragment;

    }

    @Override

    public void onTabSelected(Tab tab, FragmentTransaction ft) {

        ft.add(R.id.fragment_content, mFragment, null);

    }

    @Override

    public void onTabUnselected(Tab tab, FragmentTransaction ft) {

        ft.remove(mFragment);

    }

    @Override

    public void onTabReselected(Tab tab, FragmentTransaction ft) {

        // do nothing

    }

}

</pre>

  <p>This implementation of {@link android.app.ActionBar.TabListener} adds a constructor

that saves the {@link android.app.Fragment} associated with a tab so that each callback

can add or remove that fragment.</p>

  </li>

  <li>Get the {@link android.app.ActionBar} for your activity by calling {@link

android.app.Activity#getActionBar} from your {@link android.app.Activity}, during {@link

android.app.Activity#onCreate onCreate()} (but be sure you do so <em>after</em> you've called

{@link android.app.Activity#setContentView setContentView()}).</li>

  <li>Call {@link android.app.ActionBar#setNavigationMode(int)

setNavigationMode(NAVIGATION_MODE_TABS)} to enable tab mode for the {@link

android.app.ActionBar}.</li>

  <li>Create each tab for the action bar:

    <ol>

      <li>Create a new {@link android.app.ActionBar.Tab} by calling {@link

android.app.ActionBar#newTab()} on the {@link android.app.ActionBar}.</li>

      <li>Add title text and/or an icon for the tab by calling {@link

android.app.ActionBar.Tab#setText setText()} and/or {@link android.app.ActionBar.Tab#setIcon

setIcon()}.

        <p class="note"><strong>Tip:</strong> These methods return the same {@link

android.app.ActionBar.Tab} instance, so you can chain the calls together.</p></li>

      <li>Declare the {@link android.app.ActionBar.TabListener} to use for the tab by passing an

instance of your implementation to {@link android.app.ActionBar.Tab#setTabListener

setTabListener()}.

    </ol>

  </li>

  <li>Add each {@link android.app.ActionBar.Tab} to the action bar by calling {@link

android.app.ActionBar#addTab addTab()} on the {@link android.app.ActionBar} and passing the

{@link android.app.ActionBar.Tab}.</li>

</ol>

<p>For example, the following code combines steps 2 - 5 to create two tabs and add them to

the action bar:</p>

<pre>

@Override

protected void onCreate(Bundle savedInstanceState) {

    super.onCreate(savedInstanceState);

    setContentView(R.layout.main);

    // setup action bar for tabs

    final ActionBar actionBar = getActionBar();

    actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS);

    // remove the activity title to make space for tabs

    actionBar.setDisplayOptions(0, ActionBar.DISPLAY_SHOW_TITLE);

    // instantiate fragment for the tab

    Fragment artistsFragment = new ArtistsFragment();

    // add a new tab and set its title text and tab listener

    bar.addTab(bar.newTab().setText(R.string.tab_artists)

            .setTabListener(new TabListener(artistsFragment)));

    Fragment albumsFragment = new AlbumsFragment();

    bar.addTab(bar.newTab().setText(R.string.tab_albums)

            .setTabListener(new TabListener(albumsFragment)));

}

</pre>

<p>All the behaviors that occur when a tab is selected must be defined by your {@link

android.app.ActionBar.TabListener} callback methods. When a tab is selected, it receives a call to

{@link android.app.ActionBar.TabListener#onTabSelected onTabSelected()} and that's where you should

add the appropriate fragment to the designated view in your layout, using {@link

android.app.FragmentTransaction#add add()} with the provided {@link

android.app.FragmentTransaction}. Likewise, when a tab is deselected (because another tab becomes

selected), you should remove that fragment from the layout, using {@link

android.app.FragmentTransaction#remove remove()}.</p>

<p class="note"><strong>Note:</strong> You <strong>do not</strong> need

to call {@link android.app.FragmentTransaction#commit} for these transactions. You also

<strong>cannot</strong> add these fragment transactions to the back stack.</p>

<p>If your activity is stopped, you should retain the currently selected tab with the saved state so

that when the user returns to your application, you can open the tab. When it's time to save the

state, you can query the currently selected tab with {@link

android.app.ActionBar#getSelectedNavigationItem()}. This returns the index position of the selected

tab.</p>

<p class="caution"><strong>Caution:</strong> It's important that you save

the state of each fragment as necessary, so when the user switches fragments with the tabs,

then returns to a previous fragment, it appears the way they left. For information about saving

the state of your fragment, see the <a

href="{@docRoot}guide/topics/fragments/index.html">Fragments</a> developer guide.</p>

<p>Every ViewGroup class implements a nested class that extends {@link

android.view.ViewGroup.LayoutParams}. This subclass

contains property types that define the size and position for each child view, as

appropriate for the view group. As you can see in the figure below, the parent

appropriate for the view group. As you can see in figure 1, 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 class="img-caption"><strong>Figure 1.</strong> Visualization of a view hierarchy with layout

parameters associated with each view.</p>

<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, 

    <h2>Key classes</h2>

    <ol>

      <li>{@link android.app.Dialog}</li>

      <li>{@link android.app.AlertDialog}</li>

      <li>{@link android.app.DialogFragment}</li>

    </ol>

    <h2>Related tutorials</h2>

    <ol>

      <li><a href="{@docRoot}resources/tutorials/views/hello-datepicker.html">Hello

DatePicker</a></li>

      <li><a href="{@docRoot}resources/tutorials/views/hello-timepicker.html">Hello

TimePicker</a></li>

    </ol>

  </div>

</div>

<p>A dialog is usually a small window that appears in front of the current Activity.

The underlying Activity loses focus and the dialog accepts all user interaction. 

Dialogs are normally used

for notifications and short activities that directly relate to the application in progress.</p>

The underlying Activity loses focus and the dialog accepts all user interaction. Dialogs are

normally used for notifications that should interupt the user and to perform short tasks that

directly relate to the application in progress (such as a progress bar or a login prompt).</p>

<p>The Android API supports the following types of {@link android.app.Dialog} objects:</p>

<p>The {@link android.app.Dialog} class is the base class for creating dialogs. However, you

typically should not instantiate a {@link android.app.Dialog} directly. Instead, you should use one

of the following subclasses:</p>

<dl>

  <dt>{@link android.app.AlertDialog}</dt>

  <dd>A dialog that can manage zero, one, two, or three buttons, and/or a list of