1page.title=Adding Action Buttons
2page.tags=actionbar
3helpoutsWidget=true
4
5trainingnavtop=true
6
7@jd:body
8
9<div id="tb-wrapper">
10  <div id="tb">
11
12<h2>This lesson teaches you to</h2>
13<ol>
14  <li><a href="#XML">Specify the Actions in XML</a></li>
15  <li><a href="#AddActions">Add the Actions to the Action Bar</a></li>
16  <li><a href="#Respond">Respond to Action Buttons</a></li>
17  <li><a href="#UpNav">Add Up Button for Low-level Activities</a></li>
18</ol>
19
20<h2>You should also read</h2>
21<ul>
22  <li><a href="{@docRoot}training/implementing-navigation/ancestral.html">Providing Up
23  Navigation</a></li>
24  </div>
25</div>
26
27
28
29<p>The action bar allows you to add buttons for the most important action
30items relating to the app's current
31context. Those that appear directly in the action bar with an icon and/or text are known
32as <em>action buttons</em>. Actions that can't fit in the action bar or aren't
33important enough are hidden in the action overflow.</p>
34
35<img src="{@docRoot}images/training/basics/actionbar-actions.png" height="100" alt=""/>
36<p class="img-caption"><strong>Figure 1.</strong> An action bar with an action button
37for Search and the action overflow, which reveals additional actions.</a>
38
39
40<h2 id="XML">Specify the Actions in XML</h2>
41
42<p>All action buttons and other items available in the action overflow are defined
43in an XML <a
44href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. To add
45actions to the action bar, create a new XML file in your project's
46{@code res/menu/} directory.</p>
47
48<p>Add an {@code &lt;item>} element for each item you want to include in the action bar.
49For example:</p>
50
51<p class="code-caption">res/menu/main_activity_actions.xml</p>
52<pre>
53&lt;menu xmlns:android="http://schemas.android.com/apk/res/android" >
54    &lt;!-- Search, should appear as action button -->
55    &lt;item android:id="@+id/action_search"
56          android:icon="@drawable/ic_action_search"
57          android:title="@string/action_search"
58          android:showAsAction="ifRoom" /&gt;
59    &lt;!-- Settings, should always be in the overflow -->
60    &lt;item android:id="@+id/action_settings"
61          android:title="@string/action_settings"
62          android:showAsAction="never" /&gt;
63&lt;/menu&gt;
64</pre>
65
66<div class="sidebox">
67<h3>Download action bar icons</h3>
68<p>To best match the Android <a
69href="{@docRoot}design/style/iconography.html#action-bar">iconography</a> guidelines, you should
70use icons provided in the
71<a href="{@docRoot}design/downloads/index.html#action-bar-icon-pack">Action Bar Icon Pack</a>.</p>
72</div>
73
74<p>This declares that the Search action should appear as an action button when room
75is available in the action bar, but the
76Settings action should always appear in the overflow. (By default, all actions appear in the
77overflow, but it's good practice to explicitly declare your design intentions for each action.)
78
79<p>The {@code icon} attribute requires a resource ID for an
80image. The name that follows {@code &#64;drawable/} must be the name of a bitmap image you've
81saved in your project's {@code res/drawable/} directory. For example,
82{@code "&#64;drawable/ic_action_search"} refers to {@code ic_action_search.png}.
83Likewise, the {@code title} attribute uses a string resource that's defined by an XML
84file in your project's {@code res/values/} directory, as discussed in <a
85href="{@docRoot}training/basics/firstapp/building-ui.html#Strings">Building a Simple User
86Interface</a>.
87
88<p class="note"><strong>Note:</strong> When creating icons and other bitmap images for your app,
89it's important that you provide multiple versions that are each optimized for a different screen
90density. This is discussed more in the lesson about <a
91href="{@docRoot}training/basics/supporting-devices/screens.html">Supporting Different Screens</a>.
92
93<p><strong>If your app is using the Support Library</strong> for compatibility on versions
94as low as Android 2.1, the {@code showAsAction} attribute is not available from
95the {@code android:} namespace. Instead this attribute is provided by the Support Library
96and you must define your own XML namespace and use that namespace as the attribute prefix.
97(A custom XML namespace should be based on your app name, but it can be any
98name you want and is only accessible within the scope of the file in which you declare it.)
99For example:</p>
100
101<p class="code-caption">res/menu/main_activity_actions.xml</p>
102<pre>
103&lt;menu xmlns:android="http://schemas.android.com/apk/res/android"
104      <strong>xmlns:yourapp="http://schemas.android.com/apk/res-auto"</strong> >
105    &lt;!-- Search, should appear as action button -->
106    &lt;item android:id="@+id/action_search"
107          android:icon="@drawable/ic_action_search"
108          android:title="@string/action_search"
109          <strong>yourapp:showAsAction="ifRoom"</strong>  /&gt;
110    ...
111&lt;/menu&gt;
112</pre>
113
114
115
116<h2 id="AddActions">Add the Actions to the Action Bar</h2>
117
118<p>To place the menu items into the action bar, implement the
119{@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback
120method in your activity to inflate the menu resource into the given {@link android.view.Menu}
121object. For example:</p>
122
123<pre>
124&#64;Override
125public boolean onCreateOptionsMenu(Menu menu) {
126    // Inflate the menu items for use in the action bar
127    MenuInflater inflater = getMenuInflater();
128    inflater.inflate(R.menu.main_activity_actions, menu);
129    return super.onCreateOptionsMenu(menu);
130}
131</pre>
132
133
134
135<h2 id="Respond">Respond to Action Buttons</h2>
136
137<p>When the user presses one of the action buttons or another item in the action overflow,
138the system calls your activity's {@link android.app.Activity#onOptionsItemSelected
139onOptionsItemSelected()} callback method. In your implementation of this method,
140call {@link android.view.MenuItem#getItemId getItemId()} on the given {@link android.view.MenuItem} to
141determine which item was pressed&mdash;the returned ID matches the value you declared in the
142corresponding {@code &lt;item>} element's {@code android:id} attribute.</p>
143
144<pre>
145&#64;Override
146public boolean onOptionsItemSelected(MenuItem item) {
147    // Handle presses on the action bar items
148    switch (item.getItemId()) {
149        case R.id.action_search:
150            openSearch();
151            return true;
152        case R.id.action_settings:
153            openSettings();
154            return true;
155        default:
156            return super.onOptionsItemSelected(item);
157    }
158}
159</pre>
160
161
162
163<h2 id="UpNav">Add Up Button for Low-level Activities</h2>
164
165<div class="figure" style="width:240px">
166  <img src="{@docRoot}images/ui/actionbar-up.png" width="240" alt="">
167  <p class="img-caption"><strong>Figure 4.</strong> The <em>Up</em> button in Gmail.</p>
168</div>
169
170<p>All screens in your app that are not the main entrance to your app
171(activities that are not the "home" screen) should
172offer the user a way to navigate to the logical parent screen in the app's hierarchy by pressing
173the <em>Up</em> button in the action bar.</p>
174
175<p>When running on Android 4.1 (API level 16) or higher, or when using {@link
176android.support.v7.app.ActionBarActivity} from the Support Library, performing <em>Up</em>
177navigation simply requires that you declare the parent activity in the manifest file and enable
178the <em>Up</em> button for the action bar.</p>
179
180<p>For example, here's how you can declare an activity's parent in the manifest:</p>
181
182<pre>
183&lt;application ... >
184    ...
185    &lt;!-- The main/home activity (it has no parent activity) -->
186    &lt;activity
187        android:name="com.example.myfirstapp.MainActivity" ...>
188        ...
189    &lt;/activity>
190    &lt;!-- A child of the main activity -->
191    &lt;activity
192        android:name="com.example.myfirstapp.DisplayMessageActivity"
193        android:label="@string/title_activity_display_message"
194        android:parentActivityName="com.example.myfirstapp.MainActivity" >
195        &lt;!-- Parent activity meta-data to support 4.0 and lower -->
196        &lt;meta-data
197            android:name="android.support.PARENT_ACTIVITY"
198            android:value="com.example.myfirstapp.MainActivity" />
199    &lt;/activity>
200&lt;/application>
201</pre>
202
203  <p>Then enable the app icon as the <em>Up</em> button by calling
204{@link android.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled()}:</p>
205
206<pre>
207{@literal @}Override
208public void onCreate(Bundle savedInstanceState) {
209    super.onCreate(savedInstanceState);
210    setContentView(R.layout.activity_displaymessage);
211
212    getSupportActionBar().setDisplayHomeAsUpEnabled(true);
213    // If your minSdkVersion is 11 or higher, instead use:
214    // getActionBar().setDisplayHomeAsUpEnabled(true);
215}
216</pre>
217
218<p>Because the system now knows {@code MainActivity} is the parent activity for
219{@code DisplayMessageActivity}, when the user presses the
220<em>Up</em> button, the system navigates to
221the parent activity as appropriate&mdash;you <strong>do not</strong> need to handle the
222<em>Up</em> button's event.</p>
223
224<p>For more information about up navigation, see
225<a href="{@docRoot}training/implementing-navigation/ancestral.html">Providing Up
226  Navigation</a>.