From 18439bee6f8b525abe3f1fac69bc4cea184e1565 Mon Sep 17 00:00:00 2001
From: Scott Main 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: 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: The activity now appears with the action bar in place of the traditional title bar. 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}. 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: 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. 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: 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: 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. 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: 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: 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. Tip: These methods return the same {@link
+android.app.ActionBar.Tab} instance, so you can chain the calls together. For example, the following code combines steps 2 - 5 to create two tabs and add them to
+the action bar: 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. 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). 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 879eb8b..d50e1cb 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
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.Quickview
+
+
+
+ In this document
+
+
+
+ Key classes
+
+
+
+ See also
+
+
+
+
+
+
+
+
+
+Adding the Action Bar
+
+
+<activity android:theme="@android:style/Theme.Holo" >
+
+
+Adding Action Items
+
+
+<?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>
+
+
+Using the application icon as an action item
+
+
+@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);
+}
+
+
+
+@Override
+protected void onStart() {
+ super.onStart();
+ ActionBar actionBar = this.getActionBar();
+ actionBar.setDisplayOptions(ActionBar.DISPLAY_HOME_AS_UP, ActionBar.DISPLAY_HOME_AS_UP);
+}
+
+
+Adding Tabs
+
+
+
+
+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
+ }
+
+}
+
+
+
+
+@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)));
+}
+
+
+Key classes
+
+ Related tutorials
+
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:
Android provides three types of application 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.
+ +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.
-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.
+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:
+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 0000000..98b5f84 Binary files /dev/null and b/docs/html/images/ui/actionbar-item-withtext.png differ diff --git a/docs/html/images/ui/actionbar-logo.png b/docs/html/images/ui/actionbar-logo.png new file mode 100644 index 0000000..481ed2c Binary files /dev/null and b/docs/html/images/ui/actionbar-logo.png differ diff --git a/docs/html/images/ui/actionbar.png b/docs/html/images/ui/actionbar.png new file mode 100644 index 0000000..4fc871c Binary files /dev/null and b/docs/html/images/ui/actionbar.png differ -- cgit v1.1