ifRoomifRoom"ifRoom", the items with the lowest
+ orderInCategory values are displayed as actions, and
+ the remaining items are displayed in the overflow menu.withTextneverneveralwaysDesign Guide
+Action Buttons
++ The app bar allows you to add buttons for user actions. This feature lets you + put the most important actions for the current context right at the + top of the app. For example, a photo browsing app might show share + and create album buttons at the top when the user is looking at + their photo roll; when the user looks at an individual photo, the app might + show crop and filter buttons. +
+ ++ Space in the app bar is limited. If an app declares more actions than can + fit in the app bar, the app bar send the excess actions to an + overflow menu. The app can also specify that an action should always + be shown in the overflow menu, instead of being displayed on the app bar. +
+ +
+
++ Figure 1. An app bar with a single action button and an + overflow menu. +
+ +Add Action Buttons
+ +
+ All action buttons and other items available in the action overflow are
+ defined in an XML menu resource. To
+ add actions to the action bar, create a new XML file in your project's
+ res/menu/ directory.
+
+ Add an <item>
+ element for each item you want to include in the action bar, as shown in this
+ code example of a menu XML file:
+
+<menu xmlns:android="http://schemas.android.com/apk/res/android" > + + <!-- "Mark Favorite", should appear as action button if possible --> + <item + android:id="@+id/action_favorite" + android:icon="@drawable/ic_favorite_black_48dp" + android:title="@string/action_favorite" + app:showAsAction="ifRoom"/> + + <!-- Settings, should always be in the overflow --> + <item android:id="@+id/action_settings" + android:title="@string/action_settings" + app:showAsAction="never"/> + +</menu> ++ +
+ The app:showAsAction attribute specifies whether the action
+ should be shown as a button on the app bar. If you set
+ app:showAsAction="ifRoom" (as in the example code's favorite action), the action is displayed as a button
+ if there is room in the app bar for it; if there is not enough room, excess
+ actions are sent to the overflow menu. If you set
+ app:showAsAction="never" (as in the example code's settings action), the action is always listed in the
+ overflow menu, not displayed in the app bar.
+
+ The system uses the action's icon as the action button if the action is + displayed in the app bar. You can find many useful icons on the Material Icons page. +
+ +Respond to Actions
+ +
+ When the user selects one of the app bar items, the system calls your
+ activity's {@link android.app.Activity#onOptionsItemSelected
+ onOptionsItemSelected()} callback method, and passes a {@link
+ android.view.MenuItem} object to indicate which item was clicked. In your
+ implementation of {@link android.app.Activity#onOptionsItemSelected
+ onOptionsItemSelected()}, call the {@link android.view.MenuItem#getItemId
+ MenuItem.getItemId()} method to determine which item was pressed. The ID returned
+ matches the value you declared in the corresponding <item>
+ element's android:id attribute.
+
+ For example, the following code checks to see which action the user selected. + If the method does not recognize the user's action, it invokes the superclass + method: +
+ +
+@Override
+public boolean onOptionsItemSelected(MenuItem item) {
+ switch (item.getItemId()) {
+ case R.id.action_settings:
+ // User chose the "Settings" item, show the app settings UI...
+ return true;
+
+ case R.id.action_favorite:
+ // User chose the "Favorite" action, mark the current item
+ // as a favorite...
+ return true;
+
+ default:
+ // If we got here, the user's action was not recognized.
+ // Invoke the superclass to handle it.
+ return super.onOptionsItemSelected(item);
+
+ }
+}
+
diff --git a/docs/html/training/appbar/index.jd b/docs/html/training/appbar/index.jd
new file mode 100644
index 0000000000000..144e99f2f525b
--- /dev/null
+++ b/docs/html/training/appbar/index.jd
@@ -0,0 +1,98 @@
+page.title=Adding the App Bar
+page.tags="appbar","actionbar"
+helpoutsWidget=true
+trainingnavtop=true
+startpage=true
+
+@jd:body
+
+Dependencies and prerequisites
+-
+
- Android 2.1 (API level 7) or higher +
You should also read
+ + ++ The app bar, also known as the action bar, is one of the most + important design elements in your app's activities, because + it provides a visual structure and interactive elements that are familiar to + users. Using the app bar makes your app consistent with other Android apps, + allowing users to quickly understand how to operate your app and have a great + experience. + The key functions of the app bar + are as follows: +
+ +-
+
- A dedicated space for giving your app an identity and indicating the + user's location in the app. + + +
- Access to important actions in a predictable way, such as search. + + +
- Support for navigation and view switching (with tabs or drop-down lists). + +
+
++ This class describes how to use the + v7 + appcompat support library's {@link + android.support.v7.widget.Toolbar} widget as an app bar. There are other ways + to implement an app bar—for example, some themes set up an {@link + android.app.ActionBar} as an app bar by default—but using the appcompat + {@link android.support.v7.widget.Toolbar} makes it easy to set up an app bar + that works on the widest range of devices, and also gives you room to + customize your app bar later on as your app develops. +
+ +Lessons
+ +-
+
- + Setting Up the App Bar + + +
- + Learn how to add a {@link android.support.v7.widget.Toolbar} widget to your + activity, and set it as the activity's app bar. + + +
- + Adding and Handling Actions + + +
- + Learn how to add actions to the app bar and its overflow menu, and how to + respond when users choose those actions. + + +
- + Adding an Up Action + + +
- + Learn how to add an Up button to your app bar, so users + can navigate back to the app's home screen. + +
This lesson teaches you to
+ + + +You should also read
+ ++ In its most basic form, the action bar displays the title for the activity on + one side and an overflow menu on the other. Even in this simple + form, the app bar provides useful information to the users, and helps to give + Android apps a consistent look and feel. +
+ +
+Figure 1. An app bar with the app +title and overflow menu. + +
+ Beginning with Android 3.0 (API level 11), all + activities that use the default theme have an {@link android.app.ActionBar} + as an app bar. However, app bar features have gradually been added to the + native {@link android.app.ActionBar} over various Android releases. As a + result, the native {@link android.app.ActionBar} behaves differently + depending on what version of the Android system a device may be using. By + contrast, the most recent features are added to the support library's version + of {@link android.support.v7.widget.Toolbar}, and they are available on any + device that can use the support library. +
+ ++ For this reason, you should use the support library's {@link + android.support.v7.widget.Toolbar} class to implement your activities' app + bars. Using the support library's toolbar helps ensure that your app will + have consistent behavior across the widest range of devices. For example, the + {@link android.support.v7.widget.Toolbar} widget provides a material design experience on + devices running Android 2.1 (API level 7) or later, but the native action + bar doesn't support material design unless the device is running Android 5.0 + (API level 21) or later. +
+ +Add a Toolbar to an Activity
+ +These steps describe how to set up a {@link android.support.v7.widget.Toolbar} +as your activity's app bar: + +-
+
- Add the the + v7 + appcompat support library to your project, as described in Support Library Setup. + + +
- Make sure the activity extends {@link
+ android.support.v7.app.AppCompatActivity}:
+
+
+public class MyActivity extends AppCompatActivity { + // ... +} +++ Note: Make this change for every activity in your app + that uses a {@link android.support.v7.widget.Toolbar} as an app bar. +
+
+
+ - In the app manifest, set the
<application>+ element to use one of appcompat's {@link + android.support.v7.appcompat.R.style#Theme_AppCompat_NoActionBar NoActionBar} + themes. Using one of these themes prevents the app from using the native + {@link android.app.ActionBar} class to provide the app bar. For example: + ++<application + android:theme="@style/Theme.AppCompat.Light.NoActionBar" + /> +
+
+
+ - Add a {@link android.support.v7.widget.Toolbar} to the activity's layout.
+ For example, the following layout code adds a {@link
+ android.support.v7.widget.Toolbar} and gives it the appearance of floating
+ above the activity:
+
+
+<android.support.v7.widget.Toolbar + android:id="@+id/my_toolbar" + android:layout_width="match_parent" + android:layout_height="?attr/actionBarSize" + android:background="?attr/colorPrimary" + android:elevation="4dp" + android:theme="@style/ThemeOverlay.AppCompat.ActionBar" + app:popupTheme="@style/ThemeOverlay.AppCompat.Light"/> +
++ The + Material Design specification recommends that app bars have an + elevation of 4 dp. +
+ ++ Position the toolbar at the top of the activity's + layout, + since you are using it as an app bar. +
+
+
+ - In the activity's {@link android.app.Activity#onCreate onCreate()}
+ method, call the activity's {@link
+ android.support.v7.app.AppCompatActivity#setSupportActionBar
+ setSupportActionBar()} method, and pass the activity's toolbar. This method
+ sets the toolbar as the app bar for the activity. For example:
+
+
+@Override +protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_my); + Toolbar myToolbar = (Toolbar) findViewById(R.id.my_toolbar); + setSupportActionBar(myToolbar); + } ++
+
+ Your app now has a basic action bar. By default, the action bar contains just + the name of the app and an overflow menu. The options menu initially contains + just the Settings item. You can add more actions to the + action bar and the overflow menu, as described in Adding and Handling Actions. +
+ +Use App Bar Utility Methods
+ ++ Once you set the toolbar as an activity's app bar, you have access to the + various utility methods provided by the + v7 + appcompat support library's {@link + android.support.v7.app.ActionBar} class. This approach lets you do a number of useful + things, like hide and show the app bar. +
+ ++ To use the {@link android.support.v7.app.ActionBar} utility methods, call the + activity's {@link + android.support.v7.app.AppCompatActivity#getSupportActionBar + getSupportActionBar()} method. This method returns a reference to an + appcompat {@link android.support.v7.app.ActionBar} object. + Once you have that reference, you can call any of the {@link + android.support.v7.app.ActionBar} methods to adjust the app bar. For example, + to hide the app bar, call {@link android.support.v7.app.ActionBar#hide + ActionBar.hide()}. +
diff --git a/docs/html/training/appbar/up-action.jd b/docs/html/training/appbar/up-action.jd new file mode 100644 index 0000000000000..1336d207ff03f --- /dev/null +++ b/docs/html/training/appbar/up-action.jd @@ -0,0 +1,134 @@ +page.title=Adding an Up Action +page.tags="appbar","actionbar", "up" +helpoutsWidget=true +trainingnavtop=true + +@jd:body + +This lesson teaches you to
+ +-
+
- + Declare a Parent Activity + + +
- + Enable the Up Button + +
See Also
+ + + ++ Your app should make it easy for users to find their way back to the app's + main screen. One simple way to do this is to provide an Up + button on the app bar for all activities except the main one. When the user + selects the Up button, the app navigates to the parent + activity. +
+ ++ This lesson shows you how to add an Up button to an activity by + declaring the activity's parent in the manifest, and enabling the app bar's + Up button. +
+ +Declare a Parent Activity
+ +
+ To support the up functionality in an activity, you need to declare the
+ activity's parent. You can do this in the app manifest, by setting an
+ android:parentActivityName attribute.
+
+ The android:parentActivityName attribute
+ was introduced in Android 4.1 (API level 16). To support devices with older
+ versions of Android, define a <meta-data>
+ name-value pair, where the name is
+ "android.support.PARENT_ACTIVITY" and the value is the name of
+ the parent activity.
+
+ For example, suppose your app has a main activity named
+ MainActivity and a single child activity. The following manifest
+ code declares both activities, and specifies the parent/child relationship:
+
+<application ... > + ... + + <!-- The main/home activity (it has no parent activity) --> + + <activity + android:name="com.example.myfirstapp.MainActivity" ...> + ... + </activity> + + <!-- A child of the main activity --> + <activity + android:name="com.example.myfirstapp.MyChildActivity" + android:label="@string/title_activity_child" + android:parentActivityName="com.example.myfirstapp.MainActivity" > + + <!-- Parent activity meta-data to support 4.0 and lower --> + <meta-data + android:name="android.support.PARENT_ACTIVITY" + android:value="com.example.myfirstapp.MainActivity" /> + </activity> +</application> ++ +
Enable the Up Button
+ +
+ To enable the Up button for an activity that has a parent
+ activity, call the app bar's {@link
+ android.support.v7.app.ActionBar#setDisplayHomeAsUpEnabled
+ setDisplayHomeAsUpEnabled()} method. Typically, you would do this when the
+ activity is created. For example, the following {@link
+ android.app.Activity#onCreate onCreate()} method sets a {@link
+ android.support.v7.widget.Toolbar} as the app bar for
+ MyChildActivity, then enables that app bar's Up button:
+
+@Override
+protected void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.activity_my_child);
+
+ // my_child_toolbar is defined in the layout file
+ Toolbar myChildToolbar =
+ (Toolbar) findViewById(R.id.my_child_toolbar);
+ setSupportActionBar(myChildToolbar);
+
+ // Get a support ActionBar corresponding to this toolbar
+ ActionBar ab = getSupportActionBar();
+
+ // Enable the Up button
+ ab.setDisplayHomeAsUpEnabled(true);
+}
+
+
++ You do not need to catch the up action in the activity's {@link + android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method. + Instead, that method should call its superclass, as shown in Respond to Actions. The superclass method + responds to the Up selection by navigating to the parent + activity, as specified in the app manifest. +
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 296334520e500..002fb09927dde 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -1388,7 +1388,6 @@ results."-
-