1 page.title=Adding and Handling Actions 2 page.tags="appbar","actionbar" 3 helpoutsWidget=true 4 trainingnavtop=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><item></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 <menu xmlns:android="http://schemas.android.com/apk/res/android" > 81 82 <!-- "Mark Favorite", should appear as action button if possible --> 83 <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"/> 88 89 <!-- Settings, should always be in the overflow --> 90 <item android:id="@+id/action_settings" 91 android:title="@string/action_settings" 92 app:showAsAction="never"/> 93 94 </menu> 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><item></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 @Override 136 public 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
