1 page.title=Setting Up the App Bar 2 page.tags="appbar","actionbar", "toolbar" 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-toolbar">Add a Toolbar to an Activity</a></li> 15 <li><a href="#utility">Use App Bar Utility Methods</a></li> 16 </ol> 17 18 <h2>You should also read</h2> 19 <ul> 20 <li><a href="{@docRoot}tools/support-library/setup.html" 21 >Setting Up the Support Library</a></li> 22 </ul> 23 </div> 24 </div> 25 26 27 <p> 28 In its most basic form, the action bar displays the title for the activity on 29 one side and an <em>overflow menu</em> on the other. Even in this simple 30 form, the app bar provides useful information to the users, and helps to give 31 Android apps a consistent look and feel. 32 </p> 33 34 <img src="{@docRoot}images/training/appbar/appbar_basic_2x.png" 35 srcset="{@docRoot}images/training/appbar/appbar_basic.png 1x, 36 {@docRoot}images/training/appbar/appbar_basic_2x.png 2x" 37 width="400" alt="" /> 38 <p class="img-caption"><strong>Figure 1.</strong> An app bar with the app 39 title and overflow menu.</a> 40 41 <p> 42 Beginning with Android 3.0 (API level 11), all 43 activities that use the default theme have an {@link android.app.ActionBar} 44 as an app bar. However, app bar features have gradually been added to the 45 native {@link android.app.ActionBar} over various Android releases. As a 46 result, the native {@link android.app.ActionBar} behaves differently 47 depending on what version of the Android system a device may be using. By 48 contrast, the most recent features are added to the support library's version 49 of {@link android.support.v7.widget.Toolbar}, and they are available on any 50 device that can use the support library. 51 </p> 52 53 <p> 54 For this reason, you should use the support library's {@link 55 android.support.v7.widget.Toolbar} class to implement your activities' app 56 bars. Using the support library's toolbar helps ensure that your app will 57 have consistent behavior across the widest range of devices. For example, the 58 {@link android.support.v7.widget.Toolbar} widget provides a <a href= 59 "{@docRoot}design/material/index.html">material design</a> experience on 60 devices running Android 2.1 (API level 7) or later, but the native action 61 bar doesn't support material design unless the device is running Android 5.0 62 (API level 21) or later. 63 </p> 64 65 <h2 id="add-toolbar">Add a Toolbar to an Activity</h2> 66 67 These steps describe how to set up a {@link android.support.v7.widget.Toolbar} 68 as your activity's app bar: 69 70 <ol> 71 <li>Add the 72 <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7 73 appcompat</a> support library to your project, as described in <a href= 74 "{@docRoot}tools/support-library/setup.html">Support Library Setup</a>. 75 </li> 76 77 <li>Make sure the activity extends {@link 78 android.support.v7.app.AppCompatActivity}: 79 80 <pre> 81 public class MyActivity extends AppCompatActivity { 82 // ... 83 } 84 </pre> 85 <p class="note"> 86 <strong>Note:</strong> Make this change for every activity in your app 87 that uses a {@link android.support.v7.widget.Toolbar} as an app bar. 88 </p> 89 </li> 90 91 <li>In the app manifest, set the <a href= 92 "{@docRoot}guide/topics/manifest/application-element.html"><code><application></code></a> 93 element to use one of appcompat's {@link 94 android.support.v7.appcompat.R.style#Theme_AppCompat_NoActionBar NoActionBar} 95 themes. Using one of these themes prevents the app from using the native 96 {@link android.app.ActionBar} class to provide the app bar. For example: 97 98 <pre> 99 <application 100 android:theme="@style/Theme.AppCompat.Light.NoActionBar" 101 /> 102 </pre> 103 </li> 104 105 <li>Add a {@link android.support.v7.widget.Toolbar} to the activity's layout. 106 For example, the following layout code adds a {@link 107 android.support.v7.widget.Toolbar} and gives it the appearance of floating 108 above the activity: 109 110 <pre> 111 <android.support.v7.widget.Toolbar 112 android:id="@+id/my_toolbar" 113 android:layout_width="match_parent" 114 android:layout_height="?attr/actionBarSize" 115 android:background="?attr/colorPrimary" 116 android:elevation="4dp" 117 android:theme="@style/ThemeOverlay.AppCompat.ActionBar" 118 app:popupTheme="@style/ThemeOverlay.AppCompat.Light"/> 119 </pre> 120 <p> 121 The <a href= 122 "https://www.google.com/design/spec/what-is-material/elevation-shadows.html#elevation-shadows-shadows"> 123 Material Design specification</a> recommends that app bars have an 124 elevation of 4 dp. 125 </p> 126 127 <p> 128 Position the toolbar at the top of the activity's 129 <a href="{@docRoot}guide/topics/ui/declaring-layout.html">layout</a>, 130 since you are using it as an app bar. 131 </p> 132 </li> 133 134 <li>In the activity's {@link android.app.Activity#onCreate onCreate()} 135 method, call the activity's {@link 136 android.support.v7.app.AppCompatActivity#setSupportActionBar 137 setSupportActionBar()} method, and pass the activity's toolbar. This method 138 sets the toolbar as the app bar for the activity. For example: 139 140 <pre> 141 @Override 142 protected void onCreate(Bundle savedInstanceState) { 143 super.onCreate(savedInstanceState); 144 setContentView(R.layout.activity_my); 145 <strong>Toolbar myToolbar = (Toolbar) findViewById(R.id.my_toolbar); 146 setSupportActionBar(myToolbar);</strong> 147 } 148 </pre> 149 </li> 150 </ol> 151 152 <p> 153 Your app now has a basic action bar. By default, the action bar contains just 154 the name of the app and an overflow menu. The options menu initially contains 155 just the <strong>Settings</strong> item. You can add more actions to the 156 action bar and the overflow menu, as described in <a href= 157 "actions.html">Adding and Handling Actions</a>. 158 </p> 159 160 <h2 id="utility">Use App Bar Utility Methods</h2> 161 162 <p> 163 Once you set the toolbar as an activity's app bar, you have access to the 164 various utility methods provided by the 165 <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7 166 appcompat</a> support library's {@link 167 android.support.v7.app.ActionBar} class. This approach lets you do a number of useful 168 things, like hide and show the app bar. 169 </p> 170 171 <p> 172 To use the {@link android.support.v7.app.ActionBar} utility methods, call the 173 activity's {@link 174 android.support.v7.app.AppCompatActivity#getSupportActionBar 175 getSupportActionBar()} method. This method returns a reference to an 176 appcompat {@link android.support.v7.app.ActionBar} object. 177 Once you have that reference, you can call any of the {@link 178 android.support.v7.app.ActionBar} methods to adjust the app bar. For example, 179 to hide the app bar, call {@link android.support.v7.app.ActionBar#hide 180 ActionBar.hide()}. 181 </p> 182
