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