new class on using action bar for training basics

Change-Id: I478a9fb7989a961ebefeee55dc67e9a59c054bb0

1 files changed, 210 insertions, 0 deletions

diff --git a/docs/html/training/basics/actionbar/adding-buttons.jd b/docs/html/training/basics/actionbar/adding-buttons.jd
new file mode 100644
index 0000000..5fb0d59
--- /dev/null
+++ b/docs/html/training/basics/actionbar/adding-buttons.jd
@@ -0,0 +1,210 @@
+page.title=Adding Action Buttons
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+  <div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#XML">Specify the Actions in XML</a></li>
+  <li><a href="#AddActions">Add the Actions to the Action Bar</a></li>
+  <li><a href="#Respond">Respond to Action Buttons</a></li>
+  <li><a href="#UpNav">Add Up Button for Low-level Activities</a></li>
+</ol>
+
+<h2>You should also read</h2>
+<ul>
+  <li><a href="{@docRoot}training/implementing-navigation/ancestral.html">Providing Up
+  Navigation</a></li>
+  </div>
+</div>
+
+
+
+<p>The action bar allows you to add buttons for the most important action
+items relating to the app's current
+context. Those that appear directly in the action bar with an icon and/or text are known
+as <em>action buttons</em>. Actions that can't fit in the action bar or aren't
+important enough are hidden in the action overflow.</p>
+
+<img src="{@docRoot}images/training/basics/actionbar-actions.png" height="100" alt=""/>
+<p class="img-caption"><strong>Figure 1.</strong> An action bar with an action button
+for Search and the action overflow, which reveals additional actions.</a>
+
+
+<h2 id="XML">Specify the Actions in XML</h2>
+
+<p>All action buttons and other items available in the action overflow are defined
+in an XML <a
+href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. To add
+actions to the action bar, create a new XML file in your project's
+{@code res/menu/} directory.</p>
+
+<p>Add an {@code &lt;item>} element for each item you want to include in the action bar.
+For example:</p>
+
+<p class="code-caption">res/menu/main_activity_actions.xml</p>
+<pre>
+&lt;menu xmlns:android="http://schemas.android.com/apk/res/android" >
+    &lt;!-- Search, should appear as action button -->
+    &lt;item android:id="@+id/action_search"
+          android:icon="@drawable/ic_action_search"
+          android:title="@string/action_search"
+          android:showAsAction="ifRoom" /&gt;
+    &lt;!-- Settings, should always be in the overflow -->
+    &lt;item android:id="@+id/action_settings"
+          android:title="@string/action_settings"
+          android:showAsAction="never" /&gt;
+&lt;/menu&gt;
+</pre>
+
+<div class="sidebox">
+<h3>Download action bar icons</h3>
+<p>To best match the Android <a
+href="{@docRoot}design/style/iconography.html#action-bar">iconography</a> guidelines, you should
+use icons provided in the
+<a href="{@docRoot}design/downloads/index.html#action-bar-icon-pack">Action Bar Icon Pack</a>.</p>
+</div>
+
+<p>This declares that the Search action should appear as an action button when room
+is available in the action bar, but the
+Settings action should always appear in the overflow. (By default, all actions appear in the
+overflow, but it's good practice to explicitly declare your design intentions for each action.)
+
+<p>However, <strong>if your app is using the Support Library</strong> for compatibility on versions
+as low as Android 2.1, the {@code showAsAction} attribute is not available from
+the {@code android:} namespace. Instead this attribute is provided by the Support Library
+and you must define your own XML namespace and use that namespace as the attribute prefix.
+(A custom XML namespace should be based on your app name, but it can be any
+name you want and is only accessible within the scope of the file in which you declare it.)
+For example:</p>
+
+<p class="code-caption">res/menu/main_activity_actions.xml</p>
+<pre>
+&lt;menu xmlns:android="http://schemas.android.com/apk/res/android"
+      <strong>xmlns:yourapp="http://schemas.android.com/apk/res-auto"</strong> >
+    &lt;!-- Search, should appear as action button -->
+    &lt;item android:id="@+id/action_search"
+          android:icon="@drawable/ic_action_search"
+          android:title="@string/action_search"
+          <strong>yourapp:showAsAction="ifRoom"</strong>  /&gt;
+    ...
+&lt;/menu&gt;
+</pre>
+
+
+
+<h2 id="AddActions">Add the Actions to the Action Bar</h2>
+
+<p>To place the menu items into the action bar, implement the
+{@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback
+method in your activity to inflate the menu resource into the given {@link android.view.Menu}
+object. For example:</p>
+
+<pre>
+&#64;Override
+public boolean onCreateOptionsMenu(Menu menu) {
+    // Inflate the menu items for use in the action bar
+    MenuInflater inflater = getMenuInflater();
+    inflater.inflate(R.menu.main_activity_actions, menu);
+    return super.onCreateOptionsMenu(menu);
+}
+</pre>
+
+
+
+<h2 id="Respond">Respond to Action Buttons</h2>
+
+<p>When the user presses one of the action buttons or another item in the action overflow,
+the system calls your activity's {@link android.app.Activity#onOptionsItemSelected
+onOptionsItemSelected()} callback method. In your implementation of this method,
+call {@link android.view.MenuItem#getItemId getItemId()} on the given {@link android.view.MenuItem} to
+determine which item was pressed&mdash;the returned ID matches the value you declared in the
+corresponding {@code &lt;item>} element's {@code android:id} attribute.</p>
+
+<pre>
+&#64;Override
+public boolean onOptionsItemSelected(MenuItem item) {
+    // Handle presses on the action bar items
+    switch (item.getItemId()) {
+        case R.id.action_search:
+            openSearch();
+            return true;
+        case R.id.action_settings:
+            openSettings();
+            return true;
+        default:
+            return super.onOptionsItemSelected(item);
+    }
+}
+</pre>
+
+
+
+<h2 id="UpNav">Add Up Button for Low-level Activities</h2>
+
+<div class="figure" style="width:240px">
+  <img src="{@docRoot}images/ui/actionbar-up.png" width="240" alt="">
+  <p class="img-caption"><strong>Figure 4.</strong> The <em>Up</em> button in Gmail.</p>
+</div>
+
+<p>All screens in your app that are not the main entrance to your app
+(activities that are not the "home" screen) should
+offer the user a way to navigate to the logical parent screen in the app's hierarchy by pressing
+the <em>Up</em> button in the action bar.</p>
+
+<p>When running on Android 4.1 (API level 16) or higher, or when using {@link
+android.support.v7.app.ActionBarActivity} from the Support Library, performing <em>Up</em>
+navigation simply requires that you declare the parent activity in the manifest file and enable
+the <em>Up</em> button for the action bar.</p>
+
+<p>For example, here's how you can declare an activity's parent in the manifest:</p>
+
+<pre>
+&lt;application ... >
+    ...
+    &lt;!-- The main/home activity (it has no parent activity) -->
+    &lt;activity
+        android:name="com.example.myfirstapp.MainActivity" ...>
+        ...
+    &lt;/activity>
+    &lt;!-- A child of the main activity -->
+    &lt;activity
+        android:name="com.example.myfirstapp.DisplayMessageActivity"
+        android:label="@string/title_activity_display_message"
+        android:parentActivityName="com.example.myfirstapp.MainActivity" >
+        &lt;!-- Parent activity meta-data to support 4.0 and lower -->
+        &lt;meta-data
+            android:name="android.support.PARENT_ACTIVITY"
+            android:value="com.example.myfirstapp.MainActivity" />
+    &lt;/activity>
+&lt;/application>
+</pre>
+
+  <p>Then enable the app icon as the <em>Up</em> button by calling
+{@link android.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled()}:</p>
+
+<pre>
+{@literal @}Override
+public void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+    setContentView(R.layout.activity_displaymessage);
+
+    getSupportActionBar().setDisplayHomeAsUpEnabled(true);
+    // If your minSdkVersion is 11 or higher, instead use:
+    // getActionBar().setDisplayHomeAsUpEnabled(true);
+}
+</pre>
+
+<p>Because the system now knows {@code MainActivity} is the parent activity for
+{@code DisplayMessageActivity}, when the user presses the
+<em>Up</em> button, the system navigates to
+the parent activity as appropriate&mdash;you <strong>do not</strong> need to handle the
+<em>Up</em> button's event.</p>
+
+<p>For more information about up navigation, see
+<a href="{@docRoot}training/implementing-navigation/ancestral.html">Providing Up
+  Navigation</a>.
\ No newline at end of file