+ Figure 2. A screenshot from an action bar with two +action items.
+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.
+ + +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.
+ + +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.
+ + +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.
+ + +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:
+
+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.
+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:
+
+@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 iEvery 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
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:
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.
-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:
+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 0000000000000..98b5f8490f550
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 0000000000000..481ed2c11c34f
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 0000000000000..4fc871c670d76
Binary files /dev/null and b/docs/html/images/ui/actionbar.png differ