1page.title=Adding and Handling Actions
2page.tags="appbar","actionbar"
3helpoutsWidget=true
4trainingnavtop=true
5
6@jd:body
7
8<div id="tb-wrapper">
9  <div id="tb">
10
11    <h2>This lesson teaches you to</h2>
12
13    <ol>
14      <li><a href="#add-actions">Add Action Buttons</a></li>
15      <li><a href="#handle-actions">Respond to Actions</a></li>
16    </ol>
17
18    <h2>Useful Resources</h2>
19    <ul>
20      <li><a href="https://www.google.com/design/icons/">Material Icons</a></li>
21    </ul>
22
23
24  </div>
25</div>
26
27
28<a class="notice-designers wide" href="{@docRoot}design/patterns/actionbar.html#ActionButtons">
29  <div>
30    <h3>Design Guide</h3>
31    <p>Action Buttons</p>
32  </div>
33</a>
34
35
36<p>
37  The app bar allows you to add buttons for user actions. This feature lets you
38  put the most important <em>actions</em> for the current context right at the
39  top of the app. For example, a photo browsing app might show <em>share</em>
40  and <em>create album</em> buttons at the top when the user is looking at
41  their photo roll; when the user looks at an individual photo, the app might
42  show <em>crop</em> and <em>filter</em> buttons.
43</p>
44
45<p>
46  Space in the app bar is limited. If an app declares more actions than can
47  fit in the app bar, the app bar send the excess actions to an
48  <em>overflow</em> menu. The app can also specify that an action should always
49  be shown in the overflow menu, instead of being displayed on the app bar.
50</p>
51
52<img src="{@docRoot}images/training/appbar/appbar_with_button_2x.png"
53  srcset="{@docRoot}images/training/appbar/appbar_with_button.png 1x,
54      {@docRoot}images/training/appbar/appbar_with_button_2x.png 2x"
55  width="400" alt="">
56
57<p class="img-caption">
58  <strong>Figure 1.</strong> An app bar with a single action button and an
59  overflow menu.
60</p>
61
62<h2 id="add-actions">Add Action Buttons</h2>
63
64<p>
65  All action buttons and other items available in the action overflow are
66  defined in an XML <a href=
67  "{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. To
68  add actions to the action bar, create a new XML file in your project's
69  <code>res/menu/</code> directory.
70</p>
71
72<p>
73  Add an <a href=
74  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
75  element for each item you want to include in the action bar, as shown in this
76  code example of a menu XML file:
77</p>
78
79<pre>
80&lt;menu xmlns:android="http://schemas.android.com/apk/res/android" &gt;
81
82    &lt;!-- "Mark Favorite", should appear as action button if possible --&gt;
83    &lt;item
84        android:id="@+id/action_favorite"
85        android:icon="@drawable/ic_favorite_black_48dp"
86        android:title="@string/action_favorite"
87        app:showAsAction="ifRoom"/&gt;
88
89    &lt;!-- Settings, should always be in the overflow --&gt;
90    &lt;item android:id="@+id/action_settings"
91          android:title="@string/action_settings"
92          app:showAsAction="never"/&gt;
93
94&lt;/menu&gt;
95</pre>
96
97<p>
98  The <code>app:showAsAction</code> attribute specifies whether the action
99  should be shown as a button on the app bar. If you set
100  <code>app:showAsAction="ifRoom"</code> (as in the example code's <em>favorite</em> action), the action is displayed as a button
101  if there is room in the app bar for it; if there is not enough room, excess
102  actions are sent to the overflow menu. If you set
103  <code>app:showAsAction="never"</code> (as in the example code's <em>settings</em> action), the action is always listed in the
104  overflow menu, not displayed in the app bar.
105</p>
106
107<p>
108  The system uses the action's icon as the action button if the action is
109  displayed in the app bar. You can find many useful icons on the <a href=
110  "https://www.google.com/design/icons/">Material Icons</a> page.
111</p>
112
113<h2 id="handle-actions">Respond to Actions</h2>
114
115<p>
116  When the user selects one of the app bar items, the system calls your
117  activity's {@link android.app.Activity#onOptionsItemSelected
118  onOptionsItemSelected()} callback method, and passes a {@link
119  android.view.MenuItem} object to indicate which item was clicked. In your
120  implementation of {@link android.app.Activity#onOptionsItemSelected
121  onOptionsItemSelected()}, call the {@link android.view.MenuItem#getItemId
122  MenuItem.getItemId()} method to determine which item was pressed. The ID returned
123  matches the value you declared in the corresponding <a href=
124  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
125  element's <code>android:id</code> attribute.
126</p>
127
128<p>
129  For example, the following code checks to see which action the user selected.
130  If the method does not recognize the user's action, it invokes the superclass
131  method:
132</p>
133
134<pre>
135&#64;Override
136public boolean onOptionsItemSelected(MenuItem item) {
137    switch (item.getItemId()) {
138        case R.id.action_settings:
139            // User chose the "Settings" item, show the app settings UI...
140            return true;
141
142        case R.id.action_favorite:
143            // User chose the "Favorite" action, mark the current item
144            // as a favorite...
145            return true;
146
147        default:
148            // If we got here, the user's action was not recognized.
149            // Invoke the superclass to handle it.
150            return super.onOptionsItemSelected(item);
151
152    }
153}
154</pre>
155