From 18439bee6f8b525abe3f1fac69bc4cea184e1565 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Tue, 7 Sep 2010 17:11:38 -0700 Subject: [PATCH] docs: add dev guide for action bar and update other relevant documents Change-Id: I1d3deda4c35066f7cf05b06fe5b60acfa1fae149 --- docs/html/guide/guide_toc.cs | 3 + docs/html/guide/topics/ui/actionbar.jd | 332 ++++++++++++++++++ docs/html/guide/topics/ui/declaring-layout.jd | 4 +- docs/html/guide/topics/ui/dialogs.jd | 22 +- docs/html/guide/topics/ui/menus.jd | 96 +++-- .../images/ui/actionbar-item-withtext.png | Bin 0 -> 6582 bytes docs/html/images/ui/actionbar-logo.png | Bin 0 -> 8616 bytes docs/html/images/ui/actionbar.png | Bin 0 -> 7661 bytes 8 files changed, 412 insertions(+), 45 deletions(-) create mode 100644 docs/html/guide/topics/ui/actionbar.jd create mode 100644 docs/html/images/ui/actionbar-item-withtext.png create mode 100644 docs/html/images/ui/actionbar-logo.png create mode 100644 docs/html/images/ui/actionbar.png diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 3cc18060841fd..254812823daf7 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -71,6 +71,9 @@
  • Creating Menus
    • +
  • + Using the Action Bar + new!
  • Creating Dialogs
    • diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd new file mode 100644 index 0000000000000..2b942e74ece6e --- /dev/null +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -0,0 +1,332 @@ +page.title=Using the Action Bar +parent.title=User Interface +parent.link=index.html +@jd:body + +
    +
    + +

    Quickview

    +
      +
    • A replacement for the title bar for displaying global actions for the activity
      • +
    • Provides toolbar actions and modes of navigating around the application
      • +
    • Switches to contextual menu options when one or more items are selected
      • +
    • Requires API Level HONEYCOMB
      • +
    + +

    In this document

    +
      +
    1. Adding the Action Bar
      2. +
    2. Adding Action Items +
        +
      1. Using the application icon as an action item
        2. +
      +
      3. +
    3. Adding Tabs
      4. +
    4. Adding Drop-down Navigation
      5. +
    5. Adding Search
      6. +
    + +

    Key classes

    +
      +
    1. {@link android.app.ActionBar}
      2. +
    2. {@link android.view.Menu}
      3. +
    + +

    See also

    +
      +
    1. Creating Menus
      2. +
    +
    +
    + +

    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:

    + + + + +

    Figure 1. A screenshot of the action bar in the NotePad +sample application, containing action items to save and delete the note.

    + + +

    Adding the Action Bar

    + +

    To add the Action Bar to your activity, apply the holographic theme—{@code +Theme.Holo}—or the action bar theme—{@code Theme.WithActionBar}—in your manifest +file. For example:

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

    The activity now appears with the action bar in place of the traditional title bar.

    + + +

    Adding Action Items

    + +

    For each action item you want to add to the action bar, you must add a menu item to the +activity's options menu 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}.

    + +
    + +

    Figure 2. A screenshot from an action bar with two +action items.

    +
    + +

    You can specify a menu item to appear as an action item in the action bar—if there is room +for it—from the menu +resource 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}.

    + +

    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 with text +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.

    + +

    Here's an example of how you can declare a menu item as an action item in a menu resource file:

    +
    +<?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"
+          android:showAsAction="ifRoom|withText" />
+</menu>
+
    + +

    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.

    + +

    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.)

    + +

    Note: 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.

    + +

    You can also declare an item to always 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 if room), 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.

    + +

    For more information about menus, see the Creating Menus developer guide.

    + + +

    Using the application icon as an action item

    + +

    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.

    + +

    For example, here's an implementation of {@link android.app.Activity#onOptionsItemSelected +onOptionsItemSelected()} that returns to the application's "home" activity:

    + +
    +@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);
+}
+
    + +
    + +

    Figure 3. The standard icon for the Email application +(top) and the "up navigation" icon (bottom).

    +
    + +

    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 navigate +up to the parent activity, 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.

    + +

    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 after you've called {@link android.app.Activity#setContentView +setContentView()}).

    + +

    For example, here's how you can change the action bar display mode to show the application +icon as an "up" action:

    + +
    +@Override
+protected void onStart() {
+  super.onStart();
+  ActionBar actionBar = this.getActionBar();
+  actionBar.setDisplayOptions(ActionBar.DISPLAY_HOME_AS_UP, ActionBar.DISPLAY_HOME_AS_UP);
+}
+
    + +

    Caution: 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.

    + + +

    Adding Tabs

    + +

    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.

    + +

    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.

    + +

    To add tabs to the action bar:

    +
      +
    1. 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()}. +

      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).

      +

      For example:

      +
      +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
+    }
+
+}
+
      +

      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.

      +
      2. +
    2. 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 after you've called +{@link android.app.Activity#setContentView setContentView()}).
      3. +
    3. Call {@link android.app.ActionBar#setNavigationMode(int) +setNavigationMode(NAVIGATION_MODE_TABS)} to enable tab mode for the {@link +android.app.ActionBar}.
      4. +
    4. Create each tab for the action bar: +
        +
      1. Create a new {@link android.app.ActionBar.Tab} by calling {@link +android.app.ActionBar#newTab()} on the {@link android.app.ActionBar}.
        2. +
      2. 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()}. +

        Tip: These methods return the same {@link +android.app.ActionBar.Tab} instance, so you can chain the calls together.

        3. +
      3. 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()}. +
      +
      5. +
    5. 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}.
      6. +
    +

    For example, the following code combines steps 2 - 5 to create two tabs and add them to +the action bar:

    +
    +@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)));
+}
+
    + +

    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()}.

    + +

    Note: You do not need +to call {@link android.app.FragmentTransaction#commit} for these transactions. You also +cannot add these fragment transactions to the back stack.

    + +

    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.

    + +

    Caution: 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 Fragments developer guide.

    + + diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd index fe641a2d6602e..4d71d28a89d77 100644 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -191,10 +191,12 @@ layout parameters for the View that are appropriate for the ViewGroup in which i

    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).

    +

    Figure 1. Visualization of a view hierarchy with layout +parameters associated with each view.

    Note that every LayoutParams subclass has its own syntax for setting values. Each child element must define LayoutParams that are appropriate for its parent, diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd index 879eb8b35ea62..d50e1cb2047d5 100644 --- a/docs/html/guide/topics/ui/dialogs.jd +++ b/docs/html/guide/topics/ui/dialogs.jd @@ -22,20 +22,32 @@ parent.link=index.html

  • Creating a Custom Dialog
    • - +

    Key classes

    1. {@link android.app.Dialog}
      2. +
    2. {@link android.app.AlertDialog}
      3. +
    3. {@link android.app.DialogFragment}
      4. +
    + +

    Related tutorials

    +
      +
    1. Hello +DatePicker
      2. +
    2. Hello +TimePicker

    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.

    +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).

    -

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

    +

    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:

    {@link android.app.AlertDialog}
    A dialog that can manage zero, one, two, or three buttons, and/or a list of diff --git a/docs/html/guide/topics/ui/menus.jd b/docs/html/guide/topics/ui/menus.jd index b4e467c273f2d..ce25b9f829db2 100644 --- a/docs/html/guide/topics/ui/menus.jd +++ b/docs/html/guide/topics/ui/menus.jd @@ -36,6 +36,7 @@ parent.link=index.html

    See also

      +
    1. Using the Action Bar
    2. Menu Resource
    @@ -48,20 +49,9 @@ for you to provide application menus in your application.

    Android provides three types of application menus:

    Options Menu
    -
    The primary menu for an Activity, which appears when the user presses - the device MENU key. Within the Options Menu are two groups: -
    -
    Icon Menu
    -
    The menu items visible at the bottom of the screen - at the press of the MENU key. It supports a maximum of six menu items. - These are the only menu items that support icons and the only menu items that do not support - checkboxes or radio buttons.
    -
    Expanded Menu
    -
    The vertical list of menu items exposed by the "More" menu item in the Icon Menu. - When the Icon Menu is full, the expanded menu is comprised of the sixth - menu item and the rest.
    -
    -
    +
    The primary collection of menu items for an Activity that is associated with the device MENU +key. To provide instant access to select menu items, you can place some items in the Action Bar, if available.
    Context Menu
    A floating list of menu items that appears when the user performs a long-press on a View.
    @@ -74,7 +64,7 @@ Menu or a context menu. A submenu item cannot support a nested submenu.

    Defining Menus

    -

    Instead of instantiating {@link android.view.Menu} objects in your application code, you should +

    Instead of instantiating a {@link android.view.Menu} in your application code, you should define a menu and all its items in an XML menu resource, then inflate the menu resource (load it as a programmable object) in your application code. Defining your menus in XML is @@ -104,9 +94,9 @@ href="#groups">Menu groups. <item android:id="@+id/new_game" android:icon="@drawable/ic_new_game" android:title="@string/new_game" /> - <item android:id="@+id/quit" - android:icon="@drawable/ic_quit" - android:title="@string/quit" /> + <item android:id="@+id/help" + android:icon="@drawable/ic_help" + android:title="@string/help" /> </menu> @@ -161,36 +151,64 @@ creating an option menu is discussed more in the next section.)

    -

    The Options Menu is where you should include basic application functions -and necessary navigation items (for example, a button -to open application settings). The user -can open the Options Menu with the device MENU key. -Figure 1 shows a screenshot of an Options Menu.

    +

    The Options Menu is where you should include basic application functions and necessary navigation +items (for example, a button to open the application settings). Items in the Options Menu are +accessible in two distinct ways: in the Action Bar and in the menu revealed by the MENU +key.

    -

    When opened, the first visible portion of the Options Menu is called the Icon Menu. It -holds the first six menu items. -If you add more than six items to the Options Menu, Android places the sixth item and those after it -into the Expanded Menu, which the user can open with the "More" menu item.

    +

    The Action Bar is an optional widget that appears at the top of the activity in place of the +title bar. It can display several menu items that you choose from the Options Menu, but items in +the Action Bar display only an icon (no title text). Users can reveal the other menu items in the +Options Menu with the MENU key.

    + +

    If you include the Action Bar in your activity, the menu items that are not placed in the Action +Bar can appear in two different styles:

    +
    +
    Action Bar Menu
    +
    If the device has an extra-large screen ({@code xlarge}), then all items in the Options Menu +that are not placed in the Action Bar are placed into a drop-down list at the right side of the +Action Bar, with icons and title text. The user can reveal the drop-down list by pressing the +drop-down icon in the Action Bar or the MENU key.
    +
    Standard Options Menu
    +
    If the device does not have an extra-large screen, then all items in the Options +Menu that are not placed in the Action Bar are placed into the Standard Options Menu at the bottom +of the activity. The user can reveal the standard Options Menu by pressing the MENU key. +

    The first visible portion of the Standard Options Menu is called the Icon Menu. +It holds the first six menu items (excluding any added to the Action Bar), with icons and title +text. If there are more than six items, Android adds a "More" item as the sixth menu item and places +the remaining items into the Expanded Menu, which the user can open by selecting "More". The +Expanded Menu displays menu items only by their title text (no icon)

    +
    +

    When the user opens the Options Menu for the first time, Android calls your Activity's {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} method. Override this method in your Activity and populate the {@link android.view.Menu} that is passed into the method. Populate the {@link android.view.Menu} by inflating a menu resource as described in Inflating a Menu Resource. (You can -also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int) -add()} to add menu items.)

    +href="#Inflating">Inflating a Menu Resource. For example:

    -

    When the user selects a menu item from the Options Menu, the system calls your Activity's +

    +@Override
+public boolean onCreateOptionsMenu(Menu menu) {
+    MenuInflater inflater = getMenuInflater();
+    inflater.inflate(R.menu.game_menu, menu);
+    return true;
+}
+
    + +

    (You can also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int) +add()} to add items to the {@link android.view.Menu}.)

    + +

    When the user selects a menu item from the Options Menu (including items selected from the +Action Bar), the system calls your Activity's {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method. This method passes the {@link android.view.MenuItem} that the user selected. You can identify the menu item by calling {@link android.view.MenuItem#getItemId()}, which returns the unique ID for the menu item (defined by the {@code android:id} attribute in the menu resource or with an integer passed to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match this ID -against known menu items and perform the appropriate action.

    - -

    For example:

    +against known menu items and perform the appropriate action. For example:

     @Override
@@ -200,8 +218,8 @@ public boolean onOptionsItemSelected(MenuItem item) {
     case R.id.new_game:
         newGame();
         return true;
-    case R.id.quit:
-        quit();
+    case R.id.help:
+        showHelp();
         return true;
     default:
         return super.onOptionsItemSelected(item);
@@ -224,8 +242,8 @@ an Activity that implements nothing except the {@link android.app.Activity#onCre
 onCreateOptionsMenu()} and {@link android.app.Activity#onOptionsItemSelected(MenuItem)
 onOptionsItemSelected()} methods. Then extend this class for each Activity that should share the
 same Options Menu. This way, you have to manage only one set of code for handling menu
-actions and each decendent class inherits the menu behaviors.

    
-If you want to add menu items to one of your decendent activities,
+actions and each descendant class inherits the menu behaviors.

    
+If you want to add menu items to one of your descendant activities,
 override {@link android.app.Activity#onCreateOptionsMenu(Menu)
 onCreateOptionsMenu()} in that Activity. Call {@code super.onCreateOptionsMenu(menu)} so the
 original menu items are created, then add new menu items with {@link
@@ -542,7 +560,7 @@ hardware keyboard. Shortcuts cannot be added to items in a Context Menu.
    
 
    Intents for menu items
    
 
 
    Sometimes you'll want a menu item to launch an Activity using an Intent (whether it's an
-Actvitity in your application or another application). When you know the Intent you want to use and
+Activity in your application or another application). When you know the Intent you want to use and
 have a specific menu item that should initiate the Intent, you can execute the Intent with {@link
 android.app.Activity#startActivity(Intent) startActivity()} during the appropriate on-item-selected
 callback method (such as the {@link android.app.Activity#onOptionsItemSelected(MenuItem)
diff --git a/docs/html/images/ui/actionbar-item-withtext.png b/docs/html/images/ui/actionbar-item-withtext.png
new file mode 100644
index 0000000000000000000000000000000000000000..98b5f8490f550b92654aeecd8d50809e854cc6dc
GIT binary patch
literal 6582
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