| 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 <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> |
| <menu xmlns:android="http://schemas.android.com/apk/res/android" > |
| <!-- Search, should appear as action button --> |
| <item android:id="@+id/action_search" |
| android:icon="@drawable/ic_action_search" |
| android:title="@string/action_search" |
| android:showAsAction="ifRoom" /> |
| <!-- Settings, should always be in the overflow --> |
| <item android:id="@+id/action_settings" |
| android:title="@string/action_settings" |
| android:showAsAction="never" /> |
| </menu> |
| </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> |
| <menu xmlns:android="http://schemas.android.com/apk/res/android" |
| <strong>xmlns:yourapp="http://schemas.android.com/apk/res-auto"</strong> > |
| <!-- Search, should appear as action button --> |
| <item android:id="@+id/action_search" |
| android:icon="@drawable/ic_action_search" |
| android:title="@string/action_search" |
| <strong>yourapp:showAsAction="ifRoom"</strong> /> |
| ... |
| </menu> |
| </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> |
| @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—the returned ID matches the value you declared in the |
| corresponding {@code <item>} element's {@code android:id} attribute.</p> |
| |
| <pre> |
| @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> |
| <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.DisplayMessageActivity" |
| android:label="@string/title_activity_display_message" |
| 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> |
| </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—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>. |